Store in database and document *-name, *-version, and *-to-downstream-version package manifest values

6 files changed, 137 insertions, 5 deletions

diff --git a/bpkg/package.hxx b/bpkg/package.hxx
index 4f4f16b..14cd296 100644
--- a/bpkg/package.hxx
+++ b/bpkg/package.hxx
@@ -27,7 +27,7 @@
 //
 #define DB_SCHEMA_VERSION_BASE 12
 
-#pragma db model version(DB_SCHEMA_VERSION_BASE, 20, closed)
+#pragma db model version(DB_SCHEMA_VERSION_BASE, 21, closed)
 
 namespace bpkg
 {
@@ -670,6 +670,10 @@ namespace bpkg
   //
   #pragma db value(buildfile) definition
 
+  // distribution_name_value
+  //
+  #pragma db value(distribution_name_value) definition
+
   #pragma db object pointer(shared_ptr) session
   class available_package
   {
@@ -716,6 +720,8 @@ namespace bpkg
     optional<string>  root_build;
     vector<buildfile> buildfiles;
 
+    vector<distribution_name_value> distribution_values;
+
     // Present for non-transient objects only (and only for certain repository
     // types).
     //
@@ -734,6 +740,7 @@ namespace bpkg
           version (move (m.version)),
           dependencies (convert (move (m.dependencies))),
           tests (move (m.tests)),
+          distribution_values (move (m.distribution_values)),
           sha256sum (move (m.sha256sum))
     {
       if (!stub ())
@@ -834,6 +841,10 @@ namespace bpkg
     //
     #pragma db member(tests) id_column("") value_column("test_")
 
+    // distributions
+    //
+    #pragma db member(distribution_values) id_column("") value_column("dist_")
+
     // alt_naming
     //
     // @@ TMP Drop when database migration to the schema version 20 is no
diff --git a/bpkg/package.xml b/bpkg/package.xml
index eafcaa8..baa8dfb 100644
--- a/bpkg/package.xml
+++ b/bpkg/package.xml
@@ -1,4 +1,45 @@
 <changelog xmlns="http://www.codesynthesis.com/xmlns/odb/changelog" database="sqlite" version="1">
+  <changeset version="21">
+    <add-table name="main.available_package_distribution_values" kind="container">
+      <column name="name" type="TEXT" null="true" options="COLLATE NOCASE"/>
+      <column name="version_epoch" type="INTEGER" null="true"/>
+      <column name="version_canonical_upstream" type="TEXT" null="true"/>
+      <column name="version_canonical_release" type="TEXT" null="true" options="COLLATE BINARY"/>
+      <column name="version_revision" type="INTEGER" null="true"/>
+      <column name="version_iteration" type="INTEGER" null="true"/>
+      <column name="index" type="INTEGER" null="true"/>
+      <column name="dist_name" type="TEXT" null="true"/>
+      <column name="dist_value" type="TEXT" null="true"/>
+      <foreign-key name="object_id_fk" on-delete="CASCADE">
+        <column name="name"/>
+        <column name="version_epoch"/>
+        <column name="version_canonical_upstream"/>
+        <column name="version_canonical_release"/>
+        <column name="version_revision"/>
+        <column name="version_iteration"/>
+        <references table="main.available_package">
+          <column name="name"/>
+          <column name="version_epoch"/>
+          <column name="version_canonical_upstream"/>
+          <column name="version_canonical_release"/>
+          <column name="version_revision"/>
+          <column name="version_iteration"/>
+        </references>
+      </foreign-key>
+      <index name="available_package_distribution_values_object_id_i">
+        <column name="name"/>
+        <column name="version_epoch"/>
+        <column name="version_canonical_upstream"/>
+        <column name="version_canonical_release"/>
+        <column name="version_revision"/>
+        <column name="version_iteration"/>
+      </index>
+      <index name="available_package_distribution_values_index_i">
+        <column name="index"/>
+      </index>
+    </add-table>
+  </changeset>
+
   <changeset version="20">
     <alter-table name="main.available_package">
       <add-column name="alt_naming" type="INTEGER" null="true" default="0"/>
diff --git a/bpkg/pkg-build.cxx b/bpkg/pkg-build.cxx
index 4e88fa1..aa34594 100644
--- a/bpkg/pkg-build.cxx
+++ b/bpkg/pkg-build.cxx
@@ -2189,7 +2189,7 @@ namespace bpkg
                             false /* ignore_toolchain */,
                             false /* expand_values */,
                             true /* load_buildfiles */,
-                            true /* complete_depends */,
+                            true /* complete_values */,
                             diag ? 2 : 1));
 
               // This is a package archive.
diff --git a/bpkg/pkg-verify.cxx b/bpkg/pkg-verify.cxx
index 0541f1b..d48c5b7 100644
--- a/bpkg/pkg-verify.cxx
+++ b/bpkg/pkg-verify.cxx
@@ -566,7 +566,7 @@ namespace bpkg
                     o.ignore_unknown () /* ignore_toolchain */,
                     o.deep () /* expand_values */,
                     o.deep () /* load_buildfiles */,
-                    o.deep () /* complete_depends */,
+                    o.deep () /* complete_values */,
                     o.silent () ? 0 : 2));
 
       if (o.manifest ())
