Add note about reading the project configuration

cabal-install/src/Distribution/Client/ProjectPlanning.hs

@@ -331,11 +331,37 @@ sanityCheckElaboratedPackage
             `optStanzaSetIsSubset` pkgStanzasEnabled
         )
 
-------------------------------------------------------------------------------
-
--- * Deciding what to do: making an 'ElaboratedInstallPlan'
-
-------------------------------------------------------------------------------
+-- Note [reading project configuration]
+--
+-- The project configuration is assembled into a ProjectConfig as follows:
+--
+-- CLI arguments are converted using commandLineFlagsToProjectConfig in the
+-- v2 command entrypoints and passed to establishProjectBaseContext which
+-- then calls rebuildProjectConfig.
+--
+-- rebuildProjectConfig then calls readProjectConfig to read the project
+-- files. Because of conditionals, this output is in the form of a
+-- ProjectConfigSkeleton and will be resolved by rebuildProjectConfig using
+-- instantiateProjectConfigSkeletonFetchingCompiler.
+--
+-- readProjectConfig also loads the global configuration, which is read with
+-- loadConfig and convertd to a ProjectConfig with convertLegacyGlobalConfig.
+--
+-- *Important*
+--
+-- You can notice how some project config options are needed to read the
+-- project config! This is evident by the fact that rebuildProjectConfig
+-- takes HttpTransport and DistDirLayout as parameters. Two arguments are
+-- infact determined from the CLI alone (in establishProjectBaseContext).
+-- Consequently, project files (including global configuration) cannot
+-- affect those parameters.
+--
+-- Furthermore, the project configuration can specify a compiler to use,
+-- which we need to resolve the conditionals in the project configuration!
+-- To solve this, we configure the compiler from what is obtained by applying
+-- the CLI configuration over the the configuration obtained by "flattening"
+-- ProjectConfigSkeleton. This means collapsing all conditionals by taking
+-- both branches.
 
 -- | Return the up-to-date project config and information about the local
 -- packages within the project.
@@ -513,6 +539,11 @@ configureCompiler
             )
           $ defaultProgramDb
 
+
+------------------------------------------------------------------------------
+-- * Deciding what to do: making an 'ElaboratedInstallPlan'
+------------------------------------------------------------------------------
+
 -- | Return an up-to-date elaborated install plan.
 --
 -- Two variants of the install plan are returned: with and without packages