Merge branch 'stable'

doc/README.md

@@ -121,6 +121,10 @@ version of GHC.
     use GHCup) is to download and install the
     [Windows installer](https://get.haskellstack.org/stable/windows-x86_64-installer.exe).
 
+    !!! info
+
+        By default, the Windows installer will set the Stack root to `C:\sr`.
+
     !!! warning
 
         The Windows installer for Stack 2.9.1, 2.9.3 and 2.11.1 (only) will

doc/build_command.md

@@ -234,21 +234,44 @@ Set the flag to build nothing and output information about the build plan.
 
 ### `--flag` option
 
+The option can be specified multiple times. It has two forms:
+
+* `--flag <package_name>:[-]<flag_name>`; and
+
+* `--flag *:[-]<flag_name>`.
+
 `stack build --flag <package_name>:[-]<flag_name>` sets (or unsets) the
-specified Cabal flag for the specified package.
+specified Cabal flag for the specified package. Stack will report an error if:
 
-This option can be specified multiple times to set (or unset) multiple Cabal
-flags.
+* a package of that name is not known to Stack; or
 
-The same Cabal flag name can be set (or unset) for multiple packages (at the
-command line only) with:
+* a flag of that name is not a flag of that package.
 
-~~~text
-stack build --flag *:[-]<flag_name>
-~~~
+This overrides:
+
+* any Cabal flag specifications for the package in Stack's project-level
+  configuration file (`stack.yaml`); and
+
+* any use of `--flag *` (see below).
+
+`stack build --flag *:[-]<flag_name>` sets (or unsets) the specified Cabal flag
+for all packages (project packages and dependencies) (whether or not a flag of
+that name is a flag of the package).
+
+This overrides any Cabal flag specifications for packages in Stack's
+project-level configuration file (`stack.yaml`).
+
+!!! note
+
+    In order to set a Cabal flag for a GHC boot package, the package must be
+    specified as an [extra-dep](yaml_configuration.md#extra-deps).
+
+!!! warning
 
-In order to set a Cabal flag for a GHC boot package, the package must be
-specified as an extra-dep.
+    Stack creates snapshots when building immutable dependencies of projects.
+    The names of Cabal flags that have been set manually as disabled distinguish
+    one such snapshot from another. However, the names of Cabal flags that have
+    been set manually as enabled do not do so.
 
 ### `--[no-]force-dirty` flag
 

doc/install_and_upgrade.md

@@ -487,6 +487,11 @@ GitHub repository.
     use GHCup) is to download and use the
     [Windows installer](https://get.haskellstack.org/stable/windows-x86_64-installer.exe).
 
+    !!! info "Stack root"
+
+        By default, the Windows installer will set the Stack root by setting the
+        `STACK_ROOT` environment variable to `C:\sr`. 
+
     !!! warning "Long user PATH environment variable"
 
         The Windows installer for Stack 2.9.1, 2.9.3 and 2.11.1 (only) will

doc/yaml_configuration.md

@@ -311,8 +311,17 @@ If a specified Cabal flag for a package included directly in a snapshot is
 different to the Cabal flag specified for that package in the snapshot, then the
 package will automatically be promoted to be an [extra-dep](#extra-deps).
 
-In order to set a Cabal flag for a GHC boot package, the package must be
-specified as an [extra-dep](#extra-deps).
+!!! note
+
+    In order to set a Cabal flag for a GHC boot package, the package must be
+    specified as an [extra-dep](#extra-deps).
+
+!!! warning
+
+    Stack creates snapshots when building immutable dependencies of projects.
+    The names of Cabal flags that have been set manually as disabled distinguish
+    one such snapshot from another. However, the names of Cabal flags that have
+    been set manually as enabled do not do so.
 
 ### drop-packages