// file      : bdep/projects-configs.cli
// license   : MIT; see accompanying LICENSE file

include <bdep/common-options.hxx>;

"\section=1"
"\name=bdep-projects-configs"
"\summary=specifying projects and configurations"

{
  "<command>
   <prj-spec> <prj-dir>
   <pkg-spec> <pkg-dir>
   <cfg-spec> <cfg-name> <cfg-dir>",

  "
  \h|SYNOPSIS|

  \c{\b{bdep} <command> [<pkg-spec>] [<cfg-spec>] ...}

  \c{<cfg-spec> = (\b{@}<cfg-name> | \b{--config}|\b{-c} <cfg-dir>)... | \b{--all}|\b{-a}\n
     <pkg-spec> = (\b{--directory}|\b{-d} <pkg-dir>)... | <prj-spec>\n
     <prj-spec> = \b{--directory}|\b{-d} <prj-dir>}

  \h|DESCRIPTION|

  Most \cb{bdep} commands operate on a project or some of its packages as well
  as its build configurations. For example, \cb{status} (\l{bdep-status(1)})
  shows the status of one or more project packages in one or more build
  configurations. While \cb{fetch} (\l{bdep-fetch(1)}) fetches the list of
  available to the project dependency packages, again, in one or more build
  configurations.

  Without any \c{\b{--directory}|\b{-d}} options specified, the current
  working directory is assumed to be either the project root directory, the
  package root directory, or one of the package subdirectories. This is the
  common \cb{bdep} usage mode where you run it from within your project's
  source code directories, similar to version control tools such as
  \cb{git(1)}.

  Alternatively, the project or (several) package directories can be specified
  with the \c{\b{--directory}|\b{-d}} options. Note that \cb{bdep} operates
  on a single project but potentially multiple packages belonging to said
  project at a time.

  Some \cb{bdep} commands, such as \cb{fetch}, operate on the whole project.
  If such a command is given a package directory (either as the working
  directory or with \c{\b{--directory}|\b{-d}}), then it automatically
  determines its project directory and uses that.

  Other commands, such as \cb{status}, operate on one or more packages. If
  such a command is given a project directory, then it automatically
  determines the list of packages belonging to this project and uses
  that. Note that what exactly \i{belonging} means is command-specific. For
  most commands it means all the packages initialized in a given build
  configuration. For \cb{init} (\l{bdep-init(1)}), however, it means all the
  packages available in the project (for example, as listed in
  \cb{packages.manifest}).

  A project managed by \cb{bdep} has one or more associated build
  configurations (see \l{bdep-config(1)} for details). Some of these
  configurations, one per the configuration type, can be designated as default
  and used if no configuration is specified explicitly. So, for example,
  running \cb{status} without any arguments in the project directory will show
  the status of all the project packages initialized in the default
  configurations.

  An associated build configuration can be assigned a name in which case we
  can specify it using the \c{\b{@}\i{cfg-name}} notation. For example:

  \
  $ bdep status @gcc @clang
  \

  Note to Windows users: a command line argument with leading \cb{@} has a
  special meaning in PowerShell. To work around this, you can use the
  alternative \cb{-@gcc} syntax or the \cb{-n\ gcc} option.

  A configuration without a name can be specified as a directory using the
  \c{\b{--config}|\b{-c}} option. Name and directory specifications can be
  mixed. For example:

  \
  $ bdep status @gcc -c ../builds/clang
  \

  Finally, we can use the \c{\b{--all}|\b{-a}} option to specify all the
  build configurations associated with the project.

  "
}