Document init, add --[no]-default

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} \ \ \ [<options>] [<prj-spec>] [\b{@}<cfg-name>] <cfg-dir>\n
         \b{bdep config create} [<options>] [<prj-spec>] [\b{@}<cfg-name>] <cfg-dir> [<cfg-args>]\n
-        \b{bdep config remove} [<options>] [<prj-spec>] <cfg-spec>}
+        \b{bdep config remove} [<options>] [<prj-spec>] <cfg-spec>... | \b{--all}|\b{-a}\n
+        \b{bdep config rename} [<options>] [<prj-spec>] <cfg-spec> <cfg-name>\n
+        \b{bdep config set} \ \ \ [<options>] [<prj-spec>] <cfg-spec> \b{--}[\b{no-}]\b{default}}
 
-     \c{<cfg-args> = (<module> | <cfg-var>)...\n
-        <cfg-spec> = (\b{@}<cfg-name> | \b{--config}|\b{-c} <cfg-dir>)... | \b{--all}|\b{-a}\n
-        <prj-spec> = \b{--directory}|\b{-d} <prj-dir>}
+     \c{<cfg-spec> = \b{@}<cfg-name> | \b{--config}|\b{-c} <cfg-dir>\n
+        <prj-spec> = \b{--directory}|\b{-d} <prj-dir>\n
+        <cfg-args> = (<module> | <cfg-var>)...}
 
      \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<count> () == 0);
+    else if (*def)
+    {
+      using query = bdep::query<configuration>;
+
+      if (auto p = db.query_one<configuration> (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} [<options>] [<pkg-spec>] \b{--config-create|-C} <cfg-dir> [\b{@}<cfg-name>]\n
         \ \ \ \ \ \ \ \ \ \ [<cfg-args>]}
 
-     \c{<pkg-args> = (<pkg> | <cfg-var>)...\n
-        <cfg-spec> = (\b{@}<cfg-name> | \b{--config}|\b{-c} <cfg-dir>)... | \b{--all}|\b{-a}\n
+     \c{<cfg-spec> = (\b{@}<cfg-name> | \b{--config}|\b{-c} <cfg-dir>)... | \b{--all}|\b{-a}\n
         <pkg-spec> = (\b{--directory}|\b{-d} <pkg-dir>)... | <prj-spec>\n
         <prj-spec> = \b{--directory}|\b{-d} <prj-dir>\n
+        <pkg-args> = (<pkg> | <cfg-var>)...\n
         <cfg-args> = (<module> | <cfg-var>)...}
 
      \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
+     (<pkg-spec>), or, if the project itself is specified (<prj-spec>), all
+     its available packages, in one or more build configurations (<cfg-spec>)
+     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 <pkg-args> are the
+     additional arguments to the underlying \l{bpkg-pkg-build(1)} command.
 
-     If <cfg-spec> 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 <pkg-spec> is omitted, then the current working directory is
-     assumed. In this case the current directory must be either a project
-     directory (<prj-dir>), a package directory (<pkg-dir>) 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 <cfg-args> in the
+     fourth form are the additional arguments to the underlying
+     \l{bpkg-cfg-create(1)} command.
 
-     <cfg-args> are arguments to \cb{bpkg cfg-create}. <pkg-args> 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
       "<dir>",
       "Create a new build configuration in <dir>."
     }
+
+    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<bool> 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<bool> 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<bool> 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<bool> 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 <bdep/common-options.hxx>;
   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 <bdep/common-options.hxx>;
   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}: