From d268ff193e240751485bb6ff01268d45c21548ed Mon Sep 17 00:00:00 2001 From: Karen Arutyunov Date: Wed, 30 Oct 2019 14:19:56 +0300 Subject: Document default options files for remaining commands --- bdep/.gitignore | 1 + bdep/buildfile | 8 +++++--- bdep/ci.cli | 21 +++++++++++++++++++ bdep/clean.cli | 21 +++++++++++++++++++ bdep/config.cli | 25 +++++++++++++++++++++++ bdep/config.cxx | 4 ++++ bdep/deinit.cli | 21 +++++++++++++++++++ bdep/fetch.cli | 21 +++++++++++++++++++ bdep/help.cli | 14 +++++++++++++ bdep/help.cxx | 3 +++ bdep/init.cli | 26 ++++++++++++++++++++++++ bdep/init.cxx | 4 ++++ bdep/new.cli | 62 ++++++++++++++++++++++++++++---------------------------- bdep/publish.cli | 23 ++++++++++++++++++++- bdep/release.cli | 25 +++++++++++++++++++++++ bdep/release.cxx | 6 +++++- bdep/status.cli | 21 +++++++++++++++++++ bdep/sync.cli | 27 +++++++++++++++++++++++- bdep/sync.cxx | 4 ++++ bdep/test.cli | 21 +++++++++++++++++++ bdep/update.cli | 21 +++++++++++++++++++ doc/cli.sh | 3 ++- 22 files changed, 344 insertions(+), 38 deletions(-) diff --git a/bdep/.gitignore b/bdep/.gitignore index 97e4d6d..b8da6c9 100644 --- a/bdep/.gitignore +++ b/bdep/.gitignore @@ -3,6 +3,7 @@ bdep *-odb.?xx *-options.?xx projects-configs.?xx +default-options-files.?xx version.hxx # Testscript output directory (can be symlink). diff --git a/bdep/buildfile b/bdep/buildfile index 7a14c51..7828fa6 100644 --- a/bdep/buildfile +++ b/bdep/buildfile @@ -36,7 +36,7 @@ test-options \ update-options \ clean-options -help_topics = projects-configs +help_topics = projects-configs default-options-files ./: exe{bdep}: {hxx ixx txx cxx}{+bdep} libue{bdep} @@ -125,7 +125,8 @@ if $cli.configured # Help topics. # - cli.cxx{projects-configs}: cli{projects-configs} + cli.cxx{projects-configs}: cli{projects-configs} + cli.cxx{default-options-files}: cli{default-options-files} # Option length must be the same to get commands/topics/options aligned. # @@ -153,7 +154,8 @@ if $cli.configured # Avoid generating CLI runtime and empty inline file for help topics. # - cli.cxx{projects-configs}: cli.options += --suppress-cli --suppress-inline + cli.cxx{projects-configs}: cli.options += --suppress-cli --suppress-inline + cli.cxx{default-options-files}: cli.options += --suppress-cli --suppress-inline # Include the generated cli files into the distribution and don't remove # them when cleaning in src (so that clean results in a state identical to diff --git a/bdep/ci.cli b/bdep/ci.cli index ccf6ed3..ed51f01 100644 --- a/bdep/ci.cli +++ b/bdep/ci.cli @@ -157,4 +157,25 @@ namespace bdep documentation." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bdep-default-options-files(1)} for an overview of the default + options files. For the \cb{ci} command the search start directory is + the project directory. The following options files are searched for in + each directory and, if found, loaded in the order listed: + + \ + bdep.options + bdep-ci.options + \ + + The following \cb{ci} command options cannot be specified in the + default options files: + + \ + --directory|-d + \ + " } diff --git a/bdep/clean.cli b/bdep/clean.cli index 999722f..24460df 100644 --- a/bdep/clean.cli +++ b/bdep/clean.cli @@ -46,4 +46,25 @@ namespace bdep { "\h|CLEAN OPTIONS|" }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bdep-default-options-files(1)} for an overview of the default + options files. For the \cb{clean} command the search start directory is + the project directory. The following options files are searched for in + each directory and, if found, loaded in the order listed: + + \ + bdep.options + bdep-clean.options + \ + + The following \cb{clean} command options cannot be specified in the + default options files: + + \ + --directory|-d + \ + " } diff --git a/bdep/config.cli b/bdep/config.cli index 818f600..5481bae 100644 --- a/bdep/config.cli +++ b/bdep/config.cli @@ -164,4 +164,29 @@ namespace bdep { "\h|CONFIG OPTIONS|" }; + + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bdep-default-options-files(1)} for an overview of the default + options files. For the \cb{config} command the search start directory is + the project directory. The following options files are searched for in + each directory and, if found, loaded in the order listed: + + \ + bdep.options + bdep-config.options + bdep-config-add.options # if the create subcommand + bdep-config-.options # (subcommand-dependent) + \ + + The following \cb{config} command options cannot be specified in the + default options files: + + \ + --directory|-d + --wipe + \ + " } diff --git a/bdep/config.cxx b/bdep/config.cxx index f08bd41..ee5f9df 100644 --- a/bdep/config.cxx +++ b/bdep/config.cxx @@ -799,6 +799,8 @@ namespace bdep const cmd_config_options& o, const strings& args) { + // NOTE: remember to update the documentation if changing anything here. + // bdep.options // bdep-config.options // bdep-config-.options @@ -841,6 +843,8 @@ namespace bdep merge_options (const default_options& defs, const cmd_config_options& cmd) { + // NOTE: remember to update the documentation if changing anything here. + return merge_default_options ( defs, cmd, diff --git a/bdep/deinit.cli b/bdep/deinit.cli index ad7e626..cd14fec 100644 --- a/bdep/deinit.cli +++ b/bdep/deinit.cli @@ -49,4 +49,25 @@ namespace bdep directory has been removed or is otherwise unusable." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bdep-default-options-files(1)} for an overview of the default + options files. For the \cb{deinit} command the search start directory is + the project directory. The following options files are searched for in + each directory and, if found, loaded in the order listed: + + \ + bdep.options + bdep-deinit.options + \ + + The following \cb{deinit} command options cannot be specified in the + default options files: + + \ + --directory|-d + \ + " } diff --git a/bdep/fetch.cli b/bdep/fetch.cli index acbb360..7d4d001 100644 --- a/bdep/fetch.cli +++ b/bdep/fetch.cli @@ -50,4 +50,25 @@ namespace bdep "Perform a full re-fetch of all the repositories." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bdep-default-options-files(1)} for an overview of the default + options files. For the \cb{fetch} command the search start directory is + the project directory. The following options files are searched for in + each directory and, if found, loaded in the order listed: + + \ + bdep.options + bdep-fetch.options + \ + + The following \cb{fetch} command options cannot be specified in the + default options files: + + \ + --directory|-d + \ + " } diff --git a/bdep/help.cli b/bdep/help.cli index 238a730..c6aa1ab 100644 --- a/bdep/help.cli +++ b/bdep/help.cli @@ -27,4 +27,18 @@ namespace bdep { //"\h|HELP OPTIONS|" }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bdep-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: + + \ + bdep.options + bdep-help.options + \ + " } diff --git a/bdep/help.cxx b/bdep/help.cxx index fe64c2a..4175b89 100644 --- a/bdep/help.cxx +++ b/bdep/help.cxx @@ -12,6 +12,7 @@ // Help topics. // #include +#include using namespace std; using namespace butl; @@ -32,6 +33,8 @@ namespace bdep usage = &print_bdep_common_options_long_usage; else if (t == "projects-configs") usage = &print_bdep_projects_configs_usage; + else if (t == "default-options-files") + usage = &print_bdep_default_options_files_usage; else fail << "unknown bdep command/help topic '" << t << "'" << info << "run 'bdep help' for more information"; diff --git a/bdep/init.cli b/bdep/init.cli index 5071913..32024eb 100644 --- a/bdep/init.cli +++ b/bdep/init.cli @@ -174,4 +174,30 @@ namespace bdep an explicit \l{bdep-sync(1)} command." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bdep-default-options-files(1)} for an overview of the default + options files. For the \cb{init} command the search start directory is the + project directory. The following options files are searched for in each + directory and, if found, loaded in the order listed: + + \ + bdep.options + bdep-{config config-add}.options # if --config-add|-A + bdep-{config config-add config-create}.options # if --config-create|-C + bdep-init.options + \ + + The following \cb{init} command options cannot be specified in the + default options files: + + \ + --directory|-d + --config-add|-A + --config-create|-C + --wipe + \ + " } diff --git a/bdep/init.cxx b/bdep/init.cxx index 86f570f..5bc6a72 100644 --- a/bdep/init.cxx +++ b/bdep/init.cxx @@ -278,6 +278,8 @@ namespace bdep default_options_files options_files (const char*, const cmd_init_options& o, const strings&) { + // NOTE: remember to update the documentation if changing anything here. + // bdep.options // bdep-{config config-add}.options # -A // bdep-{config config-add config-create}.options # -C @@ -308,6 +310,8 @@ namespace bdep merge_options (const default_options& defs, const cmd_init_options& cmd) { + // NOTE: remember to update the documentation if changing anything here. + return merge_default_options ( defs, cmd, diff --git a/bdep/new.cli b/bdep/new.cli index e338683..259a4df 100644 --- a/bdep/new.cli +++ b/bdep/new.cli @@ -575,37 +575,37 @@ namespace bdep " \h|DEFAULT OPTIONS FILES| - See \l{bdep-default-options-files(1)} for an overview of the default - options files. For the \cb{new} command the search start directory is the - project directory in the package and subdirectory modes and the parent - directory of the new project in all other modes. The following options - files are searched for in each directory and, if found, loaded in the - order listed: - - \ - bdep.options - bdep-{config config-add}.options # if --config-add|-A - bdep-{config config-add config-create}.options # if --config-create|-C - bdep-new.options - bdep-new-{project|package|subdirectory}.options # (mode-dependent) - \ - - The following \cb{new} command options cannot be specified in the - default options files: - - \ - --output-dir|-o - --directory|-d - --package - --subdirectory - --no-checks - --config-add|-A - --config-create|-C - --wipe - \ - - While the presence of the \cb{--pre-hook} or \cb{--post-hook} options in - remote default options files will trigger a prompt. + See \l{bdep-default-options-files(1)} for an overview of the default + options files. For the \cb{new} command the search start directory is the + project directory in the package and subdirectory modes and the parent + directory of the new project in all other modes. The following options + files are searched for in each directory and, if found, loaded in the + order listed: + + \ + bdep.options + bdep-{config config-add}.options # if --config-add|-A + bdep-{config config-add config-create}.options # if --config-create|-C + bdep-new.options + bdep-new-{project|package|subdirectory}.options # (mode-dependent) + \ + + The following \cb{new} command options cannot be specified in the + default options files: + + \ + --output-dir|-o + --directory|-d + --package + --subdirectory + --no-checks + --config-add|-A + --config-create|-C + --wipe + \ + + While the presence of the \cb{--pre-hook} or \cb{--post-hook} options in + remote default options files will trigger a prompt. \h|ENVIRONMENT| diff --git a/bdep/publish.cli b/bdep/publish.cli index 1d3771c..0a3eafb 100644 --- a/bdep/publish.cli +++ b/bdep/publish.cli @@ -151,7 +151,28 @@ namespace bdep } }; - "\h|ENVIRONMENT| + " + \h|DEFAULT OPTIONS FILES| + + See \l{bdep-default-options-files(1)} for an overview of the default + options files. For the \cb{publish} command the search start directory is + the project directory. The following options files are searched for in + each directory and, if found, loaded in the order listed: + + \ + bdep.options + bdep-publish.options + \ + + The following \cb{publish} command options cannot be specified in the + default options files: + + \ + --directory|-d + \ + + + \h|ENVIRONMENT| The \cb{BDEP_AUTHOR_NAME} and \cb{BDEP_AUTHOR_EMAIL} environment variables can be used to specify the publisher's name and email address, diff --git a/bdep/release.cli b/bdep/release.cli index b20edb1..44d339a 100644 --- a/bdep/release.cli +++ b/bdep/release.cli @@ -237,4 +237,29 @@ namespace bdep current working directory." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bdep-default-options-files(1)} for an overview of the default + options files. For the \cb{release} command the search start directory is + the project directory. The following options files are searched for in + each directory and, if found, loaded in the order listed: + + \ + bdep.options + bdep-release.options + bdep-release-{version|revision|open|tag}.options # (mode-dependent) + \ + + The following \cb{release} command options cannot be specified in the + default options files: + + \ + --directory|-d + --revision + --open + --tag + \ + " } diff --git a/bdep/release.cxx b/bdep/release.cxx index 08cc61e..abb3784 100644 --- a/bdep/release.cxx +++ b/bdep/release.cxx @@ -1321,9 +1321,11 @@ namespace bdep default_options_files options_files (const char*, const cmd_release_options& o, const strings&) { + // NOTE: remember to update the documentation if changing anything here. + // bdep.options // bdep-release.options - // bdep-release{version|revision|open|tag}.options + // bdep-release-{version|revision|open|tag}.options default_options_files r { {path ("bdep.options"), path ("bdep-release.options")}, @@ -1343,6 +1345,8 @@ namespace bdep merge_options (const default_options& defs, const cmd_release_options& cmd) { + // NOTE: remember to update the documentation if changing anything here. + return merge_default_options ( defs, cmd, diff --git a/bdep/status.cli b/bdep/status.cli index 422dbe6..8960277 100644 --- a/bdep/status.cli +++ b/bdep/status.cli @@ -79,4 +79,25 @@ namespace bdep "Perform the \cb{fetch --full} command prior to printing the status." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bdep-default-options-files(1)} for an overview of the default + options files. For the \cb{status} command the search start directory is + the project directory. The following options files are searched for in + each directory and, if found, loaded in the order listed: + + \ + bdep.options + bdep-status.options + \ + + The following \cb{status} command options cannot be specified in the + default options files: + + \ + --directory|-d + \ + " } diff --git a/bdep/sync.cli b/bdep/sync.cli index 04b8330..f4afc85 100644 --- a/bdep/sync.cli +++ b/bdep/sync.cli @@ -222,7 +222,32 @@ namespace bdep uint16_t --hook = 0; }; - "\h|ENVIRONMENT| + " + \h|DEFAULT OPTIONS FILES| + + See \l{bdep-default-options-files(1)} for an overview of the default + options files. For the \cb{sync} command the search start directory is the + project directory, except for the implicit mode for which only the + predefined directories (system, etc) are searched in. The following options + files are searched for in each directory and, if found, loaded in the order + listed: + + \ + bdep.options + bdep-{sync|sync-implicit}.options # (mode-dependent) + \ + + The following \cb{sync} command options cannot be specified in the + default options files: + + \ + --directory|-d + --implicit + --config|-c + \ + + + \h|ENVIRONMENT| The \cb{BDEP_SYNC} environment variable can be used to suppress automatic synchronization on build system invocation. If set, auto-synchronization diff --git a/bdep/sync.cxx b/bdep/sync.cxx index 1ed3c12..4084572 100644 --- a/bdep/sync.cxx +++ b/bdep/sync.cxx @@ -900,6 +900,8 @@ namespace bdep default_options_files options_files (const char*, const cmd_sync_options& o, const strings&) { + // NOTE: remember to update the documentation if changing anything here. + // bdep.options // bdep-{sync|sync-implicit}.options @@ -934,6 +936,8 @@ namespace bdep merge_options (const default_options& defs, const cmd_sync_options& cmd) { + // NOTE: remember to update the documentation if changing anything here. + return merge_default_options ( defs, cmd, diff --git a/bdep/test.cli b/bdep/test.cli index 4b6349f..58d7764 100644 --- a/bdep/test.cli +++ b/bdep/test.cli @@ -62,4 +62,25 @@ namespace bdep "Also test all dependencies, recursively." } }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bdep-default-options-files(1)} for an overview of the default + options files. For the \cb{test} command the search start directory is + the project directory. The following options files are searched for in + each directory and, if found, loaded in the order listed: + + \ + bdep.options + bdep-test.options + \ + + The following \cb{test} command options cannot be specified in the + default options files: + + \ + --directory|-d + \ + " } diff --git a/bdep/update.cli b/bdep/update.cli index 3868a0a..83b1b79 100644 --- a/bdep/update.cli +++ b/bdep/update.cli @@ -46,4 +46,25 @@ namespace bdep { "\h|UPDATE OPTIONS|" }; + + " + \h|DEFAULT OPTIONS FILES| + + See \l{bdep-default-options-files(1)} for an overview of the default + options files. For the \cb{update} command the search start directory is + the project directory. The following options files are searched for in + each directory and, if found, loaded in the order listed: + + \ + bdep.options + bdep-update.options + \ + + The following \cb{update} command options cannot be specified in the + default options files: + + \ + --directory|-d + \ + " } diff --git a/doc/cli.sh b/doc/cli.sh index 3ba95b9..e331e4f 100755 --- a/doc/cli.sh +++ b/doc/cli.sh @@ -63,7 +63,8 @@ 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 as well as in bdep.cli. +# NOTE: remember to update a similar list in buildfile and bdep.cli as well as +# the help topics sections in bdep/buildfile and help.cxx. # pages="new help init sync fetch status ci release publish deinit config test \ update clean projects-configs default-options-files" -- cgit v1.1