Improve search for available package corresponding to selected package in pkg-build

1 files changed, 17 insertions, 1 deletions

diff --git a/bpkg/package.hxx b/bpkg/package.hxx
index 26eb34b..fbf8643 100644
--- a/bpkg/package.hxx
+++ b/bpkg/package.hxx
@@ -876,11 +876,27 @@ namespace bpkg
   // version constraint and return them in the version descending order, by
   // default. Note that a stub satisfies any constraint.
   //
+  // By default if the revision is not explicitly specified for the version
+  // constraint, then compare ignoring the revision. The idea is that when the
+  // user runs 'bpkg build libfoo/1' and there is 1+1 available, it should
+  // just work. The user shouldn't have to spell the revision
+  // explicitly. Similarly, when we have 'depends: libfoo == 1', then it would
+  // be strange if 1+1 did not satisfy this constraint. The same for libfoo <=
+  // 1 -- 1+1 should satisfy.
+  //
+  // Note that by default we compare ignoring the iteration, as it can not be
+  // specified in the manifest/command line. This way the latest iteration
+  // will always be picked up.
+  //
+  // Pass true as the revision argument to query the exact available package
+  // version, also comparing the version revision and iteration.
+  //
   odb::result<available_package>
   query_available (database&,
                    const package_name&,
                    const optional<version_constraint>&,
-                   bool order = true);
+                   bool order = true,
+                   bool revision = false);
 
   // Only return packages that are in the specified repository fragments, their
   // complements or prerequisites (if prereq is true), recursively. While you