Document *-build-config, *-builds, *-build-{include,exclude} package manifest values

2 files changed, 105 insertions, 25 deletions

diff --git a/bpkg/pkg-build.cxx b/bpkg/pkg-build.cxx
index 78ed73d..a5dd813 100644
--- a/bpkg/pkg-build.cxx
+++ b/bpkg/pkg-build.cxx
@@ -302,7 +302,8 @@ namespace bpkg
               fail << "multiple " << db.type << " configurations specified "
                    << "for dependency package " << nm <<
                 info << i->db->config_orig <<
-                info << j->db->config_orig;
+                info << j->db->config_orig <<
+                info << "consider using the --no-move option";
             }
           }
         }
diff --git a/doc/manual.cli b/doc/manual.cli
index 6767f22..d6eeecd 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -1077,6 +1077,12 @@ license: <licenses> [; <comment>]
 [build-include]: <config>[/<target>] [; <comment>]
 [build-exclude]: <config>[/<target>] [; <comment>]
 
+[*-build-config]: <args> [; <comment>]
+
+[*-builds]: <class-expr> [; <comment>]
+[*-build-include]: <config>[/<target>] [; <comment>]
+[*-build-exclude]: <config>[/<target>] [; <comment>]
+
 [build-file]: <path>
 
 [bootstrap-build]: <text>
@@ -2119,41 +2125,43 @@ builds: -windows
 <class-term> = ('+'|'-'|'&')['!'](<class-name> | '(' <class-expr> ')')
 \
 
