From 7d03940f6816329fa9ae131591717749bc76be5a Mon Sep 17 00:00:00 2001 From: Karen Arutyunov Date: Wed, 30 Oct 2019 16:56:24 +0300 Subject: Document default options files for commands --- bpkg/.gitignore | 1 + bpkg/bpkg.cli | 5 +++ bpkg/buildfile | 15 ++++++--- bpkg/cfg-create.cli | 23 +++++++++++++ bpkg/cfg-create.cxx | 4 +++ bpkg/default-options-files.cli | 73 ++++++++++++++++++++++++++++++++++++++++++ bpkg/help.cli | 14 ++++++++ bpkg/help.cxx | 3 ++ bpkg/pkg-build.cli | 21 ++++++++++++ bpkg/pkg-checkout.cli | 21 ++++++++++++ bpkg/pkg-clean.cli | 21 ++++++++++++ bpkg/pkg-configure.cli | 21 ++++++++++++ bpkg/pkg-disfigure.cli | 21 ++++++++++++ bpkg/pkg-drop.cli | 21 ++++++++++++ bpkg/pkg-fetch.cli | 22 +++++++++++++ bpkg/pkg-fetch.cxx | 2 ++ bpkg/pkg-install.cli | 21 ++++++++++++ bpkg/pkg-purge.cli | 21 ++++++++++++ bpkg/pkg-status.cli | 21 ++++++++++++ bpkg/pkg-test.cli | 21 ++++++++++++ bpkg/pkg-uninstall.cli | 21 ++++++++++++ bpkg/pkg-unpack.cli | 22 +++++++++++++ bpkg/pkg-unpack.cxx | 2 ++ bpkg/pkg-update.cli | 21 ++++++++++++ bpkg/pkg-verify.cli | 14 ++++++++ bpkg/rep-add.cli | 21 ++++++++++++ bpkg/rep-create.cli | 21 ++++++++++++ bpkg/rep-create.cxx | 4 +++ bpkg/rep-fetch.cli | 21 ++++++++++++ bpkg/rep-info.cli | 23 +++++++++++++ bpkg/rep-info.cxx | 4 +++ bpkg/rep-list.cli | 21 ++++++++++++ bpkg/rep-remove.cli | 21 ++++++++++++ doc/buildfile | 3 +- doc/cli.sh | 5 +-- 35 files changed, 588 insertions(+), 8 deletions(-) create mode 100644 bpkg/default-options-files.cli diff --git a/bpkg/.gitignore b/bpkg/.gitignore index e2eadc4..4a212df 100644 --- a/bpkg/.gitignore +++ b/bpkg/.gitignore @@ -5,6 +5,7 @@ bpkg repository-signing.?xx repository-types.?xx argument-grouping.?xx +default-options-files.?xx version.hxx # Testscript output directory (can be symlink). diff --git a/bpkg/bpkg.cli b/bpkg/bpkg.cli index 573189c..37e25be 100644 --- a/bpkg/bpkg.cli +++ b/bpkg/bpkg.cli @@ -286,6 +286,11 @@ namespace bpkg "\l{bpkg-common-options(1)} \- details on common options" } + bool default-options-files + { + "\l{bpkg-default-options-files(1)} \- specifying default options" + } + bool repository-types { "\l{bpkg-repository-types(1)} \- repository types, structure, and URLs" diff --git a/bpkg/buildfile b/bpkg/buildfile index 5275437..ca3cdb9 100644 --- a/bpkg/buildfile +++ b/bpkg/buildfile @@ -42,7 +42,10 @@ rep-info-options \ rep-list-options \ rep-remove-options -help_topics = repository-signing repository-types argument-grouping +help_topics = repository-signing \ + repository-types \ + argument-grouping \ + default-options-files ./: exe{bpkg}: {hxx ixx txx cxx}{+bpkg} libue{bpkg} @@ -146,9 +149,10 @@ if $cli.configured # Help topics. # - cli.cxx{repository-signing}: cli{repository-signing} - cli.cxx{repository-types}: cli{repository-types} - cli.cxx{argument-grouping}: cli{argument-grouping} + cli.cxx{repository-signing}: cli{repository-signing} + cli.cxx{repository-types}: cli{repository-types} + cli.cxx{argument-grouping}: cli{argument-grouping} + cli.cxx{default-options-files}: cli{default-options-files} # Option length must be the same to get commands/topics/options aligned. # @@ -170,7 +174,8 @@ bpkg::pkg_build_pkg_options=exclude-base --generate-modifier # Avoid generating CLI runtime and empty inline file for help topics. # - cli.cxx{repository-signing repository-types argument-grouping}: \ + cli.cxx{repository-signing repository-types argument-grouping \ + default-options-files}: \ cli.options += --suppress-cli --suppress-inline # Include the generated cli files into the distribution and don't remove diff --git a/bpkg/cfg-create.cli b/bpkg/cfg-create.cli index 571c614..2bda017 100644 --- a/bpkg/cfg-create.cli +++ b/bpkg/cfg-create.cli @@ -79,4 +79,27 @@ namespace bpkg configuration directory explicitly with \cb{--directory|-d}." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bpkg-default-options-files(1)} for an overview of the default + options files. For the \cb{cfg-create} command the search start directory + is the parent directory of the new configuration. The following options + files are searched for in each directory and, if found, loaded in the + order listed: + + \ + bpkg.options + bpkg-cfg-create.options + \ + + The following \cb{cfg-create} command options cannot be specified in the + default options files: + + \ + --directory|-d + --wipe + \ + " } diff --git a/bpkg/cfg-create.cxx b/bpkg/cfg-create.cxx index affc0b0..4563374 100644 --- a/bpkg/cfg-create.cxx +++ b/bpkg/cfg-create.cxx @@ -175,6 +175,8 @@ namespace bpkg default_options_files options_files (const char*, const cfg_create_options& o, const strings&) { + // NOTE: remember to update the documentation if changing anything here. + // bpkg.options // bpkg-cfg-create.options @@ -198,6 +200,8 @@ namespace bpkg merge_options (const default_options& defs, const cfg_create_options& cmd) { + // NOTE: remember to update the documentation if changing anything here. + return merge_default_options ( defs, cmd, diff --git a/bpkg/default-options-files.cli b/bpkg/default-options-files.cli new file mode 100644 index 0000000..9b4af38 --- /dev/null +++ b/bpkg/default-options-files.cli @@ -0,0 +1,73 @@ +// file : bpkg/default-options-files.cli +// copyright : Copyright (c) 2014-2019 Code Synthesis Ltd +// license : MIT; see accompanying LICENSE file + +include ; + +"\section=1" +"\name=bpkg-default-options-files" +"\summary=specifying default options" + +{ + " ", + + " + \h|SYNOPSIS| + + \c{\b{bpkg} [] ...} + + \h|DESCRIPTION| + + Instead of having a separate config file format for tool configuration, the + \cb{build2} toolchain uses \i{default options files} which contain the same + options as what can be specified on the command line. The default options + files are like options files that one can specify with \cb{--options-file} + (\l{bpkg-common-options(1)}) except that they are loaded by default. + + The default options files are searched for in the \cb{.build2/} and + \cb{.build2/local/} subdirectories of each outer directory beginning from + the \i{start directory} and until reaching either the home directory or the + filesystem root directory (both excluding). Then in the \cb{.build2/} + subdirectory of the home directory and finally in the system directory (for + example, \cb{/etc/build2/}) if configured. + + Once the search is complete, the files are loaded in the reverse order, that + is, beginning from the system directory (if any), followed by the home + directory, ending with the start directory, and finishing off with the + options specified on the command line. In other words, the files are loaded + from the more generic to the more specific with the command line options + having the ability to override any values specified in the default options + files. + + The start directory, the names of the default options files, and in which + order they are loaded within each directory are determined by the + and potentially its . See each command's DEFAULT OPTIONS FILES + section for details. + + If a default options file contains \cb{--no-default-options}, then the + search is stopped at the directory containing this file and no outer files + are loaded. If this option is specified on the command line, then none of + the default options files are searched for or loaded. + + An additional directory containing default options files can be specified + with \cb{--default-options}. If such a directory is a subdirectory of the + start directory or is between the start directory and the end of the outer + search, then its configuration files are loaded at the corresponding point + in the directory hierarchy. Otherwise, they are loaded after the home + directory. + + The presence of the \cb{.git} filesystem entry causes the default options + files in this directory and any of its subdirectories to be considered + remote. Depending on the command, some security-sensitive options may be + disallowed or trigger a prompt when specified in remote options files (in + the current implementation this is the case even for files from the + \cb{.build2/local/} subdirectory since the mere location is not a sufficient + ground to definitively conclude that the file is not remote; to be sure we + would need to query the version control system). Note that additional + default options files specified with \cb{--default-options} are never + considered remote. + + The order in which default options files are loaded is traced at the + verbosity level 3 (\cb{-V} option) or higher. + " +} diff --git a/bpkg/help.cli b/bpkg/help.cli index f5fda42..4c87146 100644 --- a/bpkg/help.cli +++ b/bpkg/help.cli @@ -27,4 +27,18 @@ namespace bpkg { //"\h|HELP OPTIONS|" }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bpkg-default-options-files(1)} for an overview of the default + options files. For the \cb{help} command the following options files are + searched for only in the predefined directories (home, system, etc) and, if + found, loaded in the order listed: + + \ + bpkg.options + bpkg-help.options + \ + " } diff --git a/bpkg/help.cxx b/bpkg/help.cxx index 3946a5f..4b655f1 100644 --- a/bpkg/help.cxx +++ b/bpkg/help.cxx @@ -14,6 +14,7 @@ #include #include #include +#include using namespace std; using namespace butl; @@ -38,6 +39,8 @@ namespace bpkg usage = &print_bpkg_repository_types_usage; else if (t == "argument-grouping") usage = &print_bpkg_argument_grouping_usage; + else if (t == "default-options-files") + usage = &print_bpkg_default_options_files_usage; else fail << "unknown bpkg command/help topic '" << t << "'" << info << "run 'bpkg help' for more information"; diff --git a/bpkg/pkg-build.cli b/bpkg/pkg-build.cli index 0ac8dcb..d4a8841 100644 --- a/bpkg/pkg-build.cli +++ b/bpkg/pkg-build.cli @@ -296,4 +296,25 @@ namespace bpkg option in \l{bpkg-rep-fetch(1)} for details." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bpkg-default-options-files(1)} for an overview of the default + options files. For the \cb{pkg-build} command the search start + directory is the configuration directory. The following options files are + searched for in each directory and, if found, loaded in the order listed: + + \ + bpkg.options + bpkg-pkg-build.options + \ + + The following \cb{pkg-build} command options cannot be specified in the + default options files: + + \ + --directory|-d + \ + " } diff --git a/bpkg/pkg-checkout.cli b/bpkg/pkg-checkout.cli index 869aef0..509d88b 100644 --- a/bpkg/pkg-checkout.cli +++ b/bpkg/pkg-checkout.cli @@ -38,4 +38,25 @@ namespace bpkg unpacked." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bpkg-default-options-files(1)} for an overview of the default + options files. For the \cb{pkg-checkout} command the search start directory + is the configuration directory. The following options files are searched + for in each directory and, if found, loaded in the order listed: + + \ + bpkg.options + bpkg-pkg-checkout.options + \ + + The following \cb{pkg-checkout} command options cannot be specified in the + default options files: + + \ + --directory|-d + \ + " } diff --git a/bpkg/pkg-clean.cli b/bpkg/pkg-clean.cli index 78802af..4cdd0a2 100644 --- a/bpkg/pkg-clean.cli +++ b/bpkg/pkg-clean.cli @@ -42,4 +42,25 @@ namespace bpkg "Clean all held packages." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bpkg-default-options-files(1)} for an overview of the default + options files. For the \cb{pkg-clean} command the search start directory + is the configuration directory. The following options files are searched + for in each directory and, if found, loaded in the order listed: + + \ + bpkg.options + bpkg-pkg-clean.options + \ + + The following \cb{pkg-clean} command options cannot be specified in the + default options files: + + \ + --directory|-d + \ + " } diff --git a/bpkg/pkg-configure.cli b/bpkg/pkg-configure.cli index 0f51aa0..6908018 100644 --- a/bpkg/pkg-configure.cli +++ b/bpkg/pkg-configure.cli @@ -38,4 +38,25 @@ namespace bpkg { "\h|PKG-CONFIGURE OPTIONS|" }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bpkg-default-options-files(1)} for an overview of the default + options files. For the \cb{pkg-configure} command the search start + directory is the configuration directory. The following options files are + searched for in each directory and, if found, loaded in the order listed: + + \ + bpkg.options + bpkg-pkg-configure.options + \ + + The following \cb{pkg-configure} command options cannot be specified in the + default options files: + + \ + --directory|-d + \ + " } diff --git a/bpkg/pkg-disfigure.cli b/bpkg/pkg-disfigure.cli index db3b1d4..a97b68e 100644 --- a/bpkg/pkg-disfigure.cli +++ b/bpkg/pkg-disfigure.cli @@ -38,4 +38,25 @@ namespace bpkg "Don't clean the package's output directory." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bpkg-default-options-files(1)} for an overview of the default + options files. For the \cb{pkg-disfigure} command the search start + directory is the configuration directory. The following options files are + searched for in each directory and, if found, loaded in the order listed: + + \ + bpkg.options + bpkg-pkg-disfigure.options + \ + + The following \cb{pkg-disfigure} command options cannot be specified in the + default options files: + + \ + --directory|-d + \ + " } diff --git a/bpkg/pkg-drop.cli b/bpkg/pkg-drop.cli index 7002d57..298cafc 100644 --- a/bpkg/pkg-drop.cli +++ b/bpkg/pkg-drop.cli @@ -83,4 +83,25 @@ namespace bpkg
line (unless it is empty)." }; }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bpkg-default-options-files(1)} for an overview of the default + options files. For the \cb{pkg-drop} command the search start + directory is the configuration directory. The following options files are + searched for in each directory and, if found, loaded in the order listed: + + \ + bpkg.options + bpkg-pkg-drop.options + \ + + The following \cb{pkg-drop} command options cannot be specified in the + default options files: + + \ + --directory|-d + \ + " } diff --git a/bpkg/pkg-fetch.cli b/bpkg/pkg-fetch.cli index 1986627..8056c35 100644 --- a/bpkg/pkg-fetch.cli +++ b/bpkg/pkg-fetch.cli @@ -58,4 +58,26 @@ namespace bpkg "Remove the existing package archive when the package is purged." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bpkg-default-options-files(1)} for an overview of the default + options files. For the \cb{pkg-fetch} command the search start + directory is the configuration directory. The following options files are + searched for in each directory and, if found, loaded in the order listed: + + \ + bpkg.options + bpkg-pkg-fetch.options + \ + + The following \cb{pkg-fetch} command options cannot be specified in the + default options files: + + \ + --directory|-d + --purge|-p + \ + " } diff --git a/bpkg/pkg-fetch.cxx b/bpkg/pkg-fetch.cxx index b86ac85..0c880ac 100644 --- a/bpkg/pkg-fetch.cxx +++ b/bpkg/pkg-fetch.cxx @@ -351,6 +351,8 @@ namespace bpkg merge_options (const default_options& defs, const pkg_fetch_options& cmd) { + // NOTE: remember to update the documentation if changing anything here. + return merge_default_options ( defs, cmd, diff --git a/bpkg/pkg-install.cli b/bpkg/pkg-install.cli index 9caf48b..4f54a8f 100644 --- a/bpkg/pkg-install.cli +++ b/bpkg/pkg-install.cli @@ -65,4 +65,25 @@ namespace bpkg "Also install all dependencies, recursively." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bpkg-default-options-files(1)} for an overview of the default + options files. For the \cb{pkg-install} command the search start + directory is the configuration directory. The following options files are + searched for in each directory and, if found, loaded in the order listed: + + \ + bpkg.options + bpkg-pkg-install.options + \ + + The following \cb{pkg-install} command options cannot be specified in the + default options files: + + \ + --directory|-d + \ + " } diff --git a/bpkg/pkg-purge.cli b/bpkg/pkg-purge.cli index f4ae2eb..7128d0e 100644 --- a/bpkg/pkg-purge.cli +++ b/bpkg/pkg-purge.cli @@ -46,4 +46,25 @@ namespace bpkg package from the configuration." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bpkg-default-options-files(1)} for an overview of the default + options files. For the \cb{pkg-purge} command the search start + directory is the configuration directory. The following options files are + searched for in each directory and, if found, loaded in the order listed: + + \ + bpkg.options + bpkg-pkg-purge.options + \ + + The following \cb{pkg-purge} command options cannot be specified in the + default options files: + + \ + --directory|-d + \ + " } diff --git a/bpkg/pkg-status.cli b/bpkg/pkg-status.cli index 999e3c3..6d8dad8 100644 --- a/bpkg/pkg-status.cli +++ b/bpkg/pkg-status.cli @@ -194,4 +194,25 @@ namespace bpkg "Don't print the version hold status." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bpkg-default-options-files(1)} for an overview of the default + options files. For the \cb{pkg-status} command the search start + directory is the configuration directory. The following options files are + searched for in each directory and, if found, loaded in the order listed: + + \ + bpkg.options + bpkg-pkg-status.options + \ + + The following \cb{pkg-status} command options cannot be specified in the + default options files: + + \ + --directory|-d + \ + " } diff --git a/bpkg/pkg-test.cli b/bpkg/pkg-test.cli index afa05aa..6ccb8c1 100644 --- a/bpkg/pkg-test.cli +++ b/bpkg/pkg-test.cli @@ -55,4 +55,25 @@ namespace bpkg "Also test all dependencies, recursively." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bpkg-default-options-files(1)} for an overview of the default + options files. For the \cb{pkg-test} command the search start + directory is the configuration directory. The following options files are + searched for in each directory and, if found, loaded in the order listed: + + \ + bpkg.options + bpkg-pkg-test.options + \ + + The following \cb{pkg-test} command options cannot be specified in the + default options files: + + \ + --directory|-d + \ + " } diff --git a/bpkg/pkg-uninstall.cli b/bpkg/pkg-uninstall.cli index 6c17866..d36a8e8 100644 --- a/bpkg/pkg-uninstall.cli +++ b/bpkg/pkg-uninstall.cli @@ -56,4 +56,25 @@ namespace bpkg "Also uninstall all dependencies, recursively." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bpkg-default-options-files(1)} for an overview of the default + options files. For the \cb{pkg-uninstall} command the search start + directory is the configuration directory. The following options files are + searched for in each directory and, if found, loaded in the order listed: + + \ + bpkg.options + bpkg-pkg-uninstall.options + \ + + The following \cb{pkg-uninstall} command options cannot be specified in the + default options files: + + \ + --directory|-d + \ + " } diff --git a/bpkg/pkg-unpack.cli b/bpkg/pkg-unpack.cli index c2ec3ea..bafab7e 100644 --- a/bpkg/pkg-unpack.cli +++ b/bpkg/pkg-unpack.cli @@ -74,4 +74,26 @@ namespace bpkg fetched. Can only be specified with an external package." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bpkg-default-options-files(1)} for an overview of the default + options files. For the \cb{pkg-unpack} command the search start + directory is the configuration directory. The following options files are + searched for in each directory and, if found, loaded in the order listed: + + \ + bpkg.options + bpkg-pkg-unpack.options + \ + + The following \cb{pkg-unpack} command options cannot be specified in the + default options files: + + \ + --directory|-d + --purge|-p + \ + " } diff --git a/bpkg/pkg-unpack.cxx b/bpkg/pkg-unpack.cxx index 801496d..7727535 100644 --- a/bpkg/pkg-unpack.cxx +++ b/bpkg/pkg-unpack.cxx @@ -433,6 +433,8 @@ namespace bpkg merge_options (const default_options& defs, const pkg_unpack_options& cmd) { + // NOTE: remember to update the documentation if changing anything here. + return merge_default_options ( defs, cmd, diff --git a/bpkg/pkg-update.cli b/bpkg/pkg-update.cli index 9eb98b8..57e46ad 100644 --- a/bpkg/pkg-update.cli +++ b/bpkg/pkg-update.cli @@ -52,4 +52,25 @@ namespace bpkg \cb{install} or \cb{test}." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bpkg-default-options-files(1)} for an overview of the default + options files. For the \cb{pkg-update} command the search start + directory is the configuration directory. The following options files are + searched for in each directory and, if found, loaded in the order listed: + + \ + bpkg.options + bpkg-pkg-update.options + \ + + The following \cb{pkg-update} command options cannot be specified in the + default options files: + + \ + --directory|-d + \ + " } diff --git a/bpkg/pkg-verify.cli b/bpkg/pkg-verify.cli index 0546695..49714a0 100644 --- a/bpkg/pkg-verify.cli +++ b/bpkg/pkg-verify.cli @@ -59,4 +59,18 @@ namespace bpkg files and the package dependency constraints are completed." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bpkg-default-options-files(1)} for an overview of the default + options files. For the \cb{pkg-verify} command the following options files + are searched for in the predefined directories (system, etc) and, if found, + loaded in the order listed: + + \ + bpkg.options + bpkg-pkg-verify.options + \ + " } diff --git a/bpkg/rep-add.cli b/bpkg/rep-add.cli index 3bfd537..f9a91fa 100644 --- a/bpkg/rep-add.cli +++ b/bpkg/rep-add.cli @@ -57,4 +57,25 @@ namespace bpkg and \cb{git}." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bpkg-default-options-files(1)} for an overview of the default + options files. For the \cb{rep-add} command the search start + directory is the configuration directory. The following options files are + searched for in each directory and, if found, loaded in the order listed: + + \ + bpkg.options + bpkg-rep-add.options + \ + + The following \cb{rep-add} command options cannot be specified in the + default options files: + + \ + --directory|-d + \ + " } diff --git a/bpkg/rep-create.cli b/bpkg/rep-create.cli index 006cf56..557d941 100644 --- a/bpkg/rep-create.cli +++ b/bpkg/rep-create.cli @@ -45,4 +45,25 @@ namespace bpkg \cb{openssl} cryptographic engine is used." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bpkg-default-options-files(1)} for an overview of the default + options files. For the \cb{rep-create} command the search start + directory is the repository directory. The following options files are + searched for in each directory and, if found, loaded in the order listed: + + \ + bpkg.options + bpkg-rep-create.options + \ + + The following \cb{rep-create} command options cannot be specified in the + remote default options files: + + \ + --key + \ + " } diff --git a/bpkg/rep-create.cxx b/bpkg/rep-create.cxx index 98bf7f8..12bc6e5 100644 --- a/bpkg/rep-create.cxx +++ b/bpkg/rep-create.cxx @@ -260,6 +260,8 @@ namespace bpkg default_options_files options_files (const char*, const rep_create_options&, const strings& args) { + // NOTE: remember to update the documentation if changing anything here. + // bpkg.options // bpkg-rep-create.options @@ -286,6 +288,8 @@ namespace bpkg merge_options (const default_options& defs, const rep_create_options& cmd) { + // NOTE: remember to update the documentation if changing anything here. + return merge_default_options ( defs, cmd, diff --git a/bpkg/rep-fetch.cli b/bpkg/rep-fetch.cli index 6c564e7..c9ac510 100644 --- a/bpkg/rep-fetch.cli +++ b/bpkg/rep-fetch.cli @@ -47,4 +47,25 @@ namespace bpkg prerequisites has changed." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bpkg-default-options-files(1)} for an overview of the default + options files. For the \cb{rep-fetch} command the search start + directory is the configuration directory. The following options files are + searched for in each directory and, if found, loaded in the order listed: + + \ + bpkg.options + bpkg-rep-fetch.options + \ + + The following \cb{rep-fetch} command options cannot be specified in the + default options files: + + \ + --directory|-d + \ + " } diff --git a/bpkg/rep-info.cli b/bpkg/rep-info.cli index 916209f..9cecd3d 100644 --- a/bpkg/rep-info.cli +++ b/bpkg/rep-info.cli @@ -128,4 +128,27 @@ namespace bpkg "Use configuration in for the trusted certificate database." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bpkg-default-options-files(1)} for an overview of the default + options files. If the \cb{rep-info} command uses an existing \c{bpkg} + configuration, then the start directory is the configuration directory. + Otherwise, only the predefined directories (home, system, etc) are + searched. The following options files are searched for in each directory + and, if found, loaded in the order listed: + + \ + bpkg.options + bpkg-rep-info.options + \ + + The following \cb{rep-info} command options cannot be specified in the + default options files: + + \ + --directory|-d + \ + " } diff --git a/bpkg/rep-info.cxx b/bpkg/rep-info.cxx index 086a142..b90ace8 100644 --- a/bpkg/rep-info.cxx +++ b/bpkg/rep-info.cxx @@ -378,6 +378,8 @@ namespace bpkg default_options_files options_files (const char*, const rep_info_options& o, const strings&) { + // NOTE: remember to update the documentation if changing anything here. + // bpkg.options // bpkg-rep-info.options @@ -411,6 +413,8 @@ namespace bpkg merge_options (const default_options& defs, const rep_info_options& cmd) { + // NOTE: remember to update the documentation if changing anything here. + return merge_default_options ( defs, cmd, diff --git a/bpkg/rep-list.cli b/bpkg/rep-list.cli index 44241fd..59d6f09 100644 --- a/bpkg/rep-list.cli +++ b/bpkg/rep-list.cli @@ -43,4 +43,25 @@ namespace bpkg "List prerequisite repositories." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bpkg-default-options-files(1)} for an overview of the default + options files. For the \cb{rep-list} command the search start + directory is the configuration directory. The following options files are + searched for in each directory and, if found, loaded in the order listed: + + \ + bpkg.options + bpkg-rep-list.options + \ + + The following \cb{rep-list} command options cannot be specified in the + default options files: + + \ + --directory|-d + \ + " } diff --git a/bpkg/rep-remove.cli b/bpkg/rep-remove.cli index de92271..aea0571 100644 --- a/bpkg/rep-remove.cli +++ b/bpkg/rep-remove.cli @@ -52,4 +52,25 @@ namespace bpkg "Clean the repository state." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bpkg-default-options-files(1)} for an overview of the default + options files. For the \cb{pkg-rep-remove} command the search start + directory is the configuration directory. The following options files are + searched for in each directory and, if found, loaded in the order listed: + + \ + bpkg.options + bpkg-rep-remove.options + \ + + The following \cb{rep-remove} command options cannot be specified in the + default options files: + + \ + --directory|-d + \ + " } diff --git a/doc/buildfile b/doc/buildfile index d1e80b2..6d3097d 100644 --- a/doc/buildfile +++ b/doc/buildfile @@ -34,7 +34,8 @@ define xhtml: doc xhtml{*}: extension = xhtml ./: {man1 xhtml}{bpkg bpkg-common-options bpkg-repository-signing \ - bpkg-repository-types bpkg-argument-grouping $cmds} \ + bpkg-repository-types bpkg-argument-grouping \ + bpkg-default-options-files $cmds} \ css{common pre-box man} \ file{man-*} diff --git a/doc/cli.sh b/doc/cli.sh index 7ad18f4..47601ad 100755 --- a/doc/cli.sh +++ b/doc/cli.sh @@ -61,13 +61,14 @@ compile "bpkg" $o --output-prefix "" --suppress-undocumented --class-doc bpkg::c compile "pkg-build" $o --class-doc bpkg::pkg_build_pkg_options=exclude-base -# NOTE: remember to update a similar list in buildfile. +# NOTE: remember to update a similar list in buildfile and bpkg.cli as well as +# the help topics sections in bpkg/buildfile and help.cxx. # pages="cfg-create help pkg-clean pkg-configure pkg-disfigure \ pkg-drop pkg-fetch pkg-checkout pkg-install pkg-purge pkg-status pkg-test \ pkg-uninstall pkg-unpack pkg-update pkg-verify rep-add rep-remove rep-list \ rep-create rep-fetch rep-info repository-signing repository-types \ -argument-grouping" +argument-grouping default-options-files" for p in $pages; do compile $p $o -- cgit v1.1