Add bdep-default-options-files(1) help topic

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