Fix unexpected 'manual configuration of dependents with prefer or require clauses is not yet supported' error (GH issue #302)

1 files changed, 37 insertions, 9 deletions

diff --git a/bpkg/pkg-configure.hxx b/bpkg/pkg-configure.hxx
index 24e06a3..876d11a 100644
--- a/bpkg/pkg-configure.hxx
+++ b/bpkg/pkg-configure.hxx
@@ -45,11 +45,10 @@ namespace bpkg
   // Given dependencies of a package, return its prerequisite packages,
   // configuration variables that resulted from selection of these
   // prerequisites (import, reflection, etc), and sources of the configuration
-  // variables resulted from evaluating the reflect clauses. See
-  // pkg_configure() for the semantics of the dependency list. Fail if for
-  // some of the dependency alternative lists there is no satisfactory
-  // alternative (all its dependencies are configured, satisfy the respective
-  // constraints, etc).
+  // variables resulted from evaluating the reflect clauses. Fail if for some
+  // of the dependency alternative lists there is no satisfactory alternative
+  // (all its dependencies are configured, satisfy the respective constraints,
+  // etc).
   //
   // The package dependency constraints are expected to be complete.
   //
@@ -62,12 +61,41 @@ namespace bpkg
   // be parallel to the dependencies argument and specify indexes of the
   // selected alternatives.
   //
-  // If prerequisites corresponding to the previous configured state of the
-  // package are specified, then for each depends value try to select an
-  // alternative where dependencies all belong to this list (the "recreate
+  // If the dependency alternatives are not pre-selected (alternatives ==
+  // NULL), then for each depends value select the first satisfactory
+  // alternative encountered. If, however, prerequisites corresponding to the
+  // previous configured state of the package are specified
+  // (prev_prerequisites != NULL), then for each depends value try to select
+  // an alternative where dependencies all belong to this list (the "recreate
   // dependency decisions" mode). Failed that, select an alternative as if no
   // prerequisites are specified (the "make dependency decisions" mode).
   //
+  // Note that there are actually 3 possible use cases for
+  // pkg_configure_prerequisites():
+  //
+  // - The package is being configured manually. In this case its dependency
+  //   alternatives are not pre-selected and there is no information about its
+  //   previous configured state (alternatives == NULL, prev_prerequisites ==
+  //   NULL).
+  //
+  // - The package is being built, upgraded, or re-evaluated. In this case its
+  //   dependency alternatives are pre-selected, their enable, prefer, and
+  //   require clauses are evaluated, and there is no need in the previous
+  //   configured state information (alternatives != NULL, prev_prerequisites
+  //   == NULL).
+  //
+  // - The package is being reconfigured for a reason other than any of the
+  //   mentioned above (dependency up/down-grade/reconfiguration, deorphaning,
+  //   pkg-build --disfigure is specified, etc). In this case its dependency
+  //   alternatives are not pre-selected but the previous configured state
+  //   information is provided (alternatives == NULL, prev_prerequisites !=
+  //   NULL).
+  //
+  // - There are no use cases when both dependency alternatives are
+  //   pre-selected and the previous configured state information needs to be
+  //   provided. Thus, alternatives and prev_prerequisites must never be both
+  //   NULL.
+  //
   // Optionally, remove constraints from the specified dependencies
   // (unconstrain_deps). Only allowed in the simulation mode.
   //
@@ -122,7 +150,7 @@ namespace bpkg
   //       required.
   //
   // Note: expects all the non-external packages to be configured to be
-  //       already unpackged (for subproject discovery).
+  //       already unpacked (for subproject discovery).
   //
   void
   pkg_configure (const common_options&,