Document that qualification is flag independent

See #3268 (comment)

(cherry picked from commit 4ff4e2b)

Author: edsko

cabal-install/Distribution/Client/Dependency/Modular/Dependency.hs

@@ -186,6 +186,12 @@ data QualifyOptions = QO {
 
 -- | Apply built-in rules for package qualifiers
 --
+-- Although the behaviour of 'qualifyDeps' depends on the 'QualifyOptions',
+-- it is important that these 'QualifyOptions' are _static_. Qualification
+-- does NOT depend on flag assignment; in other words, it behaves the same no
+-- matter which choices the solver makes (modulo the global 'QualifyOptions');
+-- we rely on this in 'linkDeps' (see comment there).
+--
 -- NOTE: It's the _dependencies_ of a package that may or may not be independent
 -- from the package itself. Package flag choices must of course be consistent.
 qualifyDeps :: QualifyOptions -> QPN -> FlaggedDeps Component PN -> FlaggedDeps Component QPN

cabal-install/Distribution/Client/Dependency/Modular/Linking.hs

@@ -282,6 +282,11 @@ makeCanonical lg qpn@(Q pp _) i =
 -- as well, and cover their dependencies at that point.
 linkDeps :: QPN -> [Var QPN] -> FlaggedDeps Component QPN -> UpdateState ()
 linkDeps target = \blame deps -> do
+    -- linkDeps is called in two places: when we first link one package to
+    -- another, and when we discover more dependencies of an already linked
+    -- package after doing some flag assignment. It is therefore important that
+    -- flag assignments cannot influence _how_ dependencies are qualified;
+    -- fortunately this is a documented property of 'qualifyDeps'.
     rdeps <- requalify deps
     go blame deps rdeps
   where