-The package build configurations. They specify the build configuration classes
-the package should or should not be built for by automated build bots. For
-example:
+The common package build target configurations. They specify the target
+configuration classes the package should or should not be built for by
+automated build bots, unless overridden by a package configuration-specific
+value (see \l{#manifest-package-build-config \c{*-build-config}} for details).
+For example:
 
 \
 builds: -windows
 \
 
-Build configurations can belong to multiple classes with their names and
-semantics varying between different build bot deployments. However, the
+Build target configurations can belong to multiple classes with their names
+and semantics varying between different build bot deployments. However, the
 pre-defined \c{none}, \c{default}, \c{all}, \c{host}, and \c{build2} classes
 are always provided. If no \c{builds} value is specified in the package
 manifest, then the \c{default} class is assumed.
 
-\N|A build configuration class can also derive from another class in which
+\N|A target configuration class can also derive from another class in which
 case configurations that belong to the derived class are treated as also
 belonging to the base class (or classes, recursively). See the Build
 Configurations page of the build bot deployment for the list of available
-build configurations and their classes.|
+target configurations and their classes.|
 
 The \c{builds} value consists of an optional underlying class set
 (\c{<class-uset>}) followed by a class set expression (\c{<class-expr>}). The
 underlying set is a space-separated list of class names that define the set of
-build configurations to consider. If not specified, then all the
+build target configurations to consider. If not specified, then all the
 configurations belonging to the \c{default} class are assumed. The class set
 expression can then be used to exclude certain configurations from this
 initial set.
 
 The class expression is a space-separated list of terms that are evaluated
 from left to right. The first character of each term determines whether the
-build configuration that belong to its set are added to (\c{+}), subtracted
-from (\c{-}), or intersected with (\c{&}) the current set. If the second
-character in the term is \c{!}, then its set of configuration is inverted
-against the underlying set. The term itself can be either the class name or a
-parenthesized expression. Some examples (based on the
+build target configuration that belong to its set are added to (\c{+}),
+subtracted from (\c{-}), or intersected with (\c{&}) the current set. If the
+second character in the term is \c{!}, then its set of configuration is
+inverted against the underlying set. The term itself can be either the class
+name or a parenthesized expression. Some examples (based on the
 \l{https://ci.cppget.org/?build-configs cppget.org} deployment):
 
 \
@@ -2194,7 +2202,7 @@ builds: -( +macos &gcc)      ; Homebrew GCC is not supported.
 \
 
 \N|The \c{builds} value comments are used by the web interface (\c{brep}) to
-display the reason for the build configuration exclusion.|
+display the reason for the build target configuration exclusion.|
 
 After evaluating all the \c{builds} values, the final configuration set can be
 further fine-tuned using the \l{#manifest-package-include-exclude
@@ -2208,20 +2216,20 @@ further fine-tuned using the \l{#manifest-package-include-exclude
 [build-exclude]: <config>[/<target>] [; <comment>]
 \
 
-The package build inclusions and exclusions. The \c{build-include} and
+The common package build inclusions and exclusions. The \c{build-include} and
 \c{build-exclude} values further reduce the configuration set produced by
 evaluating the \l{#manifest-package-builds \c{builds}} values. The \i{config}
 and \i{target} values are filesystem wildcard patterns which are matched
-against the build configuration names and target names (see the \c{bbot}
-documentation for details). In particular, the \c{*} wildcard matches zero or
-more characters within the name component while the \c{**} sequence matches
-across the components. Plus, wildcard-only pattern components match absent
-name components. For example:
+against the build target configuration names and target names (see the
+\c{bbot} documentation for details). In particular, the \c{*} wildcard matches
+zero or more characters within the name component while the \c{**} sequence
+matches across the components. Plus, wildcard-only pattern components match
+absent name components. For example:
 
 \
-build-exclude: windows**     # matches windows_10-msvc_15
-build-exclude: macos*-gcc**  # matches macos_10.13-gcc_8.1-O3
-build-exclude: linux-gcc*-*  # matches linux-gcc_8.1 and linux-gcc_8.1-O3
+build-exclude: windows**    # matches windows_10-msvc_15
+build-exclude: macos*-gcc** # matches macos_10.13-gcc_8.1-O3
+build-exclude: linux-gcc*-* # matches linux-gcc_8.1 and linux-gcc_8.1-O3
 \
 
 The exclusion and inclusion patterns are applied in the order specified with
@@ -2245,7 +2253,78 @@ build-exclude: ** ; Only supported on Linux.
 \
 
 Note that the comment of the matching exclusion is used by the web interface
-(\c{brep}) to display the reason for the build configuration exclusion.
+(\c{brep}) to display the reason for the build target configuration exclusion.
+
+
+\h2#manifest-package-build-config|\c{*-build-config}|
+
+\
+[*-build-config]: <args> [; <comment>]
+
+<args> = [<config-var>]* [<dependency-spec>]*
+<dependency-spec> = [{ <config-var> [<config-var>]* }+] <dependency>
+<dependency> = ?[sys:]<name>[<version-spec>]
+<version-spec> = /<version> | <version-constraint>
+
+[*-builds]: <class-expr> [; <comment>]
+[*-build-include]: <config>[/<target>] [; <comment>]
+[*-build-exclude]: <config>[/<target>] [; <comment>]
+\
+
+The package build configurations where the substring matched by \c{*} in
+\c{*-build-config} denotes the configuration name. If specified, then the
+package is built in these configurations by automated build bots in addition
+to the default configuration (which is called \c{default}).
+
+The \c{*-build-config} values contain whitespace separated lists of
+potentially double/single-quoted package configuration arguments to the
+\l{bpkg-pkg-build(1)} command. For example:
+
+\
+network-build-config: config.libfoo.network=true; Enable networking API.
+
+cache-build-config:
+\\
+config.libfoo.cache=true
+config.libfoo.buffer=4096
+;
+Enable caching.
+\\
+
+libbar-network-build-config:
+\\
+{ config.libbar.network=true }+ ?libbar
+; Enable networking API in libbar.
+\\
+
+older-libz-build-config: \"?libz ^1.0.0\"; Test with older libz version.
+
+sys-build-config: ?sys:libbar ?sys:libz; Test with system dependencies.
+\
+
+The package build configuration can also override the common build target
+configurations set (specified with \l{#manifest-package-builds \c{builds}} and
+\l{#manifest-package-include-exclude \c{build-{include, exclude\}}}) by
+specifying the matching \c{*-builds} and/or \c{*-build-{include, exclude\}}
+values. For example:
+
+\
+network-builds: linux; Only supported on Linux.
+network-build-config: config.libfoo.network=true; Enable networking API.
+\
+
+Note that the common build target configurations set is overridden
+hierarchically meaning that the \c{*-build-{include, exclude\}} overrides
+don't discard the common \c{builds} values.
+
+The default configuration should normally build the package with no
+configuration arguments and for the common target build configurations
+set. While not recommended, this can be overridden by using the special
+\c{default} configuration name. For example:
+
+\
+default-build-config: config.libfoo.cache=true
+\
 
 
 \h2#manifest-package-build-file|\c{build-file}|