Documentation work

1 files changed, 87 insertions, 0 deletions

diff --git a/bdep/projects-configs.cli b/bdep/projects-configs.cli
new file mode 100644
index 0000000..82ab462
--- /dev/null
+++ b/bdep/projects-configs.cli
@@ -0,0 +1,87 @@
+// file      : bdep/projects-configs.cli
+// copyright : Copyright (c) 2014-2017 Code Synthesis Ltd
+// 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)}) re-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). One of these
+  configurations can be designated as the default and used if no configuration
+  is explicitly specified. 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 configuration.
+
+  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
+  \
+
+  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.
+
+  "
+}