Merge branch 'stable'

Author: mpilgrem

doc/build_command.md

@@ -85,6 +85,13 @@ supported syntaxes for targets are:
     of the test suite and benchmark components, respectively, are selected to be
     built.
 
+    Stackage snapshots do not include directly the packages in GHC's global
+    package database which come with GHC (GHC boot libraries). For example, if
+    `Cabal` is not a local package or an extra dep, then `stack build Cabal`
+    will specify the latest version of that package in the package index, which
+    may differ from the version provided by the version of GHC specified by the
+    snapshot.
+
 *   *package identifier*, e.g. `stack build foobar-1.2.3`, is usually used to
     include specific package versions from the package index. If the version
     selected conflicts with an existing local package or extra dep, then Stack

doc/ghc_command.md

@@ -15,4 +15,7 @@ option.
 Pass the option `--package <package>` to add the initial GHC argument
 `-package-id=<unit_id>`, where `<unit_id>` is the unit ID of the specified
 package in the installed package database. The option can be specified multiple
-times.
+times. Alternatively, the option `--package "<packages>"` can be used, where
+`<packages>` is a white space-delimited list of packages. The approach taken to
+these packages is the same as if they were specified as targets to
+[`stack build`](build_command.md#target-syntax).

doc/run_command.md

@@ -29,7 +29,9 @@ The `--cwd` option can be used to set the working directory before the
 executable is run.
 
 The `--package` option (which can be specified multiple times) can be used to
-add a package name to build targets.
+add a package name to build targets. Alternatively, the option
+`--package "<packages>"` can be used, where `<packages>` is a white
+space-delimited list of packages.
 
 The `--rts-options` option (which can be specified multiple times) can be used
 to pass a list of GHC's

doc/runghc_command.md

@@ -16,4 +16,7 @@ option.
 Pass the option `--package <package>` to add the initial GHC argument
 `-package-id=<unit_id>`, where `<unit_id>` is the unit ID of the specified
 package in the installed package database. The option can be specified multiple
-times.
+times. Alternatively, the option `--package "<packages>"` can be used, where
+`<packages>` is a white space-delimited list of packages. The approach taken to
+these packages is the same as if they were specified as targets to
+[`stack build`](build_command.md#target-syntax).