aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2018-03-20 06:41:20 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2018-03-20 06:41:20 +0200
commitfcb50d36651e660db33f3bfaca564d4789273145 (patch)
treeee741c1d928b62db10549208096199def1cddaa8
parentc02d4eeb02c06dcd0e3340bb3681f250d468922d (diff)
Documentation work
-rw-r--r--bdep/.gitignore1
-rw-r--r--bdep/bdep.cli5
-rw-r--r--bdep/buildfile19
-rw-r--r--bdep/help.cxx6
-rw-r--r--bdep/init.cli6
-rw-r--r--bdep/new.cli2
-rw-r--r--bdep/projects-configs.cli87
-rw-r--r--bdep/status.cli22
-rw-r--r--bdep/sync.cli100
-rwxr-xr-xdoc/cli.sh2
10 files changed, 225 insertions, 25 deletions
diff --git a/bdep/.gitignore b/bdep/.gitignore
index 02a0554..da387e5 100644
--- a/bdep/.gitignore
+++ b/bdep/.gitignore
@@ -1,4 +1,5 @@
bdep
*-odb.?xx
*-options.?xx
+projects-configs.?xx
version.hxx
diff --git a/bdep/bdep.cli b/bdep/bdep.cli
index 69c7ffc..9974458 100644
--- a/bdep/bdep.cli
+++ b/bdep/bdep.cli
@@ -100,6 +100,11 @@ namespace bdep
{
"\l{bdep-common-options(1)} \- details on common options"
}
+
+ bool projects-configs
+ {
+ "\l{bdep-projects-configs(1)} \- specifying projects and configurations"
+ }
};
class options: common_options
diff --git a/bdep/buildfile b/bdep/buildfile
index 75f5320..ac355e4 100644
--- a/bdep/buildfile
+++ b/bdep/buildfile
@@ -26,10 +26,13 @@ fetch-options \
status-options \
config-options
-exe{bdep}: {hxx ixx txx cxx}{** -{$options_topics} -*-odb -version} \
- {hxx ixx cxx}{$options_topics} \
- {hxx ixx cxx}{project-odb database-views-odb} \
- {hxx}{version} $libs
+help_topics = projects-configs
+
+exe{bdep}: \
+ {hxx ixx txx cxx}{** -{$options_topics} -{$help_topics} -*-odb -version} \
+ {hxx ixx cxx}{$options_topics} {hxx cxx}{$help_topics} \
+ {hxx ixx cxx}{project-odb database-views-odb} \
+ {hxx}{version} $libs
hxx{version}: in{version} $src_root/file{manifest}
@@ -62,6 +65,10 @@ if $cli.configured
cli.cxx{status-options}: cli{status}
cli.cxx{config-options}: cli{config}
+ # Help topics.
+ #
+ cli.cxx{projects-configs}: cli{projects-configs}
+
# Option length must be the same to get commands/topics/options aligned.
#
cli.options += -I $src_root --include-with-brackets --include-prefix bdep \
@@ -78,6 +85,10 @@ if $cli.configured
cli.cxx{new-options}: cli.options += \
--cxx-prologue "#include <bdep/new-parsers.hxx>"
+ # Avoid generating CLI runtime and empty inline file for help topics.
+ #
+ cli.cxx{projects-configs}: cli.options += --suppress-cli --suppress-inline
+
# Include the generated cli files into the distribution and don't remove
# them when cleaning in src (so that clean results in a state identical to
# distributed).
diff --git a/bdep/help.cxx b/bdep/help.cxx
index ec2c4c2..098e902 100644
--- a/bdep/help.cxx
+++ b/bdep/help.cxx
@@ -9,6 +9,10 @@
#include <bdep/diagnostics.hxx>
#include <bdep/bdep-options.hxx>
+// Help topics.
+//
+#include <bdep/projects-configs.hxx>
+
using namespace std;
using namespace butl;
@@ -26,6 +30,8 @@ namespace bdep
//
else if (t == "common-options")
usage = &print_bdep_common_options_long_usage;
+ else if (t == "projects-configs")
+ usage = &print_bdep_projects_configs_usage;
else
fail << "unknown bdep command/help topic '" << t << "'" <<
info << "run 'bdep help' for more information";
diff --git a/bdep/init.cli b/bdep/init.cli
index 8629bfe..ded6913 100644
--- a/bdep/init.cli
+++ b/bdep/init.cli
@@ -46,12 +46,12 @@ namespace bdep
<cfg-args> are arguments to \cb{bpkg cfg-create}. <pkg-args> are arguments
to \cb{bpkg pkg-build}.
- In the first variant the configurations can also be specified as
+ In the first form the configurations can also be specified as
directories using the \cb{--config|-c} option.
- The second and third variants are semantically equivalent to first
+ The second and third forms are semantically equivalent to first
performing the \cb{config add} and \cb{config create} commands
- (\l{bdep-config(1)}), respectively, followed by the first variant. In
+ (\l{bdep-config(1)}), respectively, followed by the first form. In
both cases the \cb{--default|-d} option can be used to make the
added/created configuration default.
"
diff --git a/bdep/new.cli b/bdep/new.cli
index ddf61c0..1e91b41 100644
--- a/bdep/new.cli
+++ b/bdep/new.cli
@@ -34,7 +34,7 @@ namespace bdep
The \cb{new} command...
- The first variant, unless the \cb{--no-init} is specified, initializes
+ The first form, unless the \cb{--no-init} is specified, initializes
an empty configuration set, as if by performing \cb{init --empty}.
Recognized \cb{c++} language options:
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.
+
+ "
+}
diff --git a/bdep/status.cli b/bdep/status.cli
index 6a562da..8ef909b 100644
--- a/bdep/status.cli
+++ b/bdep/status.cli
@@ -28,17 +28,19 @@ namespace bdep
\h|DESCRIPTION|
- The \cb{status} command prints the status of the project and/or its
- dependencies in build configurations. If no <dep-spec> arguments are
- specified, then \cb{status} prints the status of the project's packages.
- Otherwise, the status of the specified dependency packages is printed.
- Additionally, the status of immediate or all dependencies of the above
- packages can be printed by specifying the \c{\b{--immediate}|\b{-i}} or
- \c{\b{--recursive}|\b{-r}} options, respectively. Note that the status is
- written to \cb{STDOUT}, not \cb{STDERR}.
+ The \cb{status} command prints the status of project packages and/or
+ their dependencies in build configurations. If no <dep-spec> arguments
+ are specified, then \cb{status} prints the status of the project's
+ packages. Otherwise, the status of the specified dependency packages is
+ printed. Additionally, the status of immediate or all dependencies of the
+ above packages can be printed by specifying the
+ \c{\b{--immediate}|\b{-i}} or \c{\b{--recursive}|\b{-r}} options,
+ respectively. See \l{bdep-projects-configs(1)} for details on specifying
+ packages (<pkg-spec>) and configurations (<cfg-spec>).
- The status of each package is printed on a separate line. The semantics
- of <dep-spec> and the format of the status line are described in
+ The status of each package is printed on a separate line. Note that the
+ status is written to \cb{STDOUT}, not \cb{STDERR}. The semantics of
+ <dep-spec> and the format of the status line are described in
\l{bpkg-pkg-status(1)}.
"
}
diff --git a/bdep/sync.cli b/bdep/sync.cli
index 0a3965d..7db5ac9 100644
--- a/bdep/sync.cli
+++ b/bdep/sync.cli
@@ -14,19 +14,85 @@ namespace bdep
"<options>
<prj-spec> <prj-dir>
<pkg-spec> <pkg-dir>
- <cfg-spec> <cfg-name> <cfg-dir>",
+ <cfg-spec> <cfg-name> <cfg-dir>
+ <dep-spec> <pkg> <ver>",
"\h|SYNOPSIS|
- \c{\b{bdep sync} [<options>] [<pkg-spec>] [<cfg-spec>]}
+ \c{\b{bdep sync} [<options>] [<pkg-spec>] [<cfg-spec>]\n
+ \b{bdep sync} [<options>] [<pkg-spec>] [<cfg-spec>] \ \b{--upgrade}|\b{-u} | \b{--patch}|\b{-p}\n
+ \b{bdep sync} [<options>] [<pkg-spec>] [<cfg-spec>] [\b{--upgrade}|\b{-u} | \b{--patch}|\b{-p}]\n
+ \ \ \ \ \ \ \ \ \ \ <dep-spec>...
+ }
- \c{<cfg-spec> = (\b{@}<cfg-name> | \b{--config}|\b{-c} <cfg-dir>)... | \b{--all}|\b{-a}\n
+ \c{<dep-spec> = <pkg>[\b{/}<ver>]\n
+ <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|
- The \cb{sync} command..."
+ The \cb{sync} command synchronizes a project with its build
+ configurations. The first form (no arguments nor \cb{--upgrade} or
+ \cb{--patch} specified) upgrades the project packages to the latest
+ iteration, adjusts their dependencies according to the latest manifest
+ information and updates the lockfile.
+
+ The second form (no arguments but with either \cb{--upgrade} or
+ \cb{--patch} specified), in addition to the first form's functionality,
+ also upgrades or patches immediate (by default or
+ \c{\b{--immediate}|\b{-i}} specified) or all (\c{\b{--recursive}|\b{-r}}
+ specified) dependencies of the specified project packages.
+
+ The third form (one or more arguments), in addition to the first form's
+ functionality, also upgrades (by default or \cb{--upgrade} specified) or
+ patches (\cb{--patch} specified) the specified dependencies. If
+ \c{\b{--immediate}|\b{-i}} or \c{\b{--recursive}|\b{-r}} is specified,
+ then it also upgrades or patches the immediate or all dependencies of the
+ specified dependencies, respectively. Alternative to \cb{--upgrade} and
+ \cb{--patch}, the desired upgrade (or downgrade) version can be specified
+ explicitly.
+
+ As an example, consider project \cb{proj} with two packages, \cb{test}
+ and \cb{libtest}:
+
+ \
+ proj/
+ ├── test/
+ └── libtest/
+ \
+
+ The following invocations illustrate the common \cb{sync} use cases (the
+ current working directory is shown before the shell prompt):
+
+ \
+ proj/$ bdep sync # Synchronize test/ and libtest/ with the
+ # default configuration.
+
+ proj/$ cd test
+ test/$ bdep sync # The same (all packages in a project are
+ # always synchronized together).
+
+ test/$ edit manifest # Add 'depends: libx >= 1.0.0'
+ test/$ bdep sync # Fetch and configure suitable libx version.
+
+ test/$ bdep sync -u # Upgrade all immediate dependencies of test.
+ test/$ cd ../
+ proj/$ bdep sync -u -r # Upgrade all dependencies of all packages in
+ # a project recursively.
+
+ proj/$ bdep sync libx # Upgrade libx to the latest version.
+ proj/$ bdep sync -i libx # ...and its immediate dependecies.
+
+ proj/$ bdep sync -p libx # Upgrade libx to the latest patch.
+ proj/$ bdep sync -p -r libx # ...and its dependecies, recursively.
+
+ proj/$ bdep sync libx/1.2.3 # Upgrade libx to version 1.2.3.
+ proj/$ bdep sync -p -r libx/1.2.3 # ...and patch its dependecies,
+ # recursively.
+ \
+
+ "
}
// Note that not all project/configuration options are valid for all
@@ -36,9 +102,26 @@ namespace bdep
{
"\h|SYNC OPTIONS|"
- bool --yes|-y
+ bool --upgrade|-u
{
- "Don't prompt for confirmation when up/down-grading dependencies."
+ "Upgrade the dependencies to the latest available version that satisfies
+ all the constraints."
+ }
+
+ bool --patch|-p
+ {
+ "Upgrade the dependencies to the latest available patch version that
+ satisfies all the constraints."
+ }
+
+ bool --immediate|-i
+ {
+ "Also upgrade or patch immediate dependencies."
+ }
+
+ bool --recursive|-r
+ {
+ "Also upgrade or patch all dependencies, recursively."
}
bool --fetch|-f
@@ -50,5 +133,10 @@ namespace bdep
{
"Perform the \cb{fetch --full} command prior to synchronization."
}
+
+ bool --yes|-y
+ {
+ "Don't prompt for confirmation when up/down-grading dependencies."
+ }
};
}
diff --git a/doc/cli.sh b/doc/cli.sh
index af6638d..48a8b74 100755
--- a/doc/cli.sh
+++ b/doc/cli.sh
@@ -57,7 +57,7 @@ o="--suppress-undocumented --output-prefix bdep- --class-doc bdep::common_option
compile "common" $o --output-suffix "-options" --class-doc bdep::common_options=long
compile "bdep" $o --output-prefix "" --class-doc bdep::commands=short --class-doc bdep::topics=short
-pages="new help init sync fetch status config"
+pages="new help init sync fetch status config projects-configs"
for p in $pages; do
compile $p $o