aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--bpkg/bpkg-options.cli42
-rw-r--r--bpkg/bpkg.cxx14
-rw-r--r--bpkg/build-options.cli51
-rw-r--r--bpkg/buildfile19
-rw-r--r--bpkg/common-options.cli29
-rw-r--r--bpkg/help6
-rw-r--r--bpkg/help.cxx55
-rw-r--r--bpkg/pkg-status-options.cli126
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
diff --git a/bpkg/help b/bpkg/help
index 8bd5596..e941d40 100644
--- a/bpkg/help
+++ b/bpkg/help
@@ -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|"
};
}