From efc78a6f3b0d1e0a2278ea5a7f2c502a6b4f00d0 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Sat, 24 Mar 2018 11:27:37 +0200 Subject: Document init, add --[no]-default --- bdep/config.cli | 29 ++++++++--- bdep/config.cxx | 12 +++++ bdep/init.cli | 128 ++++++++++++++++++++++++++++++++++++++++------ bdep/init.cxx | 36 +++++++++---- bdep/init.hxx | 3 +- bdep/new.cli | 14 +++++ bdep/new.cxx | 32 ++++++++---- bdep/projects-configs.cli | 4 +- bdep/sync.cli | 2 + 9 files changed, 215 insertions(+), 45 deletions(-) diff --git a/bdep/config.cli b/bdep/config.cli index 5b414b3..30f7ed7 100644 --- a/bdep/config.cli +++ b/bdep/config.cli @@ -20,15 +20,26 @@ namespace bdep \c{\b{bdep config add} \ \ \ [] [] [\b{@}] \n \b{bdep config create} [] [] [\b{@}] []\n - \b{bdep config remove} [] [] } + \b{bdep config remove} [] [] ... | \b{--all}|\b{-a}\n + \b{bdep config rename} [] [] \n + \b{bdep config set} \ \ \ [] [] \b{--}[\b{no-}]\b{default}} - \c{ = ( | )...\n - = (\b{@} | \b{--config}|\b{-c} )... | \b{--all}|\b{-a}\n - = \b{--directory}|\b{-d} } + \c{ = \b{@} | \b{--config}|\b{-c} \n + = \b{--directory}|\b{-d} \n + = ( | )...} \h|DESCRIPTION| - The \cb{config} command..." + The \cb{config} command... + + + Unless the \cb{--no-default} option is specified, the first added or + created build configuration is designated as the default configuration. + Several \cb{bdep} commands use such a configuration by default if no + configuration was specified explicitly (see \l{bdep-projects-configs(1)} + for details). To make a subsequently added configuration the default use + the \cb{--default} option. + " } // Note that not all project/configuration options are valid for all @@ -40,8 +51,12 @@ namespace bdep bool --default { - //@@ Need to explain what it means. - "Make the added or created configuration default." + "Make the added or created configuration the default." + } + + bool --no-default + { + "Don't make the first added or created configuration then default." } }; } diff --git a/bdep/config.cxx b/bdep/config.cxx index 9f94a29..12a6e61 100644 --- a/bdep/config.cxx +++ b/bdep/config.cxx @@ -32,6 +32,14 @@ namespace bdep // if (!def) def = (db.query_value () == 0); + else if (*def) + { + using query = bdep::query; + + if (auto p = db.query_one (query::default_)) + fail << "configuration " << *p << " is already the default" << + info << "use 'bdep config set --no-default' to clear"; + } // Make sure the configuration path is absolute and normalized. Also // derive relative to project directory path is possible. @@ -95,11 +103,15 @@ namespace bdep cmd_config (const cmd_config_options& o, cli::scanner&) { //@@ TODO: get subcommand and pass to tracer. + //@@ TODO: define a CLI options class for subcommands? tracer trace ("config"); //@@ TODO: validate project/config options for subcommands. + if (o.default_ () && o.no_default ()) + fail << "both --default and --no-default specified"; + for (const string& n: o.config_name ()) text << n; diff --git a/bdep/init.cli b/bdep/init.cli index ded6913..48d29ac 100644 --- a/bdep/init.cli +++ b/bdep/init.cli @@ -26,34 +26,114 @@ namespace bdep \b{bdep init} [] [] \b{--config-create|-C} [\b{@}]\n \ \ \ \ \ \ \ \ \ \ []} - \c{ = ( | )...\n - = (\b{@} | \b{--config}|\b{-c} )... | \b{--all}|\b{-a}\n + \c{ = (\b{@} | \b{--config}|\b{-c} )... | \b{--all}|\b{-a}\n = (\b{--directory}|\b{-d} )... | \n = \b{--directory}|\b{-d} \n + = ( | )...\n = ( | )...} \h|DESCRIPTION| - The \cb{init} command... + The \cb{init} command initializes a project in one or more build + configurations. The first form initializes the specified project packages + (), or, if the project itself is specified (), all + its available packages, in one or more build configurations () + that have already been associated with the project (\l{bdep-config(1)}). + If no project directory is specified, then the current working directory + is assumed. If no configuration is specified, the the default + configuration is assumed. See \l{bdep-projects-configs(1)} for details on + specifying projects and configurations. Optional are the + additional arguments to the underlying \l{bpkg-pkg-build(1)} command. - If is omitted, then the default configuration is assumed. + The second form (\cb{--empty} is specified) initializes an empty project + database that can later be used to first add build configurations + (\l{bdep-config(1)}) and then initialize project packages using the first + form. - If is omitted, then the current working directory is - assumed. In this case the current directory must be either a project - directory (), a package directory () or a subdirectory - of package directory. + The third (\cb{--config-add}) and fourth (\cb{--config-create}) forms are + shortcuts that can be used to first add an existing or newly created + build configuration and then initialize project packages in that + configuration. Semantically they are equivalent to first performing the + \cb{config add} or \cb{config create} commands (\l{bdep-config(1)}), + respectively, followed by the first form. Optional in the + fourth form are the additional arguments to the underlying + \l{bpkg-cfg-create(1)} command. - are arguments to \cb{bpkg cfg-create}. are arguments - to \cb{bpkg pkg-build}. + \h|EXAMPLES| - In the first form the configurations can also be specified as - directories using the \cb{--config|-c} option. + As an example, consider project \cb{prj} with two packages, \cb{foo} + and \cb{libfoo}: + + \ + prj/ + ├── foo/ + └── libfoo/ + \ + + The following invocations illustrate the common \cb{init} use cases (the + current working directory is shown before the shell prompt). + + Create new build configuration in \cb{../prj-gcc}, call it \cb{gcc} and + initialize project packages \cb{foo} and \cb{libfoo} in this + configuration: + + \ + prj/$ bdep init -C ../prj-gcc @gcc cc config.cxx=g++ + \ + + Create new build configuration in \cb{../prj-clang} using + \l{bpkg-cfg-create(1)}. Then add it calling it \cb{clang} and initialize + project package \cb{foo} in this configuration: + + \ + prj/$ bpkg create -d ../prj-clang cc config.cxx=clang++ + prj/$ cd foo + foo/$ bdep init -A ../../prj-clang @clang + \ + + Initialize project package \cb{libfoo} in the build configuration + \cb{clang}: + + \ + foo/$ cd .. + prj/$ bdep init -d libfoo @clang + \ + + The following set of invocations achieves the same end result but using + the \l{bdep-config(1)} command to manage configuration. + + Initialize an empty project database: + + \ + prj/$ bdep init --empty + \ + + Create new build configuration in \cb{../prj-gcc}, call it \cb{gcc}: + + \ + prj/$ bdep config create ../prj-gcc @gcc cc config.cxx=g++ + \ + + Add existing build configuration in \cb{../prj-clang}, call it + \cb{clang}. + + \ + prj/$ bdep config add ../prj-clang @clang + \ + + Initialize project packages \cb{foo} and \cb{libfoo} in build + configurations \cb{gcc} and \cb{clang}. + + \ + prj/$ bdep init @gcc @clang + \ + + Or, alternatively, in all the build configurations: + + \ + prj/$ bdep init -a + \ - The second and third forms are semantically equivalent to first - performing the \cb{config add} and \cb{config create} commands - (\l{bdep-config(1)}), respectively, followed by the first form. In - both cases the \cb{--default|-d} option can be used to make the - added/created configuration default. " } @@ -77,5 +157,19 @@ namespace bdep "", "Create a new build configuration in ." } + + bool --default + { + "Make the added or created configuration the default. Only valid with + \cb{--config-add} or \cb{--config-create}, see \l{bdep-config(1)} for + details." + } + + bool --no-default + { + "Don't make the first added or created configuration then default. Only + valid with \cb{--config-add} or \cb{--config-create}, see + \l{bdep-config(1)} for details." + } }; } diff --git a/bdep/init.cxx b/bdep/init.cxx index 5fce13f..9b0ed37 100644 --- a/bdep/init.cxx +++ b/bdep/init.cxx @@ -21,7 +21,9 @@ namespace bdep const dir_path& prj, database& db, const dir_path& cfg, - bool ca, bool cc) + bool ca, + bool cc, + optional cd) { const char* m (!ca ? "--config-create" : !cc ? "--config-add" : @@ -53,7 +55,7 @@ namespace bdep db, cfg, move (name), - nullopt /* default */, // @@ TODO: --[no]-default + cd, move (id)) : nullptr; // @@ TODO: create } @@ -131,6 +133,27 @@ namespace bdep { tracer trace ("init"); + bool ca (o.config_add_specified ()); + bool cc (o.config_create_specified ()); + + optional cd; + if (o.default_ () || o.no_default ()) + { + if (!ca && !cc) + fail << "--[no-]default specified without --config-(add|create)"; + + if (o.default_ () && o.no_default ()) + fail << "both --default and --no-default specified"; + + cd = o.default_ () && !o.no_default (); + } + + if (o.empty ()) + { + if (ca) fail << "both --empty and --config-add specified"; + if (cc) fail << "both --empty and --config-create specified"; + } + project_packages pp ( find_project_packages (o, o.empty () /* ignore_packages */)); @@ -154,14 +177,8 @@ namespace bdep // --empty // - bool ca (o.config_add_specified ()); - bool cc (o.config_create_specified ()); - if (o.empty ()) { - if (ca) fail << "both --empty and --config-add specified"; - if (cc) fail << "both --empty and --config-create specified"; - //@@ TODO: what should we do if the database already exists? return 0; @@ -184,7 +201,8 @@ namespace bdep db, ca ? o.config_add () : o.config_create (), ca, - cc)); + cc, + cd)); // Fall through. } diff --git a/bdep/init.hxx b/bdep/init.hxx index f3397ff..1bb690b 100644 --- a/bdep/init.hxx +++ b/bdep/init.hxx @@ -21,7 +21,8 @@ namespace bdep database&, const dir_path& cfg, bool config_add_specified, - bool config_create_specified); + bool config_create_specified, + optional config_default); // Initialize each package in each configuration skipping those that are // already initialized. Then synchronize each configuration. diff --git a/bdep/new.cli b/bdep/new.cli index 1e91b41..6bbf07e 100644 --- a/bdep/new.cli +++ b/bdep/new.cli @@ -121,5 +121,19 @@ namespace bdep "Don't initialize a \cb{git(1)} repository inside the project nor generate any \cb{.gitignore} files." } + + bool --default + { + "Make the added or created configuration the default. Only valid with + \cb{--config-add} or \cb{--config-create}, see \l{bdep-config(1)} for + details." + } + + bool --no-default + { + "Don't make the first added or created configuration then default. Only + valid with \cb{--config-add} or \cb{--config-create}, see + \l{bdep-config(1)} for details." + } }; } diff --git a/bdep/new.cxx b/bdep/new.cxx index d43bfa9..67ba23e 100644 --- a/bdep/new.cxx +++ b/bdep/new.cxx @@ -22,6 +22,27 @@ namespace bdep { tracer trace ("new"); + bool ca (o.config_add_specified ()); + bool cc (o.config_create_specified ()); + + optional cd; + if (o.default_ () || o.no_default ()) + { + if (!ca && !cc) + fail << "--[no-]default specified without --config-(add|create)"; + + if (o.default_ () && o.no_default ()) + fail << "both --default and --no-default specified"; + + cd = o.default_ () && !o.no_default (); + } + + if (o.no_init ()) + { + if (ca) fail << "both --no-init and --config-add specified"; + if (cc) fail << "both --no-init and --config-create specified"; + } + // Validate type options. // const type& t (o.type ()); @@ -315,16 +336,8 @@ namespace bdep // --no-init // - bool ca (o.config_add_specified ()); - bool cc (o.config_create_specified ()); - if (o.no_init ()) - { - if (ca) fail << "both --no-init and --config-add specified"; - if (cc) fail << "both --no-init and --config-create specified"; - return 0; - } // Create .bdep/. // @@ -346,7 +359,8 @@ namespace bdep db, ca ? o.config_add () : o.config_create (), ca, - cc)}; + cc, + cd)}; package_locations pkgs {{n, dir_path ()}}; // project == package diff --git a/bdep/projects-configs.cli b/bdep/projects-configs.cli index 82ab462..7b3e175 100644 --- a/bdep/projects-configs.cli +++ b/bdep/projects-configs.cli @@ -69,7 +69,7 @@ include ; can specify it using the \c{\b{@}\i{cfg-name}} notation. For example: \ - bdep status @gcc @clang + $ bdep status @gcc @clang \ A configuration without a name can be specified as a directory using the @@ -77,7 +77,7 @@ include ; mixed. For example: \ - bdep status @gcc -c ../builds/clang/ + $ bdep status @gcc -c ../builds/clang/ \ Finally, we can use the \c{\b{--all}|\b{-a}} option to specify all the diff --git a/bdep/sync.cli b/bdep/sync.cli index ab01dff..1c97ac8 100644 --- a/bdep/sync.cli +++ b/bdep/sync.cli @@ -57,6 +57,8 @@ namespace bdep Note also that \c{\b{--immediate}|\b{-i}} or \c{\b{--recursive}|\b{-r}} can only be specified with an explicit \cb{--upgrade} or \cb{--patch}. + \h|EXAMPLES| + As an example, consider project \cb{prj} with two packages, \cb{foo} and \cb{libfoo}: -- cgit v1.1