Add documentation for 'all-packages'

In the user guide, changelog and add a few code comments.

Cabal/doc/nix-local-build.rst

@@ -861,7 +861,7 @@ The following settings control the behavior of the dependency solver:
 Package configuration options
 -----------------------------
 
-Package options affect the building of specific packages. There are two
+Package options affect the building of specific packages. There are three
 ways a package option can be specified:
 
 -  They can be specified at the top-level, in which case they apply only
@@ -871,6 +871,11 @@ ways a package option can be specified:
    apply to the build of the package, whether or not it is local or
    external.
 
+-  They can be specified inside an ``all-packages`` stanza, in which case they
+   apply to all packages, local ones from the project and also external
+   dependencies.
+
+
 For example, the following options specify that :cfg-field:`optimization`
 should be turned off for all local packages, and that ``bytestring`` (possibly
 an external dependency) should be built with ``-fno-state-hack``::

cabal-install/Distribution/Client/ProjectConfig/Legacy.hs

@@ -1083,6 +1083,9 @@ packageRepoSectionDescr =
                            }
     }
 
+-- | The definitions of all the fields that can appear in the @package pkgfoo@
+-- and @all-packages@ sections of the @cabal.project@-format files.
+--
 packageSpecificOptionsFieldDescrs :: [FieldDescr LegacyPackageConfig]
 packageSpecificOptionsFieldDescrs =
     legacyPackageConfigFieldDescrs
@@ -1102,6 +1105,10 @@ packageSpecificOptionsFieldDescrs =
       )
       programLocationsFieldDescrs
 
+-- | The definition of the @all-packages@ sections of the
+-- @cabal.project@-format files. This is the one that applies to all packages
+-- used anywhere by the project, locally or as dependencies.
+--
 allPackagesOptionsSectionDescr :: SectionDescr LegacyProjectConfig
 allPackagesOptionsSectionDescr =
     SectionDescr {
@@ -1120,6 +1127,9 @@ allPackagesOptionsSectionDescr =
       sectionEmpty       = mempty
     }
 
+-- | The definition of the @package pkgfoo@ sections of the @cabal.project@-format
+-- files. This section is per-package name.
+--
 packageSpecificOptionsSectionDescr :: SectionDescr LegacyProjectConfig
 packageSpecificOptionsSectionDescr =
     SectionDescr {

cabal-install/Distribution/Client/ProjectPlanning.hs

@@ -1763,6 +1763,9 @@ elaborateInstallPlan verbosity platform compiler compilerprogdb pkgConfigDB
     lookupPerPkgOption :: (Package pkg, Monoid m)
                        => pkg -> (PackageConfig -> m) -> m
     lookupPerPkgOption pkg f =
+        -- This is where we merge the options from the project config that
+        -- apply to all packages, all project local packages, and to specific
+        -- named packages
         global `mappend` local `mappend` perpkg
       where
         global = f allPackagesConfig

cabal-install/changelog

@@ -46,6 +46,8 @@
 	* Added support for '--enable-tests' and '--enable-benchmarks' to
 	'cabal fetch' (#4948).
 	* Removed support for building cabal-install with GHC < 7.10.
+	* New 'all-packages' section in 'cabal.project' files that applies
+	options to all packages, not just those local to the project.
 
 2.0.0.1 Mikhail Glushenkov <[email protected]> December 2017
 	* Support for GHC's numeric -g debug levels (#4673).