aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--bdep/bdep.cli5
-rw-r--r--bdep/default-options-files.cli73
-rw-r--r--doc/buildfile5
-rwxr-xr-xdoc/cli.sh4
4 files changed, 83 insertions, 4 deletions
diff --git a/bdep/bdep.cli b/bdep/bdep.cli
index b324612..f0d13c0 100644
--- a/bdep/bdep.cli
+++ b/bdep/bdep.cli
@@ -495,6 +495,11 @@ namespace bdep
"\l{bdep-common-options(1)} \- details on common options"
}
+ bool default-options-files
+ {
+ "\l{bdep-default-options-files(1)} \- specifying default options"
+ }
+
bool projects-configs
{
"\l{bdep-projects-configs(1)} \- specifying projects and configurations"
diff --git a/bdep/default-options-files.cli b/bdep/default-options-files.cli
new file mode 100644
index 0000000..0ec9b68
--- /dev/null
+++ b/bdep/default-options-files.cli
@@ -0,0 +1,73 @@
+// file : bdep/default-options-files.cli
+// copyright : Copyright (c) 2014-2019 Code Synthesis Ltd
+// license : MIT; see accompanying LICENSE file
+
+include <bdep/common-options.hxx>;
+
+"\section=1"
+"\name=bdep-default-options-files"
+"\summary=specifying default options"
+
+{
+ "<command> <mode-options>",
+
+ "
+ \h|SYNOPSIS|
+
+ \c{\b{bdep} <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{bdep-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/doc/buildfile b/doc/buildfile
index 2e31fc0..564ed7a 100644
--- a/doc/buildfile
+++ b/doc/buildfile
@@ -25,8 +25,9 @@ css{*}: extension = css
define xhtml: doc
xhtml{*}: extension = xhtml
-./: {man1 xhtml}{bdep bdep-common-options bdep-projects-configs $cmds} \
- css{common pre-box man} \
+./: {man1 xhtml}{bdep bdep-common-options bdep-projects-configs \
+ default-options-files $cmds} \
+ css{common pre-box man} \
file{man-*}
./: file{cli.sh}
diff --git a/doc/cli.sh b/doc/cli.sh
index a826523..3ba95b9 100755
--- a/doc/cli.sh
+++ b/doc/cli.sh
@@ -63,10 +63,10 @@ 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
-# NOTE: remember to update a similar list in buildfile.
+# NOTE: remember to update a similar list in buildfile as well as in bdep.cli.
#
pages="new help init sync fetch status ci release publish deinit config test \
-update clean projects-configs"
+update clean projects-configs default-options-files"
for p in $pages; do
compile $p $o