aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKaren Arutyunov <karen@codesynthesis.com>2019-10-30 16:56:24 +0300
committerKaren Arutyunov <karen@codesynthesis.com>2019-10-31 17:49:58 +0300
commit7d03940f6816329fa9ae131591717749bc76be5a (patch)
tree4bd95c2c08261cb67a4b21a9040645de902e2925
parentdad48d98b1a57706179c34853950588ec75a8467 (diff)
Document default options files for commands
-rw-r--r--bpkg/.gitignore1
-rw-r--r--bpkg/bpkg.cli5
-rw-r--r--bpkg/buildfile15
-rw-r--r--bpkg/cfg-create.cli23
-rw-r--r--bpkg/cfg-create.cxx4
-rw-r--r--bpkg/default-options-files.cli73
-rw-r--r--bpkg/help.cli14
-rw-r--r--bpkg/help.cxx3
-rw-r--r--bpkg/pkg-build.cli21
-rw-r--r--bpkg/pkg-checkout.cli21
-rw-r--r--bpkg/pkg-clean.cli21
-rw-r--r--bpkg/pkg-configure.cli21
-rw-r--r--bpkg/pkg-disfigure.cli21
-rw-r--r--bpkg/pkg-drop.cli21
-rw-r--r--bpkg/pkg-fetch.cli22
-rw-r--r--bpkg/pkg-fetch.cxx2
-rw-r--r--bpkg/pkg-install.cli21
-rw-r--r--bpkg/pkg-purge.cli21
-rw-r--r--bpkg/pkg-status.cli21
-rw-r--r--bpkg/pkg-test.cli21
-rw-r--r--bpkg/pkg-uninstall.cli21
-rw-r--r--bpkg/pkg-unpack.cli22
-rw-r--r--bpkg/pkg-unpack.cxx2
-rw-r--r--bpkg/pkg-update.cli21
-rw-r--r--bpkg/pkg-verify.cli14
-rw-r--r--bpkg/rep-add.cli21
-rw-r--r--bpkg/rep-create.cli21
-rw-r--r--bpkg/rep-create.cxx4
-rw-r--r--bpkg/rep-fetch.cli21
-rw-r--r--bpkg/rep-info.cli23
-rw-r--r--bpkg/rep-info.cxx4
-rw-r--r--bpkg/rep-list.cli21
-rw-r--r--bpkg/rep-remove.cli21
-rw-r--r--doc/buildfile3
-rwxr-xr-xdoc/cli.sh5
35 files changed, 588 insertions, 8 deletions
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<cfg_create_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 <bpkg/common-options.hxx>;
+
+"\section=1"
+"\name=bpkg-default-options-files"
+"\summary=specifying default options"
+
+{
+ "<command> <mode-options>",
+
+ "
+ \h|SYNOPSIS|
+
+ \c{\b{bpkg} <command> [<mode-options>] ...}
+
+ \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 <command>
+ and potentially its <mode-options>. 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 <bpkg/repository-signing.hxx>
#include <bpkg/repository-types.hxx>
#include <bpkg/argument-grouping.hxx>
+#include <bpkg/default-options-files.hxx>
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
<header> 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<pkg_fetch_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<pkg_unpack_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<rep_create_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 <dir> 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<rep_info_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