diff options
| -rw-r--r-- | bpkg/bpkg-options.cli | 42 | ||||
| -rw-r--r-- | bpkg/bpkg.cxx | 14 | ||||
| -rw-r--r-- | bpkg/build-options.cli | 51 | ||||
| -rw-r--r-- | bpkg/buildfile | 19 | ||||
| -rw-r--r-- | bpkg/common-options.cli | 29 | ||||
| -rw-r--r-- | bpkg/help | 6 | ||||
| -rw-r--r-- | bpkg/help.cxx | 55 | ||||
| -rw-r--r-- | bpkg/pkg-status-options.cli | 126 |
8 files changed, 170 insertions, 172 deletions
diff --git a/bpkg/bpkg-options.cli b/bpkg/bpkg-options.cli index 5da4213..b0f14e3 100644 --- a/bpkg/bpkg-options.cli +++ b/bpkg/bpkg-options.cli @@ -10,25 +10,39 @@ include <bpkg/common-options.cli>; namespace bpkg { - class bpkg_options: common_options { - bool --help; - bool --version; - }; + "<command> <topic> <common-options> <command-options> <command-args>", + + "\h|SYNOPSIS| + + \cb{bpkg --help}\n + \cb{bpkg --version}\n + \c{\b{bpkg help} [<command>|<topic>]}\n + \c{\b{bpkg} [<common-options>] <command> [<command-options>] <command-args>} + + \h|DESCRIPTION| + + @@ TODO + + Note that the common options can also be specified as part of the + command-specific options." + } - class bpkg_commands + class commands { + "\h|COMMANDS|" + bool help { "[<topic>]", - "Show detailed help for a command or help topic.", + "Show help for a command or help topic \- \l{bpkg-help(1)}.", "" }; bool build { "<pkg>...", - "Build one or more packages.", + "Build one or more packages \- \l{bpkg-build-options(1)}.", "" }; @@ -140,11 +154,19 @@ namespace bpkg // Make sure these don't conflict with command names above. // - class bpkg_topics + class topics { - bool common + "\h|HELP TOPICS|" + + bool common-options { - "Detailed description of common options." + "Options common for all commands \- \l{bpkg-common-options(1)}." }; }; + + class options: common_options + { + bool --help; + bool --version; + }; } diff --git a/bpkg/bpkg.cxx b/bpkg/bpkg.cxx index 85f6477..386d284 100644 --- a/bpkg/bpkg.cxx +++ b/bpkg/bpkg.cxx @@ -72,10 +72,10 @@ try // First parse common options and --version/--help. // - bpkg_options bo; - bo.parse (args, unknown_mode::stop); + options o; + o.parse (args, unknown_mode::stop); - if (bo.version ()) + if (o.version ()) { cout << "bpkg " << BPKG_VERSION_STR << "; " << "libbpkg " << LIBBPKG_VERSION_STR << endl @@ -84,13 +84,13 @@ try return 0; } - if (bo.help ()) + if (o.help ()) { help (help_options (), "", nullptr); return 0; } - const common_options& co (bo); + const common_options& co (o); // The next argument should be a command. // @@ -100,7 +100,7 @@ try int cmd_argc (2); char* cmd_argv[] {argv[0], const_cast<char*> (args.next ())}; - bpkg_commands cmd; + commands cmd; cmd.parse (cmd_argc, cmd_argv, true, unknown_mode::stop); if (cmd_argc != 1) @@ -125,7 +125,7 @@ try // First see if this is a command. // - cmd = bpkg_commands (); // Clear help option. + cmd = commands (); // Clear the help option. cmd.parse (cmd_argc, cmd_argv, true, unknown_mode::stop); // If not, then it got to be a help topic. diff --git a/bpkg/build-options.cli b/bpkg/build-options.cli index 7164dbb..00a4c9c 100644 --- a/bpkg/build-options.cli +++ b/bpkg/build-options.cli @@ -8,41 +8,42 @@ include <bpkg/configuration-options.cli>; "\name=bpkg-build" "\summary=build one or more packages" +namespace bpkg { -"<options> <pkg> <ver> <file> <dir>", - -"\h|SYNOPSIS| + { + "<options> <pkg> <ver> <file> <dir>", -\c{\b{bpkg build} [<options>] (<pkg>[/<ver>] | <file> | <dir>)...} + "\h|SYNOPSIS| -\h|DESCRIPTION| + \c{\b{bpkg build} [<options>] (<pkg>[/<ver>] | <file> | <dir>)...} -The \cb{build} command builds one or more packages including all their -prerequisites. Each package can be specified as just the name (<pkg>) with -optional package version (<ver>) in which case the package will be -automatically fetched from one of the configuration's source repositories -(see the \cb{rep-add} and \cb{rep-fetch} commands). Alternatively, the -package can be specified as either the path to the package source archive -(<file>) or package source directory (<dir>). See the \cb{pkg-fetch} and -\cb{pkg-unpack} commands for more information on the semantics of specifying -the package as an archive or directory. + \h|DESCRIPTION| -Packages that are specified explicitly on the command line will be \i{held}, -that is, they will not be considered for automatic removal if they no longer -have any dependents. Packages that are specified with the explicit package -version (<ver>) or as an archive or directory, will, in addition, have their -versions held, that is, they will not be automatically upgraded. + The \cb{build} command builds one or more packages including all their + prerequisites. Each package can be specified as just the name (<pkg>) with + optional package version (<ver>) in which case the package will be + automatically fetched from one of the configuration's source repositories + (see the \cb{rep-add} and \cb{rep-fetch} commands). Alternatively, the + package can be specified as either the path to the package source archive + (<file>) or package source directory (<dir>). See the \cb{pkg-fetch} and + \cb{pkg-unpack} commands for more information on the semantics of + specifying the package as an archive or directory. -The \cb{build} command also supports several \cb{--*-only} options that allow -you to limit the amount of work that will be done. + Packages that are specified explicitly on the command line will be + \i{held}, that is, they will not be considered for automatic removal if + they no longer have any dependents. Packages that are specified with the + explicit package version (<ver>) or as an archive or directory, will, in + addition, have their versions held, that is, they will not be + automatically upgraded. -\h|OPTIONS|" -} + The \cb{build} command also supports several \cb{--*-only} options that + allow you to limit the amount of work that will be done." + } -namespace bpkg -{ class build_options: configuration_options { + "\h|BUILD OPTIONS|" + bool --yes|-y { "Assume the answer to all prompts is \cb{yes}." diff --git a/bpkg/buildfile b/bpkg/buildfile index cc03a28..02fdb31 100644 --- a/bpkg/buildfile +++ b/bpkg/buildfile @@ -40,19 +40,17 @@ cli.options += -I $src_root --include-with-brackets --include-prefix bpkg \ --guard-prefix BPKG --cxx-prologue "#include <bpkg/types-parsers>" \ --cli-namespace bpkg::cli --generate-file-scanner --generate-specifier \ --generate-parse --ansi-color --page-usage 'bpkg::print_$name$_' \ ---long-usage --option-length 20 +--include-base-last --long-usage --option-length 20 cli.cxx{common-options}: cli{common-options} cli.cxx{common-options}: cli.options += --short-usage +cli.cxx{configuration-options}: cli{configuration-options} + cli.cxx{bpkg-options}: cli{bpkg-options} -cli.cxx{bpkg-options}: cli.options += --short-usage +cli.cxx{bpkg-options}: cli.options += --suppress-undocumented cli.cxx{help-options}: cli{help-options} -cli.cxx{help-options}: cli.options += --exclude-base - -cli.cxx{configuration-options}: cli{configuration-options} -cli.cxx{configuration-options}: cli.options += --exclude-base # # @@ -69,22 +67,15 @@ cli.cxx{pkg-configure-options}: cli{pkg-configure-options} cli.cxx{pkg-disfigure-options}: cli{pkg-disfigure-options} cli.cxx{pkg-update-options}: cli{pkg-update-options} cli.cxx{pkg-clean-options}: cli{pkg-clean-options} - -cli.cxx{pkg-verify-options}: cli{pkg-verify-options} -cli.cxx{pkg-verify-options}: cli.options += --exclude-base +cli.cxx{pkg-verify-options}: cli{pkg-verify-options} # cfg-* # cli.cxx{cfg-create-options}: cli{cfg-create-options} -cli.cxx{cfg-create-options}: cli.options += --exclude-base # rep-* # cli.cxx{rep-add-options}: cli{rep-add-options} cli.cxx{rep-fetch-options}: cli{rep-fetch-options} - cli.cxx{rep-info-options}: cli{rep-info-options} -cli.cxx{rep-info-options}: cli.options += --exclude-base - cli.cxx{rep-create-options}: cli{rep-create-options} -cli.cxx{rep-create-options}: cli.options += --exclude-base diff --git a/bpkg/common-options.cli b/bpkg/common-options.cli index a8b6744..f07d70e 100644 --- a/bpkg/common-options.cli +++ b/bpkg/common-options.cli @@ -5,13 +5,38 @@ include <bpkg/types>; "\section=1" -"\name=bpkg-common" -"\summary=common options for all commands" +"\name=bpkg-common-options" +"\summary=options common for all commands" namespace bpkg { + { + "<common-options>", + + "\h|SYNOPSIS| + + \c{\b{bpkg} [<common-options>] ...} + + \h|DESCRIPTION| + + The common options can be specified either before the command or after, + togethere with the command-specific options." + } + class common_options = 0 { + "\h|COMMON OPTIONS|" + + // Retain this note only in the summary. + // + { + "", + "The common options are summarized below with a more detailed description + available as the \l{bpkg-common-options(1) \cb{common-options}} help + topic.", + "" + } + bool -v { "Print underlying commands being executed. This is equivalent to @@ -12,10 +12,10 @@ namespace bpkg { + using usage_function = cli::usage_para (std::ostream&, cli::usage_para); + int - help (const help_options&, - const string& topic, - void (*usage) (std::ostream&)); + help (const help_options&, const string& topic, usage_function* usage); } #endif // BPKG_HELP diff --git a/bpkg/help.cxx b/bpkg/help.cxx index 0505061..df4a286 100644 --- a/bpkg/help.cxx +++ b/bpkg/help.cxx @@ -19,64 +19,21 @@ namespace bpkg static void help () { - ostream& o (cout); - - //@@ TODO - - o << "usage: bpkg --help" << endl - << " bpkg --version" << endl - << " bpkg help [<command>|<topic>]" << endl - << " bpkg [<common-options>] <command> [<command-options>] " << - "[<command-args>]" << endl - << endl; - - o << "The commands are:" << endl - << endl; - - bpkg_commands::print_short_usage (o); - o << endl; - - o << "The help topics are:" << endl - << endl; - - bpkg_topics::print_short_usage (o); - o << endl; - - o << "The common options are summarized below. Note that they can also " - "be specified" << endl - << "as part of the command-specific options." << endl - << endl; - - common_options::print_short_usage (o); - o << endl; - - o << ""<< endl; + print_bpkg_usage (cout); } int - help (const help_options&, const string& t, void (*usage) (std::ostream&)) + help (const help_options&, const string& t, usage_function* usage) { ostream& o (cout); if (usage != nullptr) // Command. - { - usage (o); - - //@@ TODO - - o << endl - << "The common options are summarized below. For details, see the " << - "'common' help" << endl - << "topic." << endl - << endl; - - common_options::print_short_usage (o); - } - else if (t.empty ()) // General help. + usage (o, cli::usage_para::none); + else if (t.empty ()) // General help. help (); - else if (t == "common") // Help topics. + else if (t == "common-options") // Help topics. { - print_bpkg_common_long_usage (cout); + print_bpkg_common_options_long_usage (cout); } else fail << "unknown bpkg command/help topic '" << t << "'" << diff --git a/bpkg/pkg-status-options.cli b/bpkg/pkg-status-options.cli index c3ea3d6..f106ddc 100644 --- a/bpkg/pkg-status-options.cli +++ b/bpkg/pkg-status-options.cli @@ -8,100 +8,102 @@ include <bpkg/configuration-options.cli>; "\name=bpkg-pkg-status" "\summary=print package status" +namespace bpkg { -"<options> <pkg> <ver>", - -"\h|SYNOPSIS| + { + "<options> <pkg> <ver>", -\c{\b{bpkg pkg-status} [<options>] <pkg>[/<ver>]} + "\h|SYNOPSIS| -\h|DESCRIPTION| + \c{\b{bpkg pkg-status} [<options>] <pkg>[/<ver>]} -The \cb{pkg-status} command prints the status of the specified package or, if -<ver> is specified, package version. Note that the status is written to -\cb{STDOUT}, not \cb{STDERR}. + \h|DESCRIPTION| -The status format is regular. First always comes one of the following status -words: + The \cb{pkg-status} command prints the status of the specified package or, + if <ver> is specified, package version. Note that the status is written + to \cb{STDOUT}, not \cb{STDERR}. -\dl| + The status format is regular. First always comes one of the following + status words: -\li|\cb{unknown} + \dl| - package is not part of the configuration nor available in one of the - repositories| + \li|\cb{unknown} -\li|\cb{available} + package is not part of the configuration nor available in one of the + repositories| - package is not part of the configuration but is available in one of the - repositories| + \li|\cb{available} -\li|\cb{fetched} + package is not part of the configuration but is available in one of + the repositories| - package is part of the configuration and is fetched| + \li|\cb{fetched} -\li|\cb{unpacked} + package is part of the configuration and is fetched| - package is part of the configuration and is unpacked| + \li|\cb{unpacked} -\li|\cb{configured} + package is part of the configuration and is unpacked| - package is part of the configuration and is configured|| + \li|\cb{configured} + package is part of the configuration and is configured|| -If only the package name was specified without the package version, then the -\cb{available} status word is followed by the list of available versions. -Similarly, if only the package name was specified, then the \cb{fetched}, -\cb{unpacked}, and \cb{configured} status words are followed by the version -of the package. After the possible package version, these status words may -be followed by one or more sub-status words. Currently, these can be -\cb{hold_package} (package should not be automatically dropped) and -\cb{hold_version} (package should not be automatically upgraded). Finally, -if only the package name was specified and newer versions are available -in the repositories, then the sub-status words are followed by '\cb{;}', -the \cb{available} status word, and the list of newer versions. + If only the package name was specified without the package version, then + the \cb{available} status word is followed by the list of available + versions. -Below are some examples, assuming the configuration has libfoo 1.0.0 -configured and held as well as libfoo 1.1.0 and 1.1.1 available from a -repository. + Similarly, if only the package name was specified, then the \cb{fetched}, + \cb{unpacked}, and \cb{configured} status words are followed by the + version of the package. After the possible package version, these status + words may be followed by one or more sub-status words. Currently, these + can be \cb{hold_package} (package should not be automatically dropped) + and \cb{hold_version} (package should not be automatically upgraded). + Finally, if only the package name was specified and newer versions are + available in the repositories, then the sub-status words are followed + by '\cb{;}', the \cb{available} status word, and the list of newer + versions. -\ -bpkg pkg-status libbar -unknown + Below are some examples, assuming the configuration has libfoo 1.0.0 + configured and held as well as libfoo 1.1.0 and 1.1.1 available from a + repository. -bpkg pkg-status libbar/1.0.0 -unknown + \ + bpkg pkg-status libbar + unknown -bpkg pkg-status libfoo/1.0.0 -configured hold_package + bpkg pkg-status libbar/1.0.0 + unknown -bpkg pkg-status libfoo/1.1.0 -available + bpkg pkg-status libfoo/1.0.0 + configured hold_package -bpkg pkg-status libfoo -configured 1.0.0 hold_package; available 1.1.0 1.1.1 -\ + bpkg pkg-status libfoo/1.1.0 + available -Assuming now that we dropped libfoo from the configuration: + bpkg pkg-status libfoo + configured 1.0.0 hold_package; available 1.1.0 1.1.1 + \ -\ -bpkg pkg-status libfoo/1.0.0 -unknown + Assuming now that we dropped libfoo from the configuration: -bpkg pkg-status libfoo/1.1.0 -available + \ + bpkg pkg-status libfoo/1.0.0 + unknown -bpkg pkg-status libfoo -available 1.1.0 1.1.1 -\ + bpkg pkg-status libfoo/1.1.0 + available -\h|OPTIONS|" -} + bpkg pkg-status libfoo + available 1.1.0 1.1.1 + \ + " + } -namespace bpkg -{ class pkg_status_options: configuration_options { + "\h|PKG-STATUS OPTIONS|" }; } |