diff options
Diffstat (limited to 'bdep/default-options-files.cxx')
| -rw-r--r-- | bdep/default-options-files.cxx | 91 |
1 files changed, 91 insertions, 0 deletions
diff --git a/bdep/default-options-files.cxx b/bdep/default-options-files.cxx new file mode 100644 index 0000000..b18acd9 --- /dev/null +++ b/bdep/default-options-files.cxx @@ -0,0 +1,91 @@ +// -*- C++ -*- +// +// This file was generated by CLI, a command line interface +// compiler for C++. +// + +// Begin prologue. +// +#include <bdep/types-parsers.hxx> +// +// End prologue. + +#include <bdep/default-options-files.hxx> + +#include <map> + +namespace bdep +{ + ::bdep::cli::usage_para + print_bdep_default_options_files_usage (::std::ostream& os, ::bdep::cli::usage_para p) + { + CLI_POTENTIALLY_UNUSED (os); + + if (p != ::bdep::cli::usage_para::none) + os << ::std::endl; + + os << "\033[1mSYNOPSIS\033[0m" << ::std::endl + << ::std::endl + << "\033[1mbdep\033[0m \033[4mcommand\033[0m [\033[4mmode-options\033[0m] ...\033[0m" << ::std::endl + << ::std::endl + << "\033[1mDESCRIPTION\033[0m" << ::std::endl + << ::std::endl + << "Instead of having a separate config file format for tool configuration, the" << ::std::endl + << "\033[1mbuild2\033[0m toolchain uses \033[4mdefault options files\033[0m which contain the same options as" << ::std::endl + << "what can be specified on the command line. The default options files are like" << ::std::endl + << "options files that one can specify with \033[1m--options-file\033[0m (\033[1mbdep-common-options(1)\033[0m)" << ::std::endl + << "except that they are loaded by default." << ::std::endl + << ::std::endl + << "The default options files are searched for in the \033[1m.build2/\033[0m and \033[1m.build2/local/\033[0m" << ::std::endl + << "subdirectories of each outer directory beginning from the \033[4mstart directory\033[0m and" << ::std::endl + << "until reaching either the home directory or the filesystem root directory (both" << ::std::endl + << "excluding). Then in the \033[1m.build2/\033[0m subdirectory of the home directory and finally" << ::std::endl + << "in the system directory (for example, \033[1m/etc/build2/\033[0m) if configured." << ::std::endl + << ::std::endl + << "Once the search is complete, the files are loaded in the reverse order, that" << ::std::endl + << "is, beginning from the system directory (if any), followed by the home" << ::std::endl + << "directory, ending with the start directory, and finishing off with the options" << ::std::endl + << "specified on the command line. In other words, the files are loaded from the" << ::std::endl + << "more generic to the more specific with the command line options having the" << ::std::endl + << "ability to override any values specified in the default options files." << ::std::endl + << ::std::endl + << "The start directory, the names of the default options files, and in which order" << ::std::endl + << "they are loaded within each directory are determined by the \033[4mcommand\033[0m and" << ::std::endl + << "potentially its \033[4mmode-options\033[0m. See each command's DEFAULT OPTIONS FILES section" << ::std::endl + << "for details." << ::std::endl + << ::std::endl + << "If a default options file contains \033[1m--no-default-options\033[0m, then the search is" << ::std::endl + << "stopped at the directory containing this file and no outer files are loaded. If" << ::std::endl + << "this option is specified on the command line, then none of the default options" << ::std::endl + << "files are searched for or loaded." << ::std::endl + << ::std::endl + << "An additional directory containing default options files can be specified with" << ::std::endl + << "\033[1m--default-options\033[0m. If such a directory is a subdirectory of the start directory" << ::std::endl + << "or is between the start directory and the end of the outer search, then its" << ::std::endl + << "configuration files are loaded at the corresponding point in the directory" << ::std::endl + << "hierarchy. Otherwise, they are loaded after the home directory." << ::std::endl + << ::std::endl + << "The presence of the \033[1m.git\033[0m filesystem entry causes the default options files in" << ::std::endl + << "this directory and any of its subdirectories to be considered remote. Depending" << ::std::endl + << "on the command, some security-sensitive options may be disallowed or trigger a" << ::std::endl + << "prompt when specified in remote options files (in the current implementation" << ::std::endl + << "this is the case even for files from the \033[1m.build2/local/\033[0m subdirectory since the" << ::std::endl + << "mere location is not a sufficient ground to definitively conclude that the file" << ::std::endl + << "is not remote; to be sure we would need to query the version control system)." << ::std::endl + << "Note that additional default options files specified with \033[1m--default-options\033[0m are" << ::std::endl + << "never considered remote." << ::std::endl + << ::std::endl + << "The order in which default options files are loaded is traced at the verbosity" << ::std::endl + << "level 3 (\033[1m-V\033[0m option) or higher." << ::std::endl; + + p = ::bdep::cli::usage_para::text; + + return p; + } +} + +// Begin epilogue. +// +// +// End epilogue. + |