diff --git a/bpkg/pkg-verify.hxx b/bpkg/pkg-verify.hxx
index 631f0be..0609844 100644
--- a/bpkg/pkg-verify.hxx
+++ b/bpkg/pkg-verify.hxx
@@ -26,7 +26,7 @@ namespace bpkg
   // description-type value to the effective description type (see
   // libbpkg/manifest.hxx), load the bootstrap, root, and config/*.build
   // buildfiles into the respective *-build values, and complete the
-  // dependency constraints.
+  // manifest values (depends, <distribution>-version, etc).
   //
   // Throw not_package (derived from failed) if this doesn't look like a
   // package. Throw plain failed if this does looks like a package but
@@ -47,7 +47,7 @@ namespace bpkg
               bool ignore_toolchain,
               bool expand_values,
               bool load_buildfiles,
-              bool complete_depends = true,
+              bool complete_values = true,
               int diag_level = 2);
 
   // Similar to the above but verifies that a source directory is a valid
diff --git a/doc/manual.cli b/doc/manual.cli
index d6eeecd..10b3047 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -1040,6 +1040,7 @@ a full package manifest they can be interleaved with non-header values.
 \
 name: <name>
 version: <version>
+[upstream-version]: <string>
 [project]: <name>
 [priority]: <priority> [; <comment>]
 summary: <text>
@@ -1092,6 +1093,10 @@ license: <licenses> [; <comment>]
 [bootstrap-build2]: <text>
 [root-build2]: <text>
 [*-build2]: <text>
+
+[*-name]: <name> [<name>...]
+[*-version]: <string>
+[*-to-downstream-version]: <regex>
 \
 
 \h2#manifest-package-name|\c{name}|
@@ -2385,6 +2390,81 @@ automatically added, for example, when the \l{#manifest-package-list-pkg
 package list manifest} is created.
 
 
+\h2#manifest-package-distribution|\c{*-name}|
+
+\
+[*-name]: <name> [<name>...]
+[*-version]: <string>
+[*-to-downstream-version]: <regex>
+
+<regex> = /<patten>/<replacement>/
+\
+
+The binary distribution packages where the substring matched by \c{*} in
+\c{*-name} denotes the distribution name which has the
+\c{<name>[\b{_}<version>]} form. For example:
+
+\
+debian
+debian_10
+fedora_32
+ubuntu_16.04
+freebsd_12.1
+windows_10
+macos_10
+macos_10.15
+macos_12
+\
+
+If the \c{*-name} values are specified, then the packages required for these
+binary distributions can be created using the \l{bpkg-pkg-bindist(1)}
+command. The \c{*-name} values contain whitespace separated lists of the
+distribution package names. Normally such a list contains a single primary
+package name, but can additionally contain the related package names which
+cannot automatically be deduced from the primary package name. For example:
+
+\
+debian_10-name: libssl1.1 libssl-dev
+fedora_32-name: openssl-libs
+\
+
+If the distribution package version differs from the upstream package version
+(the \c{upstream-version} value, if present, and the \c{version} value
+otherwise), then the matching \c{*-version} value needs to be specified. For
+example:
+
+\
+debian-name: libssl1.1 libssl-dev
+debian-version: 1.1.1n
+\
+
+To specify the distribution package version to be the same as the \cb{bpkg}
+package version, the special \c{$} value can be used. For example:
+
+\
+debian-version: $
+\
+
+When configuring a package as a system dependency the \l{bpkg-pkg-build(1)}
+command needs to map the binary distribution package versions back to the
+\cb{bpkg} package versions, so it can verify the version constraints imposed
+by the dependent packages on this dependency package. Unless such a mapping is
+maintained externally, it should be specified at the \cb{bpkg} package level
+by using the \c{*-to-downstream-version} values. For example:
+
+\
+debian-name: libssl1.1 libssl-dev
+debian-version: 1.1.1n
+debian-to-downstream-version: /([^.])\.([^.])\.([^.])n/\1.\2.\3+14/
+debian-to-downstream-version: /([^.])\.([^.])\.([^.])o/\1.\2.\3+15/
+debian-to-downstream-version: /([^.])\.([^.])\.([^.])p/\1.\2.\3+16/
+\
+
+If \cb{bpkg} finds the matching regular expression pattern, then it uses the
+corresponding replacement to produce the \cb{bpkg} package version. Otherwise,
+it excludes this binary distribution package version from the consideration.
+
+
 \h#manifest-package-list-pkg|Package List Manifest for \cb{pkg} Repositories|
 
 The package list manifest (the \c{packages.manifest} file found in the