diff options
| -rw-r--r-- | bdep/.gitignore | 1 | ||||
| -rw-r--r-- | bdep/bdep.cli | 5 | ||||
| -rw-r--r-- | bdep/buildfile | 19 | ||||
| -rw-r--r-- | bdep/help.cxx | 6 | ||||
| -rw-r--r-- | bdep/init.cli | 6 | ||||
| -rw-r--r-- | bdep/new.cli | 2 | ||||
| -rw-r--r-- | bdep/projects-configs.cli | 87 | ||||
| -rw-r--r-- | bdep/status.cli | 22 | ||||
| -rw-r--r-- | bdep/sync.cli | 100 | ||||
| -rwxr-xr-x | doc/cli.sh | 2 |
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." + } }; } @@ -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 |