Merge branch 'stable'

Author: mpilgrem

doc/topics/GHC_from_source.md

@@ -122,6 +122,20 @@ The Hadrian build system has certain
 It requires certain versions of the `happy` and `alex` executables on the PATH.
 Stack will build and install `happy` and `alex`, if not already on the PATH.
 
+!!! note
+
+    If `happy` and/or `alex` is already on the PATH, it may not be a version
+    that Hadrian supports. In that case, you may wish to remove that version
+    from the PATH and ensure that the package version specified by
+    `hadrian/stack.yaml` or, if applicable, via the contents of the `STACK` environment variable is an appropriate one.
+
+!!! note
+
+    `alex-3.5.0.0` removed `-v` as an alias for `--version` and added `-v` as an
+    alias for `--verbose` (a flag that is not implemented as of `alex-3.5.4.0`).
+
+    Hadrian may expect `-v` to be an alias for `--version`.
+
 === "macOS"
 
     Hadrian requires, or case use, certain tools or Python packages that do not

doc/tutorial/cabal_flags_and_ghc_options.md

@@ -7,6 +7,35 @@ flags and with GHC options.
 
 ## Cabal flags
 
+A package description may specify one or more Cabal flags:
+
+=== "Cabal file"
+
+    ~~~text
+    flag my-flag-name
+      description: My (optional) description of my flag.
+      default: false -- Optional: the default value is true
+      manual: true -- Optional: the default value is false
+    ~~~
+
+=== "`package.yaml` (Hpack)"
+
+    ~~~yaml
+    flags:
+      my-flag-name:
+        description: My (optional) description of my flag.
+        default: true # Required
+        manual: false # Required
+    ~~~
+
+??? question "How does `manual: false` affect Stack's builds?"
+
+    `manual: false` has different implications for Cabal and Stack. Cabal tries
+    to 'solve' dependencies using the flag’s default value and, if it can't,
+    tries again with the negated default value. Stack emphasises reproducible
+    builds. It only tries to build with the flag's default value and, if it
+    can't, reports that it can't.
+
 Cabal flags can be set or unset at the command line or as a project-specific
 Stack option.