Update pkg-build documentation

2 files changed, 106 insertions, 25 deletions

diff --git a/bpkg/pkg-build.cli b/bpkg/pkg-build.cli
index 80abc60..b7a75dc 100644
--- a/bpkg/pkg-build.cli
+++ b/bpkg/pkg-build.cli
@@ -12,23 +12,43 @@ namespace bpkg
 {
   {
     "<options>
-     <pkg-spec> <scheme> <pkg> <ver>
+     <pkg-spec> <flags> <scheme> <pkg> <ver>
      <file>
      <dir>
      <rep-loc>",
 
     "\h|SYNOPSIS|
 
-     \c{\b{bpkg pkg-build}|\b{build} [<options>] (<pkg-spec> | [\b{@}]<rep-loc> | <file> | <dir>/)...}
+     \c{\b{bpkg pkg-build}|\b{build} [<options>] [\b{--upgrade}|\b{-u} | \b{--patch}|\b{-p}] <pkg-spec>...\n
+        \b{bpkg pkg-build}|\b{build} [<options>] \ \b{--upgrade}|\b{-u} | \b{--patch}|\b{-p}}
 
-     \c{<pkg-spec> = [<scheme>\b{:}]<pkg>[\b{/}<ver>][\b{,}...\b{@}<rep-loc>]\n
-        <scheme> \ \ = [\b{?}]\b{sys}}
+     \c{<pkg-spec> = [<flags>](([<scheme>\b{:}]<pkg>[\b{/}<ver>])\b{,}...[\b{@}<rep-loc>] | \n
+        \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ [\b{@}]<rep-loc> \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ | \n
+        \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ <file> \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ | \n
+        \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ <dir>\b{/})\n
+        <flags>\ \ \ \ = \b{?}\n
+        <scheme> \ \ = \b{sys}}
 
      \h|DESCRIPTION|
 
-     The \cb{pkg-build} command builds one or more packages including all their
-     prerequisites. Besides building new packages, this command is also used to
-     upgrade or downgrade packages that already exists in the configuration.
+     The \cb{pkg-build} command builds one or more packages including all
+     their prerequisites. Besides building new packages, this command is also
+     used to upgrade or downgrade packages that are already present in the
+     configuration.
+
+     The first form (one or more packages are specified) builds new or
+     upgrades (by default or if \cb{--upgrade} is specified) or patches (if
+     \cb{--patch} is specified) the specified packages. The second form (no
+     arguments but either \cb{--upgrade} or \cb{--patch} is specified)
+     upgrades or patches all the held packages in the configuration (see
+     below for details on held package).
+
+     In both forms specifying the \c{\b{--immediate}|\b{-i}} or
+     \c{\b{--recursive}|\b{-r}} option causes \cb{pkg-build} to also upgrade
+     or patch the immediate or all dependencies of the specified (first form)
+     or held (second form) packages, respectively. Note also that in the first
+     form these options can only be specified with an explicit \cb{--upgrade}
+     or \cb{--patch}.
 
      Each package can be specified as just the name (<pkg>) with optional
      package version (<ver>) in which case the source code for the package
@@ -62,16 +82,13 @@ namespace bpkg
      bpkg build @/path/to/repository/
      \
 
-     A package name (<pkg>) can also be prefixed with a package scheme
-     (<scheme>:). Currently the only recognized scheme is \cb{sys:} which
+     A package name (<pkg>) can be prefixed with a package scheme
+     (<scheme>). Currently the only recognized scheme is \cb{sys} which
      instructs \cb{pkg-build} to configure the package as available from the
      system rather than building it from source. If the system package version
      (<ver>) is not specified, then it is considered to be unknown but
      satisfying any dependency constraint. Such a version is displayed as
-     \cb{*}. In certain cases you may want to indicate that a certain package
-     is available from the system but only add it to the configuration if it
-     is required by other packages being built. In this case you can use the
-     \cb{?sys:} system scheme variant.
+     '\cb{*}'.
 
      Finally, a package can be specified as either the path to the package
      archive (<file>) or to the package directory (<dir>\cb{/}; note that it
@@ -79,24 +96,78 @@ namespace bpkg
      \l{bpkg-pkg-unpack(1)} commands for more information on the semantics of
      specifying the package as an archive or a directory.
 
-     Packages that are specified explicitly on the command line will be
-     \i{held}, that is, they will not be considered for automatic removal if
-     they no longer have any dependents. Packages that are specified with the
-     explicit package version (<ver>) or as an archive or directory, will, in
-     addition, have their versions held, that is, they will not be
-     automatically upgraded.
+     By default a package that is specified explicitly on the command line is
+     built to \i{hold}: it will not be considered for automatic removal if it
+     no longer has any dependents. Only versions from repositories that were
+     added to the configuration (\l{bpkg-rep-add(1)}) are considered as
+     available for build to hold.
+
+     Alternatively, a package can be built (or, more commonly,
+     upgraded/downgraded) as a \i{dependency} by specifying the \cb{?} flag
+     (<flags>) or the \cb{--dependency} option. Such a package will only be
+     added to the configuration if it actually has any dependents and once no
+     longer used, it will be automatically dropped. Only versions from
+     prerequisite repositories of dependent packages are considered as
+     available for build as a dependency.
+
+     Packages (both built to hold and as dependents) that are specified with
+     an explicit package version (<ver>) or as an archive or directory,
+     will have their versions held, that is, they will not be automatically
+     upgraded.
+
+     As an illustration, let's assume in the following example that the stable
+     repository contains packages \cb{foo} \cb{1.0.0} as well as
+     \cb{libfoo} \cb{1.0.0} and \cb{1.1.0} while testing \- \cb{libfoo}
+     \cb{2.0.0}, that testing is complemented by stable, and that \cb{foo}
+     depends on \cb{libfoo >= 1.0.0}:
 
-     The \cb{pkg-build} command also supports several options (described
-     below) that allow you to control the amount of work that will be done."
+     \
+     bpkg fetch https://example.org/1/testing
+
+     bpkg build foo            # build foo    1.0.0 to hold
+                               # build libfoo 1.1.0 as dependency
+
+     bpkg build ?libfoo/1.0.0  # downgrade libfoo 1.0.0 as dependency,
+                               #           also hold version 1.0.0
+
+     bpkg build ?libfoo/2.0.0  # error: 2.0.0 unavailable in dependent's
+                               #        (foo) repository (stable)
+
+     bpkg build libfoo/2.0.0   # upgrade libfoo 2.0.0 to hold,
+                               #         also hold version 2.0.0
+     \
+     "
   }
 
   class pkg_build_pkg_options
   {
     "\h|PKG-BUILD PACKAGE OPTIONS|
 
-    The following options can be grouped to apply to a specific package as
-    well as specified globally, in which case they apply to all the specified
-    packages."
+     The following options can be grouped to apply to a specific \ci{pkg-spec}
+     as well as specified globally, in which case they apply to all the
+     specified packages."
+
+    bool --upgrade|-u
+    {
+      "Upgrade packages to the latest available version that satisfies all the
+       constraints."
+    }
+
+    bool --patch|-p
+    {
+      "Upgrade packages to the latest available patch version that satisfies
+       all the constraints."
+    }
+
+    bool --immediate|-i
+    {
+      "Also upgrade or patch immediate dependencies."
+    }
+
+    bool --recursive|-r
+    {
+      "Also upgrade or patch all dependencies, recursively."
+    }
 
     bool --dependency
     {
diff --git a/bpkg/pkg-build.cxx b/bpkg/pkg-build.cxx
index b884fba..4b703b4 100644
--- a/bpkg/pkg-build.cxx
+++ b/bpkg/pkg-build.cxx
@@ -1186,6 +1186,16 @@ namespace bpkg
     const dir_path& c (o.directory ());
     l4 ([&]{trace << "configuration: " << c;});
 
+    // The --immediate or --recursive option can only be specified with an
+    // explicit --upgrade or --patch.
+    //
+    if (const char* n = (o.immediate () ? "--immediate" :
+                         o.recursive () ? "--recursive" : nullptr))
+    {
+      if (!o.upgrade () && !o.patch ())
+        fail << n << " requires explicit --upgrade|-u or --patch|-p";
+    }
+
     if (o.drop_prerequisite () && o.keep_prerequisite ())
       fail << "both --drop-prerequisite|-D and --keep-prerequisite|-K "
            << "specified" <<
@@ -2043,7 +2053,7 @@ namespace bpkg
     // Almost forgot, there is one more thing: when we upgrade or downgrade a
     // package, it may change the list of its prerequisites. Which means we
     // may end up with packages that are no longer necessary and it would be
-    // nice to offer to drop those. This, howeve, is a tricky business and is
+    // nice to offer to drop those. This, however, is a tricky business and is
     // the domain of pkg_drop(). For example, a prerequisite may still have
     // other dependents (so it looks like we shouldn't be dropping it) but
     // they are all from the "drop set" (so we should offer to drop it after