From d4f80a50197f6ca0a3111510bf363b7d586d5591 Mon Sep 17 00:00:00 2001
From: Duncan Coutts <duncan@community.haskell.org>
Date: Sun, 24 Dec 2017 18:34:45 +0000
Subject: [PATCH] Add documentation for 'all-packages'

In the user guide, changelog and add a few code comments.
---
 Cabal/doc/nix-local-build.rst                          |  7 ++++++-
 .../Distribution/Client/ProjectConfig/Legacy.hs        | 10 ++++++++++
 cabal-install/Distribution/Client/ProjectPlanning.hs   |  3 +++
 cabal-install/changelog                                |  2 ++
 4 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/Cabal/doc/nix-local-build.rst b/Cabal/doc/nix-local-build.rst
index cf94b1898b1..e6d0b7b2132 100644
--- a/Cabal/doc/nix-local-build.rst
+++ b/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``::
diff --git a/cabal-install/Distribution/Client/ProjectConfig/Legacy.hs b/cabal-install/Distribution/Client/ProjectConfig/Legacy.hs
index 814313f1e9a..b4f2af997db 100644
--- a/cabal-install/Distribution/Client/ProjectConfig/Legacy.hs
+++ b/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 {
diff --git a/cabal-install/Distribution/Client/ProjectPlanning.hs b/cabal-install/Distribution/Client/ProjectPlanning.hs
index 6f77825bf59..c49bb114bee 100644
--- a/cabal-install/Distribution/Client/ProjectPlanning.hs
+++ b/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
diff --git a/cabal-install/changelog b/cabal-install/changelog
index 9ed760eb5ac..6b75f287a55 100644
--- a/cabal-install/changelog
+++ b/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 <mikhail.glushenkov@gmail.com> December 2017
 	* Support for GHC's numeric -g debug levels (#4673).