packages feed

stack 3.1.1 → 3.3.1

raw patch · 115 files changed

+2707/−1465 lines, 115 filesdep ~Win32dep ~arraydep ~bytestring

Dependency ranges changed: Win32, array, bytestring, conduit, containers, crypton, filepath, generic-deriving, ghc-boot, hashable, hi-file-parser, hpc, hspec, http-conduit, stm, template-haskell, text, unix-compat, vector, zlib

Files

CONTRIBUTING.md view
@@ -87,12 +87,19 @@ in responding to such matters is greatly appreciated.
 
 While support-related matters can be posted here as an 'issue', we encourage the
-use of other forums, in particular
-[Haskell's Discourse](https://discourse.haskell.org/). We also recommend
-Haskell's Discourse for general discussions about Stack's current or desired
-features. Stack is also discussed on Reddit's
-[Haskell community](https://www.reddit.com/r/haskell/).
+use of other forums, in particular the
+[Haskell Community](https://discourse.haskell.org/) forum. See its 'Learn'
+category. We also recommend that forum for general discussions about Stack's
+current or desired features.
 
+Stack is also discussed:
+
+* in the Haskell
+  [Stack and Stackage](https://matrix.to/#/#haskell-stack:matrix.org) room
+  (address `#haskell-stack:matrix.org`) on [Matrix](https://matrix.org/); and
+
+* on Reddit's [Haskell community](https://www.reddit.com/r/haskell/).
+
 We encourage use of those other forums because support-related discussions can
 clog up the issue tracker and make it more difficult to maintain the project.
 People needing support may also get a faster and fuller response on other
@@ -329,7 +336,7 @@ [documentation](https://github.com/commercialhaskell/stack/tree/master/doc/)
 updates with your pull request.
 
-## Backwards Compatability
+## Backwards Compatibility
 
 The Stack package provides a library and an executable (`stack`) that depends on
 the library. The library is intended for use only by the executable.
@@ -341,9 +348,8 @@ Stack aims to depend on well-known packages. The specific versions on which it
 depends at any time are specified by `package.yaml` and `stack.yaml`. It does
 not aim to be compatible with more than one version of the `Cabal` package at
-any time. At the time of writing (July 2024) the package versions are primarily
-ones in Stackage snapshot LTS Haskell 22.28 (for GHC 9.6.6), together with
-extra-deps to depend on the latest version of `hpack`, `pantry` and `tar`.
+any time. At the time of writing (December 2024) the package versions are
+primarily ones in Stackage snapshot LTS Haskell 23.0 (for GHC 9.8.4).
 
 A Stack executable makes use of Cabal (the library) through a small 'Setup'
 executable that it compiles from Haskell source code. The executable compiles
@@ -474,7 +480,7 @@ * Stack's imports are listed alphabetically, including `Stack.Prelude`, where
   applicable. The module names are left aligned, with space left for `qualified`
   where it is absent.
-* Stack's code is sufficiently stable that explict import lists can sensibly be
+* Stack's code is sufficiently stable that explicit import lists can sensibly be
   used. The exception is the import of `Stack.Prelude`. Not all modules have
   comprehensive explicit import lists.
 * Short explicit import lists follow the module name. Longer lists start on the
@@ -663,7 +669,7 @@ 
 [Stan](https://hackage.haskell.org/package/stan) is a Haskell static analysis
 tool. As of `stan-0.1.0.1`, it supports GHC >= 9.6.3 and Stack is built with
-GHC 9.6.6. The tool is configured by the contents of the `.stan.toml` file.
+GHC 9.8.4. The tool is configured by the contents of the `.stan.toml` file.
 
 This workflow will run if:
ChangeLog.md view
@@ -1,6 +1,52 @@ # Changelog
 
-## v3.1.1 2024-07-28
+## v3.3.1 - 2024-12-28
+
+**Changes since v3.1.1:**
+
+Behavior changes:
+
+* Stack interprets consecutive line ends in the value of the `user-message`
+  project-specific configuration option as a single blank line. Previously all
+  line ends were interpreted as white space.
+* Stack no longer supports Docker versions before Docker 1.9.1 and,
+  consequently, if a Docker container is not being run 'detached', its standard
+  input channel will always be kept open. (Before Docker 1.9.1 the use of an
+  interactive container could hang in certain circumstances.)
+* On Windows, Stack will always warn (message S-8432) if there is a space
+  character in Stack's 'programs' path, as GHC 9.4.1 and later do not work if
+  there is a space in the path to the `ghc` executable. S-8432 now presents as a
+  warning and not an error.
+* Stack respects the `--no-run-tests` and `--no-run-benchmarks` flags when
+  determining build actions. Previously Stack respected the flags when executing
+  the run test suites or run benchmarks actions for each targeted project
+  package.
+
+Other enhancements:
+
+* Consider GHC 9.10 to be a tested compiler and remove warnings.
+* Consider Cabal 3.12 to be a tested library and remove warnings.
+* Add flags `--run-tests` and `--run-benchmarks` (the existing defaults) to
+  Stack's `build` command, which take precedence over the existing
+  `no-run-tests` and `no-run-benchmarks` configuration options, respectively.
+* In configuration files, the `notify-if-no-run-tests` and
+  `notify-if-no-run-benchmarks` keys are introduced, to allow the exisitng
+  notification to be muted if unwanted.
+
+Bug fixes:
+
+* Stack's in-app messages refer to https://haskellstack.org as currently
+  structured. (Most URLs in older Stack versions are redirected.)
+* Stack's `upgrade` command only treats the current running Stack executable
+  as '`stack`' if the executable file is named `stack` or, on Windows,
+  `stack.exe`. Previously only how it was invoked was considered.
+* `stack test --no-run-tests --dry-run` no longer reports that Stack would test
+   project packages with test suites and
+   `stack bench --no-run-benchmarks --dry-run` no longer reports that Stack
+   would benchmark project packages with benchmarks.
+* `StackSetupShim` compiles with `Cabal >= 3.14.0.0`.
+
+## v3.1.1 - 2024-07-28
 
 Release notes:
README.md view
@@ -20,11 +20,7 @@ You can participate with the Stack community in the following areas:
 
 * the [Haskell Community](https://discourse.haskell.org/) forum
-* the Haskell Foundation's
-  [Slack workspace](https://haskell-foundation.slack.com/join/shared_invite/zt-z45o9x38-8L55P27r12YO0YeEufcO2w#/shared-invite/email)
-    * `#stack-users` channel, for general Stack discussion
-    * `#stack-collaborators` channel, for working on Stack's code base
-* the [Haskell Stack room](https://matrix.to/#/#haskell-stack:matrix.org) on
-  [Matrix](https://matrix.org/)
-* the [Google Group mailing list](https://groups.google.com/g/haskell-stack) for
-  Stack
+
+* the Haskell
+  [Stack and Stackage](https://matrix.to/#/#haskell-stack:matrix.org)
+  room (address `#haskell-stack:matrix.org`) on [Matrix](https://matrix.org/)
cabal.config view
@@ -2,30 +2,27 @@   , Cabal ==3.10.3.0
   , Cabal-syntax ==3.10.3.0
   , Glob ==0.10.2
-  , OneTuple ==0.4.1.1
+  , OneTuple ==0.4.2
   , QuickCheck ==2.14.3
   , StateVar ==1.2.2
-  , Win32 ==2.13.3.0
-  , aeson ==2.1.2.1
+  , Win32 ==2.13.4.0
+  , aeson ==2.2.3.0
   , aeson-warning-parser ==0.1.1
   , annotated-wl-pprint ==0.7.0
-  , ansi-terminal ==1.0.2
-  , ansi-terminal-types ==0.11.5
+  , ansi-terminal ==1.1.2
+  , ansi-terminal-types ==1.1
   , appar ==0.1.8
-  , array ==0.5.6.0
+  , array ==0.5.8.0
   , asn1-encoding ==0.9.6
   , asn1-parse ==0.9.5
   , asn1-types ==0.3.4
-  , assoc ==1.1
+  , assoc ==1.1.1
   , async ==2.2.5
   , attoparsec ==0.14.4
-  , attoparsec-aeson ==2.1.0.0
-  , attoparsec-iso8601 ==1.1.0.1
-  , auto-update ==0.1.6
-  , base ==4.18.2.1
-  , base-compat ==0.13.1
-  , base-compat-batteries ==0.13.1
-  , base-orphans ==0.9.2
+  , attoparsec-aeson ==2.2.2.0
+  , auto-update ==0.2.4
+  , base ==4.19.2.0
+  , base-orphans ==0.9.3
   , base16-bytestring ==1.0.2.0
   , base64-bytestring ==1.2.1.0
   , basement ==0.0.16
@@ -36,80 +33,86 @@   , blaze-html ==0.9.2.0
   , blaze-markup ==0.8.3.0
   , byteorder ==1.0.4
-  , bytestring ==0.11.5.3
+  , bytestring ==0.12.1.0
   , casa-client ==0.0.2
   , casa-types ==0.0.2
   , case-insensitive ==1.2.1.0
+  , cborg ==0.2.10.0
   , cereal ==0.5.8.3
+  , character-ps ==0.1
   , clock ==0.8.4
   , cmdargs ==0.10.22
   , colour ==2.3.6
-  , comonad ==5.0.8
+  , comonad ==5.0.9
   , companion ==0.1.0
-  , conduit ==1.3.5
+  , conduit ==1.3.6
   , conduit-combinators ==1.3.0
   , conduit-extra ==1.3.6
-  , containers ==0.6.7
+  , containers ==0.6.8
   , contravariant ==1.5.5
-  , cookie ==0.4.6
+  , cookie ==0.5.0
   , cryptohash-sha256 ==0.11.102.1
-  , crypton ==0.34
+  , crypton ==1.0.1
   , crypton-conduit ==0.2.3
-  , crypton-connection ==0.3.2
-  , crypton-x509 ==1.7.6
+  , crypton-connection ==0.4.3
+  , crypton-x509 ==1.7.7
   , crypton-x509-store ==1.6.9
   , crypton-x509-system ==1.6.7
-  , crypton-x509-validation ==1.6.12
-  , data-default-class ==0.1.2.0
-  , data-fix ==0.3.2
-  , deepseq ==1.4.8.1
+  , crypton-x509-validation ==1.6.13
+  , data-default ==0.7.1.3
+  , data-default-class ==0.1.2.2
+  , data-default-instances-containers ==0.1.0.3
+  , data-default-instances-dlist ==0.0.1.2
+  , data-default-instances-old-locale ==0.0.1.2
+  , data-fix ==0.3.4
+  , deepseq ==1.5.1.0
   , digest ==0.0.2.1
-  , directory ==1.3.8.4
+  , directory ==1.3.8.5
   , distributive ==0.6.2.1
   , dlist ==1.0
   , easy-file ==0.2.5
   , echo ==0.1.4
   , ed25519 ==0.0.5.0
   , exceptions ==0.10.7
-  , extra ==1.7.14
-  , fast-logger ==3.2.2
+  , extra ==1.7.16
+  , fast-logger ==3.2.5
   , file-embed ==0.0.16.0
   , filelock ==0.1.1.7
-  , filepath ==1.4.300.1
+  , filepath ==1.4.301.0
   , fsnotify ==0.4.1.0
-  , generic-deriving ==1.14.5
+  , generic-deriving ==1.14.6
   , generically ==0.1.1
   , ghc-bignum ==1.3
-  , ghc-boot ==9.6.6
-  , ghc-boot-th ==9.6.6
-  , ghc-prim ==0.10.0
+  , ghc-boot ==9.8.4
+  , ghc-boot-th ==9.8.4
+  , ghc-prim ==0.11.0
   , githash ==0.1.7.0
-  , hackage-security ==0.6.2.4
-  , hashable ==1.4.4.0
-  , hi-file-parser ==0.1.6.0
-  , hinotify ==0.4.1
+  , hackage-security ==0.6.2.6
+  , half ==0.3.2
+  , hashable ==1.4.7.0
+  , hi-file-parser ==0.1.7.0
   , hourglass ==0.2.12
   , hpack ==0.37.0
-  , hpc ==0.6.2.0
-  , http-api-data ==0.5.1
+  , hpc ==0.7.0.0
+  , http-api-data ==0.6.1
   , http-client ==0.7.17
-  , http-client-tls ==0.3.6.3
-  , http-conduit ==2.3.8.3
+  , http-client-tls ==0.3.6.4
+  , http-conduit ==2.3.9.1
   , http-download ==0.2.1.0
   , http-types ==0.12.4
-  , indexed-traversable ==0.1.3
-  , indexed-traversable-instances ==0.1.1.2
+  , indexed-traversable ==0.1.4
+  , indexed-traversable-instances ==0.1.2
   , infer-license ==0.2.0
-  , integer-conversion ==0.1.0.1
+  , integer-conversion ==0.1.1
   , integer-gmp ==1.1
   , integer-logarithms ==1.0.3.1
-  , iproute ==1.7.12
+  , iproute ==1.7.15
   , libyaml ==0.1.4
   , libyaml-clib ==0.2.5
-  , lift-type ==0.1.1.1
+  , lift-type ==0.1.2.0
   , lifted-base ==0.2.3.12
-  , lukko ==0.1.1.3
-  , megaparsec ==9.5.0
+  , lukko ==0.1.2
+  , megaparsec ==9.6.1
   , memory ==0.18.0
   , microlens ==0.4.13.1
   , microlens-mtl ==0.2.0.3
@@ -119,34 +122,34 @@   , monad-control ==1.0.3.1
   , monad-logger ==0.3.40
   , monad-loops ==0.4.3
-  , mono-traversable ==1.0.17.0
+  , mono-traversable ==1.0.20.0
   , mtl ==2.3.1
   , mtl-compat ==0.2.2
   , mustache ==2.4.2
   , neat-interpolation ==0.5.1.4
-  , network ==3.1.4.0
+  , network ==3.2.7.0
   , network-uri ==2.6.4.2
   , old-locale ==1.0.0.7
   , old-time ==1.1.0.4
   , open-browser ==0.2.1.0
   , optparse-applicative ==0.18.1.0
   , optparse-simple ==0.1.1.4
-  , os-string ==2.0.2.1
+  , os-string ==2.0.7
   , pantry ==0.10.0
-  , parsec ==3.1.16.1
+  , parsec ==3.1.17.0
   , parser-combinators ==1.3.0
   , path ==0.9.5
-  , path-io ==1.8.1
+  , path-io ==1.8.2
   , path-pieces ==0.2.1
   , pem ==0.2.4
-  , persistent ==2.14.6.1
+  , persistent ==2.14.6.3
   , persistent-sqlite ==2.13.3.0
   , persistent-template ==2.12.0.0
   , pretty ==1.1.3.6
   , prettyprinter ==1.7.1
   , prettyprinter-ansi-terminal ==1.1.3
-  , primitive ==0.8.0.0
-  , process ==1.6.19.0
+  , primitive ==0.9.0.0
+  , process ==1.6.25.0
   , project-template ==0.2.1.0
   , random ==1.2.1.2
   , resource-pool ==0.4.0.0
@@ -158,51 +161,55 @@   , rts ==1.0.2
   , safe ==0.3.21
   , safe-exceptions ==0.1.7.4
-  , scientific ==0.3.7.0
-  , semialign ==1.3
+  , scientific ==0.3.8.0
+  , semialign ==1.3.1
   , semigroupoids ==6.0.1
-  , silently ==1.2.5.3
+  , serialise ==0.2.6.1
+  , silently ==1.2.5.4
   , socks ==0.6.1
   , split ==0.2.5
   , splitmix ==0.1.0.5
-  , stack ==3.1.1
-  , static-bytes ==0.1.0
-  , stm ==2.5.1.0
+  , stack ==3.3.1
+  , static-bytes ==0.1.1
+  , stm ==2.5.3.1
   , stm-chans ==3.0.0.9
   , streaming-commons ==0.2.2.6
-  , strict ==0.5
+  , strict ==0.5.1
   , tagged ==0.8.8
-  , tar ==0.6.2.0
+  , tar ==0.6.3.0
   , tar-conduit ==0.4.1
-  , template-haskell ==2.20.0.0
+  , tasty ==1.5.2
+  , template-haskell ==2.21.0.0
   , temporary ==1.3
-  , text ==2.0.2
-  , text-metrics ==0.3.2
-  , text-short ==0.1.5
-  , th-abstraction ==0.5.0.0
-  , th-compat ==0.1.5
-  , th-lift ==0.8.4
+  , text ==2.1.1
+  , text-iso8601 ==0.1.1
+  , text-metrics ==0.3.3
+  , text-short ==0.1.6
+  , th-abstraction ==0.7.1.0
+  , th-compat ==0.1.6
+  , th-lift ==0.8.6
   , th-lift-instances ==0.1.20
-  , these ==1.2
+  , these ==1.2.1
   , time ==1.12.2
-  , time-compat ==1.9.6.1
-  , tls ==1.8.0
+  , time-compat ==1.9.7
+  , tls ==2.1.1
   , transformers ==0.6.1.0
   , transformers-base ==0.4.6
   , transformers-compat ==0.7.2
-  , typed-process ==0.2.11.1
-  , unix ==2.8.4.0
-  , unix-compat ==0.7.1
-  , unix-time ==0.4.12
+  , typed-process ==0.2.12.0
+  , unix ==2.8.6.0
+  , unix-compat ==0.7.3
+  , unix-time ==0.4.16
   , unliftio ==0.2.25.0
   , unliftio-core ==0.2.1.0
   , unordered-containers ==0.2.20
-  , uuid-types ==1.0.5.1
+  , uuid-types ==1.0.6
   , vault ==0.3.1.5
-  , vector ==0.13.1.0
-  , vector-algorithms ==0.9.0.1
+  , vector ==0.13.2.0
+  , vector-algorithms ==0.9.0.3
   , vector-stream ==0.1.0.1
-  , witherable ==0.4.2
+  , witherable ==0.5
   , yaml ==0.11.11.2
   , zip-archive ==0.4.3.2
-  , zlib ==0.6.3.0
+  , zlib ==0.7.1.0
+  , zlib-clib ==1.3.1
cabal.project view
@@ -33,8 +33,8 @@ -- specified by the snapshot specifed in Stack's project-level YAML
 -- configuration file (`stack.yaml`). The relevant version of GHC can be
 -- confirmed by reviewing the snapshot on Stackage. For example, at:
--- https://www.stackage.org/lts-22.28/cabal.config.
+-- https://www.stackage.org/lts-23.0/cabal.config.
 --
-with-compiler: ghc-9.6.6
+with-compiler: ghc-9.8.4
 import: cabal.config
 packages: .
doc/CONTRIBUTING.md view
@@ -87,12 +87,19 @@ in responding to such matters is greatly appreciated.
 
 While support-related matters can be posted here as an 'issue', we encourage the
-use of other forums, in particular
-[Haskell's Discourse](https://discourse.haskell.org/). We also recommend
-Haskell's Discourse for general discussions about Stack's current or desired
-features. Stack is also discussed on Reddit's
-[Haskell community](https://www.reddit.com/r/haskell/).
+use of other forums, in particular the
+[Haskell Community](https://discourse.haskell.org/) forum. See its 'Learn'
+category. We also recommend that forum for general discussions about Stack's
+current or desired features.
 
+Stack is also discussed:
+
+* in the Haskell
+  [Stack and Stackage](https://matrix.to/#/#haskell-stack:matrix.org) room
+  (address `#haskell-stack:matrix.org`) on [Matrix](https://matrix.org/); and
+
+* on Reddit's [Haskell community](https://www.reddit.com/r/haskell/).
+
 We encourage use of those other forums because support-related discussions can
 clog up the issue tracker and make it more difficult to maintain the project.
 People needing support may also get a faster and fuller response on other
@@ -329,7 +336,7 @@ [documentation](https://github.com/commercialhaskell/stack/tree/master/doc/)
 updates with your pull request.
 
-## Backwards Compatability
+## Backwards Compatibility
 
 The Stack package provides a library and an executable (`stack`) that depends on
 the library. The library is intended for use only by the executable.
@@ -341,9 +348,8 @@ Stack aims to depend on well-known packages. The specific versions on which it
 depends at any time are specified by `package.yaml` and `stack.yaml`. It does
 not aim to be compatible with more than one version of the `Cabal` package at
-any time. At the time of writing (July 2024) the package versions are primarily
-ones in Stackage snapshot LTS Haskell 22.28 (for GHC 9.6.6), together with
-extra-deps to depend on the latest version of `hpack`, `pantry` and `tar`.
+any time. At the time of writing (December 2024) the package versions are
+primarily ones in Stackage snapshot LTS Haskell 23.0 (for GHC 9.8.4).
 
 A Stack executable makes use of Cabal (the library) through a small 'Setup'
 executable that it compiles from Haskell source code. The executable compiles
@@ -474,7 +480,7 @@ * Stack's imports are listed alphabetically, including `Stack.Prelude`, where
   applicable. The module names are left aligned, with space left for `qualified`
   where it is absent.
-* Stack's code is sufficiently stable that explict import lists can sensibly be
+* Stack's code is sufficiently stable that explicit import lists can sensibly be
   used. The exception is the import of `Stack.Prelude`. Not all modules have
   comprehensive explicit import lists.
 * Short explicit import lists follow the module name. Longer lists start on the
@@ -663,7 +669,7 @@ 
 [Stan](https://hackage.haskell.org/package/stan) is a Haskell static analysis
 tool. As of `stan-0.1.0.1`, it supports GHC >= 9.6.3 and Stack is built with
-GHC 9.6.6. The tool is configured by the contents of the `.stan.toml` file.
+GHC 9.8.4. The tool is configured by the contents of the `.stan.toml` file.
 
 This workflow will run if:
doc/ChangeLog.md view
@@ -1,6 +1,52 @@ # Changelog
 
-## v3.1.1 2024-07-28
+## v3.3.1 - 2024-12-28
+
+**Changes since v3.1.1:**
+
+Behavior changes:
+
+* Stack interprets consecutive line ends in the value of the `user-message`
+  project-specific configuration option as a single blank line. Previously all
+  line ends were interpreted as white space.
+* Stack no longer supports Docker versions before Docker 1.9.1 and,
+  consequently, if a Docker container is not being run 'detached', its standard
+  input channel will always be kept open. (Before Docker 1.9.1 the use of an
+  interactive container could hang in certain circumstances.)
+* On Windows, Stack will always warn (message S-8432) if there is a space
+  character in Stack's 'programs' path, as GHC 9.4.1 and later do not work if
+  there is a space in the path to the `ghc` executable. S-8432 now presents as a
+  warning and not an error.
+* Stack respects the `--no-run-tests` and `--no-run-benchmarks` flags when
+  determining build actions. Previously Stack respected the flags when executing
+  the run test suites or run benchmarks actions for each targeted project
+  package.
+
+Other enhancements:
+
+* Consider GHC 9.10 to be a tested compiler and remove warnings.
+* Consider Cabal 3.12 to be a tested library and remove warnings.
+* Add flags `--run-tests` and `--run-benchmarks` (the existing defaults) to
+  Stack's `build` command, which take precedence over the existing
+  `no-run-tests` and `no-run-benchmarks` configuration options, respectively.
+* In configuration files, the `notify-if-no-run-tests` and
+  `notify-if-no-run-benchmarks` keys are introduced, to allow the exisitng
+  notification to be muted if unwanted.
+
+Bug fixes:
+
+* Stack's in-app messages refer to https://haskellstack.org as currently
+  structured. (Most URLs in older Stack versions are redirected.)
+* Stack's `upgrade` command only treats the current running Stack executable
+  as '`stack`' if the executable file is named `stack` or, on Windows,
+  `stack.exe`. Previously only how it was invoked was considered.
+* `stack test --no-run-tests --dry-run` no longer reports that Stack would test
+   project packages with test suites and
+   `stack bench --no-run-benchmarks --dry-run` no longer reports that Stack
+   would benchmark project packages with benchmarks.
+* `StackSetupShim` compiles with `Cabal >= 3.14.0.0`.
+
+## v3.1.1 - 2024-07-28
 
 Release notes:
doc/README.md view
@@ -150,6 +150,19 @@                 Systems with antivirus software may need to add Stack to the
                 list of 'trusted' applications.
 
+            ??? warning "I have a Windows username with a space in it"
+
+                GHC 9.4.1 and later have a bug which means they do not work if
+                the path to the `ghc` executable has a space character in it.
+                The default location for Stack's 'programs' directory will have
+                a space in the path if the value of the `USERNAME` environment
+                variable includes a space.
+
+                A solution is to configure Stack to use a different location for
+                its 'programs' directory. For further information, see the
+                [`local-programs-path`](configure/yaml/non-project.md#local-programs-path)
+                non-project specific configuration option documentation.
+
         === "Windows on Arm"
 
             The GHC project does not yet provide a version of GHC that runs on
@@ -404,7 +417,7 @@ [FAQ](faq.md).
 
 For general questions please post to the
-[Haskell Community](https://discourse.haskell.org/about).
+[Haskell Community](https://discourse.haskell.org/about) forum.
 
 ## Get involved!
doc/commands/bench_command.md view
@@ -16,9 +16,9 @@             [--[no-]copy-bins] [--[no-]copy-compiler-tool] [--[no-]prefetch]
             [--[no-]keep-going] [--[no-]keep-tmp-files] [--[no-]force-dirty]
             [--[no-]test] [--[no-]rerun-tests] [--ta|--test-arguments TEST_ARGS]
-            [--coverage] [--no-run-tests] [--test-suite-timeout ARG]
+            [--coverage] [--[no-]run-tests] [--test-suite-timeout ARG]
             [--[no-]tests-allow-stdin] [--[no-]bench]
-            [--ba|--benchmark-arguments BENCH_ARGS] [--no-run-benchmarks]
+            [--ba|--benchmark-arguments BENCH_ARGS] [--[no-]run-benchmarks]
             [--[no-]reconfigure] [--cabal-verbosity VERBOSITY |
               --[no-]cabal-verbose] [--[no-]split-objs] [--skip ARG]
             [--[no-]interleaved-output] [--ddump-dir ARG]
doc/commands/build_command.md view
@@ -16,9 +16,9 @@             [--[no-]copy-bins] [--[no-]copy-compiler-tool] [--[no-]prefetch]
             [--[no-]keep-going] [--[no-]keep-tmp-files] [--[no-]force-dirty]
             [--[no-]test] [--[no-]rerun-tests] [--ta|--test-arguments TEST_ARGS]
-            [--coverage] [--no-run-tests] [--test-suite-timeout ARG]
+            [--coverage] [--[no-]run-tests] [--test-suite-timeout ARG]
             [--[no-]tests-allow-stdin] [--[no-]bench]
-            [--ba|--benchmark-arguments BENCH_ARGS] [--no-run-benchmarks]
+            [--ba|--benchmark-arguments BENCH_ARGS] [--[no-]run-benchmarks]
             [--[no-]reconfigure] [--cabal-verbosity VERBOSITY |
               --[no-]cabal-verbose] [--[no-]split-objs] [--skip ARG]
             [--[no-]interleaved-output] [--ddump-dir ARG]
@@ -294,7 +294,7 @@     For a package included directly in the snapshot, if the Cabal flag
     specifications differ from the Cabal flag specifications (if any) in the
     snapshot, then the package will automatically be promoted to be an
-    [extra-dep](#extra-deps).
+    [extra-dep](../configure/yaml/project.md#extra-deps).
 
 !!! note
 
@@ -369,7 +369,7 @@ directory (see [`stack path --dist-dir`](path_command.md)).
 
 Unless flags are set to exclude the building of project packages, for each
-targetted project package with generated documentation, an archive of the
+targeted project package with generated documentation, an archive of the
 `<package_version>-docs` directory and its contents is in Stack's dist work
 directory. (The flags that exclude project packages are
 [`--only-dependencies`](#-only-dependencies-flag),
@@ -382,7 +382,7 @@   flag is ignored and `--haddock-hyperlink-source` is implied;
 * the [`--[no-]haddock-deps`](#-no-haddock-deps-flag) flag is ignored and the
   default value for the flag is implied;
-* the [`--[no-]haddock-internal`](#-no-haddock-hyperlink-internal-flag) flag is
+* the [`--[no-]haddock-internal`](#-no-haddock-internal-flag) flag is
   ignored and `--no-haddock-internal` is implied;
 * the [`--[no-]open`](#-no-open-flag) flag is ignored and `--no-open` is
   implied; and
@@ -614,13 +614,20 @@     The content of single quotes is taken literally. Within single quotes, `''`
     escapes a single quote.
 
-=== "Windows (PowerShell)"
+=== "Windows"
 
+    In PowerShell:
+
     `stack bench --benchmark-arguments '"''a single quoted string''"'`
 
     The content of single quotes is taken literally. Within single quotes, `''`
     escapes a single quote.
 
+!!! note "Runtime system (RTS) options"
+
+    RTS options must be quoted to prevent the RTS extracting them as its own
+    when the Stack executable is run.
+
 ### `--exec` option
 
 `stack build --exec '<command> [<argument(s)>]'` will run the specified command
@@ -650,13 +657,34 @@     The content of single quotes is taken literally. Within single quotes, `''`
     escapes a single quote.
 
-=== "Windows (PowerShell)"
+=== "Windows"
 
+    In PowerShell:
+
     `stack build --exec '<command> "''a single quoted string''"'`
 
     The content of single quotes is taken literally. Within single quotes, `''`
     escapes a single quote.
 
+### `--[no-]rerun-tests` flag
+
+Default: Enabled
+
+Unset the flag to disable the automatic running of targeted test-suites that
+have already been successful.
+
+### `--[no-]run-benchmarks` flag
+
+Default: Enabled
+
+Unset the flag to disable the automatic running of targeted benchmarks.
+
+### `--[no-]run-tests` flag
+
+Default: Enabled
+
+Unset the flag to disable the automatic running of targeted test suites.
+
 ### `--test-arguments`, `--ta` option
 
 `stack build --test --test-arguments=<argument(s)>` will pass the specified
@@ -687,13 +715,20 @@     The content of single quotes is taken literally. Within single quotes, `''`
     escapes a single quote.
 
-=== "Windows (PowerShell)"
+=== "Windows"
 
+    In PowerShell:
+
     `stack test --test-arguments '"''a single quoted string''"'`
 
     The content of single quotes is taken literally. Within single quotes, `''`
     escapes a single quote.
 
+!!! note "Runtime system (RTS) options"
+
+    RTS options must be quoted to prevent the RTS extracting them as its own
+    when the Stack executable is run.
+
 ## Flags affecting GHC's behaviour
 
 ### `--[no-]executable-profiling` flag
@@ -958,7 +993,7 @@ build output from GHC (as opposed to from Stack) in respect of dependencies is
 ignored. The behaviour then depends whether there is one target package or more
 than one. There can be one target if the project has a single package or if one
-package is targetted in a multi-package project (for example, using
+package is targeted in a multi-package project (for example, using
 `stack build <package_name>`).
 
 * **One target package:** The build output for the target package is sent to the
doc/commands/dot_command.md view
@@ -20,29 +20,34 @@ 
 By default:
 
-* external dependencies are excluded from the output. Pass the flag
-  `--external` to include external dependencies;
-* the `base` package and its dependencies are included in the output. Pass the
-  flag `--no-include-base` to exclude `base` and its dependencies;
-* there is no limit to the depth of the resolution of dependencies. Pass the
-  `--depth <depth>` option to limit the depth;
-* all relevant packages are included in the output. Pass the
-  `--prune <packages>` option to exclude the specified packages, where
-  `<packages>` is a list of package names separated by commas;
-* all packages in the project are included in the output. However, the target
-  for the command can be specified as an argument. It uses the same format
-  as the [`stack build` command](build_command.md);
-* test components of the packages in the project are excluded from the output.
-  Pass the flag `--test` to include test components; and
-* benchmark components of the packages in the project are excluded from the
-  output. Pass the flag `--bench` to include benchmark components.git p
-
-Pass the option `--flag <package_name>:<flag_name>` or
-`--flag <package_name>:-<flag_name>` to set or unset a Cabal flag. This
-option can be specified multiple times.
-
-Pass the flag `--global-hints` to use a hint file for global packages. If a hint
-file is used, GHC does not need to be installed.
+*   external dependencies are excluded from the output. Pass the flag
+    `--external` to include external dependencies;
+*   the `base` package and its dependencies are included in the output. Pass the
+    flag `--no-include-base` to exclude `base` and its dependencies;
+*   there is no limit to the depth of the resolution of dependencies. Pass the
+    `--depth <depth>` option to limit the depth;
+*   all relevant packages are included in the output. Pass the
+    `--prune <packages>` option to exclude the specified packages (including
+    project packages), where `<packages>` is a list of package names separated
+    by commas;
+*   for all relevant project packages, relevant dependencies are included in the
+    output. However, each project package for which dependencies are included
+    can be specified as a target argument. The argument uses the same format as
+    the [`stack build` command](build_command.md) but components of project
+    packages are ignored. Non-project packages are also ignored;
+*   Cabal flags are as specified by the package description files and the
+    project-level configuration file (`stack.yaml`, by default). Pass the
+    option `--flag <package_name>:<flag_name>` or
+    `--flag <package_name>:-<flag_name>` to set or unset a Cabal flag. This
+    option can be specified multiple times;
+*   test components of project packages are excluded from the output. Pass the
+    flag `--test` to include test components;
+*   benchmark components of project packages are excluded from the output. Pass
+    the flag `--bench` to include benchmark components; and
+*   global packages for the specified version of GHC are those specified by the
+    global package database of an installed GHC. Pass the flag `--global-hints`
+    to use a hint file for global packages. If a hint file is used, GHC does not
+    need to be installed.
 
 ## Examples
doc/commands/exec_command.md view
@@ -19,8 +19,10 @@ * the `GHC_PACKAGE_PATH` environment variable is set for the command's process.
   Pass the flag `--no-ghc-package-path` to not set the environment variable;
 
-* the `STACK_EXE` environment variable is set for the command's process. Pass
-  the flag `--no-stack-exe` to not set the environment variable; and
+* if the operating system provides a reliable way to determine it and where a
+  result was available, the `STACK_EXE` environment variable is set to the path
+  to the current Stack executable for the command's process. Pass the flag
+  `--no-stack-exe` to not set the environment variable; and
 
 * the specified executable is executed in the current directory. Pass the option
   `--cwd <directory>` to execute the executable in the specified directory.
@@ -58,7 +60,9 @@     The content of single quotes is taken literally. Within single quotes, `''`
     escapes a single quote.
 
-=== "Windows (PowerShell)"
+=== "Windows"
+
+    In PowerShell:
 
     `stack exec <command> -- '''a single quoted string'''`
doc/commands/ghci_command.md view
@@ -76,7 +76,7 @@     GHCi (only).
 
 *   Stack configures GHCi to hide unnecessary packages, unless no packages are
-    targetted and no additional packages are specified. Pass the
+    targeted and no additional packages are specified. Pass the
     `--package-hiding` flag to hide unnecessary packages or
     `--no-package-hiding` flag not to hide unnecessary packages.
 
@@ -131,6 +131,10 @@     The default for `<XDG_CACHE_HOME>` is `$HOME/.cache`.
 
 === "Windows"
+
+     On Windows, the default for `<XDG_CACHE_HOME>` is `$Env:LOCALAPPDATA`.
+
+=== "Windows (Command Prompt)"
 
      On Windows, the default for `<XDG_CACHE_HOME>` is `%LOCALAPPDATA%`.
doc/commands/haddock_command.md view
@@ -1,6 +1,6 @@ <div class="hidden-warning"><a href="https://docs.haskellstack.org/"><img src="https://cdn.jsdelivr.net/gh/commercialhaskell/stack/doc/img/hidden-warning.svg"></a></div>
 
-# The `stack bench` command
+# The `stack haddock` command
 
 ~~~text
 stack haddock [TARGET] [--dry-run] [--pedantic] [--fast] [--ghc-options OPTIONS]
@@ -16,10 +16,10 @@               [--[no-]copy-bins] [--[no-]copy-compiler-tool] [--[no-]prefetch]
               [--[no-]keep-going] [--[no-]keep-tmp-files] [--[no-]force-dirty]
               [--[no-]test] [--[no-]rerun-tests]
-              [--ta|--test-arguments TEST_ARGS] [--coverage] [--no-run-tests]
+              [--ta|--test-arguments TEST_ARGS] [--coverage] [--[no-]run-tests]
               [--test-suite-timeout ARG] [--[no-]tests-allow-stdin]
               [--[no-]bench] [--ba|--benchmark-arguments BENCH_ARGS]
-              [--no-run-benchmarks] [--[no-]reconfigure]
+              [--[no-]run-benchmarks] [--[no-]reconfigure]
               [--cabal-verbosity VERBOSITY | --[no-]cabal-verbose]
               [--[no-]split-objs] [--skip ARG] [--[no-]interleaved-output]
               [--ddump-dir ARG]
doc/commands/index.md view
@@ -10,6 +10,36 @@ information about some of those features, organised as a reference guide. Some
 of the features are complex and separate pages are dedicated to them.
 
+## stack command
+
+Stack is usually used with one of its commands (see further below). However:
+
+* `stack`, `stack --help` (or `-h`) lists Stack's commands, and flags and
+  options common to those commands;
+
+* `stack <command> --help` (or `-h`) — provides help on the particular Stack
+  command, including flags and options specific to the command; and
+
+* `stack --version` identifies the version and Git hash of the Stack executable.
+
+!!! info "Runtime system (RTS) options"
+
+    The Stack executable is built by GHC with the `-rtsopts=some` option. This
+    means that the RTS extracts command-line arguments bracketed between `+RTS`
+    and `-RTS` as its own when Stack is run. Only the following RTS
+    options are available:
+
+    *   `-?` (e.g. `stack +RTS -?`) causes the RTS to output information about
+        RTS options; and
+
+    *   `--info` (e.g. `stack +RTS --info`) causes the RTS to output information
+        about the RTS.
+
+    To avoid the RTS extracting such command-line arguments as its own when
+    using Stack commands such as [`exec`](exec_command.md),
+    [`test`](test_command.md) or [`bench`](bench_command.md), see the
+    documentation for those commands.
+
 ## Stack commands (thematic)
 
 ### Setting up
doc/commands/install_command.md view
@@ -16,10 +16,10 @@               [--[no-]copy-bins] [--[no-]copy-compiler-tool] [--[no-]prefetch]
               [--[no-]keep-going] [--[no-]keep-tmp-files] [--[no-]force-dirty]
               [--[no-]test] [--[no-]rerun-tests]
-              [--ta|--test-arguments TEST_ARGS] [--coverage] [--no-run-tests]
+              [--ta|--test-arguments TEST_ARGS] [--coverage] [--[no-]run-tests]
               [--test-suite-timeout ARG] [--[no-]tests-allow-stdin]
               [--[no-]bench] [--ba|--benchmark-arguments BENCH_ARGS]
-              [--no-run-benchmarks] [--[no-]reconfigure]
+              [--[no-]run-benchmarks] [--[no-]reconfigure]
               [--cabal-verbosity VERBOSITY | --[no-]cabal-verbose]
               [--[no-]split-objs] [--skip ARG] [--[no-]interleaved-output]
               [--ddump-dir ARG]
doc/commands/list_command.md view
@@ -31,8 +31,8 @@ ~~~text
 stack list base unix Win32 acme-missiles pantry
 base-4.20.0.1
-unix-2.8.5.1
-Win32-2.14.0.0
+unix-2.8.6.0
+Win32-2.14.1.0
 acme-missiles-0.3
 pantry-0.10.0
 
@@ -45,20 +45,20 @@          pantry, pretty, pasty, xattr, alloy, para, pappy, alure, polar and
          factory.
 
-stack --snapshot lts-22.28 list base unix Win32 acme-missiles pantry
+stack --snapshot lts-23.0 list base unix Win32 acme-missiles pantry
 Error: [S-4926]
        * Package does not appear in snapshot (directly or indirectly): acme-missiles.
 
-stack --snapshot lts-22.28 list base unix Win32 pantry
-base-4.18.2.1
-unix-2.8.4.0
-Win32-2.13.3.0
-pantry-0.9.3.2
+stack --snapshot lts-23.0 list base unix Win32 pantry
+base-4.19.2.0
+unix-2.8.6.0
+Win32-2.13.4.0
+pantry-0.10.0
 
-stack --snapshot lts-22.28 list
+stack --snapshot lts-23.0 list
 AC-Angle-1.0
 ALUT-2.4.0.3
 ...
+zot-0.0.3
 zstd-0.1.3.0
-zxcvbn-hs-0.3.6
 ~~~
doc/commands/ls_command.md view
@@ -34,27 +34,63 @@ or
 
 ~~~text
-stack ls dependencies [--separator SEP] [--[no-]license] [--filter ITEM]
+stack ls dependencies [--[no-]license] [--separator SEP] [--filter ITEM]
                       [--[no-]external] [--[no-]include-base] [--depth DEPTH]
                       [--prune PACKAGES] [TARGET] [--flag PACKAGE:[-]FLAG]
                       [--test] [--bench] [--global-hints]
 ~~~
 
-`stack ls dependencies` lists all of the packages and versions used for a
-project. All project packages are considered by default, but one or more targets
-can be specified as an argument. For further information, see the
-[target syntax](build_command.md#target-syntax) documentation.
+`stack ls dependencies` lists package versions used for a project.
 
-!!! note
+By default:
 
-    If the first target is one of `cabal`, `json`, `text` and `tree`, then a
-    subcommand must be specified.
+*   with the `text` or `tree` subcommand (see below), the package name is
+    followed by its version. Pass the `--license` flag to follow the package
+    name with its licence. (Consistent with the Cabal package description format
+    specification, only the American English spelling (license) is accepted.)
+*   With the `text` or `tree` subcommand, the separator between the package name
+    and what follows is a space character. Pass the `--separator` option to
+    specify a different separator;
+*   with the `text` command, all relevant package names are included. Pass the
+    `--filter` option to specify an item to be filtered out from the results, if
+    present. An item can be `$locals` (for all project packages) or a package
+    name. It can be specified multiple times;
 
-!!! info
+    !!! note
 
-    If a specified target is not a project package, then it will not contribute
-    packages to the command's output.
+        The special value `$locals` will need to be enclosed with single quotes
+        to distinguish it from a shell variable.
 
+*   external dependencies are excluded from the output. Pass the flag
+    `--external` to include external dependencies;
+*   the `base` package and its dependencies are included in the output. Pass the
+    flag `--no-include-base` to exclude `base` and its dependencies;
+*   there is no limit to the depth of the resolution of dependencies. Pass the
+    `--depth <depth>` option to limit the depth;
+*   all relevant packages are included in the output. Pass the
+    `--prune <packages>` option to exclude the specified packages (including
+    project packages), where `<packages>` is a list of package names separated
+    by commas;
+*   for all relevant project packages, relevant dependencies are included in the
+    output. However, each project package for which dependencies are included
+    can be specified as a target argument. The argument uses the same format as
+    the [`stack build` command](build_command.md) but components of project
+    packages are ignored. Non-project packages are also ignored;
+
+    !!! note
+
+        If the first target is one of `cabal`, `json`, `text` and `tree`, then a
+        subcommand must be specified.
+
+*   test components of project packages are excluded from the output. Pass the
+    flag `--test` to include test components;
+*   benchmark components of project packages are excluded from the output. Pass
+    the flag `--bench` to include benchmark components; and
+*   global packages for the specified version of GHC are those specified by the
+    global package database of an installed GHC. Pass the flag `--global-hints`
+    to use a hint file for global packages. If a hint file is used, GHC does not
+    need to be installed.
+
 Subcommands specify the format of the output, as follows:
 
 *   `cabal` lists the packages in the format of exact Cabal constraints.
@@ -107,9 +143,10 @@ *   `text` (the default) lists the packages, each on a separate line.
 
     ~~~text
-    stack ls dependencies text [--separator SEP] [--[no-]license] [--filter ITEM]
-                               [--[no-]external] [--[no-]include-base]
-                               [--depth DEPTH] [--prune PACKAGES] [TARGET]
+    stack ls dependencies text [--[no-]license] [--separator SEP]
+                               [--filter ITEM] [--[no-]external]
+                               [--[no-]include-base] [--depth DEPTH]
+                               [--prune PACKAGES] [TARGET]
                                [--flag PACKAGE:[-]FLAG] [--test] [--bench]
                                [--global-hints]
     ~~~
@@ -125,9 +162,11 @@ *   `tree` lists dependencies in the format of a tree.
 
     ~~~text
-    stack ls dependencies tree [--separator SEP] [--[no-]license] [--[no-]external]
-                               [--[no-]include-base] [--depth DEPTH]
-                               [--prune PACKAGES] [TARGET] [--flag PACKAGE:[-]FLAG] [--test] [--bench] [--global-hints]
+    stack ls dependencies tree [--[no-]license] [--separator SEP]
+                               [--[no-]external] [--[no-]include-base]
+                               [--depth DEPTH] [--prune PACKAGES] [TARGET]
+                               [--flag PACKAGE:[-]FLAG] [--test] [--bench]
+                               [--global-hints]
     ~~~
 
     For example (extract):
@@ -143,43 +182,6 @@       │ │ │ │   └── rts 1.0.2
       │ │ │ ├─┬ ghc-prim 0.8.0
     ~~~
-
-The `--separator` option, with the `text` or `tree` subcommand, specifies the
-separator between the package name and its version. The default is a space
-character.
-
-Set the `--license` flag, after the `text` or `tree` subcommand, to replace each
-package's version with its licence. (Consistent with the Cabal package
-description format specification, only the American English spelling (license)
-is accepted.)
-
-The `--filter` option, with the `text` subcommand, specifies an item to be
-filtered out from the results, if present. An item can be `$locals` (for all
-project packages) or a package name. It can be specified multiple times.
-
-!!! note
-
-    The special value `$locals` will need to be enclosed with single quotes to
-    distinguish it from a shell variable.
-
-Set the `--no-external` flag to exclude external dependencies.
-
-Set the `--no-include-base` flag to exclude dependencies on the `base` package.
-
-The `--depth` option limits the depth of dependency resolution.
-
-The `--prune <packages>` option prunes the specified packages and their
-dependencies from the tree of packages used to generate the output, where
-`<packages>` is a comma separated list of package names.
-
-The `--flag` option allows Cabal flags to be specified.
-
-Pass the `--test` flag to consider the dependencies of test suite components.
-
-Pass the `--bench` flag to consider the dependencies of benchmark components.
-
-Pass the `--global-hints` flag to use a hints file for global packages. The
-command then does not require an installed GHC.
 
 ## The `stack ls globals` command
doc/commands/new_command.md view
@@ -50,7 +50,7 @@ If a snapshot is specified at the command line and the project is initialised
 for use with Stack, `stack new` will try to use it. For further information, see
 the documentation for the
-[`--snapshot`](../configre/global_flags.md#-snapshot-option) and
+[`--snapshot`](../configure/global_flags.md#-snapshot-option) and
 [`--resolver`](../configure/global_flags.md#-resolver-option) options.
 
 ## Project templates
doc/commands/script_command.md view
@@ -40,7 +40,7 @@ ## GHC
 
 The `stack script` command behaves as if the
-[`--install-ghc`](../configure/global_flags.md#--no-install-ghc-flag) flag had
+[`--install-ghc`](../configure/global_flags.md#-no-install-ghc-flag) flag had
 been passed at the command line.
 
 ## Snapshot and extra-deps
@@ -49,7 +49,7 @@ For example:
 
 ~~~text
-stack script --snapshot lts-22.28 MyScript.hs
+stack script --snapshot lts-23.0 MyScript.hs
 ~~~
 
 A package version can be added to the snapshot on the command line with the
@@ -187,7 +187,7 @@ can be compiled and run, with arguments, with:
 
 ~~~text
-stack --snapshot lts-22.28 script --package acme-missiles --compile MyScript.hs -- "Don't panic!" "Duck and cover!"
+stack --snapshot lts-23.0 script --package acme-missiles --compile MyScript.hs -- "Don't panic!" "Duck and cover!"
 ~~~
 
 `acme-missiles-0.3` (the most recent version in the package index) will be used.
@@ -207,7 +207,7 @@ 
 ~~~haskell
 {- stack script
-   -- snapshot lts-22.28
+   -- snapshot lts-23.0
    -- extra-dep acme-missiles-0.2
    -- package acme-missiles
 -}
@@ -309,7 +309,7 @@ 
 ~~~haskell
 {- stack script
-   --snapshot lts-22.28
+   --snapshot lts-23.0
 -}
 
 {-# LANGUAGE OverloadedStrings #-}
doc/commands/sdist_command.md view
@@ -13,31 +13,29 @@ `stack sdist` generates a file for your package, in the format accepted by
 Hackage for uploads. The command will report the location of the generated file.
 
-## `--ignore-check` flag
-
-Pass the flag to disable checks of the package for common mistakes. By default,
-the command will check the package for common mistakes.
-
-## `--pvp-bounds` option
-
-The `--pvp-bounds <pvp_bounds_mode>` option determines whether and, if so, how
-PVP version bounds should be added to the Cabal file of the package. The
-available modes for basic use are: `none`, `lower`, `upper`, and `both`. The
-available modes for use with Cabal file revisions are `lower-revision`,
-`upper-revision` and `both-revision`.
+By default:
 
-For futher information, see the
-[`pvp-bounds`](../configure/yaml/non-project.md#pvp-bounds) non-project specific
-configuration option documentation.
+*   a file is generated for each project package. In the alternative, one or
+    more project package directories can be specified;
 
-## `--tar-dir` option
+*   the command will check the package for common mistakes. Pass the flag
+    `--ignore-check` to disable the checks;
 
-The `--tar-dir <path_to_directory>` option determines whether the package
-archive should be copied to the specified directory.
+*   Stack will not test the generated file by attempting to build it. Pass the
+    flag `--test-tarball` to cause Stack to test the generated file;
 
-## `--[no-]test-tarball` flag
+*   the generated file will be created in the `dist` directory of the project
+    package directory. For information about the directory's location, command
+    [`stack path --dist-dir`](path_command.md). Pass the option
+    ``--tar-dir <path_to_directory>` to also copy the file to the specified
+    directory; and
 
-Default: Disabled
+*   no PVP version bounds are added to the Cabal file of the package. Pass the
+    option `--pvp-bounds <pvp_bounds_mode>` to determine whether and, if so,
+    how bounds should be added. The available modes for basic use are: `none`,
+    `lower`, `upper`, and `both`. The available modes for use with Cabal file
+    revisions are `lower-revision`, `upper-revision` and `both-revision`.
 
-Set the flag to cause Stack to test the resulting package archive, by attempting
-to build it.
+    For futher information, see the
+    [`pvp-bounds`](../configure/yaml/non-project.md#pvp-bounds) non-project
+    specific configuration option documentation.
doc/commands/setup_command.md view
@@ -13,7 +13,7 @@ 
 * the version of GHC is the one required by the project. Specify the version of
   GHC as an argument to attempt to install a different version of GHC. For
-  example `stack setup 9.6.6` will attempt to install GHC 9.6.6; and
+  example `stack setup 9.8.4` will attempt to install GHC 9.8.4; and
 
 * an attempt to install is made only if the version of GHC is not already
   available to Stack. Pass the flag `--reinstall` (disabled by default) to
doc/commands/test_command.md view
@@ -16,9 +16,9 @@             [--[no-]copy-bins] [--[no-]copy-compiler-tool] [--[no-]prefetch]
             [--[no-]keep-going] [--[no-]keep-tmp-files] [--[no-]force-dirty]
             [--[no-]test] [--[no-]rerun-tests] [--ta|--test-arguments TEST_ARGS]
-            [--coverage] [--no-run-tests] [--test-suite-timeout ARG]
+            [--coverage] [--[no-]run-tests] [--test-suite-timeout ARG]
             [--[no-]tests-allow-stdin] [--[no-]bench]
-            [--ba|--benchmark-arguments BENCH_ARGS] [--no-run-benchmarks]
+            [--ba|--benchmark-arguments BENCH_ARGS] [--[no-]run-benchmarks]
             [--[no-]reconfigure] [--cabal-verbosity VERBOSITY |
               --[no-]cabal-verbose] [--[no-]split-objs] [--skip ARG]
             [--[no-]interleaved-output] [--ddump-dir ARG]
doc/commands/upgrade_command.md view
@@ -36,15 +36,17 @@   local binary directory (see `stack path --local-bin`) and named `stack`
   (replacing any existing executable named `stack` there);
 
-* if the current running Stack executable is named `stack` (or, on Windows,
-  `stack.exe`) (this is case insensitive), an existing binary distribution will
-  replace it. If the executable is located outside of Stack's local binary
-  directory, pass the `--only-local-bin` flag to skip that step;
+* if the current running Stack executable is '`stack`' (that is, it was invoked
+  as `stack` or, on Windows, `stack.exe` - this is case insensitive - and the
+  Stack executable file is named `stack` or, on Windows, `stack.exe` - this is
+  case sensitive), an existing binary distribution will replace it. If the
+  executable is located outside of Stack's local binary directory, pass the
+  `--only-local-bin` flag to skip that step;
 
-* if the current running Stack executable is named other than `stack` (and, on
-  Windows, `stack.exe`), an existing binary distribution will only be put in
-  Stack's local binary directory and named `stack`. Pass the
-  `--no-only-local-bin` flag to replace also the current running executable;
+* if the current running Stack executable is not '`stack`' (as described above),
+  an existing binary distribution will only be put in Stack's local binary
+  directory and named `stack`. Pass the `--no-only-local-bin` flag to replace
+  also the current running executable;
 
 * the new version will be the latest available. Pass the
   `--binary-version <version>` option to specify the version (this implies
@@ -85,9 +87,9 @@ * `stack upgrade --force-download` seeks an upgrade to the latest version of
   Stack available as a binary distribution for the platform, even if not newer.
 
-* If the Stack executable is named `my-stack`, `my-stack upgrade` seeks only to
-  put the latest version of Stack available as a binary distribution for the
-  platform, if newer, in Stack's local binary directory and name it `stack`.
+* If the Stack executable is invoked as `my-stack`, `my-stack upgrade` seeks
+  only to put the latest version of Stack available as a binary distribution for
+  the platform, if newer, in Stack's local binary directory and name it `stack`.
   `my-stack upgrade --no-only-local-bin` seeks also to upgrade `my-stack` to the
   latest version of Stack available.
doc/commands/upload_command.md view
@@ -101,7 +101,7 @@     stack upload .
     ~~~
 
-=== "Windows (with PowerShell)"
+=== "Windows"
 
     ~~~text
     $Env:HACKAGE_USERNAME='<username>'
@@ -109,6 +109,14 @@     stack upload .
     ~~~
 
+=== "Windows (Command Prompt)"
+
+    ~~~text
+    set HACKAGE_USERNAME=<username>
+    set HACKAGE_PASSWORD=<password>
+    stack upload .
+    ~~~
+
 ## The `HACKAGE_KEY` environment variable
 
 [:octicons-tag-24: 2.7.5](https://github.com/commercialhaskell/stack/releases/tag/v2.7.5)
@@ -127,9 +135,16 @@      stack upload .
      ~~~
 
-=== "Windows (with PowerShell)"
+=== "Windows"
 
      ~~~text
      $Env:HACKAGE_KEY=<api_authentification_token>
+     stack upload .
+     ~~~
+
+=== "Windows (Command Prompt)"
+
+     ~~~text
+     set HACKAGE_KEY=<api_authentification_token>
      stack upload .
      ~~~
doc/community/index.md view
@@ -8,7 +8,7 @@ ## Feedback and discussion
 
 * For general comments, feedback and support, please post to the
-  [Haskell Community](https://discourse.haskell.org/about).
+  [Haskell Community](https://discourse.haskell.org/about) forum.
 * For bugs, issues, or requests, please
   [open an issue](https://github.com/commercialhaskell/stack/issues/new).
 * When using Stack Overflow, please use the
doc/configure/environment_variables.md view
@@ -41,13 +41,20 @@      stack upload .
      ~~~
 
-=== "Windows (with PowerShell)"
+=== "Windows"
 
      ~~~text
      $Env:HACKAGE_KEY=<api_authentification_token>
      stack upload .
      ~~~
 
+=== "Windows (Command Prompt)"
+
+     ~~~text
+     set HACKAGE_KEY=<api_authentification_token>
+     stack upload .
+     ~~~
+
 ## `HACKAGE_USERNAME` and `HACKAGE_PASSWORD`
 
 [:octicons-tag-24: 2.3.1](https://github.com/commercialhaskell/stack/releases/tag/v2.3.1)
@@ -67,11 +74,19 @@     stack upload .
     ~~~
 
-=== "Windows (with PowerShell)"
+=== "Windows"
 
     ~~~text
     $Env:HACKAGE_USERNAME='<username>'
     $Env:HACKAGE_PASSWORD='<password>'
+    stack upload .
+    ~~~
+
+=== "Windows (Command Prompt)"
+
+    ~~~text
+    set HACKAGE_USERNAME=<username>
+    set HACKAGE_PASSWORD=<password>
     stack upload .
     ~~~
doc/configure/global_flags.md view
@@ -25,6 +25,27 @@ corresponding non-project specific configuration
 [option](yaml/non-project.md#arch).
 
+## `--bash-completion-index` option
+
+Visibility: Hidden
+
+See the [shell auto-completion](../topics/shell_autocompletion.md)
+documentation.
+
+## `--bash-completion-script` option
+
+Visibility: Hidden
+
+See the [shell auto-completion](../topics/shell_autocompletion.md)
+documentation.
+
+## `--bash-completion-index` option
+
+Visibility: Hidden
+
+See the [shell auto-completion](../topics/shell_autocompletion.md)
+documentation.
+
 ## `--color` or `-colour` options
 
 Pass the option `stack --color <when>` to specify when to use color in output.
@@ -73,6 +94,13 @@ information, see the documentation for the corresponding non-project specific
 configuration [option](yaml/non-project.md#extra-lib-dirs).
 
+## `--fish-completion-script` option
+
+Visibility: Hidden
+
+See the [shell auto-completion](../topics/shell_autocompletion.md)
+documentation.
+
 ## `--ghc-build` option
 
 Pass the option `--ghc-build <build>` to specify the relevant specialised GHC
@@ -85,6 +113,17 @@ For further information, see the documentation for the corresponding non-project
 specific configuration [option](yaml/non-project.md#ghc-variant).
 
+## `--help` or `-h` flags
+
+Pass the `--help` (or `-h`) flag to cause Stack to list its commands and flags
+and options common to those commands. Alternatively, command
+
+~~~text
+stack
+~~~
+
+for the same information.
+
 ## `--[no-]hpack-force` flag
 
 [:octicons-tag-24: 3.1.1](https://github.com/commercialhaskell/stack/releases/tag/v3.1.1)
@@ -341,6 +380,13 @@ path must be a relative one, relative to the the root directory of the project
 or package. The relative path cannot include a `..` (parent directory)
 component.
+
+## `--zsh-completion-script` option
+
+Visibility: Hidden
+
+See the [shell auto-completion](../topics/shell_autocompletion.md)
+documentation.
 
 ## `--setup-info-yaml` command option
doc/configure/yaml/index.md view
@@ -94,7 +94,7 @@ 
     * system-wide: `/etc/stack/config.yaml`; and
     * user-specific: `config.yaml` in the
-      [Stack root](../../topcis/stack_root.md).
+      [Stack root](../../topics/stack_root.md).
 
     !!! note
doc/configure/yaml/non-project.md view
@@ -38,7 +38,8 @@ Default: `false`
 
 Command line equivalent (takes precedence):
-[`stack build --[no-]allow-newer`](build_command.md#-allow-newer-flag) flag
+[`stack build --[no-]allow-newer`](../../commands/build_command.md#-no-allow-newer-flag)
+flag
 
 Whether to ignore lower and upper version bounds in Cabal files.
 
@@ -98,7 +99,8 @@ Default: `locals`
 
 Related command line:
-[`stack build --PROG-option`](../../commands/build_command.md#-prog-option-options) options
+[`stack build --PROG-option`](../../commands/build_command.md#-prog-option-options)
+options
 
 Determines to which packages all and any `--PROG-option` command line options
 specified on the command line are applied. Possible values are: `everything`
@@ -288,12 +290,12 @@ 
 Overrides the compiler version in the snapshot. Note that the `compiler-check`
 flag also applies to the version numbers. This uses the same syntax as compiler
-snapshots like `ghc-9.6.6`. This can be used to override the compiler for a
+snapshots like `ghc-9.8.4`. This can be used to override the compiler for a
 Stackage snapshot, like this:
 
 ~~~yaml
-snapshot: lts-22.28
-compiler: ghc-9.6.5
+snapshot: lts-23.0
+compiler: ghc-9.8.3
 compiler-check: match-exact
 ~~~
 
@@ -431,9 +433,10 @@ be able to find versions of those packages (on Hackage, etc.) that are
 compatible with the compiler.
 
-The easiest way to deal with this issue is to drop the offending packages as
-follows. Instead of using the packages specified in the snapshot, the global
-packages bundled with GHC will be used.
+The easiest way to deal with this issue is to use the
+[`drop-packages`](project.md#drop-packages) project-specific configuration
+option to drop the offending packages as follows. Instead of using the packages
+specified in the snapshot, the global packages bundled with GHC will be used.
 
 ~~~yaml
 drop-packages:
@@ -442,8 +445,9 @@ ~~~
 
 Another way to deal with this issue is to add the relevant packages as
-`extra-deps` built from source. To avoid mismatching versions, you can use
-exactly the same commit id you used to build GHC as follows:
+[`extra-deps`](project.md#extra-deps) built from source. To avoid mismatching
+versions, you can use exactly the same commit id you used to build GHC as
+follows:
 
 ~~~
 extra-deps:
@@ -492,7 +496,7 @@ [:octicons-tag-24: 2.1.1](https://github.com/commercialhaskell/stack/releases/tag/v2.1.1)
 
 Related command line (takes precedence):
-[`stack build --PROG-option`](../../commands/build_command.md#prog-option-options)
+[`stack build --PROG-option`](../../commands/build_command.md#-prog-option-options)
 options
 
 `configure-options` can specify Cabal (the library) options (including
@@ -532,19 +536,19 @@ 
 [:octicons-tag-24: 3.1.1](https://github.com/commercialhaskell/stack/releases/tag/v3.1.1)
 
-Default: As for the [`stack init`](init_command.md) command when no snapshot is
-specified at the command line.
+Default: As for the [`stack init`](../../commands/init_command.md) command when
+no snapshot is specified at the command line.
 
 Command line equivalent (takes precedence):
-[`--snapshot`](global_flags.md#snapshot-option) or
-[`--resolver`](global_flags.md#resolver-option) option
+[`--snapshot`](../global_flags.md#-snapshot-option) or
+[`--resolver`](../global_flags.md#-resolver-option) option
 
 This option specifies which snapshot to use with `stack init`, when none is
 specified at the command line.
 
 `default-init-snapshot: global` specifies the snapshot specified by the
 project-level configuration file in the `global-project` directory in the
-[Stack root](stack_root.md#global-project-directory).
+[Stack root](../../topics/stack_root.md#global-project-directory).
 
 ## default-template
 
@@ -664,14 +668,14 @@ 
 Specifies the location of an executable or `sh` shell script to be run after
 each attempted build with
-[`build --file-watch`](build_command.md#-file-watch-flag). An absolute or
-relative path can be specified. Changes to the configuration after the
-initial `build --file-watch` command are ignored.
+[`build --file-watch`](../../commands/build_command.md#-file-watch-flag). An
+absolute or relative path can be specified. Changes to the configuration after
+the initial `build --file-watch` command are ignored.
 
 If the project-level configuration is provided in the `global-project` directory
-in the [Stack root](stack_root.md), a relative path is assumed to be relative to
-the current directory. Otherwise, it is assumed to be relative to the directory
-of the project-level configuration file.
+in the [Stack root](../../topics/stack_root.md), a relative path is assumed to
+be relative to the current directory. Otherwise, it is assumed to be relative to
+the directory of the project-level configuration file.
 
 ## ghc-build
 
@@ -850,7 +854,7 @@ Default: `false`
 
 Command line equivalent (takes precedence):
-[`--hpack-force` option](global_flags.md#-no-hpack-force-flag)
+[`--hpack-force` option](../global_flags.md#-no-hpack-force-flag)
 
 Whether or not to allow Hpack to overwrite a Cabal file that has been modified
 manually. By default, Hpack 0.20.0 or later will decline to overwrite such a
@@ -924,25 +928,100 @@ 
 === "Windows"
 
-    Default: `%LOCALAPPDATA%\Programs\stack`, if the `%LOCALAPPDATA%`
+    Default: `$Env:LOCALAPPDATA\Programs\stack`, if the `LOCALAPPDATA`
     environment variable exists. Otherwise, the `programs` directory in the
     [Stack root](../../topics/stack_root.md).
 
     The MSYS2 tool is also installed in the Stack 'programs' directory.
 
-    !!! warning
+    !!! warning "Space character in the path to Stack's 'programs' directory"
 
         If there is a space character in the path to Stack's 'programs'
-        directory this may cause problems with building packages that make use
-        of the GNU project's `autoconf` package and `configure` shell script
-        files. That may be the case particularly if there is no corresponding
-        short name ('8 dot 3' name) for the directory in the path with the space
-        (which may be the case if '8 dot 3' names have been stripped or their
-        creation not enabled by default). If there are problems building, it
-        will be necessary to specify an alternative path that does not contain
-        space characters. Examples of packages on Hackage that make use of
-        `configure` are `network` and `process`.
+        directory this may cause problems:
 
+        *   with building packages that make use of the GNU project's `autoconf`
+            package and `configure` shell script files. That may be the case
+            particularly if there is no corresponding short name ('8 dot 3'
+            name) for the directory in the path with the space (which may be the
+            case if '8 dot 3' names have been stripped or their creation not
+            enabled by default). Examples of packages on Hackage that make use
+            of `configure` are `network` and `process`; and
+
+        *   building with GHC 9.4.1 and later. These versions of GHC have a bug
+            which means they do not work if the path to the `ghc` executable has
+            a space in it.
+
+        The default location for Stack's 'programs' directory will have a space
+        in the path if the value of the `USERNAME` environment variable includes
+        a space.
+
+        If there are problems building, it will be necessary to specify an
+        alternative path that does not contain spaces. For example, the
+        `programs` directory in the [Stack root](../../topics/stack_root.md)
+        (assuming that path is space-free). For example, if the relevant
+        directory is `C:\sr\programs`, add:
+        ~~~yaml
+        local-programs-path: C:\sr\programs
+        ~~~
+
+        to Stack's [global configuration](https://docs.haskellstack.org/en/stable/configure/yaml/#location-of-global-configuration)
+        file (`config.yaml`).
+
+        If that global configuration file does not yet exist, command:
+        ~~~text
+        stack --no-install-ghc setup
+        ~~~
+
+        to cause Stack to create it (without also installing GHC).
+
+=== "Windows (Command Prompt)"
+
+    Default: `%LOCALAPPDATA%\Programs\stack`, if the `LOCALAPPDATA`
+    environment variable exists. Otherwise, the `programs` directory in the
+    [Stack root](../../topics/stack_root.md).
+
+    The MSYS2 tool is also installed in the Stack 'programs' directory.
+
+    !!! warning "Space character in the path to Stack's 'programs' directory"
+
+        If there is a space character in the path to Stack's 'programs'
+        directory this may cause problems:
+
+        *   with building packages that make use of the GNU project's `autoconf`
+            package and `configure` shell script files. That may be the case
+            particularly if there is no corresponding short name ('8 dot 3'
+            name) for the directory in the path with the space (which may be the
+            case if '8 dot 3' names have been stripped or their creation not
+            enabled by default). Examples of packages on Hackage that make use
+            of `configure` are `network` and `process`; and
+
+        *   building with GHC 9.4.1 and later. These versions of GHC have a bug
+            which means they do not work if the path to the `ghc` executable has
+            a space in it.
+
+        The default location for Stack's 'programs' directory will have a space
+        in the path if the value of the `USERNAME` environment variable includes
+        a space.
+
+        If there are problems building, it will be necessary to specify an
+        alternative path that does not contain spaces. For example, the
+        `programs` directory in the [Stack root](../../topics/stack_root.md)
+        (assuming that path is space-free). For example, if the relevant
+        directory is `C:\sr\programs`, add:
+        ~~~yaml
+        local-programs-path: C:\sr\programs
+        ~~~
+
+        to Stack's [global configuration](https://docs.haskellstack.org/en/stable/configure/yaml/#location-of-global-configuration)
+        file (`config.yaml`).
+
+        If that global configuration file does not yet exist, command:
+        ~~~text
+        stack --no-install-ghc setup
+        ~~~
+
+        to cause Stack to create it (without also installing GHC).
+
 ## modify-code-page
 
 [:octicons-tag-24: 0.1.6.0](https://github.com/commercialhaskell/stack/releases/tag/v0.1.6.0)
@@ -992,7 +1071,7 @@ for details).
 
 For further information, see the
-[Nix integration](../../topics/nix_integration.md#configuration) documentation.
+[Nix integration](../../topics/nix_integration.md#non-project-specific-configuration) documentation.
 
 ## notify-if-arch-unknown
 
@@ -1030,6 +1109,24 @@ If Stack's integration with the Nix package manager is not enabled, should Stack
 notify the user if a `nix` executable is on the PATH?
 
+## notify-if-no-run-benchmarks
+
+[:octicons-tag-24: 3.3.1](https://github.com/commercialhaskell/stack/releases/tag/v3.3.1)
+
+Default: `true`
+
+Should Stack notify the user if the automatic running of a benchmark is
+prevented by the `--no-run-benchmarks` flag?
+
+## notify-if-no-run-tests
+
+[:octicons-tag-24: 3.3.1](https://github.com/commercialhaskell/stack/releases/tag/v3.3.1)
+
+Default: `true`
+
+Should Stack notify the user if the automatic running of a test suite is
+prevented by the `--no-run-tests` flag?
+
 ## package-index
 
 [:octicons-tag-24: 2.9.3](https://github.com/commercialhaskell/stack/releases/tag/v2.9.3)
@@ -1090,8 +1187,9 @@ 
 Default: `none`
 
-Command line equivalent (takes precedence): `stack sdist --pvp-bounds` option or
-`stack upload --pvp-bounds` option
+Command line equivalent (takes precedence):
+[`stack sdist --pvp-bounds`](../../commands/sdist_command.md) option or
+[`stack upload --pvp-bounds`](../../commands/upload_command.md) option
 
 !!! warning
 
@@ -1179,7 +1277,8 @@ Default: `true`
 
 Command line equivalent (takes precedence):
-[`stack upload --[no]-save-hackage-creds`](upload_command.md) option
+[`stack upload --[no]-save-hackage-creds`](../../commands/upload_command.md)
+option
 
 Controls whether, when using `stack upload`, the user's Hackage username and
 password are stored in a local file.
doc/configure/yaml/project.md view
@@ -30,8 +30,8 @@ ## snapshot
 
 Command line equivalent (takes precedence):
-[`--snapshot`](../global_flags.md#snapshot-option) or
-[`--resolver`](../global_flags.md#resolver-option) option
+[`--snapshot`](../global_flags.md#-snapshot-option) or
+[`--resolver`](../global_flags.md#-resolver-option) option
 
 The `snapshot` key specifies which snapshot is to be used for this project. A
 snapshot defines a GHC version, the package version of packages available for
@@ -39,10 +39,10 @@ resolver since a snapshot states how dependencies are resolved. There are
 currently four snapshot types:
 
-* LTS Haskell snapshots, e.g. `snapshot: lts-22.21`
-* Stackage Nightly snapshots, e.g. `snapshot: nightly-2024-05-06`
+* LTS Haskell snapshots, e.g. `snapshot: lts-23.0`
+* Stackage Nightly snapshots, e.g. `snapshot: nightly-2024-12-13`
 * No snapshot, just use packages shipped with the compiler. For GHC this looks
-  like `snapshot: ghc-9.6.5`
+  like `snapshot: ghc-9.8.4`
 * Custom snapshot, via a URL or relative file path. For further information, see
   the [snapshot location](../../topics/snapshot_location.md) documentation.
 
@@ -186,7 +186,7 @@ the same name. An extra-dep can be shadowed by a [project package](#packages) of
 the same name.
 
-!!! info
+!!! info "GHC wired-in packages"
 
     Some Haskell packages published on Hackage, for example `base` and `ghc`,
     are referred to as 'wired-in' to one or more versions of GHC or as 'magic'.
@@ -286,19 +286,21 @@ configuration and make any changes if needed. The user can delete this message
 if the generated configuration is acceptable.
 
+Consecutive line ends in the message are interpreted as a single blank line.
+
 For example, a user-message is inserted by `stack init` when it omits packages
 or adds external dependencies, namely:
 
 ~~~yaml
-user-message: ! 'Warning: Some packages were found to be incompatible with the resolver
-  and have been left commented out in the packages section.
-
-  Warning: Specified resolver could not satisfy all dependencies. Some external packages
-  have been added as dependencies.
+user-message: |
+  Warning (added by new or init): Some packages were found to be incompatible
+  with the snapshot and have been left commented out in the packages section.
 
-  You can omit this message by removing it from stack.yaml
+  Warning (added by new or init): Specified snapshot could not satisfy all
+  dependencies. Some external packages have been added as dependencies.
 
-'
+  You can omit this message by removing it from the project-level configuration
+  file.
 ~~~
 
 ## custom-preprocessor-extensions
doc/faq.md view
@@ -125,9 +125,9 @@ 
     ~~~text
     myproject/
-      stack-ghc-9.0.2.yaml
-      stack-ghc-9.2.4.yaml
-      stack.yaml --> symlink to stack-ghc-9.2.4.yaml
+      stack-ghc-9.8.4.yaml
+      stack-ghc-9.8.4.yaml
+      stack.yaml --> symlink to stack-ghc-9.8.4.yaml
       myproject.cabal
       src/
         ...
@@ -138,19 +138,25 @@ 
     === "Unix-like"
 
-        ~~~bash
-        stack build  # builds using the default stack.yaml
-        STACK_YAML=stack-ghc-7.10.yaml
-        stack build  # builds using the given yaml file
+        ~~~text
+        STACK_YAML=stack-ghc-9.8.4.yaml
+        stack build
         ~~~
 
-    === "Windows (with PowerShell)"
+    === "Windows"
 
-        ~~~ps
-        $Env:STACK_YAML='stack-ghc-9.0.2.yaml'
+        ~~~text
+        $Env:STACK_YAML='stack-ghc-9.8.4.yaml'
         stack build
         ~~~
 
+    === "Windows (Command Prompt)"
+
+        ~~~text
+        set STACK_YAML=stack-ghc-9.8.4.yaml
+        stack build
+        ~~~
+
 ## Setup-related
 
 ??? question "Where is Stack installed?"
@@ -181,9 +187,9 @@ 
 ??? question "On Windows, `stack setup` tells me to add certain paths to the PATH instead of doing it?"
 
-    With PowerShell, it is easy to automate even that step. Command:
+    In PowerShell, it is easy to automate even that step. Command:
 
-    ~~~ps
+    ~~~text
     $Env:Path = ( stack setup | %{ $_ -replace '[^ ]+ ', ''} ), $Env:Path -join ";"
     ~~~
 
@@ -313,6 +319,98 @@ 
 ## `stack build`-related
 
+??? question "Why does `stack build` fail with GHC 9.8.1 and 9.8.2 only?"
+
+    If the Cabal file of the relevant package makes use of a `c-sources` field,
+    the failure may be due to `Cabal-3.10.2.0` enforcing that the field can
+    specify only `*.c` files. Earlier and later versions of Cabal (the library)
+    tolerate other files.
+
+    When the Cabal build type is not `Custom`, Stack builds with the `Cabal`
+    boot package of the specified version of GHC. The boot package of GHC 9.8.1
+    and 9.8.2 is `Cabal-3.10.2.0`.
+
+??? question "What causes dependency on multiple versions of the same package?"
+
+    When building a package, during its configuration, Stack may warn:
+
+    ~~~text
+    This package indirectly depends on multiple versions of the same package.
+    This is very likely to cause a compile failure.
+    ~~~
+
+    and the build subsequently fails.
+
+    Often the cause is that: (1) the package depends, directly or indirectly, on
+    a GHC wired-in package (for example, the `ghc` package); and (2) a direct or
+    indirect dependency of that wired-in package is also specified as an
+    extra-dep but the versions differ.
+
+??? question "Why does `stack test` trigger a rebuild of other components?"
+
+    If the set of dependencies of a project package to be built are not a
+    subset of the set of dependencies when it was last built, then that will
+    trigger a rebuild of components that were previously built.
+
+    The command:
+
+    ~~~text
+    stack build
+    ~~~
+
+    will build the library and executable components of project packages and the
+    build will take into account the dependencies of those components.
+
+    If you then command:
+
+    ~~~text
+    stack test
+    ~~~
+
+    or, equivalently:
+
+    ~~~text
+    stack build --test
+    ~~~
+
+    the test suite components of project packages are added to the build
+    targets.
+
+    That can add dependencies to a project package, if its test suite
+    components have dependencies that are not dependencies of its library
+    and executable components.
+
+    What is true of test suite components applies equally to benchmark
+    components.
+
+    If that behaviour is undesirable, a way to avoid it is to change the
+    description of each project package so that adding its test suite (or
+    benchmark) components does not add dependencies to the package. That is,
+    to specify, in the package description, the dependencies as common to all
+    the components that you are switching between from one build to another.
+
+    For example, if you are using `package.yaml`, add the dependencies to its
+    top-level `dependencies` key.
+
+    Alternatively, build all components of project packages without running
+    tests or benchmarks once built. Add the following to a configuration file:
+
+    ~~~yaml
+    build:
+      test: true
+      test-arguments:
+        no-run-tests: true
+      bench: true
+      benchmark-opts:
+        no-run-benchmarks: true
+    ~~~
+
+    or command:
+
+    ~~~text
+    stack build --test --no-run-tests --bench --no-run-benchmarks
+    ~~~
+
 ??? question "How do I use a custom preprocessor?"
 
     See the
@@ -353,7 +451,7 @@     is as follows:
 
     * In the Cabal file, the following
-      [`ld-options`](https://cabal.readthedocs.io/en/stable/cabal-package.html#pkg-field-ld-options)
+      [`ld-options`](https://cabal.readthedocs.io/en/stable/cabal-package-description-file.html#pkg-field-ld-options)
       are set: `-static` and `-pthread`.
 
     * The Stack command is run in a Docker container based on Alpine Linux. The
@@ -406,49 +504,6 @@     See issue [#644](https://github.com/commercialhaskell/stack/issues/644) for more
     details.
 
-??? question "I get strange `ld` errors about recompiling with `-fPIC`"
-
-    (Updated in January 2019)
-
-    This is related to more recent versions of Linux distributions that have GCC
-    with PIE enabled by default. The continuously-updated distros like Arch, in
-    particular, had been in flux with this change and the upgrading
-    libtinfo6/ncurses6, and there were some workarounds attempted in Stack that
-    ended up causing trouble as these distros evolved.
-
-    GHC added official support for this setup in 8.0.2, so if you are using an
-    older version your best bet is to upgrade. You may be able to work around it
-    for older versions by editing `~/.stack/programs/x86_64-osx/ghc-VER/lib/ghc-
-    VER/settings` (replace `VER` with the GHC version) and adding `-no-pie` (or
-    `--no-pie` in the case of Gentoo, at least as of December 2017) to the __C
-    compiler link flags__.
-
-    If `stack setup` complains that there is no `linuxNN-*-nopie` bindist available,
-    try adding `ghc-build: *` (replacing the `*` with the actual value that
-    precedes `-nopie`, which may be empty) to your `~/.stack/config.yaml` (this
-    will no longer be necessary for stack >= 1.7).
-
-    If you are experiencing this with GHC >= 8.0.2, try running
-    `stack setup --reinstall` if you've upgraded your Linux distribution or you set
-    up GHC before late December 2017.
-
-    If GHC doesn't recognize your C compiler as being able to use `-no-pie`, this
-    can happen even with GCC and Clang, it might be necessary to enable this feature
-    manually. To do this, just change
-    `("C compiler supports -no-pie", "NO"),` to
-    `("C compiler supports -no-pie", "YES"),`
-    in the file `~/.stack/programs/x86_64-osx/ghc-VER/lib/ghc-VER/settings`.
-
-    If you are still having trouble after trying the above, check the following for
-    more possible workarounds:
-
-      * Previous version of this [FAQ entry](https://docs.haskellstack.org/en/v1.6.3/faq/#i-get-strange-ld-errors-about-recompiling-with-fpic)
-      * Related issues:
-        [#3518](https://github.com/commercialhaskell/stack/issues/3518),
-        [#2712](https://github.com/commercialhaskell/stack/issues/2712),
-        [#3630](https://github.com/commercialhaskell/stack/issues/3630),
-        [#3648](https://github.com/commercialhaskell/stack/issues/3648)
-
 ??? question "Where does the output from `--ghc-options=-ddump-splices` (and other `-ddump*` options) go?"
 
     These are written to `*.dump-*` files inside the package's `.stack-work`
@@ -565,6 +620,11 @@     Stack. See issue [#399](https://github.com/commercialhaskell/stack/issues/399)
     for the ongoing effort and information on workarounds.
 
+??? question "I have a Windows username with a space in it and problems building"
+
+    See the [`local-programs-path`](configure/yaml/non-project.md#local-programs-path)
+    non-project specific configuration option documentation for advice.
+
 ??? question "How to get a working executable on Windows?"
 
     When executing a binary after building with `stack build` (e.g. for target
@@ -588,14 +648,3 @@     https://msdn.microsoft.com/de-de/library/7d83bc18.aspx).
 
     See issue [#425](https://github.com/commercialhaskell/stack/issues/425).
-
-    Another issue that may arise with building on Windows is as follows. The default
-    location of Stack's programs folder is `%LOCALAPPDATA\Programs\stack`. If there
-    is a space character in the `%LOCALAPPDATA%` path this may, in some
-    circumstances, cause problems with building packages that make use of the GNU
-    project's `autoconf` package and `configure` shell script files. It may be
-    necessary to override the default location of Stack's programs folder. See the
-    [local-programs-path](configure/yaml/non-project.md#local-programs-path) option
-    for more information.
-
-    See issue [#4726](https://github.com/commercialhaskell/stack/issues/4726).
doc/glossary.md view
@@ -4,58 +4,60 @@ 
 The following terms are used in Stack's documentation.
 
-|Term               |Meaning                                                   |
-|-------------------|----------------------------------------------------------|
-|Cabal              |The Haskell Common Architecture for Building Applications and Libraries, provided by the [`Cabal` package](https://hackage.haskell.org/package/Cabal). Also referred to as Cabal (the library) to distinguish it from Cabal (the tool).|
-|Cabal file|A file containing a [package description](https://cabal.readthedocs.io/en/stable/cabal-package.html) used by Cabal, named `<package_name>.cabal`.|
-|Cabal (the tool)|The Haskell tool used for building provided by the [`cabal-install` package](https://hackage.haskell.org/package/cabal-install).|
-|CI                 |Continuous integration.                                   |
-|CMake              |A [system](https://cmake.org/) for managing build processes.|
-|`config.yaml`      |A global and non-project-specific configuration file used by Stack.|
-|dependency         |A Haskell package other than a project package and on which a project package depends (directly or indirectly), located locally or elsewhere.|
-|Docker             |A [platform](https://www.docker.com/) for developing,  shipping, and running applications. It can package and run an application in a loosely isolated environment called a _container_.|
-|Emacs              |[GNU Emacs](https://www.gnu.org/software/emacs/), an extensible, customisable text editor.|
-|extra-deps         |Extra dependencies (one version of each) that add to, or shadow, those specified in a snapshot.|
-|FreeBSD            |A Unix-like operating system.                             |
-|GCC                |The [GNU Compiler Collection](https://gcc.gnu.org/) or its executable `gcc`.|
-|GHC                |The [Glasgow Haskell Compiler](https://www.haskell.org/ghc/).|
-|GHC boot package   |A package that comes with GHC, is included in GHC's global package database, and is not included in a Stackage snapshot. See the output of command `stack exec -- ghc-pkg list --global`.|
-|GHCi               |GHC's [interactive environment](https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/ghci.html).|
-|GHCJS              |A Haskell to JavaScript [compiler](https://github.com/ghcjs/ghcjs).|
-|GHCup              |An [installer](https://www.haskell.org/ghcup/) for Haskell.
-|Git                |A [distributed version control system](https://git-scm.com/).|
-|GPG                |The [GNU Privacy Guard](https://gnupg.org/) or GnuPG, software that allows you to encrypt or sign your data and communications.|
-|Hackage            |The [Haskell Package Repository](https://hackage.haskell.org/).
-|Haddock            |The [document generation tool](https://hackage.haskell.org/package/haddock) for Haskell libraries.|
-|'Haskell' extension|The ['Haskell' extension]() for VS Code.                  |
-|HLS                |[Haskell Language Server](https://haskell-language-server.readthedocs.io/en/latest/), an implementation of the Language Server Protocol for Haskell.|
-|Homebrew           |A [package manager](https://brew.sh/) for macOS or Linux, or its executable `brew`.|
-|Hoogle             |A Haskell API [search engine](https://hoogle.haskell.org/).|
-|Hpack              |A [format](https://github.com/sol/hpack) for Haskell packages or the executable `hpack` that produces a Cabal file from `package.yaml`.|
-|Linux              |A family of operating systems based on the Linux kernel.  |
-|macOS              |The primary operating system for Apple's Mac computers. Previously known as Mac OS X or OS X.|
-|Make               |A [build automation tool](https://www.gnu.org/software/make/).|
-|MSYS2              |The [MSYS2](https://www.msys2.org/) software distribution and building platform for Windows.|
-|Nix                |A purely functional [package manager](https://nixos.org/), available for Linux and macOS.|
-|package            |A Haskell package is an organised collection of Haskell code and related files. It is described by a Cabal file or a `package.yaml` file, which is itself part of the package.|
-|`package.yaml`     |A file that describes a package in the Hpack format.      |
-|Pantry             |A library for content-addressable Haskell package management, provided by the [`pantry` package](https://hackage.haskell.org/package/pantry). A dependency of Stack.|
-|PATH               |The `PATH` environment variable, specifying a list of directories searched for executable files.|
-|project            |A Stack project is a local directory that contains a project-level configuration file (`stack.yaml`, by default). A project may relate to more than one project package.|
-|project package    |A Haskell package that is part of a project and located locally. Distinct from a dependency located locally.|
-|PVP                |The Haskell [Package Versioning Policy](https://pvp.haskell.org/), which tells developers of libraries how to set their version numbers.|
-|REPL               |An interactive (run-eval-print loop) programming environment.|
-|resolver           |A synonym for snapshot.                                   |
-|`Setup.hs`         |A project-specific file used by Cabal to perform setup tasks.|
-|snapshot           |A snapshot defines a GHC version, a set of packages (one version of each), and build flags or other settings.|
-|Stack              |The Haskell Tool Stack project or its executable `stack`. |
-|`stack.yaml`       |A project-level configuration file used by Stack, which may also contain non-project-specific options.|
-|Stackage           |A [distribution](https://www.stackage.org/) of compatible Haskell packages.|
-|Stack root         |A directory in which Stack stores important files. See `stack path --stack-root`. On Windows, or if Stack is configured to use the XDG Base Directory Specification, Stack also stores important files outside of the Stack root.|
+|Term                |Meaning                                                  |
+|--------------------|---------------------------------------------------------|
+|Cabal               |The Haskell Common Architecture for Building Applications and Libraries, provided by the [`Cabal` package](https://hackage.haskell.org/package/Cabal). Also referred to as Cabal (the library) to distinguish it from Cabal (the tool).|
+|Cabal file          |A file containing a [package description](https://cabal.readthedocs.io/en/stable/cabal-package-description-file.html) used by Cabal, named `<package_name>.cabal`.|
+|Cabal (the tool)    |The Haskell tool used for building provided by the [`cabal-install` package](https://hackage.haskell.org/package/cabal-install).|
+|CI                  |Continuous integration.                                  |
+|CMake               |A [system](https://cmake.org/) for managing build processes.|
+|`config.yaml`       |A global and non-project-specific configuration file used by Stack.|
+|dependency          |A Haskell package other than a project package and on which a project package depends (directly or indirectly), located locally or elsewhere.|
+|Docker              |A [platform](https://www.docker.com/) for developing,  shipping, and running applications. It can package and run an application in a loosely isolated environment called a _container_.|
+|Emacs               |[GNU Emacs](https://www.gnu.org/software/emacs/), an extensible, customisable text editor.|
+|extra-deps          |Extra dependencies (one version of each) that add to, or shadow, those specified in a snapshot.|
+|FreeBSD             |A Unix-like operating system.                            |
+|GCC                 |The [GNU Compiler Collection](https://gcc.gnu.org/) or its executable `gcc`.|
+|GHC                 |The [Glasgow Haskell Compiler](https://www.haskell.org/ghc/).|
+|GHC boot package    |A package that comes with GHC, is included in GHC's global package database, and is not included in a Stackage snapshot. See the output of command `stack exec -- ghc-pkg list --global`.|
+|GHC wired-in package|A GHC boot package that cannot be shaddowed with different versions of the same package. Also referred to as 'magic'.|
+|GHCi                |GHC's [interactive environment](https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/ghci.html).|
+|GHCJS               |A Haskell to JavaScript [compiler](https://github.com/ghcjs/ghcjs).|
+|GHCup               |An [installer](https://www.haskell.org/ghcup/) for Haskell.
+|Git                 |A [distributed version control system](https://git-scm.com/).|
+|GPG                 |The [GNU Privacy Guard](https://gnupg.org/) or GnuPG, software that allows you to encrypt or sign your data and communications.|
+|Hackage             |The [Haskell Package Repository](https://hackage.haskell.org/).
+|Haddock             |The [document generation tool](https://hackage.haskell.org/package/haddock) for Haskell libraries.|
+|'Haskell' extension |The ['Haskell' extension]() for VS Code.                  |
+|HLS                 |[Haskell Language Server](https://haskell-language-server.readthedocs.io/en/latest/), an implementation of the Language Server Protocol for Haskell.|
+|Homebrew            |A [package manager](https://brew.sh/) for macOS or Linux, or its executable `brew`.|
+|Hoogle              |A Haskell API [search engine](https://hoogle.haskell.org/).|
+|Hpack               |A [format](https://github.com/sol/hpack) for Haskell packages or the executable `hpack` that produces a Cabal file from `package.yaml`.|
+|Linux               |A family of operating systems based on the Linux kernel. |
+|macOS               |The primary operating system for Apple's Mac computers. Previously known as Mac OS X or OS X.|
+|Make                |A [build automation tool](https://www.gnu.org/software/make/).|
+|Markdown            |A plain text [formatting syntax](https://daringfireball.net/projects/markdown/) or software used to convert files in that format to HTML.|
+|MSYS2               |The [MSYS2](https://www.msys2.org/) software distribution and building platform for Windows.|
+|Nix                 |A purely functional [package manager](https://nixos.org/), available for Linux and macOS.|
+|package             |A Haskell package is an organised collection of Haskell code and related files. It is described by a Cabal file or a `package.yaml` file, which is itself part of the package.|
+|`package.yaml`      |A file that describes a package in the Hpack format.      |
+|Pantry              |A library for content-addressable Haskell package management, provided by the [`pantry` package](https://hackage.haskell.org/package/pantry). A dependency of Stack.|
+|PATH                |The `PATH` environment variable, specifying a list of directories searched for executable files.|
+|project             |A Stack project is a local directory that contains a project-level configuration file (`stack.yaml`, by default). A project may relate to more than one project package.|
+|project package     |A Haskell package that is part of a project and located locally. Distinct from a dependency located locally.|
+|PVP                 |The Haskell [Package Versioning Policy](https://pvp.haskell.org/), which tells developers of libraries how to set their version numbers.|
+|REPL                |An interactive (run-eval-print loop) programming environment.|
+|resolver            |A synonym for snapshot.                                  |
+|`Setup.hs`          |A project-specific file used by Cabal to perform setup tasks.|
+|snapshot            |A snapshot defines a GHC version, a set of packages (one version of each), and build flags or other settings.|
+|Stack               |The Haskell Tool Stack project or its executable `stack`.|
+|`stack.yaml`        |A project-level configuration file used by Stack, which may also contain non-project-specific options.|
+|Stackage            |A [distribution](https://www.stackage.org/) of compatible Haskell packages.|
+|Stack root          |A directory in which Stack stores important files. See `stack path --stack-root`. On Windows, or if Stack is configured to use the XDG Base Directory Specification, Stack also stores important files outside of the Stack root.|
 |Stack work directory|A directory within a local project or package directory in which Stack stores files created during the build process. Named `.stack-work`, by default.|
 |Unix-like operating systems|Linux, FreeBSD and macOS.                         |
-|VS Code            |[Visual Studio Code](https://code.visualstudio.com/), a source code editor.|
-|Windows            |A group of operating systems developed by Microsoft.      |
-|WSL                |[Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/). Provides a Linux environment on Windows.|
+|VS Code             |[Visual Studio Code](https://code.visualstudio.com/), a source code editor.|
+|Windows             |A group of operating systems developed by Microsoft.     |
+|WSL                 |[Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/). Provides a Linux environment on Windows.|
 |XDG Base Directory Specification|A [specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) of directories relative to which files should be located.|
-|YAML               |A human-friendly [data serialization language](https://yaml.org/).|
+|YAML                |A human-friendly [data serialization language](https://yaml.org/).|
doc/install_and_upgrade.md view
@@ -48,6 +48,20 @@         Stack installs executables to:
 
         ~~~text
+        $Env:APPDATA\local\bin
+        ~~~
+
+        For example: `C:\Users\<user-name>\AppData\Roaming\local\bin`.
+
+        If you don't have that directory in your PATH, you may need to update
+        your PATH. That can be done by searching for 'Edit Environment variables
+        for your account' under Start.
+
+    === "Windows (Command Prompt)"
+
+        Stack installs executables to:
+
+        ~~~text
         %APPDATA%\local\bin
         ~~~
 
@@ -449,7 +463,7 @@ 
             |GHC version|LLVM versions|
             |-----------|-------------|
-            |9.8.2      |11 to 15     |
+            |9.8.4      |11 to 15     |
             |9.6.6      |11 to 15     |
             |9.4.8      |10 to 14     |
             |9.2.8      |9 to 12      |
@@ -632,8 +646,21 @@                 installer. If so, click on **More info**, and then click on the
                 **Run anyway** button that appears.
 
-            !!! warning "Long user PATH environment variable"
+            ??? warning "I have a Windows username with a space in it"
 
+                GHC 9.4.1 and later have a bug which means they do not work if
+                the path to the `ghc` executable has a space character in it.
+                The default location for Stack's 'programs' directory will have
+                a space in the path if the value of the `USERNAME` environment
+                variable includes a space.
+
+                A solution is to configure Stack to use a different location for
+                its 'programs' directory. For further information, see the
+                [`local-programs-path`](configure/yaml/non-project.md#local-programs-path)
+                non-project specific configuration option documentation.
+
+            ??? warning "Stack 2.9.1, 2.9.3 and 2.11.1: Long user PATH environment variable"
+
                 The Windows installer for Stack 2.9.1, 2.9.3 and 2.11.1 (only)
                 will replace the user `PATH` environment variable (rather than
                 append to it) if a 1024 character limit is exceeded. If the
@@ -727,6 +754,19 @@ 
         ~~~text
         $Env:http_proxy=IP:PORT
+        stack install
+        ~~~
+
+        It is not mandatory for programs to follow the 'system-wide' HTTP proxy.
+        Some programs, such as browsers, do honor this 'system-wide' HTTP proxy
+        setting, while other programs do not. That means configuring
+        'http proxy setting' in your Control Panel would not result in Stack
+        traffic going through the proxy.
+
+    === "Windows (Command Prompt)"
+
+        ~~~text
+        set http_proxy=IP:PORT
         stack install
         ~~~
doc/maintainers/releases.md view
@@ -67,7 +67,7 @@ 
 4.  Check the copyright dates, and update if needed.
 
-5.  Check the backwards compatability section of `CONTRIBUTING.md` is up to
+5.  Check the backwards compatibility section of `CONTRIBUTING.md` is up to
     date.
 
 6.  Ensure CI matrices in docs (travis-complex, appveyor, azure) have current
@@ -372,38 +372,17 @@ 
     ### G: Announce the release candidate
 
-    Announce the release candidate to the following mailing lists
-
-    * haskell-cafe@haskell.org
-
-        !!! note
-
-            You have to be a member of the mailing list to post to it. See the
-            list's
-            [interface](https://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe)
-
-    * haskell-stack@googlegroups.com
-
-        !!! note
-
-            Members of the group can post but posts from new members are held
-            for moderation.
-
-    * commercialhaskell@googlegroups.com
-
-        !!! note
-
-            Members of the group can post but posts from new members are held
-            for moderation.
-
     Announce the release candidate on the
-    [Haskell Community](https://discourse.haskell.org/c/announcements/10/l/latest).
+    [Haskell Community](https://discourse.haskell.org/c/announcements/10/l/latest)
+    forum.
 
-    Announce the release candidate in the `#stack-users` channel of the Haskell
-    Foundation's Slack workspace.
+    Announce the release candidate in the Haskell Foundation's
+    [general](https://matrix.to/#/#haskell-foundation-general:matrix.org) room
+    (address `#haskell-foundation-general:matrix.org`) on
+    [Matrix](https://matrix.org/).
 
-    Announce the release candidate in the
-    [Haskell Stack room](https://matrix.to/#/#haskell-stack:matrix.org)
+    Announce the release candidate in the Haskell
+    [Stack and Stackage](https://matrix.to/#/#haskell-stack:matrix.org) room
     (address `#haskell-stack:matrix.org`) on [Matrix](https://matrix.org/).
 
     Announce the release candidate in Reddit's
@@ -463,12 +442,14 @@             git shortlog -s origin/release..HEAD|sed 's/^[0-9 \t]*/* /'|LC_ALL=C sort -f
             ~~~
 
-        === "Windows (with PowerShell)"
+        === "Windows"
 
             ~~~text
             (git shortlog -s origin/release..HEAD) -Replace '^[0-9 \t]*', '* ' | Sort-Object
             ~~~
 
+            in PowerShell.
+
     Publish the GitHub release.
 
     ### D: Consider adding other platforms to the GitHub release
@@ -598,7 +579,7 @@         curl -vL https://get.haskellstack.org/upgrade/linux-x86_64.tar.gz >/dev/null
         ~~~
 
-    === "Windows (with PowerShell)"
+    === "Windows"
 
         ~~~text
         curl -vL https://get.haskellstack.org/stable/linux-x86_64.tar.gz >NUL
@@ -655,38 +636,17 @@ 
     ### K: Announce the release
 
-    Announce the release to the following mailing lists
-
-    * haskell-cafe@haskell.org
-
-        !!! note
-
-            You have to be a member of the mailing list to post to it. See the
-            list's
-            [interface](https://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe)
-
-    * haskell-stack@googlegroups.com
-
-        !!! note
-
-            Members of the group can post but posts from new members are held
-            for moderation.
-
-    * commercialhaskell@googlegroups.com
-
-        !!! note
-
-            Members of the group can post but posts from new members are held
-            for moderation.
-
     Announce the release on the
-    [Haskell Community](https://discourse.haskell.org/c/announcements/10/l/latest).
+    [Haskell Community](https://discourse.haskell.org/c/announcements/10/l/latest)
+    forum.
 
-    Announce the release in the `#stack-users` channel of the Haskell
-    Foundation's Slack workspace.
+    Announce the release candidate in the Haskell Foundation's
+    [general](https://matrix.to/#/#haskell-foundation-general:matrix.org)
+    room (address `#haskell-foundation-general:matrix.org`) on
+    [Matrix](https://matrix.org/).
 
-    Announce the release in the
-    [Haskell Stack room](https://matrix.to/#/#haskell-stack:matrix.org)
+    Announce the release in the Haskell
+    [Stack and Stackage](https://matrix.to/#/#haskell-stack:matrix.org) room
     (address `#haskell-stack:matrix.org`) on [Matrix](https://matrix.org/).
 
     Announce the release in Reddit's
doc/maintainers/self-hosted_runners.md view
@@ -61,6 +61,23 @@ If the available space is low, that may be due to unncessary GHC versions
 installed in Stack's `programs` directory.
 
+## Re-configuring a removed `stack-github-action3` runner
+
+A self-hosted runner is automatically removed from GitHub if it has not
+connected to GitHub Actions for more than 14 days.
+
+Re-adding a self-hosted runner to GitHub requires it to be configured, and
+GitHub will suggest a configuration command like:
+
+~~~text
+./config.sh --url https://github.com/commercialhaskell/stack --token <token_value>
+~~~
+
+However, to re-use and configure the runner machine, you have first to delete
+the `.runner` file inside the `actions-runner` directory. This allows the runner
+to be registered without having to re-download the self-hosted runner
+application.
+
 ## The `ghc-arm-5` runner
 
 From 9 February 2024, the Haskell Foundation sought to provide an alternative
doc/maintainers/stack_errors.md view
@@ -5,7 +5,7 @@ In connection with considering Stack's support of the
 [Haskell Error Index](https://errors.haskell.org/) initiative, this page seeks
 to take stock of the errors that Stack itself can raise, by reference to the
-`master` branch of the Stack repository. Last updated: 2024-06-03.
+`master` branch of the Stack repository. Last updated: 2024-09-07.
 
 *   `Stack.main`: catches exceptions from action `commandLineHandler`.
 
@@ -385,6 +385,7 @@         [S-8100] | GHCProfOptionInvalid
         [S-1727] | NotOnlyLocal [PackageName] [Text]
         [S-6362] | CompilerVersionMismatch (Maybe (ActualCompiler, Arch)) (WantedCompiler, Arch) GHCVariant CompilerBuild VersionCheck WantedCompilerSetter Text
+        [S-4660] | ActionNotFilteredBug StyleDoc
         ~~~
 
     -   `Stack.Types.Compiler.CompilerException`
@@ -424,6 +425,7 @@         [S-6854] | BadMsysEnvironment MsysEnvironment Arch
         [S-5006] | NoDefaultMsysEnvironmentBug
         [S-8398] | ConfigFileNotProjectLevelBug
+        [S-6890] | NoExecutablePath String
         ~~~
 
     -   `Stack.Types.Config.ParseAbsolutePathException`
@@ -541,12 +543,28 @@ 
 *   `Stack.Config.configFromConfigMonoid`:
 
+    Presented as a warning rather than as an error:
+
     ~~~text
-    [S-8432] Stack's 'programs' path contains a space character and has no alternative
+    [S-8432]
+    Stack's 'programs' path is <path>. It contains a space character. This will
+    prevent building with GHC 9.4.1 or later. It also has has no alternative
     short ('8 dot 3') name. This will cause problems with packages that use the
-    GNU project's 'configure' shell script. Use the 'local-programs-path'
-    configuration option to specify an alternative path. The current path is:
-    <path>
+    GNU project's 'configure' shell script.
+
+    To avoid such problems, use the local-programs-path non-project specific
+    configuration option to specify an alternative space-free path.
+    ~~~
+
+    or
+
+    ~~~text
+    [S-8432]
+    Stack's 'programs' path is <path>. It contains a space character. This will
+    prevent building with GHC 9.4.1 or later.
+
+    To avoid such problems, use the local-programs-path non-project specific
+    configuration option to specify an alternative space-free path.
     ~~~
 
 *   `Stack.Coverage.generateHpcReport`: catches exceptions from
doc/maintainers/team_process.md view
@@ -156,7 +156,7 @@ ## Real-time communications
 
 At present, the maintainer team mostly communicates via a rather quiet channel
-called [`#stack-collaborators`](../CONTRIBUTING/#slack-channel) in the
+called [`#stack-collaborators`](../CONTRIBUTING.md#slack-channel) in the
 Haskell Foundation's Slack workspace, although we may migrate to some other
 platform in the future.
doc/other_resources.md view
@@ -17,3 +17,10 @@ * The [haskell-stack tag on Stack Overflow](http://stackoverflow.com/questions/tagged/haskell-stack)
 * [Another getting started with Stack tutorial](http://seanhess.github.io/2015/08/04/practical-haskell-getting-started.html)
 * [Why is Stack not Cabal?](https://www.fpcomplete.com/blog/2015/06/why-is-stack-not-cabal)
+
+Package description format specifications supported by Stack:
+
+* Cabal's: a
+  [Cabal file](https://cabal.readthedocs.io/en/stable/cabal-package-description-file.html)
+* Hpack's: a
+  [`package.yaml` file](https://github.com/sol/hpack?tab=readme-ov-file#documentation)
doc/topics/Stack_and_VS_Code.md view
@@ -10,112 +10,159 @@ The 'Haskell' extension can be used with Stack but there are some things to be
 aware of, set out below.
 
-## Haskell Language Server
+## GHCup
 
-The VS Code extension makes use of the Haskell Language Server (HLS). To work,
-HLS has to be built with the same version of GHC that it will support. That is,
-a version of HLS is required for each version of GHC in use. It is possible that
-the most recent versions of GHC are not supported by HLS.
+The separate [GHCup](https://www.haskell.org/ghcup/) project provides a tool
+that can be used to install various tools useful for developing Haskell
+projects. Those tools include:
 
-By default, the VS Code extension uses tools that are in the PATH. However, the
-extension's settings (under 'Haskell: Manage HLS') allow a user to specify
-that the extension should use a separate application,
-[GHCup](https://www.haskell.org/ghcup/), to download and install the versions of
-HLS that it needs. GHCup can download and install things other than HLS,
-including GHC, MSYS2 (on Windows), Cabal (a tool for building Haskell code), and
-Stack itself. GHCup can also update itself. On Windows, GHCup has the capability
-of using the Stack-supplied MSYS2 rather than installing a duplicate copy. Cabal
-(the tool), like Stack, depends on the Cabal (the library). Cabal (the tool),
-unlike Stack, does not have the capability to automatically install necessary
-versions of GHC, and (as well as supporting the extension) GHCup fills a
-important gap for users of the Cabal tool.
+* GHC,
+* HLS (see further below),
+* MSYS2 (on Windows; see the developing on Windows
+  [documentation](developing_on_windows.md)),
+* Stack, and
+* Cabal (the tool).
 
-If the VS Code extension is set not to use GHCup, its user needs to ensure that
-each version of HLS that the extension needs is on the PATH.
+Stack itself can be used to install GHC and MSYS2. Stack can also be used to
+upgrade, or downgrade, Stack.
 
-For the most part, the versions of HLS provided by GHCup are built with the same
-versions of GHC that Stack downloads from its default `setup-info` dictionary
-(see the [`setup-info`](../configure/yaml/non-project.md#setup-info) non-project
-specific configuration option documentation). Stack's default is to mirror the
-'official' binary distributions published by GHC. However, in some cases, it is
-possible that a GHCup-supplied and GHCup-selected HLS has been built with a
-different binary distribution of GHC than the one which Stack has installed.
+GHCup can configure Stack so that if Stack needs a version of GHC, GHCup takes
+over obtaining and installing that version. By default, the script to install
+GHCup (which can be run more than once) configures Stack in that way. For
+further information about how GHCup configures Stack, see the GHC installation
+customisation
+[documentation](../configure/customisation_scripts.md#ghc-installation-customisation).
 
-One example of that occurred with the release of GHC 9.0.2. For some Linux users
-(Debian 9 and Fedora 27), the version of GHC 9.0.2 linked on GHC’s download
-[web page](https://www.haskell.org/ghc/download_ghc_9_0_2.html) was broken. The
-GHC developers made alternative ‘9.0.2a’ versions available. For a while, Stack
-referred to the versions published by GHC on its download web page while the
-GHCup-supplied versions of HLS were built using alternative versions. This
-incompatibility led to problems. It was resolved by Stack's default also being
-changed to refer to the '9.0.2a' versions. (Where Stack has already installed
-GHC 9.0.2, it is necessary to delete GHC 9.0.2 from the `stack path --programs`
-directory. This will cause Stack to reinstall the alternative version, when it
-first needs GHC 9.0.2. Stack should distinguish what it builds with the
-alternative from what it has built, and cached, with the original GHC 9.0.2.)
+On Windows, GHCup has the capability of using the Stack-supplied MSYS2 rather
+than installing a duplicate copy.
 
-### GHCup and Stack >= 2.9.1
+## HLS
 
-From Stack 2.9.1, GHCup can configure Stack so that if Stack needs a version of
-GHC, GHCup takes over obtaining and installing that version. By default, the
-script to install GHCup (which can be run more than once) configures Stack in
-that way. For further information about how GHCup configures Stack, see the GHC
-installation customisation
-[documentation](../configure/customisation_scripts.md#ghc-installation-customisation).
+The VS Code extension makes use of
+[HLS](https://github.com/haskell/haskell-language-server) (the Haskell Language
+Server). To work, HLS has to be built with the same version of GHC that it will
+support. That is, a version of HLS is required for each version of GHC in use.
+It is possible that the most recent versions of GHC are not supported by HLS.
 
-### Workaround #1
+VS Code with the 'Haskell' extension can be configured in a number of ways:
 
-If GHCup does not configure Stack in the way described above, one workaround is
-to allow GHCup to install versions of GHC on the PATH and to cause Stack to use
-those versions of GHC, by making use of Stack's `install-ghc` option (which
-needs to be disabled) and Stack's `system-ghc` option (which needs to be
-enabled). For further information about these options, see the
-[`install-ghc`](../configure/yaml/non-project.md#install-ghc) documentation and
-the [`system-ghc`](../configure/yaml/non-project.md#system-ghc) documentation.
+=== "GHCup manages HLS"
 
-For this workaround to work, each time that a snapshot is used that references a
-different version of GHC, then GHCup must be used to install it (if GHCup has
-not already installed that version). For example, to use `snapshot: lts-22.28`
-(GHC 9.6.6), the command `ghcup install ghc 9.6.6` must have been used to
-install GHC 9.6.6. That may be a minor inconvenience for some people, as one the
-primary benefits of Stack over other tools for building Haskell code has been
-that Stack automatically ensures that the necessary version of GHC is available.
+    The VS Code extension's settings (under 'Haskell: Manage HLS') allow a
+    user to specify that the extension should use GHCup, to download and install
+    the versions of HLS that it needs.
 
-### Workaround #2
+    If GHCup manages versions of HLS, versions of GHC can be managed in a number
+    of ways:
 
-If GHCup does not configure Stack, another partial workaround is to install
-GHCup so that it is 'empty' except for the current version of HLS, allow the
-VS Code extension to use GHCup to manage HLS requirements only, and to ignore
-any messages (if any) from the extension on start-up that installation of GHC,
-Cabal (the tool) and/or Stack are also necessary (they are not, if only Stack is
-being used).
+    === "Stack manages GHC using GHCup"
 
-For this workaround to work, however, there can be no differences between the
-version of GHC that the GHCup-supplied HLS was built with and the version that
-Stack has installed. A slight inconvenience here is also the possibility of
-false messages from the start-up that need to be ignored. In principle, those
-messages can be disabled by
-[setting the following](https://github.com/haskell/vscode-haskell#setting-a-specific-toolchain)
-for the VS Code extension:
+        As identified above, GHCup can configure Stack to use GHCup to manage
+        versions of GHC.
 
-~~~yaml
-"haskell.toolchain": {
-  "ghc": null,
-  "cabal": null,
-  "stack": null
-}
-~~~
+    === "Stack manages GHC directly"
 
-To install a version of GHCup that is 'empty' is a little more complicated than
-a default installation of GHCup.
+        It is possible to install GHCup so that it is 'empty' except for the
+        current version of HLS, allow the VS Code extension to use GHCup to
+        manage HLS requirements only, and to disable messages from the extension
+        on start-up that installation of GHC, Cabal (the tool)
+        and/or Stack are also necessary (they are not, if only Stack is being
+        used).
 
-On Unix-like operating systems, the following environment variable must be set
-before GHCup's installation `sh` script is run: `BOOTSTRAP_HASKELL_MINIMAL`.
+        To install a version of GHCup that is 'empty' is a little more
+        complicated than a default installation of GHCup.
 
-On Windows, the second argument to the PowerShell script must be set to
-`$false`, namely:
+        === "Unix-like"
 
-    Set-ExecutionPolicy Bypass -Scope Process -Force;[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072;Invoke-Command -ScriptBlock ([ScriptBlock]::Create((Invoke-WebRequest https://www.haskell.org/ghcup/sh/bootstrap-haskell.ps1 -UseBasicParsing))) -ArgumentList $true,$false
+            The following environment variable must be set before GHCup's
+            installation `sh` script is run: `BOOTSTRAP_HASKELL_MINIMAL`.
+
+        === "Windows"
+
+            The second argument to the PowerShell script must be set to
+            `$false`, namely:
+
+                Set-ExecutionPolicy Bypass -Scope Process -Force;[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072;Invoke-Command -ScriptBlock ([ScriptBlock]::Create((Invoke-WebRequest https://www.haskell.org/ghcup/sh/bootstrap-haskell.ps1 -UseBasicParsing))) -ArgumentList $true,$false
+
+        There is the possibility of false messages from the extension on
+        start-up that need to be ignored. Those messages can be disabled by
+        [setting the following](https://github.com/haskell/vscode-haskell#setting-a-specific-toolchain)
+        for the VS Code extension:
+
+        ~~~yaml
+        "haskell.toolchain": {
+          "ghc": null,
+          "cabal": null,
+          "stack": null
+        }
+        ~~~
+
+        There can be no differences between the version of GHC that the
+        GHCup-supplied HLS was built with and the version that Stack has
+        installed.
+
+        For the most part, the versions of HLS provided by GHCup are built with
+        the same versions of GHC that Stack downloads from its default
+        `setup-info` dictionary (see the
+        [`setup-info`](../configure/yaml/non-project.md#setup-info) non-project
+        specific configuration option documentation). Stack's default is to
+        mirror the 'official' binary distributions published by GHC.
+
+        However, in some cases, it is possible that a GHCup-supplied and
+        GHCup-selected HLS has been built with a different binary distribution
+        of GHC than the one which Stack has installed.
+
+        ??? question "When have the GHCup- and Stack-supplied GHCs differed?"
+
+            An example occurred with the release of GHC 9.0.2. For some Linux
+            users (Debian 9 and Fedora 27), the version of GHC 9.0.2 linked on
+            GHC’s download
+            [web page](https://www.haskell.org/ghc/download_ghc_9_0_2.html) was
+            broken. The GHC developers made alternative ‘9.0.2a’ versions
+            available. For a while, Stack referred to the versions published by
+            GHC on its download web page while the GHCup-supplied versions of
+            HLS were built using alternative versions. This incompatibility led
+            to problems.
+
+            It was resolved by Stack's default also being changed to refer to
+            the '9.0.2a' versions. Where Stack has already installed GHC 9.0.2,
+            it is necessary to delete GHC 9.0.2 from the `stack path --programs`
+            directory. This will cause Stack to reinstall the alternative
+            version, when it first needs GHC 9.0.2. Stack should distinguish
+            what it builds with the alternative from what it has built, and
+            cached, with the original GHC 9.0.2.
+
+    === "Stack uses a GHCup-supplied GHC"
+
+        GHCup is used to manage versions of GHC and Stack is configured to use
+        the version of GHC on the PATH.
+
+        That is, GHCup is used to install a version of GHC on the PATH. Stack is
+        configured to make use of that version, by making use of Stack's
+        `install-ghc` option (which needs to be disabled) and Stack's
+        `system-ghc` option (which needs to be enabled).
+
+        For further information about these options, see the
+        [`install-ghc`](../configure/yaml/non-project.md#install-ghc)
+        documentation and the
+        [`system-ghc`](../configure/yaml/non-project.md#system-ghc)
+        documentation.
+
+        Each time that a snapshot is used that references a different version of
+        GHC, then GHCup must be used to install it (if GHCup has not already
+        installed that version). For example, to use `snapshot: lts-23.0`
+        (GHC 9.8.4), the command `ghcup install ghc 9.8.4` must have been used
+        to install GHC 9.8.4. That may be a minor inconvenience for some people,
+        as one the primary benefits of Stack over other tools for building
+        Haskell code has been that Stack automatically ensures that the
+        necessary version of GHC is available.
+
+=== "User manages HLS"
+
+    By default, the VS Code extension uses tools that are in the PATH.
+
+    If the VS Code extension is set not to use GHCup, its user needs to ensure
+    that each version of HLS that the extension needs is on the PATH.
 
 ### Cradle
doc/topics/custom_snapshot.md view
@@ -18,8 +18,8 @@     for snapshot specification.
 
 ~~~yaml
-snapshot: lts-22.28 # Inherits GHC version and package set
-compiler: ghc-9.6.5 # Overwrites GHC version in the snapshot, optional
+snapshot: lts-23.0 # Inherits GHC version and package set
+compiler: ghc-9.8.3 # Overwrites GHC version in the snapshot, optional
 
 # Additional packages, follows extra-deps syntax
 packages:
@@ -62,35 +62,35 @@ 
 ### Overriding the compiler
 
-The following snapshot specification will be identical to `lts-22.28`, but
-instead use `ghc-9.6.5` instead of `ghc-9.6.6`:
+The following snapshot specification will be identical to `lts-23.0`, but
+instead use `ghc-9.8.3` instead of `ghc-9.8.4`:
 
 ~~~yaml
-snapshot: lts-22.28
-compiler: ghc-9.6.5
+snapshot: lts-23.0
+compiler: ghc-9.8.3
 ~~~
 
 ### Dropping packages
 
-The following snapshot specification will be identical to `lts-22.28`, but
+The following snapshot specification will be identical to `lts-23.0`, but
 without the `text` package in our snapshot. Removing this package will cause all
 the packages that depend on `text` to be unbuildable, but they will still be
 present in the snapshot.
 
 ~~~yaml
-snapshot: lts-22.28
+snapshot: lts-23.0
 drop-packages:
 - text
 ~~~
 
 ### Hiding packages
 
-The following snapshot specification will be identical to `lts-22.28`, but the
+The following snapshot specification will be identical to `lts-23.0`, but the
 `text` package will be hidden when registering. This will affect, for example,
 the import parser in the script command.
 
 ~~~yaml
-snapshot: lts-22.28
+snapshot: lts-23.0
 hidden:
 - text
 ~~~
@@ -101,11 +101,11 @@ [ghc-options](../configure/yaml/non-project.md#ghc-options) key for build
 configuration.
 
-The following snapshot specification will be identical to `lts-22.28`, but
+The following snapshot specification will be identical to `lts-23.0`, but
 provides `-O1` as a ghc-option for `text`:
 
 ~~~yaml
-snapshot: lts-22.28
+snapshot: lts-23.0
 packages:
 - text-2.0.2
 ghc-options:
@@ -124,11 +124,11 @@ 
 In order to specify Cabal flags for a package, you use the same syntax as the
 [flags](../configure/yaml/project.md#flags) key for build configuration. The
-following snapshot specification will be identical to `lts-22.28`, but
+following snapshot specification will be identical to `lts-23.0`, but
 it enables the `developer` Cabal flag:
 
 ~~~yaml
-snapshot: lts-22.28
+snapshot: lts-23.0
 packages:
 - text-2.0.2
 flags:
doc/topics/haskell_and_c_code.md view
@@ -83,7 +83,7 @@ 
 The project's `stack.yaml` file only needs to identify a snapshot:
 ~~~yaml
-snapshot: lts-22.28 # GHC 9.6.6
+snapshot: lts-23.0 # GHC 9.8.4
 ~~~
 
 This example project can be built with Stack in the normal way (`stack build`),
@@ -220,7 +220,7 @@ 
 The project's `stack.yaml` file only needs to identify a snapshot:
 ~~~yaml
-snapshot: lts-22.28 # GHC 9.6.6
+snapshot: lts-23.0 # GHC 9.8.4
 ~~~
 
 This example project can be built with Stack in the normal way (`stack build`),
doc/topics/nix_integration.md view
@@ -43,7 +43,7 @@ special requirements, such as using custom Nix packages that override the
 standard ones or using system libraries with special requirements.
 
-### Checking the Nix installation
+## Checking the Nix installation
 
 Once Nix is installed, the Nix commands (`nix-shell` etc) should be available.
 If they are not, it could be because the file
@@ -68,7 +68,7 @@ information about how Stack itself can configure `NIX_PATH`, see further
 [below](#nix-package-sources).
 
-### Enable Nix integration
+## Enable Nix integration
 
 On NixOS, Nix integration is enabled by default; on other operating systems it
 is disabled. To enable Nix integration, add the following section to your Stack
@@ -96,7 +96,7 @@ **Known limitation on macOS:** currently, `stack --nix ghci` fails on macOS, due
 to a bug in GHCi when working with external shared libraries.
 
-### Supporting both Nix and non-Nix developers
+## Supporting both Nix and non-Nix developers
 
 With Nix integration enabled in Stack's configuration file, every developer of
 your project needs to have Nix installed, but the developer also gets all
@@ -181,7 +181,7 @@ that `flake.lock` file as well, and every Nix developer of your project will use
 precisely the same package set.
 
-### GHC through Nix packages
+## GHC through Nix packages
 
 Nix integration will instruct Stack to build inside a local build environment.
 That environment will also download and use a
@@ -238,7 +238,7 @@ You can type and evaluate any Nix expression in the Nix REPL, such as the one we
 gave to `nix-instantiate` earlier.
 
-### External C libraries through Nix packages
+## External C libraries through Nix packages
 
 To let Nix manage external C libraries, add (for example) the following section
 to your Stack configuration file:
@@ -267,7 +267,7 @@ layout, you'll have to deal with that using a custom `shell.nix` file (see
 further below).
 
-### External C libraries through a `shell.nix` file
+## External C libraries through a `shell.nix` file
 
 In Nix, a 'derivation' is a description of a build action and its result is a
 Nix store object. Nix's [custom language][nix-language] can provide a fully
@@ -314,7 +314,7 @@ version as defined in the snapshot you set in Stack's project-level
 configuration file (`stack.yaml`, by default).
 
-### Pure and impure Nix shells
+## Pure and impure Nix shells
 
 By default, Stack will run the build in a *pure* Nix build environment (or
 *shell*), which means two important things:
@@ -343,7 +343,7 @@ to be resolved locale issues. So on macOS you'll need to be a bit more careful
 to check that you really have listed all dependencies.
 
-### Nix package sources
+## Nix package sources
 
 Nix organizes its packages in snapshots of packages (each snapshot being a
 "package set") similar to how Stackage organizes Haskell packages.  By default,
doc/topics/scripts.md view
@@ -19,7 +19,7 @@ 
 ~~~haskell
 #!/usr/bin/env stack
--- stack script --snapshot lts-22.28 --package turtle
+-- stack script --snapshot lts-23.0 --package turtle
 {-# LANGUAGE OverloadedStrings #-}
 import Turtle (echo)
 main = echo "Hello World!"
@@ -56,7 +56,7 @@     stack turtle-example.hs
     ~~~
 
-=== "Windows (with PowerShell)"
+=== "Windows"
 
     The first line beginning with the 'shebang' (`#!`) has a meaning on
     Unix-like operating systems but will be ignored by PowerShell. It can be
@@ -78,11 +78,11 @@ 
 The second line of the source code is the Stack interpreter options comment. In
 this example, it specifies the [`stack script`](../commands/script_command.md)
-command with the options of a LTS Haskell 22.28 snapshot
-(`--snapshot lts-22.28`) and ensuring the
+command with the options of a LTS Haskell 23.0 snapshot
+(`--snapshot lts-23.0`) and ensuring the
 [`turtle`](https://hackage.haskell.org/package/turtle) package is available
 (`--package turtle`). The version of the package will be that in the specified
-snapshot (`lts-22.28` provides `turtle-1.6.2`).
+snapshot (`lts-23.0` provides `turtle-1.6.2`).
 
 ## Arguments and interpreter options and arguments
 
@@ -117,7 +117,7 @@ ~~~haskell
 #!/usr/bin/env stack
 {- stack script
-   --snapshot lts-22.28
+   --snapshot lts-23.0
    --
    +RTS -s -RTS
 -}
@@ -133,7 +133,7 @@ is equivalent to the following command at the command line:
 
 ~~~text
-stack script --snapshot lts-22.28 -- MyScript.hs arg1 arg2 +RTS -s -RTS
+stack script --snapshot lts-23.0 -- MyScript.hs arg1 arg2 +RTS -s -RTS
 ~~~
 
 where `+RTS -s -RTS` are some of GHC's
@@ -162,7 +162,7 @@ ~~~haskell
 #!/usr/bin/env stack
 {- stack script
-   --snapshot lts-22.28
+   --snapshot lts-23.0
    --package turtle
    --package "stm async"
    --package http-client,http-conduit
@@ -207,7 +207,7 @@ 
 ~~~haskell
 {- stack script
-   --snapshot lts-22.28
+   --snapshot lts-23.0
    --package acme-missiles
 -}
 import Acme.Missiles (launchMissiles)
@@ -218,7 +218,7 @@ 
 The command `stack --script-no-run-compile Script.hs` then behaves as if the
 command
-`stack script --snapshot lts-22.28 --package acme-missiles --no-run --compile -- Script.hs`
+`stack script --snapshot lts-23.0 --package acme-missiles --no-run --compile -- Script.hs`
 had been given. `Script.hs` is compiled (without optimisation) and the resulting
 executable is not run: no missiles are launched in the process!
 
@@ -260,7 +260,7 @@ {- stack
   runghc
   --install-ghc
-  --snapshot lts-22.28
+  --snapshot lts-23.0
   --package base
   --package turtle
   --
@@ -284,7 +284,7 @@ {- stack
    exec ghci
    --install-ghc
-   --snapshot lts-22.28
+   --snapshot lts-23.0
    --package turtle
 -}
 ~~~
doc/topics/stack_root.md view
@@ -19,21 +19,48 @@ The location of the Stack root can be configured by setting the
 [`STACK_ROOT`](../configure/environment_variables.md#stack_root) environment
 variable or using Stack's
-[`--stack-root`](../configure/global_flags.md#stack-root-option) option on the
+[`--stack-root`](../configure/global_flags.md#-stack-root-option) option on the
 command line.
 
 === "Unix-like"
 
     The Stack root contains snapshot packages; (by default) tools such as GHC,
     in a `programs` directory; Stack's global
-    [configuration](../configure/yaml-configuration.md) file
-    (`config.yaml`); and Stack's
-    [`global-projects`](../configure/yaml-configuration.md) directory.
+    [configuration](../configure/yaml/index.md) file (`config.yaml`); and
+    Stack's [`global-projects`](../configure/yaml/index.md) directory.
 
     The default Stack root is `~/.stack`.
 
 === "Windows"
 
+    The default Stack root is `$Env:APPDIR\stack`.
+
+    If the `LOCALAPPDATA` environment variable exists, then the default location
+    of tools is `$Env:LOCALAPPDATA\Programs\stack`. Otherwise, it is the
+    `programs` directory in the Stack root.
+
+    !!! warning
+
+        If there is a space character in the `$Env:LOCALAPPDATA` path (which may
+        be the case if the relevant user account name and its corresponding user
+        profile path have a space) this may cause problems with building
+        packages that make use of the GNU project's `autoconf` package and
+        `configure` shell script files. That may be the case particularly if
+        there is no corresponding short name ('8 dot 3' name) for the directory
+        in the path with the space (which may be the case if '8 dot 3' names
+        have been stripped or their creation not enabled by default). If there
+        are problems building, it will be necessary to override the default
+        location of Stack's 'programs' directory to specify an alternative path
+        that does not contain space characters. Examples of packages on
+        Hackage that make use of `configure` are `network` and `process`.
+
+    On Windows, the length of filepaths may be limited (to
+    [MAX_PATH](https://docs.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=cmd)),
+    and things can break when this limit is exceeded. Setting a Stack root with
+    a short path to its location (for example, `C:\sr`) can help.
+
+=== "Windows (Command Prompt)"
+
     The default Stack root is `%APPDIR%\stack`.
 
     If the `LOCALAPPDATA` environment variable exists, then the default location
@@ -120,17 +147,16 @@ 
     The Stack root contains snapshot packages; (by default) tools such as GHC,
     in a `programs` directory; Stack's global
-    [configuration](../configure/yaml-configuration.md) file
-    (`config.yaml`); and Stack's
-    [`global-projects`](../configure/yaml-configuration.md) directory.
+    [configuration](../configure/yaml/index.md) file (`config.yaml`); and
+    Stack's [`global-projects`](../configure/yaml/index.md) directory.
 
 === "Windows"
 
     The Stack root contains snapshot packages; Stack's global
-    [configuration](../configure/yaml-configuration.md) file (`config.yaml`);
-    and Stack's [`global-projects`](../configure/yaml-configuration.md)
-    directory. The default location of tools such as GHC and MSYS2 is outside of
-    the Stack root.
+    [configuration](../configure/yaml/index.md) file (`config.yaml`); and
+    Stack's [`global-projects`](../configure/yaml/index.md) directory. The
+    default location of tools such as GHC and MSYS2 is outside of the Stack
+    root.
 
 === "XDG Base Directory Specification"
 
@@ -238,9 +264,9 @@ ### `setup-exe-src` directory
 
 See the documentation for the
-[`setup-exe-cache` directory](#setup-exe-cache-directorysetup-exe-cache). This
-contains the two source files (`setup-<hash>.hs` and `setup-shim-<hash>.hs`)
-that Stack uses to build the executable.
+[`setup-exe-cache` directory](#setup-exe-cache-directory). This contains the two
+source files (`setup-<hash>.hs` and `setup-shim-<hash>.hs`) that Stack uses to
+build the executable.
 
 If the contents of the directory are deleted, and Stack needs the executable,
 then Stack will recreate them.
doc/topics/stack_work.md view
@@ -71,8 +71,8 @@ * a `doc` directory, containing a directory for each project package. This is
   the directory reported by
   [`stack path --local-doc-root`](../commands/path_command.md);
-* if the [`stack hpc`](hpc_command.md) command is used, a `hpc` directory. This
-  is the directory reported by
+* if the [`stack hpc`](../commands/hpc_command.md) command is used, a `hpc`
+  directory. This is the directory reported by
   [`stack path --local-hpc-root`](../commands/path_command.md);
 * a `lib` directory, containing a directory named after the platform and the
   GHC version and, within that, a directory for each project package;
@@ -106,9 +106,10 @@     package depend on:
 
     * the specification of
-      [profiling](https://docs.haskellstack.org/en/stable/build_command/#flags-affecting-ghcs-behaviour);
+      [profiling](../commands/build_command.md#flags-affecting-ghcs-behaviour);
     * the specification of
-      [stripping](https://docs.haskellstack.org/en/stable/build_command/#flags-affecting-ghcs-behaviour); and
+      [stripping](../commands//build_command.md#flags-affecting-ghcs-behaviour);
+      and
     * if
       [`apply-ghc-options: everything`](../configure/yaml/non-project.md#apply-ghc-options)
       is specified, any GHC command line options specified on the command line.
doc/topics/stack_yaml_vs_cabal_package_file.md view
@@ -64,9 +64,9 @@ 
 The most common means by which this set of packages is defined is via a
 snapshot provided by Stackage. For example, if you go to the page
-<https://www.stackage.org/lts-22.28>, you will see a list of 3,373 packages at
-specific version numbers. When you then specify `snapshot: lts-22.28` or,
-alternatively, `resolver: lts-22.28`, you're telling Stack to use those package
+<https://www.stackage.org/lts-23.0>, you will see a list of 3,189 packages at
+specific version numbers. When you then specify `snapshot: lts-23.0` or,
+alternatively, `resolver: lts-23.0`, you're telling Stack to use those package
 versions in resolving dependencies down to specific versions of packages.
 
 Sometimes a snapshot doesn't have all of the packages that you want. Or you want
doc/tutorial/building_existing_projects.md view
@@ -1,6 +1,6 @@   <div class="hidden-warning"><a href="https://docs.haskellstack.org/"><img src="https://cdn.jsdelivr.net/gh/commercialhaskell/stack/doc/img/hidden-warning.svg"></a></div>
 
-# 3. Building existing projects
+# 5. Building existing projects
 
 Alright, enough playing around with simple projects. Let's take an open source
 package and try to build it. We'll be ambitious and use
@@ -129,11 +129,23 @@ _User warnings_: When packages are excluded or external dependencies added Stack
 will show warnings every time the configuration file is loaded. You can suppress
 the warnings by editing the configuration file and removing the warnings from
-it. You may see something like this:
+it. If you command:
 
 ~~~text
 stack build
-Warning: Some packages were found to be incompatible with the resolver and have been left commented out in the packages section.
-Warning: Specified resolver could not satisfy all dependencies. Some external packages have been added as dependencies.
-You can suppress this message by removing it from stack.yaml
+~~~
+
+you may see something like this:
+
+~~~text
+Warning: Warnings (added by new or init): Some packages were found to be
+         incompatible with the snapshot and have been left commented out in the
+         packages section.
+
+         Warning (added by new or init): Specified snapshot could not satisfy
+         all dependencies. Some external packages have been added as
+         dependencies.
+
+        You can omit this message by removing it from the project-level
+        configuration file.
 ~~~
doc/tutorial/building_your_project.md view
@@ -1,6 +1,6 @@ <div class="hidden-warning"><a href="https://docs.haskellstack.org/"><img src="https://cdn.jsdelivr.net/gh/commercialhaskell/stack/doc/img/hidden-warning.svg"></a></div>
 
-# 2. Building your project
+# 4. Building your project
 
 The [`stack build`](../commands/build_command.md) command is the heart of Stack.
 It is the engine that powers building your code, testing it, getting
@@ -249,7 +249,7 @@ mentioned the LTS snapshots, and you can get information about it at
 [https://www.stackage.org/lts](https://www.stackage.org/lts), including:
 
-* The appropriate value (`lts-22.30`, as is currently the latest LTS)
+* The appropriate value (`lts-23.0`, as is currently the latest LTS)
 * The GHC version used
 * A full list of all packages versions available in this snapshot
 * The ability to perform a Hoogle search on the packages in this snapshot
@@ -270,14 +270,28 @@ As mentioned, a snapshot specifies a version of GHC as well as a set of package
 versions.
 
-Let's try using an older LTS snapshot. We'll use the Stackage LTS Haskell 21.25
-snapshot with the command:
+??? question "I want to use a particular version of GHC. What snapshot should I use?"
 
+    For each supported version of GHC, the Stackage
+    [homepage](https://www.stackage.org/) lists the most recent Stackage
+    snapshot. In most cases, that is the snapshot you should use.
+
+??? question "Can I use a snapshot like `ghc-9.8.4`?"
+
+    Snapshot `ghc-9.8.4` specifies GHC 9.8.4 and, consequently, the GHC boot
+    packages that come with that compiler. However, the snapshot does not
+    include the many other package versions that will work with that compiler.
+    For a set of those package versions, see the snapshots published by the
+    [Stackage](https://www.stackage.org/) project.
+
+Let us try using an older Stackage LTS Haskell snapshot. We will use the LTS
+22.43 snapshot with the command:
+
 ~~~text
-stack --snapshot lts-21.25 build
+stack --snapshot lts-22.43 build
 ~~~
 
-Stackage LTS Haskell 21.25 specifies GHC 9.4.8. If that version of GHC is not
+Stackage LTS Haskell 22.43 specifies GHC 9.6.6. If that version of GHC is not
 already available, Stack will try to fetch it and install it before starting the
 rest of the build.
doc/tutorial/cabal_flags_and_ghc_options.md view
@@ -1,6 +1,6 @@   <div class="hidden-warning"><a href="https://docs.haskellstack.org/"><img src="https://cdn.jsdelivr.net/gh/commercialhaskell/stack/doc/img/hidden-warning.svg"></a></div>
 
-# 8. Cabal flags and GHC options
+# 10. Cabal flags and GHC options
 
 There are two common ways to alter how a package will install: with Cabal flags
 and with GHC options.
doc/tutorial/executing_commands.md view
@@ -1,6 +1,6 @@   <div class="hidden-warning"><a href="https://docs.haskellstack.org/"><img src="https://cdn.jsdelivr.net/gh/commercialhaskell/stack/doc/img/hidden-warning.svg"></a></div>
 
-# 10. Executing commands
+# 12. Executing commands
 
 We've already used `stack exec` multiple times in this guide. As you've likely
 already guessed, it allows you to run executables, but with a slightly modified
@@ -31,10 +31,10 @@ yields output like:
 
 ~~~text
-Run from outside a project, using implicit global project config
-Using latest snapshot resolver: lts-22.21
-Writing global (non-project-specific) config file to: /home/michael/.stack/global/stack.yaml
-Note: You can change the snapshot via the resolver field there.
+Writing the configuration file for the implicit global project to:
+.../global-project/stack.yaml. Note: You can change the snapshot via the
+snapshot field there.
+Using the latest snapshot lts-22.31.
 I installed the stm package via --package stm
 ~~~
doc/tutorial/hello_world_example.md view
@@ -50,6 +50,7 @@ will create the [Stack root](../topics/stack_root.md) directory.
 
 Other than any setting up, Stack will:
+
 * create the project directory;
 * download the project template;
 * attempt to populate the project template based on parameters; and
@@ -108,7 +109,7 @@         /home/<user_name>/.stack/programs/x86_64-linux/ghc-9.6.5/bin/ghc
         ~~~
 
-    === "Windows (with PowerShell)"
+    === "Windows"
 
         ~~~text
         stack exec -- where.exe ghc
@@ -137,7 +138,7 @@     ...
     helloworld> configure (lib + exe)
     Configuring helloworld-0.1.0.0...
-    helloworld> build (lib + exe) with ghc-9.6.6
+    helloworld> build (lib + exe) with ghc-9.8.4
     Preprocessing library for helloworld-0.1.0.0..
     Building library for helloworld-0.1.0.0..
     [1 of 2] Compiling Lib
@@ -146,9 +147,9 @@     Building executable 'helloworld-exe' for helloworld-0.1.0.0..
     [1 of 2] Compiling Main
     [2 of 2] Compiling Paths_helloworld
-    [3 of 3] Linking .stack-work/dist/x86_64-linux-tinfo6/ghc-9.6.6/build/helloworld-exe/helloworld-exe
+    [3 of 3] Linking .stack-work/dist/x86_64-linux-tinfo6/ghc-9.8.4/build/helloworld-exe/helloworld-exe
     helloworld> copy/register
-    Installing library in .../helloworld/.stack-work/install/x86_64-linux-tinfo6/a2caceceda039eb4f791856f85a68f9582d4daf3d0527344693ff3d1fcd92ba4/9.6.6/lib/x86_64-linux-ghc-9.6.6/helloworld-0.1.0.0-KFyX8zLxDvzLZURq3JaCVX
+    Installing library in .../helloworld/.stack-work/install/x86_64-linux-tinfo6/a2caceceda039eb4f791856f85a68f9582d4daf3d0527344693ff3d1fcd92ba4/9.6.6/lib/x86_64-linux-ghc-9.8.4/helloworld-0.1.0.0-KFyX8zLxDvzLZURq3JaCVX
     Installing executable helloworld-exe in .../helloworld/.stack-work/install/x86_64-linux-tinfo6/a2caceceda039eb4f791856f85a68f9582d4daf3d0527344693ff3d1fcd92ba4/9.6.6/bin
     Registering library for helloworld-0.1.0.0..
     ~~~
@@ -159,7 +160,7 @@     ...
     helloworld> configure (lib + exe)
     Configuring helloworld-0.1.0.0...
-    helloworld> build (lib + exe) with ghc-9.6.6
+    helloworld> build (lib + exe) with ghc-9.8.4
     Preprocessing library for helloworld-0.1.0.0..
     Building library for helloworld-0.1.0.0..
     [1 of 2] Compiling Lib
@@ -170,7 +171,7 @@     [2 of 2] Compiling Paths_helloworld
     [3 of 3] Linking .stack-work\dist\effaccc7\build\helloworld-exe\helloworld-exe.exe
     helloworld> copy/register
-    Installing library in ...\helloworld\.stack-work\install\c8c71a24\lib\x86_64-windows-ghc-9.6.6\helloworld-0.1.0.0-KFyX8zLxDvzLZURq3JaCVX
+    Installing library in ...\helloworld\.stack-work\install\c8c71a24\lib\x86_64-windows-ghc-9.8.4\helloworld-0.1.0.0-KFyX8zLxDvzLZURq3JaCVX
     Installing executable helloworld-exe in ...\helloworld\.stack-work\install\c8c71a24\bin
     Registering library for helloworld-0.1.0.0..
     ~~~
@@ -190,7 +191,7 @@ ~~~text
 helloworld> configure (lib + exe)
 ...
-helloworld> build (lib + exe) with ghc-9.6.6
+helloworld> build (lib + exe) with ghc-9.8.4
 ...
 helloworld> copy/register
 ...
@@ -275,18 +276,18 @@     helloworld-0.1.0.0: unregistering (components added: test:helloworld-test)
     helloworld> configure (lib + exe + test)
     Configuring helloworld-0.1.0.0...
-    helloworld> build (lib + exe + test) with ghc-9.6.6
+    helloworld> build (lib + exe + test) with ghc-9.8.4
     Preprocessing library for helloworld-0.1.0.0..
     Building library for helloworld-0.1.0.0..
     Preprocessing test suite 'helloworld-test' for helloworld-0.1.0.0..
     Building test suite 'helloworld-test' for helloworld-0.1.0.0..
     [1 of 2] Compiling Main
     [2 of 2] Compiling Paths_helloworld
-    [3 of 3] Linking .stack-work/dist/x86_64-linux-tinfo6/ghc-9.6.6/build/helloworld-test/helloworld-test
+    [3 of 3] Linking .stack-work/dist/x86_64-linux-tinfo6/ghc-9.8.4/build/helloworld-test/helloworld-test
     Preprocessing executable 'helloworld-exe' for helloworld-0.1.0.0..
     Building executable 'helloworld-exe' for helloworld-0.1.0.0..
     helloworld> copy/register
-    Installing library in .../helloworld/.stack-work/install/x86_64-linux-tinfo6/a2caceceda039eb4f791856f85a68f9582d4daf3d0527344693ff3d1fcd92ba4/9.6.6/lib/x86_64-linux-ghc-9.6.6/helloworld-0.1.0.0-KFyX8zLxDvzLZURq3JaCVX
+    Installing library in .../helloworld/.stack-work/install/x86_64-linux-tinfo6/a2caceceda039eb4f791856f85a68f9582d4daf3d0527344693ff3d1fcd92ba4/9.6.6/lib/x86_64-linux-ghc-9.8.4/helloworld-0.1.0.0-KFyX8zLxDvzLZURq3JaCVX
     Installing executable helloworld-exe in .../helloworld/.stack-work/install/x86_64-linux-tinfo6/a2caceceda039eb4f791856f85a68f9582d4daf3d0527344693ff3d1fcd92ba4/9.6.6/bin
     Registering library for helloworld-0.1.0.0..
     ~~~
@@ -297,7 +298,7 @@     helloworld-0.1.0.0: unregistering (components added: test:helloworld-test)
     helloworld> configure (lib + exe + test)
     Configuring helloworld-0.1.0.0...
-    helloworld> build (lib + exe + test) with ghc-9.6.6
+    helloworld> build (lib + exe + test) with ghc-9.8.4
     Preprocessing library for helloworld-0.1.0.0..
     Building library for helloworld-0.1.0.0..
     Preprocessing test suite 'helloworld-test' for helloworld-0.1.0.0..
@@ -308,7 +309,7 @@     Preprocessing executable 'helloworld-exe' for helloworld-0.1.0.0..
     Building executable 'helloworld-exe' for helloworld-0.1.0.0..
     helloworld> copy/register
-    Installing library in ...\helloworld\.stack-work\install\0aa166fa\lib\x86_64-windows-ghc-9.6.6\helloworld-0.1.0.0-KFyX8zLxDvzLZURq3JaCVX
+    Installing library in ...\helloworld\.stack-work\install\0aa166fa\lib\x86_64-windows-ghc-9.8.4\helloworld-0.1.0.0-KFyX8zLxDvzLZURq3JaCVX
     Installing executable helloworld-exe in ...\helloworld\.stack-work\install\0aa166fa\bin
     Registering library for helloworld-0.1.0.0..
     ~~~
@@ -330,113 +331,3 @@ ~~~
 
 Having build the test suite executable, Stack then automatically runs it.
-
-## Inner workings of Stack
-
-Let's look at the `helloworld` example in more detail to understand better how
-Stack works.
-
-The files in the project include:
-
-~~~text
-app/Main.hs
-src/Lib.hs
-test/Spec.hs
-ChangeLog.md
-README.md
-LICENSE
-.gitignore
-package.yaml
-helloworld.cabal
-Setup.hs
-stack.yaml
-~~~
-
-The `app/Main.hs`, `src/Lib.hs`, and `test/Spec.hs` files are all Haskell
-source files that compose the actual functionality of our project. We won't
-dwell on them here.
-
-The `ChangeLog.md`, `README.md`, `LICENSE` and `.gitignore` files have no effect
-on the build.
-
-The files of interest here are `package.yaml`, `helloworld.cabal`, `Setup.hs`
-and `stack.yaml`.
-
-### `package.yaml`
-
-Each package contains a file that describes the package. Stack uses the Cabal
-build system and that system uses a Cabal file named after the package (such as
-`helloworld.cabal`) to describe the package.
-
-However, Stack's preferred package description format is the
-[Hpack](https://github.com/sol/hpack) format.
-
-The `package.yaml` file describes the package in the Hpack format.
-
-If a `package.yaml` file is present, Stack will use its built-in Hpack
-functionality to create a Cabal file.
-
-??? question "What is covered by a package description?"
-
-    A package description includes information such as the package name and
-    version, and the package's *components*. A package can have an optional
-    main library component and optional named sub-library components. It can
-    also have optional executable components, test suite components and
-    benchmark components. The description identifies other packages on which
-    those components depend.
-
-    The
-    [Cabal User Guide](https://cabal.readthedocs.io/en/stable/cabal-package.html)
-    is the definitive reference for the Cabal package description format.
-
-    The [Hpack](https://github.com/sol/hpack#quick-reference) documentation
-    is the reference for the Hpack package description format.
-
-### `helloworld.cabal`
-
-The `helloworld.cabal` file is updated automatically as part of the
-`stack build` process and should not be modified.
-
-### `Setup.hs`
-
-The `Setup.hs` file is a component of the Cabal build system.
-
-Technically, it is not needed by Stack, but it is considered good practice to
-include it. The file we're using is boilerplate:
-
-~~~haskell
-import Distribution.Simple
-main = defaultMain
-~~~
-
-### `stack.yaml`
-
-Stack requires a Stack project-level configuration file for every project.
-`stack.yaml` is that file. The contents of the file define project-specific
-options and non-project-specific options that apply to the project.
-
-The contents of the file include comments beginning `#`. Ignoring those
-comments, the contents will look something like this:
-
-~~~yaml
-resolver:
-  url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/22/21.yaml
-packages:
-- .
-~~~
-
-The key [`resolver`](../configure/yaml/project.md#resolver) is a
-project-specific configuration option. Its value tells Stack *how* to build your
-package: which GHC version to use, which versions of package dependencies to
-use, and so on. Our value here says to use
-[LTS Haskell 22.21](https://www.stackage.org/lts-22.21), which implies GHC 9.6.5
-(which is why `stack build` installs that version of GHC if it is not already
-available to Stack). There are a number of values you can use for `resolver`,
-which we'll cover later.
-
-The key [`packages`](../configure/yaml/project.md#packages) is another
-project-specific configuration option. Its value tells Stack which project
-packages, located locally, to build. In our simple example, we have only a
-single project package, located in the same directory, so '`.`' suffices.
-However, Stack has powerful support for multi-package projects, which we'll
-describe as this guide progresses.
doc/tutorial/installed_package_databases.md view
@@ -1,6 +1,6 @@   <div class="hidden-warning"><a href="https://docs.haskellstack.org/"><img src="https://cdn.jsdelivr.net/gh/commercialhaskell/stack/doc/img/hidden-warning.svg"></a></div>
 
-# 4. Installed package databases
+# 6. Installed package databases
 
 Time to take a short break from hands-on examples and discuss a little
 architecture. Stack has the concept of multiple *databases*.
doc/tutorial/locations_used_by_stack.md view
@@ -1,6 +1,6 @@   <div class="hidden-warning"><a href="https://docs.haskellstack.org/"><img src="https://cdn.jsdelivr.net/gh/commercialhaskell/stack/doc/img/hidden-warning.svg"></a></div>
 
-# 9. Locations used by Stack
+# 11. Locations used by Stack
 
 Generally, you don't need to worry about where Stack stores various files. But
 some people like to know this stuff. That's when the `stack path` command is
@@ -55,9 +55,9 @@     /home/<user_name>/.stack/programs/x86_64-linux/ghc-9.0.2.installed
     ~~~
 
-=== "Windows (with PowerShell)"
+=== "Windows"
 
-    Command:
+    In PowerShell, command:
 
     ~~~text
     dir "$(stack path --programs)/*.installed"
doc/tutorial/multi-package_projects.md view
@@ -1,50 +1,79 @@   <div class="hidden-warning"><a href="https://docs.haskellstack.org/"><img src="https://cdn.jsdelivr.net/gh/commercialhaskell/stack/doc/img/hidden-warning.svg"></a></div>
 
-# 7. Multi-package projects
+# 9. Multi-package projects
 
-Until now, everything we've done with Stack has used a single-package project.
+Until now, everything we have done with Stack has used a single-package project.
 However, Stack's power truly shines when you're working on multi-package
 projects. All the functionality you'd expect to work just does: dependencies
 between packages are detected and respected, dependencies of all packages are
 just as one cohesive whole, and if anything fails to build, the build commands
 exits appropriately.
 
-Let's demonstrate this with the `wai-app-static` and `yackage` packages,
+Let us demonstrate this with the `wai-app-static` and `yackage` packages,
 starting in the root directory for all our Haskell projects. Command:
 
 ~~~text
 mkdir multi
 cd multi
 stack unpack wai-app-static yackage
-Unpacked wai-app-static (from Hackage) to .../multi/wai-app-static-3.1.7.4/
-Unpacked yackage (from Hackage) to .../multi/yackage-0.8.1/
+~~~
+
+The last command should report something like:
+
+~~~text
+...
+Unpacked wai-app-static (from Hackage) to .../multi/wai-app-static-3.1.9/.
+Unpacked yackage (from Hackage) to .../multi/yackage-0.8.1/.
+~~~
+
+Then command:
+
+~~~text
 stack init
-Looking for .cabal or package.yaml files to use to init the project.
-Using cabal packages:
-- wai-app-static-3.1.7.4/
-- yackage-0.8.1/
+~~~
 
-Cabal file warning in .../multi/yackage-0.8.1/yackage.cabal@47:40: version operators used. To use version operators the package needs to specify at least 'cabal-version: >= 1.8'.
-Cabal file warning in .../multi/yackage-0.8.1/yackage.cabal@21:36: version operators used. To use version operators the package needs to specify at least 'cabal-version: >= 1.8'.
-Selecting the best among 18 snapshots...
+The command should report something like:
 
-* Matches ...
+~~~text
+Looking for Cabal or package.yaml files to use to initialise Stack's
+project-level configuration file.
 
-Selected resolver: ...
-Initialising configuration using resolver: ...
-Total number of user packages considered: 2
-Writing configuration to file: stack.yaml
+Using the Cabal packages:
+* wai-app-static-3.1.9/
+* yackage-0.8.1/
+
+Cabal file warning in .../multi/yackage-0.8.1/yackage.cabal@47:40: version
+operators used. To use version operators the package needs to specify at least
+'cabal-version: >= 1.8'.
+Cabal file warning in .../multi/yackage-0.8.1/yackage.cabal@21:36: version
+operators used. To use version operators the package needs to specify at least
+'cabal-version: >= 1.8'.
+Selecting the best among 12 snapshots...
+
+Note: Matches ...
+
+Selected the snapshot ...
+Initialising Stack's project-level configuration file using snapshot ...
+Considered 2 user packages.
+Writing configuration to stack.yaml.
+Stack's project-level configuration file has been initialised.
+~~~
+
+Then command:
+
+~~~text
 stack build --haddock --test
-# Goes off to build a whole bunch of packages
 ~~~
 
+Stack should build and test the project packages.
+
 If you look at the `stack.yaml` file, you'll see exactly what you'd expect:
 
 ~~~yaml
-resolver:
-  url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/19/17.yaml
+snapshot:
+  url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/22/31.yaml
 packages:
-- wai-app-static-3.1.7.4
+- wai-app-static-3.1.9
 - yackage-0.8.1
 ~~~
+ doc/tutorial/package_description.md view
@@ -0,0 +1,415 @@+<div class="hidden-warning"><a href="https://docs.haskellstack.org/"><img src="https://cdn.jsdelivr.net/gh/commercialhaskell/stack/doc/img/hidden-warning.svg"></a></div>
+
+# 2. Package description
+
+Let us begin to look at the `helloworld` example in more detail to understand
+better how Stack works.
+
+The contents of the project directory are set out below. Click
+:material-plus-circle: to learn more about each file or directory:
+
+~~~shell
+.
+├── .stack-work # (1)!
+│   └── ...
+│
+├── app
+│   └── Main.hs # (2)!
+├── src
+│   └── Lib.hs # (3)!
+├── test
+│   └── Spec.hs # (4)!
+│
+├── .gitignore # (5)!
+├── CHANGELOG.md # (6)!
+├── LICENSE # (7)!
+├── README.md # (8)!
+│
+├── package.yaml # (9)!
+├── helloworld.cabal # (10)!
+├── Setup.hs # (11)!
+│
+└── stack.yaml # (12)!
+~~~
+
+1.  The Stack work directory for the project and the project package.
+
+    Stack work directories are ones in which Stack stores files created during
+    the build process. A product of the build - does not affect the build (other
+    than to avoid rebuilding things unnecessarily).
+
+2.  The Haskell source code for the executable (application).
+
+    As your project develops you can add further source code files to the `app`
+    directory.
+
+3.  The executable uses a library. The Haskell source code for the library.
+
+    As your project develops you can add further source code files to the `src`
+    directory.
+
+4.  The package has a test suite executable. The Haskell source code for the
+    test suite.
+
+    As your project develops you can add further source code files to the `test`
+    directory.
+
+5.  A text file used to configure the Git tool to ignore certain files. Does not
+    affect the build.
+
+6.  A text file in the Markdown format in which changes to the project can be
+    documented. Does not affect the build.
+
+7.  A text file used to document the copyright applicable to the project's files
+    and the licence for the use of those files. Does not affect the build.
+
+8.  A text file in the Markdown format which is intended to be read by users of
+    the project. Does not affect the build.
+
+9.  A file describing the package in the Hpack format. See further below.
+
+10. A file describing the package in the Cabal format. See further below.
+
+11. A Haskell source file which is a component of the Cabal build system. See
+    further below.
+
+12. A text file in the YAML format, containing Stack's project-level
+    configuration. See the next part of this guide to getting started.
+
+The files of most interest here are `package.yaml` and `helloworld.cabal`. We
+will also explain the `Setup.hs` file.
+
+## Package description formats
+
+Each package contains a file that describes the package. It is located in the
+package's root directory.
+
+??? question "What is covered by a package description?"
+
+    A package description includes information such as the package name and
+    version, and the package's *components*. A package can have an optional
+    main library component and optional named sub-library components. It can
+    also have optional executable components, test suite components and
+    benchmark components. The description identifies other packages on which
+    those components depend.
+
+Stack is aware of two different formats of package description, and both files
+may be present in the package's root directory:
+
+<div class="grid cards" markdown>
+
+-   :material-package-variant:{ .lg .middle } __Cabal: A Cabal file__
+
+    Used directly by the Cabal build system.
+
+    Unique but simple syntax.
+
+    Named after the package (eg `helloworld.cabal`).
+
+    If no `package.yaml` file, used directly by Stack.
+
+    ---
+
+    Specified by the Cabal project:
+
+    [:octicons-arrow-right-24: Learn more](https://cabal.readthedocs.io/en/stable/cabal-package-description-file.html)
+
+-   :material-package-variant-plus:{ .lg .middle } __Hpack: a package.yaml file__
+
+    Used by Stack to create a Cabal file.
+
+    YAML syntax.
+
+    Named `package.yaml`.
+
+    Stack's preferred format. If present, used by Stack.
+
+    ---
+
+    Specified by the Hpack project:
+
+    [:octicons-arrow-right-24: Learn more](https://github.com/sol/hpack?tab=readme-ov-file#documentation)
+
+</div>
+
+??? question "Why use the Hpack format?"
+
+    A `package.yaml` file can be more concise and less repetitive than the Cabal
+    file that is generated from it. That is because the Hpack format uses
+    defaults and top-level fields common to sections. The YAML syntax, which may
+    already be familiar for some users, can also avoid repetition.
+
+    In particular, the format's defaults can infer the names of exposed and
+    other modules.
+
+    The format allows a user to specify defaults in a file on GitHub or a local
+    file.
+
+??? question "I use the Hpack format. Should I also check-in a Cabal file to my repository?"
+
+    Yes. This helps people who do not use Stack or the Hpack tool separately.
+
+## `package.yaml`
+
+The `package.yaml` file describes the package in the
+[Hpack format](https://github.com/sol/hpack?tab=readme-ov-file#documentation).
+
+If a `package.yaml` file is present, Stack will use its built-in Hpack
+functionality to create a Cabal file.
+
+??? question "What are the contents of the `package.yaml` file?"
+
+    The contents of the `package.yaml` file for the `helloworld` example are
+    described below, using additional YAML comments:
+
+    ~~~yaml
+    # The name of the package:
+    name:                helloworld
+    # The version of the package:
+    version:             0.1.0.0
+    # The GitHub repository for the package (optional):
+    github:              "githubuser/helloworld"
+    # The licence for the use of the package's files (optional):
+    license:             BSD-3-Clause
+    # The author of the package (optional):
+    author:              "Author name here"
+    # The email address to contact the maintainer of the package (optional):
+    maintainer:          "example@example.com"
+    # The copyright for the package's files (optional):
+    copyright:           "2024 Author name here"
+
+    # Extra files (if any) to be distributed with the source files of the
+    # package:
+    extra-source-files:
+    - README.md
+    - CHANGELOG.md
+
+    # Metadata used when publishing your package
+    # synopsis:            Short description of your package
+    # category:            Web
+
+    # To avoid duplicated efforts in documentation and dealing with the
+    # complications of embedding Haddock markup inside cabal files, it is
+    # common to point users to the README.md file.
+    description:         Please see the README on GitHub at
+                         <https://github.com/githubuser/helloworld#readme>
+
+    # Dependencies applicable to all components:
+    dependencies:
+    - base >= 4.7 && < 5
+
+    # GHC options (if any) common to all components:
+    ghc-options:
+    # These GHC flags affect which warnings GHC will emit:
+    - -Wall
+    - -Wcompat
+    - -Widentities
+    - -Wincomplete-record-updates
+    - -Wincomplete-uni-patterns
+    - -Wmissing-export-lists
+    - -Wmissing-home-modules
+    - -Wpartial-fields
+    - -Wredundant-constraints
+
+    # The main (unnamed) library component of the package (if it has one):
+    library:
+      # Directories containing source files:
+      source-dirs: src
+
+    # The executable components of the package (if it has any):
+    executables:
+      # The executable component named 'helloworld-exe':
+      helloworld-exe:
+        # The source file exporting the 'main' function:
+        main:                Main.hs
+        # Directories containing source files:
+        source-dirs:         app
+        # GHC options applicable to the component:
+        ghc-options:
+        # Link the program with the 'threaded' version of GHC's runtime system:
+        - -threaded
+        # Make all of GHC's runtime system (RTS) options available:
+        - -rtsopts
+        # Compile so as to use simultaneous threads when running the program,
+        # based on how many processors are in the machine.
+        - -with-rtsopts=-N
+        # Dependencies applicable to the component:
+        dependencies:
+        # The main library of the package:
+        - helloworld
+
+    # The test suite components of the package (if it has any). Test suites have
+    # keys in common with executables:
+    tests:
+      # The test suite component named 'helloworld-test':
+      helloworld-test:
+        main:                Spec.hs
+        source-dirs:         test
+        ghc-options:
+        - -threaded
+        - -rtsopts
+        - -with-rtsopts=-N
+        dependencies:
+        - helloworld
+    ~~~
+
+??? question "What are the contents of a minimal `package.yaml` file?"
+
+    For a package `my-package-0.1.0.0` with a main library, an executable
+    named `my-program`, and a dependency only on the `base` package, its
+    `package.yaml` file could be as simple as the one below:
+
+    ~~~yaml
+    package: my-package
+    version: 0.1.0.0
+    dependencies:
+    - base
+    library:
+      source-dirs: src
+    executables:
+      my-program:
+        main: Main.hs
+        source-dirs: app
+        ghc-options:
+        - -threaded
+        - -rtsopts
+        - -with-rtsopts=-N
+        dependencies:
+        - my-package
+    ~~~
+
+## `helloworld.cabal`
+
+In the case of the `helloworld` example, the `helloworld.cabal` file is updated
+automatically as part of the `stack build` process and should not be modified.
+
+If the `package.yaml` file were deleted, Stack would use the Cabal file
+directly.
+
+??? question "What are the contents of the `helloworld.cabal` file?"
+
+    The contents of the `helloworld.cabal` file are described below, using
+    additional Cabal file comments:
+
+    ~~~text
+    -- The version of the Cabal package description format specification:
+    cabal-version: 2.2
+
+    -- This file has been generated from package.yaml by hpack version 0.37.0.
+    --
+    -- see: https://github.com/sol/hpack
+
+    -- The name of the package:
+    name:           helloworld
+    -- The version of the package:
+    version:        0.1.0.0
+    -- The description of the package:
+    description:    Please see the README on GitHub at
+                    <https://github.com/githubuser/helloworld#readme>
+    -- A URL for the package:
+    homepage:       https://github.com/githubuser/helloworld#readme
+    -- A URL for bug reports for the package:
+    bug-reports:    https://github.com/githubuser/helloworld/issues
+    -- The author of the package:
+    author:         Author name here
+    -- The email address to contact the maintainer of the package:
+    maintainer:     example@example.com
+    -- The copyright for the package's files:
+    copyright:      2024 Author name here
+    -- The licence for the use of the package's files:
+    license:        BSD-3-Clause
+    -- The file documenting the terms of the licence:
+    license-file:   LICENSE
+    -- The Cabal system build type of the package:
+    build-type:     Simple
+    -- Extra files to be distributed with the source files of the package:
+    extra-source-files:
+        README.md
+        CHANGELOG.md
+
+    -- The respository for the package:
+    source-repository head
+      type: git
+      location: https://github.com/githubuser/helloworld
+
+    -- The main (unnamed) library component of the package:
+    library
+      -- The modules that the library exposes:
+      exposed-modules:
+          Lib
+      -- The other modules of the compoment:
+      other-modules:
+          Paths_helloworld
+      -- Automatically generated modules of the component:
+      autogen-modules:
+          Paths_helloworld
+      -- Directories containing source files:
+      hs-source-dirs:
+          src
+      -- GHC options applicable to the component. In this case, they are flags
+      -- that affect which warnings GHC will emit:
+      ghc-options: -Wall -Wcompat -Widentities -Wincomplete-record-updates
+                   -Wincomplete-uni-patterns -Wmissing-export-lists
+                   -Wmissing-home-modules -Wpartial-fields
+                   -Wredundant-constraints
+      -- Dependencies applicable to the building of the component:
+      build-depends:
+          base >=4.7 && <5
+      -- The applicable version of the Haskell language:
+      default-language: Haskell2010
+
+    -- The executable 'helloworld-exe' component of the package. Executable
+    -- components have fields in common with library components:
+    executable helloworld-exe
+      -- The source file exporting the 'main' function:
+      main-is: Main.hs
+      other-modules:
+          Paths_helloworld
+      autogen-modules:
+          Paths_helloworld
+      hs-source-dirs:
+          app
+      -- GHC options applicable to the component. In this case, they include
+      -- flags that affect GHC's runtime system (RTS).
+      ghc-options: -Wall -Wcompat -Widentities -Wincomplete-record-updates
+                   -Wincomplete-uni-patterns -Wmissing-export-lists
+                   -Wmissing-home-modules -Wpartial-fields
+                   -Wredundant-constraints -threaded -rtsopts -with-rtsopts=-N
+      build-depends:
+          base >=4.7 && <5
+        , helloworld
+      default-language: Haskell2010
+
+    -- The test suite 'helloworld-test' component of the package. Test suite
+    -- components have fields in common with executable components:
+    test-suite helloworld-test
+      -- The type of the test suite:
+      type: exitcode-stdio-1.0
+      main-is: Spec.hs
+      other-modules:
+          Paths_helloworld
+      autogen-modules:
+          Paths_helloworld
+      hs-source-dirs:
+          test
+      ghc-options: -Wall -Wcompat -Widentities -Wincomplete-record-updates
+                   -Wincomplete-uni-patterns -Wmissing-export-lists
+                   -Wmissing-home-modules -Wpartial-fields
+                   -Wredundant-constraints -threaded -rtsopts -with-rtsopts=-N
+      build-depends:
+          base >=4.7 && <5
+        , helloworld
+      default-language: Haskell2010
+    ~~~
+
+## `Setup.hs`
+
+The `Setup.hs` file is a component of the Cabal build system.
+
+Technically, it is not needed by Stack, but it is considered good practice to
+include it. The file we're using is boilerplate:
+
+~~~haskell
+import Distribution.Simple
+main = defaultMain
+~~~
+ doc/tutorial/project_configuration.md view
@@ -0,0 +1,55 @@+<div class="hidden-warning"><a href="https://docs.haskellstack.org/"><img src="https://cdn.jsdelivr.net/gh/commercialhaskell/stack/doc/img/hidden-warning.svg"></a></div>
+
+# 3. Project configuration
+
+Let us continue to look at the `helloworld` example in more detail to understand
+better how Stack works.
+
+As discussed in the previous part of this guide to getting started, some of the
+contents of the project directory are set out below. The item of interest here
+is the `stack.yaml` file.
+
+~~~text
+.
+├── .stack-work
+│   └── ...
+...
+│
+├── package.yaml
+├── helloworld.cabal
+├── Setup.hs
+│
+└── stack.yaml
+~~~
+
+## `stack.yaml`
+
+Stack requires a Stack project-level configuration file for every project.
+`stack.yaml` is that file. The contents of the file define project-specific
+options and non-project-specific options that apply to the project.
+
+The contents of the file include comments beginning `#`. Ignoring those
+comments, the contents will look something like this:
+
+~~~yaml
+snapshot:
+  url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/23/0.yaml
+packages:
+- .
+~~~
+
+The key [`snapshot`](../configure/yaml/project.md#snapshot) is a
+project-specific configuration option. Its value tells Stack *how* to build your
+package: which GHC version to use, which versions of package dependencies to
+use, and so on. Our value here says to use
+[LTS Haskell 23.0](https://www.stackage.org/lts-23.0), which implies GHC 9.8.4
+(which is why `stack build` installs that version of GHC if it is not already
+available to Stack). There are a number of values you can use for `snapshot`,
+which we'll cover later.
+
+The key [`packages`](../configure/yaml/project.md#packages) is another
+project-specific configuration option. Its value tells Stack which project
+packages, located locally, to build. In our simple example, we have only a
+single project package, located in the same directory, so '`.`' suffices.
+However, Stack has powerful support for multi-package projects, which we'll
+describe as this guide progresses.
doc/tutorial/stack_build_synonyms.md view
@@ -1,6 +1,6 @@   <div class="hidden-warning"><a href="https://docs.haskellstack.org/"><img src="https://cdn.jsdelivr.net/gh/commercialhaskell/stack/doc/img/hidden-warning.svg"></a></div>
 
-# 5. `stack build` synonyms
+# 7. `stack build` synonyms
 
 Let's look at a subset of the `stack --help` output:
doc/tutorial/stack_build_targets.md view
@@ -1,6 +1,6 @@   <div class="hidden-warning"><a href="https://docs.haskellstack.org/"><img src="https://cdn.jsdelivr.net/gh/commercialhaskell/stack/doc/img/hidden-warning.svg"></a></div>
 
-# 6. `stack build` targets
+# 8. `stack build` targets
 
 We haven't discussed this too much yet, but, in addition to having a number of
 synonyms *and* taking a number of options on the command line, the `build`
doc/tutorial/stack_configuration.md view
@@ -1,6 +1,6 @@   <div class="hidden-warning"><a href="https://docs.haskellstack.org/"><img src="https://cdn.jsdelivr.net/gh/commercialhaskell/stack/doc/img/hidden-warning.svg"></a></div>
 
-# 12. Stack configuration
+# 14. Stack configuration
 
 Whenever you run something with Stack, it needs a project-level configuration
 file. The algorithm Stack uses to find such a file is:
doc/tutorial/tutorial_conclusion.md view
@@ -1,6 +1,6 @@   <div class="hidden-warning"><a href="https://docs.haskellstack.org/"><img src="https://cdn.jsdelivr.net/gh/commercialhaskell/stack/doc/img/hidden-warning.svg"></a></div>
 
-# 13. In conclusion
+# 15. In conclusion
 
 Stack is not the only tool available for building Haskell code. If you are
 happy building Haskell code with other tools, you may not need Stack. If
doc/tutorial/using_ghc_interactively.md view
@@ -1,6 +1,6 @@   <div class="hidden-warning"><a href="https://docs.haskellstack.org/"><img src="https://cdn.jsdelivr.net/gh/commercialhaskell/stack/doc/img/hidden-warning.svg"></a></div>
 
-# 11. Using GHC interactively
+# 13. Using GHC interactively
 
 GHCi is the interactive GHC environment, a.k.a. the REPL. You *could* access it
 with command:
src/Stack.hs view
@@ -12,6 +12,7 @@ import           Control.Monad.Extra ( whenJust )
 import           GHC.IO.Encoding ( mkTextEncoding, textEncodingName )
 import           Options.Applicative.Builder.Extra ( execExtraHelp )
+import           Path ( parseAbsFile )
 import           Stack.BuildInfo ( versionString' )
 import           Stack.CLI ( commandLineHandler )
 import           Stack.Constants ( stackProgName )
@@ -30,7 +31,7 @@                    , stackVersion
                    )
 import           System.Directory ( getCurrentDirectory )
-import           System.Environment ( getArgs, getProgName )
+import           System.Environment ( executablePath, getArgs, getProgName )
 import           System.IO ( hGetEncoding, hPutStrLn, hSetEncoding )
 import           System.Terminal ( hIsTerminalDeviceOrMinTTY )
 
@@ -61,6 +62,8 @@   hSetTranslit stderr
   args <- getArgs
   progName <- getProgName
+  mExecutableFilePath <- fromMaybe (pure Nothing) executablePath
+  let mExecutablePath = mExecutableFilePath >>= parseAbsFile
   isTerminal <- hIsTerminalDeviceOrMinTTY stdout
   execExtraHelp
     args
@@ -73,12 +76,14 @@     (nixOptsParser False)
     ("Only showing --" ++ nixCmdName ++ "* options.")
   currentDir <- getCurrentDirectory
-  eGlobalRun <- try $ commandLineHandler currentDir progName False
+  eGlobalRun <-
+    try $ commandLineHandler currentDir progName mExecutablePath False
   case eGlobalRun of
     Left (exitCode :: ExitCode) ->
       throwIO exitCode
     Right (globalMonoid, run) -> do
-      global <- globalOptsFromMonoid isTerminal globalMonoid
+      global <-
+        globalOptsFromMonoid progName mExecutablePath isTerminal globalMonoid
       when (global.logLevel == LevelDebug) $
         hPutStrLn stderr versionString'
       whenJust global.reExecVersion $ \expectVersion -> do
src/Stack/Build.hs view
@@ -53,8 +53,7 @@ import           Stack.Types.CompilerPaths ( HasCompiler, cabalVersionL )
 import           Stack.Types.ComponentUtils
                    ( StackUnqualCompName, unqualCompToString )
-import           Stack.Types.Config
-                   ( Config (..), HasConfig (..), buildOptsL )
+import           Stack.Types.Config ( Config (..), HasConfig (..), buildOptsL )
 import           Stack.Types.ConfigureOpts ( BaseConfigOpts (..) )
 import           Stack.Types.EnvConfig
                    ( EnvConfig (..), HasEnvConfig (..), HasSourceMap
@@ -71,8 +70,7 @@ import           Stack.Types.Platform ( HasPlatform (..) )
 import           Stack.Types.Runner ( Runner, globalOptsL )
 import           Stack.Types.SourceMap
-                   ( SMTargets (..)
-                   , SourceMap (..), Target (..) )
+                   ( SMTargets (..), SourceMap (..), Target (..) )
 import           System.Terminal ( fixCodePage )
 
 newtype CabalVersionPrettyException
src/Stack/Build/ConstructPlan.hs view
@@ -65,7 +65,7 @@ import qualified Stack.Types.ConfigureOpts as ConfigureOpts
 import           Stack.Types.Curator ( Curator (..) )
 import           Stack.Types.Dependency ( DepValue (..), isDepTypeLibrary )
-import           Stack.Types.DumpPackage ( DumpPackage (..), dpParentLibIdent )
+import           Stack.Types.DumpPackage ( DumpPackage (..), sublibParentPkgId )
 import           Stack.Types.EnvConfig ( EnvConfig (..), HasEnvConfig (..) )
 import           Stack.Types.EnvSettings
                    ( EnvSettings (..), minimalEnvSettings )
@@ -371,7 +371,7 @@    where
     gid = dp.ghcPkgId
     ident = dp.packageIdent
-    mParentLibId = dpParentLibIdent dp
+    mParentLibId = sublibParentPkgId dp
     deps = dp.depends
 
   maybeUnregisterReason ::
src/Stack/Build/Execute.hs view
@@ -58,18 +58,16 @@                    , taskProvides
                    )
 import           Stack.Types.Build.Exception ( BuildPrettyException (..) )
-import           Stack.Types.BuildOpts ( BuildOpts (..), TestOpts (..)
-                   )
+import           Stack.Types.BuildOpts
+                   ( BenchmarkOpts (..), BuildOpts (..), TestOpts (..) )
 import           Stack.Types.BuildOptsCLI ( BuildOptsCLI (..) )
 import           Stack.Types.BuildOptsMonoid ( ProgressBarFormat (..) )
 import           Stack.Types.Compiler ( ActualCompiler (..) )
 import           Stack.Types.CompilerPaths ( HasCompiler (..), getGhcPkgExe )
 import           Stack.Types.ComponentUtils
                    ( StackUnqualCompName, unqualCompToString )
-import           Stack.Types.Config
-                   ( Config (..), HasConfig (..), buildOptsL )
-import           Stack.Types.ConfigureOpts
-                   ( BaseConfigOpts (..) )
+import           Stack.Types.Config ( Config (..), HasConfig (..), buildOptsL )
+import           Stack.Types.ConfigureOpts ( BaseConfigOpts (..) )
 import           Stack.Types.DumpPackage ( DumpPackage (..) )
 import           Stack.Types.EnvConfig
                    ( HasEnvConfig (..), actualCompilerVersionL
@@ -87,10 +85,9 @@ import           Stack.Types.Package
                    ( LocalPackage (..), Package (..), packageIdentifier )
 import           Stack.Types.Platform ( HasPlatform (..) )
-import           Stack.Types.Runner ( HasRunner, terminalL )
+import           Stack.Types.Runner ( terminalL, viewExecutablePath )
 import           Stack.Types.SourceMap ( Target )
 import qualified System.Directory as D
-import           System.Environment ( getExecutablePath )
 import qualified System.FilePath as FP
 
 -- | Fetch the packages necessary for a build, for example in combination with
@@ -112,7 +109,7 @@       TTRemotePackage _ _ pkgloc -> Set.singleton pkgloc
 
 -- | Print a description of build plan for human consumption.
-printPlan :: (HasRunner env, HasTerm env) => Plan -> RIO env ()
+printPlan :: HasEnvConfig env => Plan -> RIO env ()
 printPlan plan = do
   case Map.elems plan.unregisterLocal of
     [] -> prettyInfo $
@@ -139,24 +136,47 @@         <> bulletedList (map displayTask xs)
         <> line
 
+  buildOpts <- view buildOptsL
   let hasTests = not . Set.null . testComponents . taskComponents
       hasBenches = not . Set.null . benchComponents . taskComponents
       tests = Map.elems $ Map.filter hasTests plan.finals
       benches = Map.elems $ Map.filter hasBenches plan.finals
+      runTests = buildOpts.testOpts.runTests
+      runBenchmarks = buildOpts.benchmarkOpts.runBenchmarks
 
-  unless (null tests) $ do
-    prettyInfo $
-         flow "Would test:"
-      <> line
-      <> bulletedList (map displayTask tests)
-      <> line
+  unless (null tests) $
+    if runTests
+      then
+        prettyInfo $
+             flow "Would test:"
+          <> line
+          <> bulletedList (map displayTask tests)
+          <> line
+      else
+        prettyInfo $
+             fillSep
+               [ flow "Would not test, as running disabled by"
+               , style Shell "--no-run-tests"
+               , "flag."
+               ]
+          <> line
 
-  unless (null benches) $ do
-    prettyInfo $
-         flow "Would benchmark:"
-      <> line
-      <> bulletedList (map displayTask benches)
-      <> line
+  unless (null benches) $
+    if runBenchmarks
+      then
+        prettyInfo $
+             flow "Would benchmark:"
+          <> line
+          <> bulletedList (map displayTask benches)
+          <> line
+      else
+        prettyInfo $
+             fillSep
+               [ flow "Would not benchmark, as running disabled by"
+               , style Shell "--no-run-benchmarks"
+               , "flag."
+               ]
+          <> line
 
   case Map.toList plan.installExes of
     [] -> prettyInfo $
@@ -282,7 +302,8 @@           Platform _ Windows -> ".exe"
           _ -> ""
 
-  currExe <- liftIO getExecutablePath -- needed for windows, see below
+  -- needed for windows, see below
+  currExe <- toFilePath <$> viewExecutablePath
 
   installed <- forMaybeM (Map.toList exes) $ \(name, loc) -> do
     let strName = unqualCompToString name
@@ -346,8 +367,18 @@              -> ExecuteEnv
              -> RIO env ()
 executePlan' installedMap0 targets plan ee = do
+  config <- view configL
   let !buildOpts = ee.buildOpts
-  let !testOpts = buildOpts.testOpts
+      !testOpts = buildOpts.testOpts
+      !benchmarkOpts = buildOpts.benchmarkOpts
+      runTests = testOpts.runTests
+      runBenchmarks = benchmarkOpts.runBenchmarks
+      noNotifyIfNoRunTests = not config.notifyIfNoRunTests
+      noNotifyIfNoRunBenchmarks = not config.notifyIfNoRunBenchmarks
+      hasTests = not . Set.null . testComponents . taskComponents
+      hasBenches = not . Set.null . benchComponents . taskComponents
+      tests = Map.elems $ Map.filter hasTests plan.finals
+      benches = Map.elems $ Map.filter hasBenches plan.finals
   when testOpts.coverage deleteHpcReports
   cv <- view actualCompilerVersionL
   whenJust (nonEmpty $ Map.toList plan.unregisterLocal) $ \ids -> do
@@ -379,6 +410,24 @@         buildOpts.keepGoing
   terminal <- view terminalL
   terminalWidth <- view termWidthL
+  unless (noNotifyIfNoRunTests || runTests || null tests) $
+    prettyInfo $
+      fillSep
+        [ flow "All test running disabled by"
+        , style Shell "--no-run-tests"
+        , flow "flag. To mute this message in future, set"
+        , style Shell (flow "notify-if-no-run-tests: false")
+        , flow "in Stack's configuration."
+        ]
+  unless (noNotifyIfNoRunBenchmarks || runBenchmarks || null benches) $
+    prettyInfo $
+      fillSep
+        [ flow "All benchmark running disabled by"
+        , style Shell "--no-run-benchmarks"
+        , flow "flag. To mute this message in future, set"
+        , style Shell (flow "notify-if-no-run-benchmarks: false")
+        , flow "in Stack's configuration."
+        ]
   errs <- liftIO $ runActions threads keepGoing actions $
     \doneVar actionsVar -> do
       let total = length actions
@@ -543,8 +592,9 @@             , concurrency = ConcurrencyAllowed
             }
       ) $
-      -- These are the "final" actions - running tests and benchmarks.
-      ( if Set.null tests
+      -- These are the "final" actions - running test suites and benchmarks,
+      -- unless --no-run-tests or --no-run-benchmarks is enabled.
+      ( if Set.null tests || not runTests
           then id
           else (:) Action
             { actionId = ActionId pkgId ATRunTests
@@ -557,7 +607,7 @@             , concurrency = ConcurrencyAllowed
             }
       ) $
-      ( if Set.null benches
+      ( if Set.null benches || not runBenchmarks
           then id
           else (:) Action
             { actionId = ActionId pkgId ATRunBenchmarks
@@ -594,6 +644,8 @@   bopts = ee.buildOpts
   topts = bopts.testOpts
   beopts = bopts.benchmarkOpts
+  runTests = topts.runTests
+  runBenchmarks = beopts.runBenchmarks
 
 taskComponents :: Task -> Set NamedComponent
 taskComponents task =
src/Stack/Build/ExecutePackage.hs view
@@ -978,11 +978,8 @@       config <- view configL
       let needHpc = topts.coverage
       toRun <-
-        if topts.disableRun
-          then do
-            announce "Test running disabled by --no-run-tests flag."
-            pure False
-          else if topts.rerunTests
+        if topts.runTests
+          then if topts.rerunTests
             then pure True
             else do
               status <- getTestStatus pkgDir
@@ -999,7 +996,7 @@                       announce "rerunning previously failed test"
                       pure True
                 TSUnknown -> pure True
-
+          else prettyThrowM $ ActionNotFilteredBug "singleTest"
       when toRun $ do
         buildDir <- distDirFromDir pkgDir
         hpcDir <- hpcDirFromDir pkgDir
@@ -1260,14 +1257,10 @@       let args = map unqualCompToString benchesToRun <> maybe []
                        ((:[]) . ("--benchmark-options=" <>))
                        beopts.additionalArgs
-
       toRun <-
-        if beopts.disableRun
-          then do
-            announce "Benchmark running disabled by --no-run-benchmarks flag."
-            pure False
-          else pure True
-
+        if beopts.runBenchmarks
+          then pure True
+          else prettyThrowM $ ActionNotFilteredBug "singleBench"
       when toRun $ do
         announce "benchmarks"
         cabal CloseOnException KeepTHLoading ("bench" : args)
src/Stack/Build/Installed.hs view
@@ -22,7 +22,7 @@ import           Stack.SourceMap ( getPLIVersion, loadVersion )
 import           Stack.Types.CompilerPaths ( getGhcPkgExe )
 import           Stack.Types.DumpPackage
-                   ( DumpPackage (..), SublibDump (..), dpParentLibIdent )
+                   ( DumpPackage (..), SublibDump (..), sublibParentPkgId )
 import           Stack.Types.EnvConfig
                     ( HasEnvConfig, packageDatabaseDeps, packageDatabaseExtra
                     , packageDatabaseLocal
@@ -199,7 +199,7 @@     -- If the sourceMap has nothing to say about this package,
     -- check if it represents a sub-library first
     -- See: https://github.com/commercialhaskell/stack/issues/3899
-    case dpParentLibIdent dp of
+    case sublibParentPkgId dp of
       Just (PackageIdentifier parentLibName version') ->
         case Map.lookup parentLibName installMap of
           Nothing -> checkNotFound
src/Stack/Build/Source.hs view
@@ -31,8 +31,8 @@ import           Stack.PackageFile ( getPackageFile )
 import           Stack.Prelude
 import           Stack.SourceMap
-                   ( DumpedGlobalPackage, getCompilerInfo, immutableLocSha
-                   , mkProjectPackage, pruneGlobals
+                   ( getCompilerInfo, immutableLocSha, mkProjectPackage
+                   , pruneGlobals
                    )
 import           Stack.Types.ApplyGhcOptions ( ApplyGhcOptions (..) )
 import           Stack.Types.ApplyProgOptions ( ApplyProgOptions (..) )
@@ -48,6 +48,7 @@ import           Stack.Types.CompilerPaths ( HasCompiler, getCompilerPath )
 import           Stack.Types.Config ( Config (..), HasConfig (..), buildOptsL )
 import           Stack.Types.Curator ( Curator (..) )
+import           Stack.Types.DumpPackage ( DumpedGlobalPackage )
 import           Stack.Types.EnvConfig
                    ( EnvConfig (..), HasEnvConfig (..), HasSourceMap (..)
                    , actualCompilerVersionL
src/Stack/BuildOpts.hs view
@@ -17,8 +17,9 @@                    , TestOpts (..)
                    )
 import           Stack.Types.BuildOptsMonoid
-                   ( BuildOptsMonoid (..), CabalVerbosity (..)
-                   , ProgressBarFormat (..), TestOptsMonoid (..)
+                   ( BenchmarkOptsMonoid (..), BuildOptsMonoid (..)
+                   , CabalVerbosity (..), ProgressBarFormat (..)
+                   , TestOptsMonoid (..)
                    )
 
 defaultBuildOpts :: BuildOpts
@@ -63,7 +64,7 @@   { rerunTests = defaultFirstTrue toMonoid.rerunTests
   , additionalArgs = []
   , coverage = defaultFirstFalse toMonoid.coverage
-  , disableRun = defaultFirstFalse toMonoid.disableRun
+  , runTests = defaultFirstTrue toMonoid.runTests
   , maximumTimeSeconds = Nothing
   , allowStdin = defaultFirstTrue toMonoid.allowStdin
   }
@@ -76,5 +77,7 @@ defaultBenchmarkOpts :: BenchmarkOpts
 defaultBenchmarkOpts = BenchmarkOpts
   { additionalArgs = Nothing
-  , disableRun = False
+  , runBenchmarks = defaultFirstTrue beoMonoid.runBenchmarks
   }
+ where
+  beoMonoid = undefined :: BenchmarkOptsMonoid
src/Stack/CLI.hs view
@@ -18,6 +18,7 @@                    ( boolFlags, extraHelpOption )
 import           Options.Applicative.Complicated
                    ( addCommand, addSubCommands, complicatedOptions )
+import           Path ( filename )
 import           RIO.NonEmpty ( (<|) )
 import qualified RIO.NonEmpty as NE
 import qualified RIO.Process ( exec )
@@ -26,7 +27,10 @@ import           Stack.BuildInfo ( hpackVersion, versionString' )
 import           Stack.Clean ( CleanCommand (..), cleanCmd )
 import           Stack.ConfigCmd as ConfigCmd
-import           Stack.Constants ( globalFooter, osIsWindows, stackProgName )
+import           Stack.Constants
+                   ( globalFooter, osIsWindows, relFileStack, relFileStackDotExe
+                   , stackProgName
+                   )
 import           Stack.Coverage ( hpcReportCmd )
 import           Stack.Docker
                    ( dockerCmdName, dockerHelpOptName, dockerPullCmdName )
@@ -84,7 +88,7 @@ import           Stack.Upgrade ( upgradeCmd )
 import           Stack.Upload ( uploadCmd )
 import qualified System.Directory as D
-import           System.Environment ( getProgName, withArgs )
+import           System.Environment ( withArgs )
 import           System.FilePath ( pathSeparator, takeDirectory )
 
 -- | Type representing \'pretty\' exceptions thrown by functions in the
@@ -103,9 +107,14 @@ commandLineHandler ::
      FilePath
   -> String
+     -- ^ The name of the current Stack executable, as it was invoked.
+  -> Maybe (Path Abs File)
+     -- ^ The path to the current Stack executable, if the operating system
+     -- provides a reliable way to determine it and where a result was
+     -- available.
   -> Bool
   -> IO (GlobalOptsMonoid, RIO Runner ())
-commandLineHandler currentDir progName isInterpreter =
+commandLineHandler currentDir progName mExecutablePath isInterpreter =
   -- Append the relevant default (potentially affecting the LogLevel) *after*
   -- appending the global options of the `stack` command to the global options
   -- of the subcommand - see #5326.
@@ -136,7 +145,7 @@               parseResultHandler (NE.toList args') f
             else
               secondaryCommandHandler args' f
-                >>= interpreterHandler currentDir args'
+                >>= interpreterHandler progName mExecutablePath currentDir args'
         )
         (NE.nonEmpty args)
       Nothing -> parseResultHandler args f
@@ -220,7 +229,7 @@         ( do
             addCommand'
               ConfigCmd.cfgCmdSetName
-              "Sets a key in YAML configuration file to value."
+              "Sets a key in configuration file to value."
               (withConfig NoReexec . cfgCmdSet)
               configCmdSetParser
             addCommandWithLocalInstallRootFooter
@@ -516,11 +525,18 @@     \upgrade Stack."
     (upgradeOptsParser onlyLocalBins)
    where
-    onlyLocalBins =
-         (lowercase progName /= lowercase stackProgName)
-      && not ( osIsWindows
-             && lowercase progName == lowercase (stackProgName <> ".EXE")
-             )
+    isProgNameStack =
+         (lowercase progName == lowercase stackProgName)
+      || (  osIsWindows
+         && lowercase progName == lowercase (stackProgName <> ".EXE")
+         )
+    isRelFileNameStack relFile =
+         (relFile == relFileStack)
+      || (osIsWindows && relFile == relFileStackDotExe )
+    isExecutableNameStack =
+      let mExecutableName = filename <$> mExecutablePath
+      in  maybe False isRelFileNameStack mExecutableName
+    onlyLocalBins = not (isProgNameStack && isExecutableNameStack)
     lowercase = map toLower
 
   upload = addCommand'
@@ -669,11 +685,17 @@ 
 interpreterHandler ::
      Monoid t
-  => FilePath
+  => String
+     -- ^ The name of the current Stack executable, as it was invoked.
+  -> Maybe (Path Abs File)
+     -- ^ The path to the current Stack executable, if the operating system
+     -- provides a reliable way to determine it and where a result was
+     -- available.
+  -> FilePath
   -> NonEmpty String
   -> ParserFailure ParserHelp
   -> IO (GlobalOptsMonoid, (RIO Runner (), t))
-interpreterHandler currentDir args f = do
+interpreterHandler progName mExecutablePath currentDir args f = do
   -- args can include top-level config such as --extra-lib-dirs=... (set by
   -- nix-shell) - we need to find the first argument which is a file, everything
   -- afterwards is an argument to the script, everything before is an argument
@@ -711,9 +733,9 @@     ("File does not exist or is not a regular file '" ++ name ++ "'.")
 
   runInterpreterCommand path stackArgs fileArgs = do
-    progName <- getProgName
     iargs <- getInterpreterArgs path
-    let parseCmdLine = commandLineHandler currentDir progName True
+    let parseCmdLine =
+          commandLineHandler currentDir progName mExecutablePath True
         -- Implicit file arguments are put before other arguments that
         -- occur after "--". See #3658
         cmdArgs = prependList stackArgs $ case NE.break (== "--") iargs of
src/Stack/Config.hs view
@@ -74,7 +74,7 @@                    , getCurrentDir, getXdgDir, resolveDir, resolveDir'
                    , resolveFile, resolveFile'
                    )
-import           RIO.List ( unzip )
+import           RIO.List ( unzip, intersperse )
 import           RIO.Process
                    ( HasProcessContext (..), ProcessContext, augmentPathMap
                    , envVarsL
@@ -347,20 +347,29 @@       -- exist.
       shortLocalProgramsFilePath <-
         liftIO $ getShortPathName localProgramsFilePath
-      when (' ' `elem` shortLocalProgramsFilePath) $
-        prettyError $
+      prettyWarn $
           "[S-8432]"
           <> line
           <> fillSep
-               [ flow "Stack's 'programs' path contains a space character and \
-                      \has no alternative short ('8 dot 3') name. This will \
-                      \cause problems with packages that use the GNU project's \
-                      \'configure' shell script. Use the"
+               (  [ flow "Stack's 'programs' path is"
+                  , style File (fromString localProgramsFilePath) <> "."
+                  , flow "It contains a space character. This will prevent \
+                         \building with GHC 9.4.1 or later."
+                  ]
+               <> [ flow "It also has no alternative short ('8 dot 3') name. \
+                         \This will cause problems with packages that use the \
+                         \GNU project's 'configure' shell script."
+                  | ' ' `elem` shortLocalProgramsFilePath
+                  ]
+               )
+          <> blankLine
+          <> fillSep
+               [ flow "To avoid sucn problems, use the"
                , style Shell "local-programs-path"
-               , flow "configuration option to specify an alternative path. \
-                      \The current path is:"
-               , style File (fromString localProgramsFilePath) <> "."
+               , flow "non-project specific configuration option to specify an \
+                      \alternative space-free path."
                ]
+          <> line
     platformOnlyDir <-
       runReaderT platformOnlyRelDir (platform, platformVariant)
     let localPrograms = localProgramsBase </> platformOnlyDir
@@ -437,6 +446,9 @@         notifyIfGhcUntested = fromFirstTrue configMonoid.notifyIfGhcUntested
         notifyIfCabalUntested = fromFirstTrue configMonoid.notifyIfCabalUntested
         notifyIfArchUnknown = fromFirstTrue configMonoid.notifyIfArchUnknown
+        notifyIfNoRunTests = fromFirstTrue configMonoid.notifyIfNoRunTests
+        notifyIfNoRunBenchmarks =
+          fromFirstTrue configMonoid.notifyIfNoRunBenchmarks
         noRunCompile = fromFirstFalse configMonoid.noRunCompile
     allowDifferentUser <-
       case getFirst configMonoid.allowDifferentUser of
@@ -597,6 +609,8 @@                 , notifyIfGhcUntested
                 , notifyIfCabalUntested
                 , notifyIfArchUnknown
+                , notifyIfNoRunTests
+                , notifyIfNoRunBenchmarks
                 , noRunCompile
                 , stackDeveloperMode
                 , casa
@@ -743,7 +757,7 @@ 
   (project', configFile) <- case config.project of
     PCProject (project, fp) -> do
-      forM_ project.userMsg prettyWarnS
+      forM_ project.userMsg prettyUserMessage
       pure (project, Right fp)
     PCNoProject extraDeps -> do
       p <-
@@ -792,7 +806,7 @@               , "# '", encodeUtf8 (T.pack $ toFilePath config.userGlobalConfigFile), "' instead.\n"
               , "#\n"
               , "# For more information about Stack's configuration, see\n"
-              , "# http://docs.haskellstack.org/en/stable/yaml_configuration/\n"
+              , "# http://docs.haskellstack.org/en/stable/configure/yaml/\n"
               , "#\n"
               , Yaml.encode p]
             writeBinaryFileAtomic (parent dest </> relFileReadmeTxt) $
@@ -860,6 +874,33 @@       , curator = Nothing
       , dropPackages = mempty
       }
+  prettyUserMessage :: String -> RIO Config ()
+  prettyUserMessage userMsg = do
+    let userMsgs = map flow $ splitAtLineEnds userMsg
+        warningDoc = mconcat $ intersperse blankLine userMsgs
+    prettyWarn warningDoc
+   where
+    splitAtLineEnds = reverse . map reverse . go []
+     where
+      go :: [String] -> String -> [String]
+      go ss [] = ss
+      go ss s = case go' [] s of
+        ([], rest) -> go ss rest
+        (s', rest) -> go (s' : ss) rest
+      go' :: String -> String -> (String, String)
+      go' s [] = (s, [])
+      go' s [c] = (c:s, [])
+      go' s "\n\n" = (s, [])
+      go' s [c1, c2] = (c2:c1:s, [])
+      go' s ('\n':'\n':rest) = (s, stripLineEnds rest)
+      go' s ('\n':'\r':'\n':rest) = (s, stripLineEnds rest)
+      go' s ('\r':'\n':'\n':rest) = (s, stripLineEnds rest)
+      go' s ('\r':'\n':'\r':'\n':rest) = (s, stripLineEnds rest)
+      go' s (c:rest) = go' (c:s) rest
+      stripLineEnds :: String -> String
+      stripLineEnds ('\n':rest) = stripLineEnds rest
+      stripLineEnds ('\r':'\n':rest) = stripLineEnds rest
+      stripLineEnds rest = rest
 
 fillProjectWanted ::
      (HasLogFunc env, HasPantryConfig env, HasProcessContext env)
@@ -1223,12 +1264,12 @@ defaultConfigYaml =
   "# This file contains default non-project-specific settings for Stack, used\n" <>
   "# in all projects. For more information about Stack's configuration, see\n" <>
-  "# http://docs.haskellstack.org/en/stable/yaml_configuration/\n" <>
+  "# http://docs.haskellstack.org/en/stable/configure/yaml/\n" <>
   "\n" <>
   "# The following parameters are used by 'stack new' to automatically fill fields\n" <>
   "# in the Cabal file. We recommend uncommenting them and filling them out if\n" <>
   "# you intend to use 'stack new'.\n" <>
-  "# See https://docs.haskellstack.org/en/stable/yaml_configuration/#templates\n" <>
+  "# See https://docs.haskellstack.org/en/stable/configure/yaml/non-project/#templates\n" <>
   "templates:\n" <>
   "  params:\n" <>
   "#    author-name:\n" <>
src/Stack/Config/Build.hs view
@@ -122,7 +122,7 @@   , TestOpts.additionalArgs =
       fromMaybe [] madditional <> toMonoid.additionalArgs
   , TestOpts.coverage = fromFirstFalse toMonoid.coverage
-  , TestOpts.disableRun = fromFirstFalse toMonoid.disableRun
+  , TestOpts.runTests = fromFirstTrue toMonoid.runTests
   , TestOpts.maximumTimeSeconds =
       fromFirst
         defaultTestOpts.maximumTimeSeconds
@@ -135,12 +135,9 @@      BenchmarkOptsMonoid
   -> Maybe [String]
   -> BenchmarkOpts
-benchmarkOptsFromMonoid beoMonoid madditional =
-  defaultBenchmarkOpts
-    { BenchmarkOpts.additionalArgs =
-        fmap (\args -> unwords args <> " ") madditional <>
-        getFirst beoMonoid.additionalArgs
-    , BenchmarkOpts.disableRun = fromFirst
-        defaultBenchmarkOpts.disableRun
-        beoMonoid.disableRun
-    }
+benchmarkOptsFromMonoid beoMonoid madditional = defaultBenchmarkOpts
+  { BenchmarkOpts.additionalArgs =
+      fmap (\args -> unwords args <> " ") madditional <>
+      getFirst beoMonoid.additionalArgs
+  , BenchmarkOpts.runBenchmarks = fromFirstTrue beoMonoid.runBenchmarks
+  }
src/Stack/Constants.hs view
@@ -259,7 +259,7 @@       -- A magic package
     , "integer-gmp"
       -- No longer magic > 1.0.3.0 (GHC >= 9.0) and deprecated in favour of
-      -- ghc-bignum. With GHC 9.6.6 at least, there seems to be no problem in
+      -- ghc-bignum. With GHC 9.8.4 at least, there seems to be no problem in
       -- using it.
     , "integer-simple"
       -- A magic package
@@ -274,7 +274,7 @@       -- if they were defined in modules all sharing a common package
       -- interactive. See 'Note [The interactive package]' at
       -- https://gitlab.haskell.org/ghc/ghc/-/blob/master/compiler/GHC/Runtime/Context.hs
-      -- With GHC 9.6.6 at least, there seems to be no problem in using it.
+      -- With GHC 9.8.4 at least, there seems to be no problem in using it.
     ]
 
 -- | Just to avoid repetition and magic strings.
src/Stack/DependencyGraph.hs view
@@ -84,8 +84,7 @@        Runner
        (Set PackageName, Map PackageName (Set PackageName, DotPayload))
 createPrunedDependencyGraph dotOpts = withDotConfig dotOpts $ do
-  localNames <-
-    view $ buildConfigL . to (Map.keysSet . (.smWanted.project))
+  localNames <- view $ buildConfigL . to (Map.keysSet . (.smWanted.project))
   logDebug "Creating dependency graph"
   resultGraph <- createDependencyGraph dotOpts
   let pkgsToPrune = if dotOpts.includeBase
@@ -141,10 +140,10 @@     logDebug "Loading source map"
     sourceMap <- loadSourceMap targets boptsCLI smActual
     let dc = DotConfig
-                { buildConfig
-                , sourceMap
-                , globalDump = toList smActual.globals
-                }
+          { buildConfig
+          , sourceMap
+          , globalDump = toList smActual.globals
+          }
     logDebug "DotConfig fully loaded"
     runRIO dc inner
 
@@ -165,28 +164,35 @@     , flags = opts.flags
     }
   modifyGO =
-    (if opts.testTargets
-       then set (globalOptsBuildOptsMonoidL . buildOptsMonoidTestsL) (Just True)
-       else id) .
-    (if opts.benchTargets
-       then set (globalOptsBuildOptsMonoidL . buildOptsMonoidBenchmarksL) (Just True)
-       else id)
+      ( if opts.testTargets
+          then
+            set
+              (globalOptsBuildOptsMonoidL . buildOptsMonoidTestsL)
+              (Just True)
+          else id
+      )
+    . ( if opts.benchTargets
+          then
+            set
+              (globalOptsBuildOptsMonoidL . buildOptsMonoidBenchmarksL)
+              (Just True)
+          else id
+      )
 
--- | Create the dependency graph, the result is a map from a package
--- name to a tuple of dependencies and payload if available. This
--- function mainly gathers the required arguments for
--- @resolveDependencies@.
+-- | Create the dependency graph, the result is a map from a package name to a
+-- tuple of dependencies and payload if available. This function mainly gathers
+-- the required arguments for @resolveDependencies@.
 createDependencyGraph ::
      DotOpts
   -> RIO DotConfig (Map PackageName (Set PackageName, DotPayload))
 createDependencyGraph dotOpts = do
   sourceMap <- view sourceMapL
   locals <- for (toList sourceMap.project) loadLocalPackage
-  let graph =
-        Map.fromList $ projectPackageDependencies dotOpts (filter (.wanted) locals)
+  let graph = Map.fromList $
+        projectPackageDependencies dotOpts (filter (.wanted) locals)
   globalDump <- view $ to (.globalDump)
-  -- TODO: Can there be multiple entries for wired-in-packages? If so,
-  -- this will choose one arbitrarily..
+  -- TODO: Can there be multiple entries for wired-in-packages? If so, this will
+  -- choose one arbitrarily..
   let globalDumpMap = Map.fromList $
         map (\dp -> (Stack.Prelude.pkgName dp.packageIdent, dp)) globalDump
       globalIdMap =
@@ -197,16 +203,19 @@         -- Skip packages that can't be loaded - see
         -- https://github.com/commercialhaskell/stack/issues/2967
         | name `elem` [mkPackageName "rts", mkPackageName "ghc"] =
-            pure ( Set.empty
-                 , DotPayload (Just version) (Just $ Right BSD3) Nothing )
-        | otherwise =
-            fmap (setOfPackageDeps &&& makePayload loc)
-                 (loadPackage loc flags ghcOptions cabalConfigOpts)
+            pure
+              ( Set.empty
+              , DotPayload (Just version) (Just $ Right BSD3) Nothing
+              )
+        | otherwise = fmap
+            (setOfPackageDeps &&& makePayload loc)
+            (loadPackage loc flags ghcOptions cabalConfigOpts)
   resolveDependencies dotOpts.dependencyDepth graph depLoader
  where
-  makePayload loc pkg = DotPayload (Just pkg.version)
-                                   (Just pkg.license)
-                                   (Just $ PLImmutable loc)
+  makePayload loc pkg = DotPayload
+    (Just pkg.version)
+    (Just pkg.license)
+    (Just $ PLImmutable loc)
 
 -- | Resolve the direct (depth 0) external dependencies of the given local
 -- packages (assumed to come from project packages)
@@ -215,21 +224,21 @@   -> [LocalPackage]
   -> [(PackageName, (Set PackageName, DotPayload))]
 projectPackageDependencies dotOpts locals =
-  map (\lp -> let pkg = localPackageToPackage lp
-                  pkgDir = parent lp.cabalFP
-                  packageDepsSet = setOfPackageDeps pkg
-                  loc = PLMutable $ ResolvedPath (RelFilePath "N/A") pkgDir
-              in  (pkg.name, (deps pkg packageDepsSet, lpPayload pkg loc)))
-      locals
+  map
+    ( \lp -> let pkg = localPackageToPackage lp
+                 pkgDir = parent lp.cabalFP
+                 packageDepsSet = setOfPackageDeps pkg
+                 loc = PLMutable $ ResolvedPath (RelFilePath "N/A") pkgDir
+             in  (pkg.name, (deps pkg packageDepsSet, lpPayload pkg loc))
+    )
+    locals
  where
   deps pkg packageDepsSet = if dotOpts.includeExternal
     then Set.delete pkg.name packageDepsSet
     else Set.intersection localNames packageDepsSet
   localNames = Set.fromList $ map (.package.name) locals
   lpPayload pkg loc =
-    DotPayload (Just pkg.version)
-               (Just pkg.license)
-               (Just loc)
+    DotPayload (Just pkg.version) (Just pkg.license) (Just loc)
 
 -- | Given a SourceMap and a dependency loader, load the set of dependencies for
 -- a package
@@ -268,7 +277,8 @@     loadDeps dp@DepPackage{ location = PLImmutable loc } = do
       let common = dp.depCommon
       gpd <- liftIO common.gpd
-      let PackageIdentifier name version = PD.package $ PD.packageDescription gpd
+      let PackageIdentifier name version =
+            PD.package $ PD.packageDescription gpd
           flags = common.flags
           ghcOptions = common.ghcOptions
           cabalConfigOpts = common.cabalConfigOpts
@@ -284,17 +294,18 @@      where
       deps = map ghcIdToPackageName dump.depends
       ghcIdToPackageName depId =
-        maybe (impureThrow $ DependencyNotFoundBug depId)
-              Stack.Prelude.pkgName
-              (Map.lookup depId globalIdMap)
+        maybe
+          (impureThrow $ DependencyNotFoundBug depId)
+          Stack.Prelude.pkgName
+          (Map.lookup depId globalIdMap)
 
   payloadFromLocal pkg =
     DotPayload (Just pkg.version) (Just pkg.license)
 
-  payloadFromDump dp =
-    DotPayload (Just $ pkgVersion dp.packageIdent)
-               (Right <$> dp.license)
-               Nothing
+  payloadFromDump dp = DotPayload
+    (Just $ pkgVersion dp.packageIdent)
+    (Right <$> dp.license)
+    Nothing
 
 -- | Resolve the dependency graph up to (Just depth) or until fixpoint is reached
 resolveDependencies ::
@@ -309,18 +320,19 @@       keys = Map.keysSet graph
       next = Set.difference values keys
   if Set.null next
-     then pure graph
-     else do
-       x <- T.traverse (\name -> (name,) <$> loadPackageDeps name) (F.toList next)
-       resolveDependencies (subtract 1 <$> limit)
-                      (Map.unionWith unifier graph (Map.fromList x))
-                      loadPackageDeps
+    then pure graph
+    else do
+      x <- T.traverse (\name -> (name,) <$> loadPackageDeps name) (F.toList next)
+      resolveDependencies
+        (subtract 1 <$> limit)
+        (Map.unionWith unifier graph (Map.fromList x))
+        loadPackageDeps
  where
   unifier (pkgs1,v1) (pkgs2,_) = (Set.union pkgs1 pkgs2, v1)
 
--- | @pruneGraph dontPrune toPrune graph@ prunes all packages in
--- @graph@ with a name in @toPrune@ and removes resulting orphans
--- unless they are in @dontPrune@
+-- | @pruneGraph dontPrune toPrune graph@ prunes all packages in @graph@ with a
+-- name in @toPrune@ and removes resulting orphans unless they are in
+-- @dontPrune@
 pruneGraph ::
      (F.Foldable f, F.Foldable g, Eq a)
   => f PackageName
src/Stack/Docker.hs view
@@ -44,7 +44,7 @@ import           Path.IO
                    ( copyFile, doesDirExist, doesFileExist, ensureDir
                    , getCurrentDir, getHomeDir, getModificationTime, listDir
-                   , removeDirRecur, removeFile, resolveFile'
+                   , removeDirRecur, removeFile
                    )
 import qualified RIO.Directory ( makeAbsolute )
 import           RIO.Process
@@ -77,12 +77,12 @@                   )
 import           Stack.Types.DockerEntrypoint
                    ( DockerEntrypoint (..), DockerUser (..) )
-import           Stack.Types.Runner ( HasDockerEntrypointMVar (..), terminalL )
-import           Stack.Types.Version ( showStackVersion, withinRange )
-import           System.Environment
-                   ( getArgs, getEnv, getEnvironment, getExecutablePath
-                   , getProgName
+import           Stack.Types.Runner
+                   ( HasDockerEntrypointMVar (..), progNameL, terminalL
+                   , viewExecutablePath
                    )
+import           Stack.Types.Version ( showStackVersion, withinRange )
+import           System.Environment ( getArgs, getEnv, getEnvironment )
 import qualified System.FilePath as FP
 import           System.IO.Error ( isDoesNotExistError )
 import qualified System.Posix.User as User
@@ -126,18 +126,18 @@     case config.docker.stackExe of
         Just DockerStackExeHost
           | config.platform == dockerContainerPlatform -> do
-              exePath <- resolveFile' =<< liftIO getExecutablePath
+              exePath <- viewExecutablePath
               cmdArgs args exePath
           | otherwise -> throwIO UnsupportedStackExeHostPlatformException
         Just DockerStackExeImage -> do
-            progName <- liftIO getProgName
+            progName <- view progNameL
             pure (FP.takeBaseName progName, args, [], [])
         Just (DockerStackExePath path) -> cmdArgs args path
         Just DockerStackExeDownload -> exeDownload args
         Nothing
           | config.platform == dockerContainerPlatform -> do
               (exePath, exeTimestamp, misCompatible) <-
-                  do exePath <- resolveFile' =<< liftIO getExecutablePath
+                  do exePath <- viewExecutablePath
                      exeTimestamp <- getModificationTime exePath
                      isKnown <-
                          loadDockerImageExeCache
@@ -212,8 +212,6 @@   isStdoutTerminal <- view terminalL
   let dockerHost = lookup "DOCKER_HOST" env
       dockerCertPath = lookup "DOCKER_CERT_PATH" env
-      bamboo = lookup "bamboo_buildKey" env
-      jenkins = lookup "JENKINS_HOME" env
       msshAuthSock = lookup "SSH_AUTH_SOCK" env
       muserEnv = lookup "USER" env
       isRemoteDocker = maybe False (isPrefixOf "tcp://") dockerHost
@@ -242,15 +240,9 @@       platformVariant = show $ hashRepoName image
       stackRoot = view stackRootL config
       sandboxHomeDir = sandboxDir </> homeDirName
-      isTerm = not docker.detach &&
-               isStdinTerminal &&
-               isStdoutTerminal &&
-               isStderrTerminal
-      keepStdinOpen = not docker.detach &&
-                      -- Workaround for https://github.com/docker/docker/issues/12319
-                      -- This is fixed in Docker 1.9.1, but will leave the workaround
-                      -- in place for now, for users who haven't upgraded yet.
-                      (isTerm || (isNothing bamboo && isNothing jenkins))
+      isTerm = isStdinTerminal && isStdoutTerminal && isStderrTerminal
+      allocatePseudoTty = not docker.detach && isTerm
+      keepStdinOpen = not docker.detach
   let mpath = T.pack <$> lookupImageEnv "PATH" imageEnvVars
   when (isNothing mpath) $ do
     prettyWarnL
@@ -335,7 +327,7 @@         , case docker.containerName of
             Just name -> ["--name=" ++ name]
             Nothing -> []
-        , ["-t" | isTerm]
+        , ["-t" | allocatePseudoTty]
         , ["-i" | keepStdinOpen]
         , docker.runArgs
         , [image]
src/Stack/Ghci.hs view
@@ -213,9 +213,9 @@         bopts <- view buildOptsL
         -- override env so running of tests and benchmarks is disabled
         let boptsLocal = bopts
-              { testOpts = bopts.testOpts { TestOpts.disableRun = True }
+              { testOpts = bopts.testOpts { TestOpts.runTests = False }
               , benchmarkOpts =
-                  bopts.benchmarkOpts { BenchmarkOpts.disableRun = True }
+                  bopts.benchmarkOpts { BenchmarkOpts.runBenchmarks = False }
               }
         local (set buildOptsL boptsLocal) (ghci ghciOpts)
src/Stack/Init.hs view
@@ -83,7 +83,7 @@   pretty (ConfigFileAlreadyExists reldest) =
     "[S-8009]"
     <> line
-    <> flow "Stack declined to create a project-level YAML configuration file."
+    <> flow "Stack declined to create a project-level configuration file."
     <> blankLine
     <> fillSep
          [ flow "The file"
@@ -94,7 +94,7 @@   pretty (PackageNameInvalid rels) =
     "[S-5267]"
     <> line
-    <> flow "Stack did not create project-level YAML configuration, as (like \
+    <> flow "Stack did not create project-level configuration, as (like \
             \Hackage) it requires a Cabal file name to match the package it \
             \defines."
     <> blankLine
@@ -115,18 +115,18 @@   pretty (SnapshotDownloadFailure e) =
     "[S-8332]"
     <> line
-    <> flow "Stack failed to create project-level YAML configuration, as it \
+    <> flow "Stack failed to create project-level configuration file, as it \
             \was unable to download the index of available snapshots."
     <> blankLine
     <> fillSep
          [ flow "This sometimes happens because Certificate Authorities are \
                 \missing on your system. You can try the Stack command again \
                 \or manually create the configuration file. For help about the \
-                \content of Stack's YAML configuration files, see (for the \
-                \most recent release of Stack)"
+                \content of Stack's configuration files, see (for the most \
+                \recent release of Stack)"
          , style
              Url
-             "http://docs.haskellstack.org/en/stable/yaml_configuration/"
+             "http://docs.haskellstack.org/en/stable/configure/yaml/"
            <> "."
          ]
     <> blankLine
@@ -250,30 +250,35 @@     getDefaultSnapshot initOpts mASnapshot' pkgDirs
   let ignored = Map.difference bundle rbundle
       dupPkgMsg
-        | dupPkgs /= [] =
+        | dupPkgs /= [] = Just
             "Warning (added by new or init): Some packages were found to have \
-            \names conflicting with others and have been commented out in the \
-            \packages section.\n"
-        | otherwise = ""
+            \names\n\
+            \conflicting with others and have been commented out in the \
+            \packages section."
+        | otherwise = Nothing
       missingPkgMsg
-        | Map.size ignored > 0 =
+        | Map.size ignored > 0 = Just
             "Warning (added by new or init): Some packages were found to be \
-            \incompatible with the snapshot and have been left commented out \
-            \in the packages section.\n"
-        | otherwise = ""
+            \incompatible\n\
+            \with the snapshot and have been left commented out in the \
+            \packages section."
+        | otherwise = Nothing
       extraDepMsg
-        | Map.size extraDeps > 0 =
+        | Map.size extraDeps > 0 = Just
             "Warning (added by new or init): Specified snapshot could not \
-            \satisfy all dependencies. Some external packages have been added \
-            \as dependencies.\n"
-        | otherwise = ""
-      makeUserMsg msgs =
-        let msg = concat msgs
-        in  if msg /= ""
-              then
-                   msg
-                <> "You can omit this message by removing it from stack.yaml\n"
-              else ""
+            \satisfy all\n\
+            \dependencies. Some external packages have been added as \
+            \dependencies."
+        | otherwise = Nothing
+      removalMsg =
+        "You can omit this message by removing it from the project-level \
+        \configuration\n\
+        \file."
+      makeUserMsg mMsgs =
+        let msgs = catMaybes mMsgs
+        in  if null msgs
+              then Nothing
+              else Just $ intercalate "\n\n" (msgs <> [removalMsg]) <> "\n"
       userMsg = makeUserMsg [dupPkgMsg, missingPkgMsg, extraDepMsg]
       gpdByDir =
         Map.fromList [ (parent fp, gpd) | (fp, gpd) <- Map.elems bundle]
@@ -284,7 +289,7 @@       completePackageLocation
         (RPLIHackage (PackageIdentifierRevision n v CFILatest) Nothing)
   let project = Project
-        { userMsg = if userMsg == "" then Nothing else Just userMsg
+        { userMsg
         , packages = resolvedRelative <$> Map.elems rbundle
         , extraDeps = map toRawPL deps
         , flagsByPkg = removeSrcPkgDefaultFlags gpds flags
@@ -296,8 +301,8 @@         }
       makeRel = fmap toFilePath . makeRelativeToCurrentDir
   prettyInfoL
-    [ flow "Initialising Stack's project-level YAML configuration file \
-           \using snapshot"
+    [ flow "Initialising Stack's project-level configuration file using \
+           \snapshot"
     , pretty (PrettyRawSnapshotLocation snapshot) <> "."
     ]
   prettyInfoL $
@@ -342,7 +347,7 @@     (Map.elems $ fmap (makeRelDir . parent . fst) ignored)
     (map (makeRelDir . parent) dupPkgs)
   prettyInfoS
-    "Stack's project-level YAML configuration file has been initialised."
+    "Stack's project-level configuration file has been initialised."
 
 -- | Render a stack.yaml file with comments, see:
 -- https://github.com/commercialhaskell/stack/issues/226
@@ -419,16 +424,16 @@     , ""
     , "Some commonly used options have been documented as comments in this file."
     , "For advanced use and comprehensive documentation of the format, please see:"
-    , "https://docs.haskellstack.org/en/stable/yaml_configuration/"
+    , "https://docs.haskellstack.org/en/stable/configure/yaml/"
     ]
   snapshotHelp = commentHelp
     [ "A 'specific' Stackage snapshot or a compiler version."
     , "A snapshot resolver dictates the compiler version and the set of packages"
     , "to be used for project dependencies. For example:"
     , ""
-    , "snapshot: lts-22.28"
-    , "snapshot: nightly-2024-07-05"
-    , "snapshot: ghc-9.6.6"
+    , "snapshot: lts-23.0"
+    , "snapshot: nightly-2024-12-13"
+    , "snapshot: ghc-9.8.4"
     , ""
     , "The location of a snapshot can be provided as a file or url. Stack assumes"
     , "a snapshot provided as a file might change, whereas a url resource does not."
@@ -552,7 +557,7 @@         | Map.null available -> do
             prettyWarnS
               "Could not find a working plan for any of the user packages. \
-              \Proceeding to create a YAML configuration file anyway."
+              \Proceeding to create a project-level configuration file anyway."
             pure (snapLoc, Map.empty, Map.empty, Map.empty)
         | otherwise -> do
             when (Map.size available == Map.size pkgDirs) $
src/Stack/Lock.hs view
@@ -188,4 +188,4 @@     "# This file was autogenerated by Stack.\n\
     \# You should not edit this file by hand.\n\
     \# For more information, please see the documentation at:\n\
-    \#   https://docs.haskellstack.org/en/stable/lock_files\n\n"
+    \#   https://docs.haskellstack.org/en/stable/topics/lock_files\n\n"
src/Stack/New.hs view
@@ -594,8 +594,7 @@          )
     <> blankLine
     <> fillSep
-         [ flow "You can provide them in Stack's global YAML configuration \
-                \file"
+         [ flow "You can provide them in Stack's global configuration file"
          , "(" <> pretty userConfigPath <> ")"
          , "like this:"
          ]
src/Stack/Nix.hs view
@@ -24,9 +24,10 @@ import           Stack.Types.Config
                    ( Config (..), HasConfig (..), configProjectRoot )
 import           Stack.Types.Docker ( reExecArgName )
+import           Stack.Types.Runner ( viewExecutablePath )
 import           Stack.Types.Nix ( NixOpts (..) )
 import           Stack.Types.Version ( showStackVersion )
-import           System.Environment ( getArgs, getExecutablePath, lookupEnv )
+import           System.Environment ( getArgs, lookupEnv )
 import qualified System.FilePath as F
 
 -- | Type representing exceptions thrown by functions exported by the
@@ -49,7 +50,7 @@              -- first stack when restarting in the container
            | otherwise =
                ("--" ++ reExecArgName ++ "=" ++ showStackVersion) : origArgs
-  exePath <- liftIO getExecutablePath
+  exePath <- toFilePath <$> viewExecutablePath
   config <- view configL
   envOverride <- view processContextL
   local (set processContextL envOverride) $ do
src/Stack/Options/BenchParser.hs view
@@ -5,9 +5,9 @@  ( benchOptsParser
  ) where
 
-import           Options.Applicative
-                   ( Parser, flag', help, long, metavar, strOption )
-import           Options.Applicative.Builder.Extra ( optionalFirst )
+import           Options.Applicative ( Parser, help, long, metavar, strOption )
+import           Options.Applicative.Builder.Extra
+                   ( firstBoolFlagsTrue, optionalFirst )
 import           Stack.Prelude
 import           Stack.Options.Utils ( hideMods )
 import           Stack.Types.BuildOptsMonoid ( BenchmarkOptsMonoid (..) )
@@ -20,15 +20,13 @@         (  long "benchmark-arguments"
         <> long "ba"
         <> metavar "BENCH_ARGS"
-        <> help "Forward BENCH_ARGS to the benchmark suite. Supports templates \
-                \from 'cabal bench'."
-        <> hide
-        ))
-  <*> optionalFirst (flag' True
-        (  long "no-run-benchmarks"
-        <> help "Disable running of benchmarks. (Benchmarks will still be \
-                \built.)"
+        <> help "Arguments passed to the benchmarks. Supports path variables \
+                \provided by the Cabal build system."
         <> hide
         ))
+  <*> firstBoolFlagsTrue
+        "run-benchmarks"
+        "running of targeted benchmarks."
+        hide
  where
   hide = hideMods hide0
src/Stack/Options/BuildParser.hs view
@@ -129,7 +129,7 @@     <> completer targetCompleter
     <> help "Can be specified multiple times. If none specified, use all \
             \project packages. See \
-            \https://docs.haskellstack.org/en/stable/build_command/#target-syntax \
+            \https://docs.haskellstack.org/en/stable/commands/build_command/#target-syntax \
             \for details."
     ))
src/Stack/Options/Completion.hs view
@@ -48,16 +48,17 @@ -- TODO: Ideally this would pay attention to --stack-yaml, may require
 -- changes to optparse-applicative.
 
-buildConfigCompleter ::
-     (String -> RIO EnvConfig [String])
-  -> Completer
+buildConfigCompleter :: (String -> RIO EnvConfig [String]) -> Completer
 buildConfigCompleter inner = mkCompleter $ \inputRaw -> do
   let input = unescapeBashArg inputRaw
   case input of
     -- If it looks like a flag, skip this more costly completion.
     ('-': _) -> pure []
     _ -> do
-      go' <- globalOptsFromMonoid False mempty
+      -- We do not need to specify the name of the current Stack executable, as
+      -- it was invoked, or the path to the current Stack executable, as
+      -- withDefaultEnvConfig does not need either.
+      go' <- globalOptsFromMonoid "" Nothing False mempty
       let go = go' { logLevel = LevelOther "silent" }
       withRunnerGlobal go $ withConfig NoReexec $ withDefaultEnvConfig $ inner input
src/Stack/Options/DotParser.hs view
@@ -12,11 +12,12 @@ import qualified Data.Set as Set
 import           Distribution.Types.PackageName ( mkPackageName )
 import           Options.Applicative
-                   ( Parser, auto, help, idm, long, metavar, option, strOption
-                   , switch
+                   ( Parser, auto, completer, help, idm, long, metavar, option
+                   , strOption, switch
                    )
-import           Options.Applicative.Builder.Extra ( boolFlags )
-import           Stack.Options.BuildParser ( flagsParser, targetsParser )
+import           Options.Applicative.Builder.Extra ( boolFlags, textArgument )
+import           Stack.Options.BuildParser ( flagsParser )
+import           Stack.Options.Completion ( targetCompleter )
 import           Stack.Prelude
 import           Stack.Types.DotOpts ( DotOpts (..) )
 
@@ -52,6 +53,17 @@     <> help "Prune specified package(s). PACKAGES is a comma-separated list of \
             \package names."
     ))
+
+  targetsParser :: Parser [Text]
+  targetsParser =
+    many (textArgument
+      (  metavar "TARGET"
+      <> completer targetCompleter
+      <> help "Can be specified multiple times. If none specified, use all \
+              \project packages. Ignores project package components and \
+              \non-project packages."
+      ))
+
   testTargets = switch
     (  long "test"
     <> help "Consider dependencies of test components."
src/Stack/Options/GhciParser.hs view
@@ -28,7 +28,7 @@         (  metavar "TARGET/FILE"
         <> completer (targetCompleter <> fileExtCompleter [".hs", ".lhs"])
         <> help "If none specified, use all project packages. See \
-                \https://docs.haskellstack.org/en/stable/build_command/#target-syntax \
+                \https://docs.haskellstack.org/en/stable/commands/build_command/#target-syntax \
                 \for details. If a path to a .hs or .lhs file is specified, it \
                 \will be loaded."
         ))
src/Stack/Options/GlobalParser.hs view
@@ -114,10 +114,16 @@ -- | Create GlobalOpts from GlobalOptsMonoid.
 globalOptsFromMonoid ::
      MonadIO m
-  => Bool
+  => String
+     -- ^ The name of the current Stack executable, as it was invoked.
+  -> Maybe (Path Abs File)
+     -- ^ The path to the current Stack executable, if the operating system
+     -- provides a reliable way to determine it and where a result was
+     -- available.
+  -> Bool
   -> GlobalOptsMonoid
   -> m GlobalOpts
-globalOptsFromMonoid defaultTerminal globalMonoid = do
+globalOptsFromMonoid progName mExecutablePath defaultTerminal globalMonoid = do
   snapshot <- for (getFirst globalMonoid.snapshot) $ \us -> do
     root <-
       case globalMonoid.snapshotRoot of
@@ -149,6 +155,8 @@     , termWidthOpt = getFirst globalMonoid.termWidthOpt
     , stackYaml
     , lockFileBehavior
+    , progName
+    , mExecutablePath
     }
 
 -- | Default logging level should be something useful but not crazy.
src/Stack/Options/LsParser.hs view
@@ -1,4 +1,5 @@ {-# LANGUAGE NoImplicitPrelude   #-}
+{-# LANGUAGE ApplicativeDo       #-}
 {-# LANGUAGE OverloadedStrings   #-}
 
 -- | Function to parse command line arguments for Stack's @ls@ command.
@@ -19,7 +20,7 @@                    , LsView (..), SnapshotOpts (..), ListGlobalsOpts
                    )
 import           Stack.Options.DotParser ( dotOptsParser )
-import           Stack.Prelude
+import           Stack.Prelude hiding ( sep )
 
 -- | Parse command line arguments for Stack's @ls@ command.
 lsOptsParser :: OA.Parser LsCmdOpts
@@ -48,9 +49,9 @@ lsDepsCmd = OA.command "dependencies" $
   OA.info lsDepOptsParser $
        OA.progDesc
-         "View the packages and versions used for a project. Use a command if \
-         \the first target specified has the name of a command. Targets other \
-         \than project packages are ignored."
+         "View the packages versions used for a project. Use a command if the \
+         \first target specified has the name of a command. Targets other than \
+         \project packages are ignored."
     <> OA.footer globalFooter
 
 lsStylesCmd :: OA.Mod OA.CommandFields LsCmds
@@ -160,8 +161,7 @@   -> OA.Mod OA.CommandFields ListDepsOpts
 formatSubCommand cmd desc formatParser =
   OA.command
-    cmd
-    (OA.info (toListDepsOptsParser formatParser) (OA.progDesc desc))
+    cmd (OA.info (toListDepsOptsParser formatParser) (OA.progDesc desc))
 
 listDepsTextParser :: OA.Parser ListDepsFormat
 listDepsTextParser =
@@ -194,9 +194,13 @@ listDepsJsonParser = pure ListDepsJSON
 
 listDepsFormatOptsParser :: OA.Parser ListDepsFormatOpts
-listDepsFormatOptsParser = ListDepsFormatOpts
-  <$> separatorParser
-  <*> licenseParser
+listDepsFormatOptsParser = do
+  license <- licenseParser
+  sep <- separatorParser
+  pure ListDepsFormatOpts
+    { sep
+    , license
+    }
 
 separatorParser :: OA.Parser Text
 separatorParser = fmap
@@ -204,7 +208,7 @@   ( textOption
       (  OA.long "separator"
       <> OA.metavar "SEP"
-      <> OA.help "Separator between package name and package version."
+      <> OA.help "Separator between package name and what follows."
       <> OA.value " "
       <> OA.showDefault
       )
src/Stack/Options/SDistParser.hs view
@@ -21,20 +21,22 @@   <$> many (strArgument
         (  metavar "DIR"
         <> completer dirCompleter
+        <> help "A relative path to a package directory. Can be specified \
+                \multiple times. If none specified, use all project packages."
         ))
   <*> optional pvpBoundsOption
   <*> ignoreCheckSwitch
   <*> buildPackageOption
   <*> optional (strOption
         (  long "tar-dir"
-        <> help "If specified, copy all the tar to this directory."
+        <> help "If specified, copy all the generated files to this directory."
         ))
  where
   ignoreCheckSwitch = switch
     (  long "ignore-check"
-    <> help "Do not check package for common mistakes."
+    <> help "Do not check packages for common mistakes."
     )
   buildPackageOption = boolFlags False
     "test-tarball"
-    "building of the resulting tarball."
+    "building of the resulting generated files."
     idm
src/Stack/Options/SetupParser.hs view
@@ -19,7 +19,7 @@ setupOptsParser = SetupCmdOpts
   <$> OA.optional (OA.argument readVersion
         (  OA.metavar "GHC_VERSION"
-        <> OA.help "Version of GHC to install, e.g. 9.6.6. (default: install \
+        <> OA.help "Version of GHC to install, e.g. 9.8.4. (default: install \
                    \the version implied by the snapshot)"
         ))
   <*> OA.boolFlags False
src/Stack/Options/TestParser.hs view
@@ -19,13 +19,13 @@ testOptsParser hide0 = TestOptsMonoid
   <$> firstBoolFlagsTrue
         "rerun-tests"
-        "running already successful tests."
+        "running already successful test suites."
         hide
   <*> fmap concat (many (argsOption
         (  long "test-arguments"
         <> long "ta"
         <> metavar "TEST_ARGS"
-        <> help "Arguments passed in to the test suite program."
+        <> help "Arguments passed to the test suites."
         <> hide
         )))
   <*> optionalFirstFalse (flag' True
@@ -33,11 +33,10 @@         <> help "Generate a code coverage report."
         <> hide
         ))
-  <*> optionalFirstFalse (flag' True
-        (  long "no-run-tests"
-        <> help "Disable running of tests. (Tests will still be built.)"
-        <> hide
-        ))
+  <*> firstBoolFlagsTrue
+        "run-tests"
+        "running of targeted test suites."
+        hide
   <*> optionalFirst (option (fmap Just auto)
         (  long "test-suite-timeout"
         <> help "Maximum test suite run time in seconds."
@@ -45,7 +44,7 @@         ))
   <*> firstBoolFlagsTrue
         "tests-allow-stdin"
-        "allow standard input in test executables."
+        "allow standard input in test suites."
         hide
  where
   hide = hideMods hide0
src/Stack/Options/UploadParser.hs view
@@ -34,7 +34,7 @@     (  metavar "ITEM"
     <> completer dirCompleter
     <> help "A relative path to a package directory or, for package upload \
-            \only, an sdist tarball."
+            \only, an sdist tarball. Can be specified multiple times."
     ))
   documentationParser = flag False True
     (  long "documentation"
@@ -57,16 +57,16 @@         Right v -> pure v
   ignoreCheckSwitch = switch
       (  long "ignore-check"
-      <> help "For package upload, do not check packages for common mistakes."
+      <> help "Do not check packages, for upload, for common mistakes."
       )
   buildPackageOption = boolFlags False
       "test-tarball"
-      "building of the resulting sdist tarball(s), for package upload."
+      "building of the resulting generated files, for package upload."
       idm
   tarDirParser = optional (strOption
     (  long "tar-dir"
-    <> help "For package upload, if specified, copy all the tar to this \
-            \directory."
+    <> help "If specified, copy all the generated files, for package upload, \
+            \to this directory."
     ))
   uploadVariantParser = flag Publishing Candidate
     (  long "candidate"
src/Stack/Setup.hs view
@@ -163,7 +163,10 @@ import           Stack.Types.Platform
                    ( HasPlatform (..), PlatformVariant (..)
                    , platformOnlyRelDir )
-import           Stack.Types.Runner ( HasRunner (..), Runner (..) )
+import           Stack.Types.Runner
+                   ( HasRunner (..), Runner (..), mExecutablePathL
+                   , viewExecutablePath
+                   )
 import           Stack.Types.SetupInfo ( SetupInfo (..) )
 import           Stack.Types.SourceMap
                    ( SMActual (..), SMWanted (..), SourceMap (..) )
@@ -173,7 +176,7 @@                    ( VersionedDownloadInfo (..) )
 import           Stack.Types.WantedCompilerSetter ( WantedCompilerSetter (..) )
 import qualified System.Directory as D
-import           System.Environment ( getExecutablePath, lookupEnv )
+import           System.Environment ( lookupEnv )
 import           System.IO.Error ( isPermissionError )
 import           System.FilePath ( searchPathSeparator )
 import qualified System.FilePath as FP
@@ -726,7 +729,7 @@ 
   distDir <- runReaderT distRelativeDir envConfig0 >>= canonicalizePath
 
-  executablePath <- liftIO getExecutablePath
+  mExecutablePath <- view mExecutablePathL
 
   utf8EnvVars <- withProcessContext menv $ getUtf8EnvVars compilerVer
 
@@ -751,7 +754,16 @@                    else id)
 
               $ (if es.stackExe
-                   then Map.insert "STACK_EXE" (T.pack executablePath)
+                   then maybe
+                     -- We don't throw an exception if there is no Stack
+                     -- executable path, so that buildConfigCompleter does not
+                     -- need to specify a path.
+                     id
+                     ( \executablePath -> Map.insert
+                         "STACK_EXE"
+                         (T.pack $ toFilePath executablePath)
+                     )
+                     mExecutablePath
                    else id)
 
               $ (if es.localeUtf8
@@ -1038,9 +1050,9 @@           , style Url "https://github.com/commercialhaskell/stack/issues/648" <> "."
           ]
         pure True
-    | ghcVersion >= mkVersion [9, 9] && notifyIfGhcUntested -> do
+    | ghcVersion >= mkVersion [9, 11] && notifyIfGhcUntested -> do
         prettyWarnL
-          [ flow "Stack has not been tested with GHC versions 9.10 and above, \
+          [ flow "Stack has not been tested with GHC versions 9.12 and above, \
                  \and using"
           , fromString (versionString ghcVersion) <> ","
           , flow "this may fail."
@@ -1082,9 +1094,9 @@           , parens (style Shell "nightly-2018-03-13")
           , flow "or later specify such GHC versions."
           ]
-    | cabalVersion >= mkVersion [3, 11] && notifyIfCabalUntested ->
+    | cabalVersion >= mkVersion [3, 13] && notifyIfCabalUntested ->
         prettyWarnL
-          [ flow "Stack has not been tested with Cabal versions 3.12 and \
+          [ flow "Stack has not been tested with Cabal versions 3.14 and \
                  \above, but version"
           , fromString (versionString cabalVersion)
           , flow "was found, this may fail."
@@ -2948,10 +2960,10 @@ 
   prettyInfoS "Download complete, testing executable."
 
-  -- We need to call getExecutablePath before we overwrite the
-  -- currently running binary: after that, Linux will append
-  -- (deleted) to the filename.
-  currExe <- liftIO getExecutablePath >>= parseAbsFile
+  -- We need to preserve the name of the executable file before we overwrite the
+  -- currently running binary: after that, Linux will append (deleted) to the
+  -- filename.
+  currExe <- viewExecutablePath
 
   liftIO $ do
     setFileExecutable (toFilePath tmpFile)
src/Stack/SourceMap.hs view
@@ -10,7 +10,6 @@   , loadVersion
   , getPLIVersion
   , loadGlobalHints
-  , DumpedGlobalPackage
   , actualFromGhc
   , actualFromHints
   , globalCondCheck
@@ -39,7 +38,8 @@ import           Stack.Types.CompilerPaths
                    ( CompilerPaths (..), GhcPkgExe, HasCompiler (..) )
 import           Stack.Types.Config ( HasConfig )
-import           Stack.Types.DumpPackage ( DumpPackage (..) )
+import           Stack.Types.DumpPackage
+                   ( DumpPackage (..), DumpedGlobalPackage )
 import           Stack.Types.Platform ( HasPlatform (..) )
 import           Stack.Types.Runner ( rslInLogL )
 import           Stack.Types.SourceMap
@@ -166,8 +166,6 @@         , fromString $ T.unpack $ textDisplay compiler
         ]
       pure mempty
-
-type DumpedGlobalPackage = DumpPackage
 
 actualFromGhc ::
      (HasConfig env, HasCompiler env)
src/Stack/Types/Build/Exception.hs view
@@ -102,7 +102,7 @@       | otherwise = pure $
           "The following target packages were not found: " ++
           intercalate ", " (map packageNameString $ Set.toList noKnown) ++
-          "\nSee https://docs.haskellstack.org/en/stable/build_command/#target-syntax for details."
+          "\nSee https://docs.haskellstack.org/en/stable/commands/build_command/#target-syntax for details."
     notInSnapshot'
       | Map.null notInSnapshot = []
       | otherwise =
@@ -261,6 +261,7 @@       VersionCheck
       WantedCompilerSetter -- Way that the wanted compiler is set
       StyleDoc -- recommended resolution
+  | ActionNotFilteredBug StyleDoc
   deriving (Show, Typeable)
 
 instance Pretty BuildPrettyException where
@@ -450,6 +451,12 @@          ]
     <> blankLine
     <> resolution
+  pretty (ActionNotFilteredBug source) = bugPrettyReport "S-4660" $
+    fillSep
+      [ source
+      , flow "is seeking to run an action that should have been filtered from \
+             \the list of actions."
+      ]
 
 instance Exception BuildPrettyException
src/Stack/Types/BuildOpts.hs view
@@ -102,7 +102,7 @@   { rerunTests :: !Bool -- ^ Whether successful tests will be run gain
   , additionalArgs :: ![String] -- ^ Arguments passed to the test program
   , coverage :: !Bool -- ^ Generate a code coverage report
-  , disableRun :: !Bool -- ^ Disable running of tests
+  , runTests :: !Bool -- ^ Enable running of tests
   , maximumTimeSeconds :: !(Maybe Int) -- ^ test suite timeout in seconds
   , allowStdin :: !Bool -- ^ Whether to allow standard input
   }
@@ -112,8 +112,8 @@ data BenchmarkOpts = BenchmarkOpts
   { additionalArgs :: !(Maybe String)
     -- ^ Arguments passed to the benchmark program
-  , disableRun :: !Bool
-    -- ^ Disable running of benchmarks
+  , runBenchmarks :: !Bool
+    -- ^ Enable running of benchmarks
   }
   deriving (Eq, Show)
src/Stack/Types/BuildOptsMonoid.hs view
@@ -258,7 +258,7 @@   { rerunTests :: !FirstTrue
   , additionalArgs :: ![String]
   , coverage :: !FirstFalse
-  , disableRun :: !FirstFalse
+  , runTests :: !FirstTrue
   , maximumTimeSeconds :: !(First (Maybe Int))
   , allowStdin :: !FirstTrue
   }
@@ -269,14 +269,14 @@     rerunTests <- FirstTrue <$> o ..:? rerunTestsArgName
     additionalArgs <- o ..:? testAdditionalArgsName ..!= []
     coverage <- FirstFalse <$> o ..:? coverageArgName
-    disableRun <- FirstFalse <$> o ..:? testDisableRunArgName
+    runTests <- FirstTrue . (not <$>) <$> o ..:? noRunTestsArgName
     maximumTimeSeconds <- First <$> o ..:? maximumTimeSecondsArgName
     allowStdin <- FirstTrue <$> o ..:? testsAllowStdinName
     pure TestOptsMonoid
       { rerunTests
       , additionalArgs
       , coverage
-      , disableRun
+      , runTests
       , maximumTimeSeconds
       , allowStdin
       }
@@ -290,8 +290,8 @@ coverageArgName :: Text
 coverageArgName = "coverage"
 
-testDisableRunArgName :: Text
-testDisableRunArgName = "no-run-tests"
+noRunTestsArgName :: Text
+noRunTestsArgName = "no-run-tests"
 
 maximumTimeSecondsArgName :: Text
 maximumTimeSecondsArgName = "test-suite-timeout"
@@ -328,24 +328,24 @@ 
 data BenchmarkOptsMonoid = BenchmarkOptsMonoid
   { additionalArgs :: !(First String)
-  , disableRun :: !(First Bool)
+  , runBenchmarks :: !FirstTrue
   }
   deriving (Generic, Show)
 
 instance FromJSON (WithJSONWarnings BenchmarkOptsMonoid) where
   parseJSON = withObjectWarnings "BenchmarkOptsMonoid" $ \o -> do
     additionalArgs <- First <$> o ..:? benchmarkAdditionalArgsName
-    disableRun <- First <$> o ..:? benchmarkDisableRunArgName
+    runBenchmarks <- FirstTrue . (not <$>) <$> o ..:? noRunBenchmarksArgName
     pure BenchmarkOptsMonoid
       { additionalArgs
-      , disableRun
+      , runBenchmarks
       }
 
 benchmarkAdditionalArgsName :: Text
 benchmarkAdditionalArgsName = "benchmark-arguments"
 
-benchmarkDisableRunArgName :: Text
-benchmarkDisableRunArgName = "no-run-benchmarks"
+noRunBenchmarksArgName :: Text
+noRunBenchmarksArgName = "no-run-benchmarks"
 
 instance Semigroup BenchmarkOptsMonoid where
   (<>) = mappenddefault
src/Stack/Types/Config.hs view
@@ -59,152 +59,158 @@ 
 -- | The top-level Stackage configuration.
 data Config = Config
-  { workDir                :: !(Path Rel Dir)
+  { workDir                 :: !(Path Rel Dir)
     -- ^ this allows to override .stack-work directory
-  , userGlobalConfigFile   :: !(Path Abs File)
+  , userGlobalConfigFile    :: !(Path Abs File)
     -- ^ The user-specific global configuration file.
-  , build                  :: !BuildOpts
+  , build                   :: !BuildOpts
     -- ^ Build configuration
-  , docker                 :: !DockerOpts
+  , docker                  :: !DockerOpts
     -- ^ Docker configuration
-  , nix                    :: !NixOpts
+  , nix                     :: !NixOpts
     -- ^ Execution environment (e.g nix-shell) configuration
-  , processContextSettings :: !(EnvSettings -> IO ProcessContext)
+  , processContextSettings  :: !(EnvSettings -> IO ProcessContext)
     -- ^ Environment variables to be passed to external tools
-  , localProgramsBase      :: !(Path Abs Dir)
+  , localProgramsBase       :: !(Path Abs Dir)
     -- ^ Non-platform-specific path containing local installations
-  , localPrograms          :: !(Path Abs Dir)
+  , localPrograms           :: !(Path Abs Dir)
     -- ^ Path containing local installations (mainly GHC)
-  , hideTHLoading          :: !Bool
+  , hideTHLoading           :: !Bool
     -- ^ Hide the Template Haskell "Loading package ..." messages from the
     -- console
-  , prefixTimestamps       :: !Bool
+  , prefixTimestamps        :: !Bool
     -- ^ Prefix build output with timestamps for each line.
-  , platform               :: !Platform
+  , platform                :: !Platform
     -- ^ The platform we're building for, used in many directory names
-  , platformVariant        :: !PlatformVariant
+  , platformVariant         :: !PlatformVariant
     -- ^ Variant of the platform, also used in directory names
-  , ghcVariant             :: !(Maybe GHCVariant)
+  , ghcVariant              :: !(Maybe GHCVariant)
     -- ^ The variant of GHC requested by the user.
-  , ghcBuild               :: !(Maybe CompilerBuild)
+  , ghcBuild                :: !(Maybe CompilerBuild)
     -- ^ Override build of the compiler distribution (e.g. standard, gmp4,
     -- tinfo6)
-  , latestSnapshot         :: !Text
+  , latestSnapshot          :: !Text
     -- ^ URL of a JSON file providing the latest LTS and Nightly snapshots.
-  , systemGHC              :: !Bool
+  , systemGHC               :: !Bool
     -- ^ Should we use the system-installed GHC (on the PATH) if
     -- available? Can be overridden by command line options.
-  , installGHC             :: !Bool
+  , installGHC              :: !Bool
     -- ^ Should we automatically install GHC if missing or the wrong
     -- version is available? Can be overridden by command line options.
-  , skipGHCCheck           :: !Bool
+  , skipGHCCheck            :: !Bool
     -- ^ Don't bother checking the GHC version or architecture.
-  , skipMsys               :: !Bool
+  , skipMsys                :: !Bool
     -- ^ On Windows: don't use a sandboxed MSYS
-  , msysEnvironment        :: !(Maybe MsysEnvironment)
+  , msysEnvironment         :: !(Maybe MsysEnvironment)
     -- ^ On Windows: what MSYS2 environment to apply. Nothing on other operating
     -- systems.
-  , compilerCheck          :: !VersionCheck
+  , compilerCheck           :: !VersionCheck
     -- ^ Specifies which versions of the compiler are acceptable.
-  , compilerRepository     :: !CompilerRepository
+  , compilerRepository      :: !CompilerRepository
     -- ^ Specifies the repository containing the compiler sources
-  , localBin               :: !(Path Abs Dir)
+  , localBin                :: !(Path Abs Dir)
     -- ^ Directory we should install executables into
-  , fileWatchHook          :: !(Maybe (Path Abs File))
+  , fileWatchHook           :: !(Maybe (Path Abs File))
     -- ^ Optional path of executable used to override --file-watch
     -- post-processing.
-  , requireStackVersion    :: !VersionRange
+  , requireStackVersion     :: !VersionRange
     -- ^ Require a version of Stack within this range.
-  , jobs                   :: !Int
+  , jobs                    :: !Int
     -- ^ How many concurrent jobs to run, defaults to number of capabilities
-  , overrideGccPath        :: !(Maybe (Path Abs File))
+  , overrideGccPath         :: !(Maybe (Path Abs File))
     -- ^ Optional gcc override path
-  , extraIncludeDirs       :: ![FilePath]
+  , extraIncludeDirs        :: ![FilePath]
     -- ^ --extra-include-dirs arguments
-  , extraLibDirs           :: ![FilePath]
+  , extraLibDirs            :: ![FilePath]
     -- ^ --extra-lib-dirs arguments
-  , customPreprocessorExts :: ![Text]
+  , customPreprocessorExts  :: ![Text]
     -- ^ List of custom preprocessors to complete the hard coded ones
-  , concurrentTests        :: !Bool
+  , concurrentTests         :: !Bool
     -- ^ Run test suites concurrently
-  , templateParams         :: !(Map Text Text)
+  , templateParams          :: !(Map Text Text)
     -- ^ Parameters for templates.
-  , scmInit                :: !(Maybe SCM)
+  , scmInit                 :: !(Maybe SCM)
     -- ^ Initialize SCM (e.g. git) when creating new projects.
-  , ghcOptionsByName       :: !(Map PackageName [Text])
+  , ghcOptionsByName        :: !(Map PackageName [Text])
     -- ^ Additional GHC options to apply to specific packages.
-  , ghcOptionsByCat        :: !(Map ApplyGhcOptions [Text])
+  , ghcOptionsByCat         :: !(Map ApplyGhcOptions [Text])
     -- ^ Additional GHC options to apply to categories of packages
-  , cabalConfigOpts        :: !(Map CabalConfigKey [Text])
+  , cabalConfigOpts         :: !(Map CabalConfigKey [Text])
     -- ^ Additional options to be passed to ./Setup.hs configure
-  , setupInfoLocations     :: ![String]
+  , setupInfoLocations      :: ![String]
     -- ^ URLs or paths to stack-setup.yaml files, for finding tools.
     -- If none present, the default setup-info is used.
-  , setupInfoInline        :: !SetupInfo
+  , setupInfoInline         :: !SetupInfo
     -- ^ Additional SetupInfo to use to find tools.
-  , pvpBounds              :: !PvpBounds
+  , pvpBounds               :: !PvpBounds
     -- ^ How PVP upper bounds should be added to packages
-  , modifyCodePage         :: !Bool
+  , modifyCodePage          :: !Bool
     -- ^ Force the code page to UTF-8 on Windows
-  , rebuildGhcOptions      :: !Bool
+  , rebuildGhcOptions       :: !Bool
     -- ^ Rebuild on GHC options changes
-  , applyGhcOptions        :: !ApplyGhcOptions
+  , applyGhcOptions         :: !ApplyGhcOptions
     -- ^ Which packages do --ghc-options on the command line apply to?
-  , applyProgOptions       :: !ApplyProgOptions
+  , applyProgOptions        :: !ApplyProgOptions
     -- ^ Which packages do all and any --PROG-option options on the command line
     -- apply to?
-  , allowNewer             :: !(First Bool)
+  , allowNewer              :: !(First Bool)
     -- ^ Ignore version ranges in .cabal files. Funny naming chosen to
     -- match cabal.
-  , allowNewerDeps         :: !(Maybe [PackageName])
+  , allowNewerDeps          :: !(Maybe [PackageName])
     -- ^ Ignore dependency upper and lower bounds only for specified
     -- packages. No effect unless allow-newer is enabled.
-  , defaultInitSnapshot    :: !(First AbstractSnapshot)
+  , defaultInitSnapshot     :: !(First AbstractSnapshot)
     -- ^ An optional default snapshot to use with @stack init@ when none is
     -- specified at the command line.
-  , defaultTemplate        :: !(Maybe TemplateName)
+  , defaultTemplate         :: !(Maybe TemplateName)
     -- ^ The default template to use when none is specified.
     -- (If Nothing, the 'default' default template is used.)
-  , allowDifferentUser     :: !Bool
+  , allowDifferentUser      :: !Bool
     -- ^ Allow users other than the Stack root owner to use the Stack
     -- installation.
-  , dumpLogs               :: !DumpLogs
+  , dumpLogs                :: !DumpLogs
     -- ^ Dump logs of local non-dependencies when doing a build.
-  , project                :: !(ProjectConfig (Project, Path Abs File))
+  , project                 :: !(ProjectConfig (Project, Path Abs File))
     -- ^ Project information and stack.yaml file location
-  , allowLocals            :: !Bool
+  , allowLocals             :: !Bool
     -- ^ Are we allowed to build local packages? The script
     -- command disallows this.
-  , saveHackageCreds       :: !FirstTrue
+  , saveHackageCreds        :: !FirstTrue
     -- ^ Should we save Hackage credentials to a file?
-  , hackageBaseUrl         :: !Text
+  , hackageBaseUrl          :: !Text
     -- ^ Hackage base URL used when uploading packages
-  , runner                 :: !Runner
-  , pantryConfig           :: !PantryConfig
-  , stackRoot              :: !(Path Abs Dir)
-  , snapshot               :: !(Maybe AbstractSnapshot)
+  , runner                  :: !Runner
+  , pantryConfig            :: !PantryConfig
+  , stackRoot               :: !(Path Abs Dir)
+  , snapshot                :: !(Maybe AbstractSnapshot)
     -- ^ Any snapshot override from the command line
-  , userStorage            :: !UserStorage
+  , userStorage             :: !UserStorage
     -- ^ Database connection pool for user Stack database
-  , hideSourcePaths        :: !Bool
+  , hideSourcePaths         :: !Bool
     -- ^ Enable GHC hiding source paths?
-  , recommendStackUpgrade  :: !Bool
+  , recommendStackUpgrade   :: !Bool
     -- ^ Recommend a Stack upgrade?
-  , notifyIfNixOnPath      :: !Bool
+  , notifyIfNixOnPath       :: !Bool
     -- ^ Notify if the Nix package manager (nix) is on the PATH, but
     -- Stack's Nix integration is not enabled?
-  , notifyIfGhcUntested    :: !Bool
+  , notifyIfGhcUntested     :: !Bool
     -- ^ Notify if Stack has not been tested with the GHC version?
-  , notifyIfCabalUntested  :: !Bool
+  , notifyIfCabalUntested   :: !Bool
     -- ^ Notify if Stack has not been tested with the Cabal version?
-  , notifyIfArchUnknown    :: !Bool
+  , notifyIfArchUnknown     :: !Bool
     -- ^ Notify if the specified machine architecture is unknown to Cabal (the
     -- library)?
-  , noRunCompile           :: !Bool
+  , notifyIfNoRunTests      :: !Bool
+    -- ^ Notify if the --no-run-tests flag has prevented the running of a
+    -- targeted test suite?
+  , notifyIfNoRunBenchmarks :: !Bool
+    -- ^ Notify if the --no-run-benchmarks flag has prevented the running of a
+    -- targeted benchmark?
+  , noRunCompile            :: !Bool
     -- ^ Use --no-run and --compile options when using `stack script`
-  , stackDeveloperMode     :: !Bool
+  , stackDeveloperMode      :: !Bool
     -- ^ Turn on Stack developer mode for additional messages?
-  , casa                   :: !(Maybe (CasaRepoPrefix, Int))
+  , casa                    :: !(Maybe (CasaRepoPrefix, Int))
     -- ^ Optional Casa configuration
   }
src/Stack/Types/Config/Exception.hs view
@@ -55,7 +55,7 @@     , T.unpack url
     , "':\n"
     , Yaml.prettyPrintParseException exception
-    , "\nSee https://docs.haskellstack.org/en/stable/custom_snapshot/"
+    , "\nSee https://docs.haskellstack.org/en/stable/topics/custom_snapshot/"
     ]
   displayException (NoProjectConfigFound dir mcmd) = concat
     [ "Error: [S-2206]\n"
@@ -168,6 +168,7 @@   | BadMsysEnvironment !MsysEnvironment !Arch
   | NoMsysEnvironmentBug
   | ConfigFileNotProjectLevelBug
+  | NoExecutablePath !String
   deriving (Show, Typeable)
 
 instance Pretty ConfigPrettyException where
@@ -177,7 +178,7 @@     <> fillSep
          [ flow "Stack could not load and parse"
          , pretty configFile
-         , flow "as a YAML configuraton file."
+         , flow "as a configuraton file."
          ]
     <> blankLine
     <> flow "While loading and parsing, Stack encountered the following \
@@ -186,11 +187,11 @@     <> string (Yaml.prettyPrintParseException exception)
     <> blankLine
     <> fillSep
-         [ flow "For help about the content of Stack's YAML configuration \
-                \files, see (for the most recent release of Stack)"
+         [ flow "For help about the content of Stack's configuration files, \
+                \see (for the most recent release of Stack)"
          ,    style
                 Url
-                "http://docs.haskellstack.org/en/stable/yaml_configuration/"
+                "http://docs.haskellstack.org/en/stable/configure/yaml/"
            <> "."
          ]
   pretty (StackWorkEnvNotRelativeDir x) =
@@ -238,6 +239,14 @@     flow "No default MSYS2 environment."
   pretty ConfigFileNotProjectLevelBug = bugPrettyReport "[S-8398]" $
     flow "The configuration file is not a project-level one."
+  pretty (NoExecutablePath progName) =
+    "[S-6890]"
+    <> line
+    <> fillSep
+         [ flow "The path for the executable file invoked as"
+         , style Shell (fromString progName)
+         , flow "can not be identified."
+         ]
 
 instance Exception ConfigPrettyException
src/Stack/Types/ConfigMonoid.hs view
@@ -59,145 +59,149 @@ -- | An uninterpreted representation of configuration options. Configurations
 -- may be "cascaded" using mappend (left-biased).
 data ConfigMonoid = ConfigMonoid
-  { stackRoot          :: !(First (Path Abs Dir))
+  { stackRoot               :: !(First (Path Abs Dir))
     -- ^ See: 'clStackRoot'
-  , workDir            :: !(First (Path Rel Dir))
+  , workDir                 :: !(First (Path Rel Dir))
     -- ^ See: 'configWorkDir'.
-  , buildOpts          :: !BuildOptsMonoid
+  , buildOpts               :: !BuildOptsMonoid
     -- ^ build options.
-  , dockerOpts         :: !DockerOptsMonoid
+  , dockerOpts              :: !DockerOptsMonoid
     -- ^ Docker options.
-  , nixOpts            :: !NixOptsMonoid
+  , nixOpts                 :: !NixOptsMonoid
     -- ^ Options for the execution environment (nix-shell or container)
-  , connectionCount    :: !(First Int)
+  , connectionCount         :: !(First Int)
     -- ^ See: 'configConnectionCount'
-  , hideTHLoading      :: !FirstTrue
+  , hideTHLoading           :: !FirstTrue
     -- ^ See: 'configHideTHLoading'
-  , prefixTimestamps   :: !(First Bool)
+  , prefixTimestamps        :: !(First Bool)
     -- ^ See: 'configPrefixTimestamps'
-  , latestSnapshot     :: !(First Text)
+  , latestSnapshot          :: !(First Text)
     -- ^ See: 'configLatestSnapshot'
-  , packageIndex     :: !(First PackageIndexConfig)
+  , packageIndex            :: !(First PackageIndexConfig)
     -- ^ See: 'withPantryConfig'
-  , systemGHC          :: !(First Bool)
+  , systemGHC               :: !(First Bool)
     -- ^ See: 'configSystemGHC'
-  , installGHC          :: !FirstTrue
+  , installGHC              :: !FirstTrue
     -- ^ See: 'configInstallGHC'
-  , skipGHCCheck        :: !FirstFalse
+  , skipGHCCheck            :: !FirstFalse
     -- ^ See: 'configSkipGHCCheck'
-  , skipMsys            :: !FirstFalse
+  , skipMsys                :: !FirstFalse
     -- ^ See: 'configSkipMsys'
-  , msysEnvironment     :: !(First MsysEnvironment)
+  , msysEnvironment         :: !(First MsysEnvironment)
     -- ^ See: 'configMsysEnvironment'
-  , compilerCheck       :: !(First VersionCheck)
+  , compilerCheck           :: !(First VersionCheck)
     -- ^ See: 'configCompilerCheck'
-  , compilerRepository  :: !(First CompilerRepository)
+  , compilerRepository      :: !(First CompilerRepository)
     -- ^ See: 'configCompilerRepository'
-  , requireStackVersion :: !IntersectingVersionRange
+  , requireStackVersion     :: !IntersectingVersionRange
     -- ^ See: 'configRequireStackVersion'
-  , arch                :: !(First String)
+  , arch                    :: !(First String)
     -- ^ Used for overriding the platform
-  , ghcVariant          :: !(First GHCVariant)
+  , ghcVariant              :: !(First GHCVariant)
     -- ^ Used for overriding the platform
-  , ghcBuild            :: !(First CompilerBuild)
+  , ghcBuild                :: !(First CompilerBuild)
     -- ^ Used for overriding the GHC build
-  , jobs                :: !(First Int)
+  , jobs                    :: !(First Int)
     -- ^ See: 'configJobs'
-  , extraIncludeDirs    :: ![FilePath]
+  , extraIncludeDirs        :: ![FilePath]
     -- ^ See: 'configExtraIncludeDirs'
-  , extraLibDirs        :: ![FilePath]
+  , extraLibDirs            :: ![FilePath]
     -- ^ See: 'configExtraLibDirs'
-  , customPreprocessorExts :: ![Text]
+  , customPreprocessorExts  :: ![Text]
     -- ^ See: 'configCustomPreprocessorExts'
-  , overrideGccPath     :: !(First (Path Abs File))
+  , overrideGccPath         :: !(First (Path Abs File))
     -- ^ Allow users to override the path to gcc
-  , overrideHpack       :: !(First FilePath)
+  , overrideHpack           :: !(First FilePath)
     -- ^ Use Hpack executable (overrides bundled Hpack)
-  , hpackForce          :: !FirstFalse
+  , hpackForce              :: !FirstFalse
     -- ^ Pass --force to Hpack to always overwrite Cabal file
-  , concurrentTests     :: !(First Bool)
+  , concurrentTests         :: !(First Bool)
     -- ^ See: 'configConcurrentTests'
-  , localBinPath        :: !(First FilePath)
+  , localBinPath            :: !(First FilePath)
     -- ^ Used to override the binary installation dir
-  , fileWatchHook       :: !(First FilePath)
+  , fileWatchHook           :: !(First FilePath)
     -- ^ Path to executable used to override --file-watch post-processing.
-  , templateParameters  :: !(Map Text Text)
+  , templateParameters      :: !(Map Text Text)
     -- ^ Template parameters.
-  , scmInit             :: !(First SCM)
+  , scmInit                 :: !(First SCM)
     -- ^ Initialize SCM (e.g. git init) when making new projects?
-  , ghcOptionsByName    :: !(MonoidMap PackageName (Monoid.Dual [Text]))
+  , ghcOptionsByName        :: !(MonoidMap PackageName (Monoid.Dual [Text]))
     -- ^ See 'configGhcOptionsByName'. Uses 'Monoid.Dual' so that
     -- options from the configs on the right come first, so that they
     -- can be overridden.
-  , ghcOptionsByCat     :: !(MonoidMap ApplyGhcOptions (Monoid.Dual [Text]))
+  , ghcOptionsByCat         :: !(MonoidMap ApplyGhcOptions (Monoid.Dual [Text]))
     -- ^ See 'configGhcOptionsAll'. Uses 'Monoid.Dual' so that options
     -- from the configs on the right come first, so that they can be
     -- overridden.
-  , cabalConfigOpts     :: !(MonoidMap CabalConfigKey (Monoid.Dual [Text]))
+  , cabalConfigOpts         :: !(MonoidMap CabalConfigKey (Monoid.Dual [Text]))
     -- ^ See 'configCabalConfigOpts'.
-  , extraPath           :: ![Path Abs Dir]
+  , extraPath               :: ![Path Abs Dir]
     -- ^ Additional paths to search for executables in
-  , setupInfoLocations  :: ![String]
+  , setupInfoLocations      :: ![String]
     -- ^ See 'configSetupInfoLocations'
-  , setupInfoInline     :: !SetupInfo
+  , setupInfoInline         :: !SetupInfo
     -- ^ See 'configSetupInfoInline'
-  , localProgramsBase   :: !(First (Path Abs Dir))
+  , localProgramsBase       :: !(First (Path Abs Dir))
     -- ^ Override the default local programs dir, where e.g. GHC is installed.
-  , pvpBounds           :: !(First PvpBounds)
+  , pvpBounds               :: !(First PvpBounds)
     -- ^ See 'configPvpBounds'
-  , modifyCodePage      :: !FirstTrue
+  , modifyCodePage          :: !FirstTrue
     -- ^ See 'configModifyCodePage'
-  , rebuildGhcOptions   :: !FirstFalse
+  , rebuildGhcOptions       :: !FirstFalse
     -- ^ See 'configMonoidRebuildGhcOptions'
-  , applyGhcOptions     :: !(First ApplyGhcOptions)
+  , applyGhcOptions         :: !(First ApplyGhcOptions)
     -- ^ See 'configApplyGhcOptions'
-  , applyProgOptions     :: !(First ApplyProgOptions)
+  , applyProgOptions        :: !(First ApplyProgOptions)
     -- ^ See 'configApplyProgOptions'
-  , allowNewer          :: !(First Bool)
+  , allowNewer              :: !(First Bool)
     -- ^ See 'configMonoidAllowNewer'
-  , allowNewerDeps      :: !(Maybe AllowNewerDeps)
+  , allowNewerDeps          :: !(Maybe AllowNewerDeps)
     -- ^ See 'configMonoidAllowNewerDeps'
-  , defaultInitSnapshot :: !(First (Unresolved AbstractSnapshot))
+  , defaultInitSnapshot     :: !(First (Unresolved AbstractSnapshot))
    -- ^ An optional default snapshot to use with @stack init@ when none is
    -- specified.
-  , defaultTemplate     :: !(First TemplateName)
+  , defaultTemplate         :: !(First TemplateName)
    -- ^ The default template to use when none is specified.
    -- (If Nothing, the 'default' default template is used.)
-  , allowDifferentUser :: !(First Bool)
+  , allowDifferentUser      :: !(First Bool)
    -- ^ Allow users other than the Stack root owner to use the Stack
    -- installation.
-  , dumpLogs           :: !(First DumpLogs)
+  , dumpLogs                :: !(First DumpLogs)
     -- ^ See 'configDumpLogs'
-  , saveHackageCreds   :: !FirstTrue
+  , saveHackageCreds        :: !FirstTrue
     -- ^ See 'configSaveHackageCreds'
-  , hackageBaseUrl     :: !(First Text)
+  , hackageBaseUrl          :: !(First Text)
     -- ^ See 'configHackageBaseUrl'
-  , colorWhen          :: !(First ColorWhen)
+  , colorWhen               :: !(First ColorWhen)
     -- ^ When to use 'ANSI' colors
-  , styles             :: !StylesUpdate
-  , hideSourcePaths    :: !FirstTrue
+  , styles                  :: !StylesUpdate
+  , hideSourcePaths         :: !FirstTrue
     -- ^ See 'configHideSourcePaths'
   , recommendStackUpgrade   :: !FirstTrue
     -- ^ See 'configRecommendStackUpgrade'
-  , notifyIfNixOnPath  :: !FirstTrue
+  , notifyIfNixOnPath       :: !FirstTrue
     -- ^ See 'configNotifyIfNixOnPath'
-  , notifyIfGhcUntested  :: !FirstTrue
+  , notifyIfGhcUntested     :: !FirstTrue
     -- ^ See 'configNotifyIfGhcUntested'
-  , notifyIfCabalUntested  :: !FirstTrue
+  , notifyIfCabalUntested   :: !FirstTrue
     -- ^ See 'configNotifyIfCabalUntested'
-  , notifyIfArchUnknown  :: !FirstTrue
+  , notifyIfArchUnknown     :: !FirstTrue
     -- ^ See 'configNotifyIfArchUnknown'
-  , casaOpts :: !CasaOptsMonoid
+  , notifyIfNoRunTests      :: !FirstTrue
+    -- ^ See 'configNotifyIfNoRunTests'
+  , notifyIfNoRunBenchmarks :: !FirstTrue
+    -- ^ See 'configNotifyIfNoRunBenchmarks'
+  , casaOpts                :: !CasaOptsMonoid
     -- ^ Casa configuration options.
-  , casaRepoPrefix     :: !(First CasaRepoPrefix)
+  , casaRepoPrefix          :: !(First CasaRepoPrefix)
     -- ^ Casa repository prefix (deprecated).
-  , snapshotLocation :: !(First Text)
+  , snapshotLocation        :: !(First Text)
     -- ^ Custom location of LTS/Nightly snapshots
-  , globalHintsLocation :: !(First (Unresolved GlobalHintsLocation))
+  , globalHintsLocation     :: !(First (Unresolved GlobalHintsLocation))
     -- ^ Custom location of global hints
-  , noRunCompile  :: !FirstFalse
+  , noRunCompile            :: !FirstFalse
     -- ^ See: 'configNoRunCompile'
-  , stackDeveloperMode :: !(First Bool)
+  , stackDeveloperMode      :: !(First Bool)
     -- ^ See 'configStackDeveloperMode'
   }
   deriving Generic
@@ -338,6 +342,10 @@     FirstTrue <$> obj ..:? configMonoidNotifyIfCabalUntestedName
   notifyIfArchUnknown <-
     FirstTrue <$> obj ..:? configMonoidNotifyIfArchUnknownName
+  notifyIfNoRunTests <-
+    FirstTrue <$> obj ..:? configMonoidNotifyIfNoRunTestsName
+  notifyIfNoRunBenchmarks <-
+    FirstTrue <$> obj ..:? configMonoidNotifyIfNoRunBenchmarksName
   casaOpts <- jsonSubWarnings (obj ..:? configMonoidCasaOptsName ..!= mempty)
   casaRepoPrefix <- First <$> obj ..:? configMonoidCasaRepoPrefixName
   snapshotLocation <- First <$> obj ..:? configMonoidSnapshotLocationName
@@ -407,6 +415,8 @@     , notifyIfGhcUntested
     , notifyIfCabalUntested
     , notifyIfArchUnknown
+    , notifyIfNoRunTests
+    , notifyIfNoRunBenchmarks
     , casaOpts
     , casaRepoPrefix
     , snapshotLocation
@@ -597,6 +607,12 @@ 
 configMonoidNotifyIfArchUnknownName :: Text
 configMonoidNotifyIfArchUnknownName = "notify-if-arch-unknown"
+
+configMonoidNotifyIfNoRunTestsName :: Text
+configMonoidNotifyIfNoRunTestsName = "notify-if-no-run-tests"
+
+configMonoidNotifyIfNoRunBenchmarksName :: Text
+configMonoidNotifyIfNoRunBenchmarksName = "notify-if-no-run-benchmarks"
 
 configMonoidCasaOptsName :: Text
 configMonoidCasaOptsName = "casa"
src/Stack/Types/DumpPackage.hs view
@@ -5,7 +5,8 @@ module Stack.Types.DumpPackage
   ( DumpPackage (..)
   , SublibDump (..)
-  , dpParentLibIdent
+  , DumpedGlobalPackage
+  , sublibParentPkgId
   ) where
 
 import qualified Distribution.License as C
@@ -14,17 +15,17 @@ import           Stack.Types.Component ( StackUnqualCompName )
 import           Stack.Types.GhcPkgId ( GhcPkgId )
 
--- | Type representing dump information for a single package, as output by the
--- @ghc-pkg describe@ command.
+-- | Type representing dump information for a single installed package, as
+-- output by the @ghc-pkg describe@ command.
 data DumpPackage = DumpPackage
   { ghcPkgId :: !GhcPkgId
     -- ^ The @id@ field.
   , packageIdent :: !PackageIdentifier
     -- ^ The @name@ and @version@ fields. The @name@ field is the munged package
-    -- name. If the package is not for a sub library, its munged name is its
+    -- name. If the package is not for a sub-library, its munged name is its
     -- name.
   , sublib :: !(Maybe SublibDump)
-    -- ^ The sub library information if it's a sub-library.
+    -- ^ The sub-library information, if it is a sub-library.
   , license :: !(Maybe C.License)
   , libDirs :: ![FilePath]
     -- ^ The @library-dirs@ field.
@@ -40,20 +41,22 @@   }
   deriving (Eq, Read, Show)
 
--- | ghc-pkg has a notion of sublibraries when using ghc-pkg dump. We can only
--- know it's different through the fields it shows.
+-- | An installed package for a sub-library of a Cabal package has additional
+-- fields.
 data SublibDump = SublibDump
   { packageName :: PackageName
-    -- ^ "package-name" field from ghc-pkg
+    -- ^ The @package-name@ field.
   , libraryName :: StackUnqualCompName
-    -- ^ "lib-name" field from ghc-pkg
+    -- ^ The @lib-name@ field.
   }
   deriving (Eq, Read, Show)
 
-dpParentLibIdent :: DumpPackage -> Maybe PackageIdentifier
-dpParentLibIdent dp = case (dp.sublib, dp.packageIdent) of
-  (Nothing, _) -> Nothing
-  (Just sublibDump, PackageIdentifier _ v) ->
-    Just $ PackageIdentifier libParentPackageName v
-   where
-    SublibDump { packageName = libParentPackageName } = sublibDump
+-- | Type synonym representing dump information for a single installed package
+-- in the global package database.
+type DumpedGlobalPackage = DumpPackage
+
+-- | If the given 'DumpPackage' is for a sub-library of a Cabal package, yields
+-- the package identifier of the Cabal package.
+sublibParentPkgId :: DumpPackage -> Maybe PackageIdentifier
+sublibParentPkgId dp = dp.sublib <&> \subLibDump ->
+  PackageIdentifier subLibDump.packageName dp.packageIdent.pkgVersion
src/Stack/Types/GlobalOpts.hs view
@@ -17,27 +17,33 @@ 
 -- | Parsed global command-line options.
 data GlobalOpts = GlobalOpts
-  { reExecVersion :: !(Maybe String)
+  { reExecVersion    :: !(Maybe String)
     -- ^ Expected re-exec in container version
   , dockerEntrypoint :: !(Maybe DockerEntrypoint)
     -- ^ Data used when Stack is acting as a Docker entrypoint (internal use
     -- only)
-  , logLevel     :: !LogLevel -- ^ Log level
-  , timeInLog    :: !Bool -- ^ Whether to include timings in logs.
-  , rslInLog     :: !Bool
+  , logLevel         :: !LogLevel -- ^ Log level
+  , timeInLog        :: !Bool -- ^ Whether to include timings in logs.
+  , rslInLog         :: !Bool
     -- ^ Whether to include raw snapshot layer (RSL) in logs.
-  , planInLog :: !Bool
+  , planInLog        :: !Bool
     -- ^ Whether to include debug information about the construction of the
     -- build plan in logs.
-  , configMonoid :: !ConfigMonoid
+  , configMonoid     :: !ConfigMonoid
     -- ^ Config monoid, for passing into 'loadConfig'
-  , snapshot     :: !(Maybe AbstractSnapshot) -- ^ Snapshot override
-  , compiler     :: !(Maybe WantedCompiler) -- ^ Compiler override
-  , terminal     :: !Bool -- ^ We're in a terminal?
-  , stylesUpdate :: !StylesUpdate -- ^ SGR (Ansi) codes for styles
-  , termWidthOpt  :: !(Maybe Int) -- ^ Terminal width override
-  , stackYaml    :: !StackYamlLoc -- ^ Override project stack.yaml
+  , snapshot         :: !(Maybe AbstractSnapshot) -- ^ Snapshot override
+  , compiler         :: !(Maybe WantedCompiler) -- ^ Compiler override
+  , terminal         :: !Bool -- ^ We're in a terminal?
+  , stylesUpdate     :: !StylesUpdate -- ^ SGR (Ansi) codes for styles
+  , termWidthOpt     :: !(Maybe Int) -- ^ Terminal width override
+  , stackYaml        :: !StackYamlLoc -- ^ Override project stack.yaml
   , lockFileBehavior :: !LockFileBehavior
+  , progName         :: !String
+    -- ^ The name of the current Stack executable, as it was invoked.
+  , mExecutablePath  :: !(Maybe (Path Abs File))
+    -- ^ The path to the current Stack executable, if the operating system
+    -- provides a reliable way to determine it and where a result was
+    -- available.
   }
 
 globalOptsBuildOptsMonoidL :: Lens' GlobalOpts BuildOptsMonoid
src/Stack/Types/Package.hs view
@@ -278,38 +278,39 @@ 
 -- | Information on a locally available package of source code.
 data LocalPackage = LocalPackage
-  { package       :: !Package
+  { package        :: !Package
      -- ^ The @Package@ info itself, after resolution with package flags, with
      -- tests and benchmarks disabled
-  , components    :: !(Set NamedComponent)
+  , components     :: !(Set NamedComponent)
     -- ^ Components to build, not including the library component.
-  , unbuildable   :: !(Set NamedComponent)
+  , unbuildable    :: !(Set NamedComponent)
     -- ^ Components explicitly requested for build, that are marked
     -- "buildable: false".
-  , wanted        :: !Bool -- FIXME Should completely drop this "wanted"
-                             -- terminology, it's unclear
+  , wanted         :: !Bool
     -- ^ Whether this package is wanted as a target.
-  , testBench     :: !(Maybe Package)
+
+    -- FIXME Should completely drop this "wanted" terminology, it's unclear.
+  , testBench      :: !(Maybe Package)
     -- ^ This stores the 'Package' with tests and benchmarks enabled, if either
     -- is asked for by the user.
-  , cabalFP     :: !(Path Abs File)
+  , cabalFP        :: !(Path Abs File)
     -- ^ Absolute path to the Cabal file.
-  , buildHaddocks :: !Bool
+  , buildHaddocks  :: !Bool
     -- ^ Is Haddock documentation being built for this package?
-  , forceDirty    :: !Bool
-  , dirtyFiles    :: !(MemoizedWith EnvConfig (Maybe (Set FilePath)))
+  , forceDirty     :: !Bool
+  , dirtyFiles     :: !(MemoizedWith EnvConfig (Maybe (Set FilePath)))
     -- ^ Nothing == not dirty, Just == dirty. Note that the Set may be empty if
     -- we forced the build to treat packages as dirty. Also, the Set may not
     -- include all modified files.
   , newBuildCaches :: !( MemoizedWith
-                             EnvConfig
-                             (Map NamedComponent (Map FilePath FileCacheInfo))
-                         )
+                           EnvConfig
+                           (Map NamedComponent (Map FilePath FileCacheInfo))
+                       )
     -- ^ current state of the files
   , componentFiles :: !( MemoizedWith
-                             EnvConfig
-                             (Map NamedComponent (Set (Path Abs File)))
-                         )
+                           EnvConfig
+                           (Map NamedComponent (Set (Path Abs File)))
+                       )
     -- ^ all files used by this package
   }
   deriving Show
src/Stack/Types/Runner.hs view
@@ -1,5 +1,6 @@ {-# LANGUAGE NoImplicitPrelude     #-}
 {-# LANGUAGE DuplicateRecordFields #-}
+{-# LANGUAGE LambdaCase            #-}
 {-# LANGUAGE NoFieldSelectors      #-}
 {-# LANGUAGE OverloadedRecordDot   #-}
 
@@ -13,10 +14,14 @@   , terminalL
   , reExecL
   , rslInLogL
+  , progNameL
+  , mExecutablePathL
+  , viewExecutablePath
   ) where
 
 import           RIO.Process ( HasProcessContext (..), ProcessContext )
 import           Stack.Prelude hiding ( stylesUpdate )
+import           Stack.Types.Config.Exception ( ConfigPrettyException (..) )
 import           Stack.Types.GlobalOpts ( GlobalOpts (..) )
 import           Stack.Types.LockFileBehavior ( LockFileBehavior )
 import           Stack.Types.StackYamlLoc ( StackYamlLoc )
@@ -66,24 +71,44 @@ class HasRunner env => HasDockerEntrypointMVar env where
   dockerEntrypointMVarL :: Lens' env (MVar Bool)
 
+-- | See the @stackYaml@ field of the 'GlobalOpts' data constructor.
 stackYamlLocL :: HasRunner env => Lens' env StackYamlLoc
 stackYamlLocL =
   globalOptsL . lens (.stackYaml) (\x y -> x { stackYaml = y })
 
+-- | See the @lockFileBehavior@ field of the 'GlobalOpts' data constructor.
 lockFileBehaviorL :: HasRunner env => SimpleGetter env LockFileBehavior
 lockFileBehaviorL = globalOptsL . to (.lockFileBehavior)
 
+-- | See the 'GlobalOpts' type.
 globalOptsL :: HasRunner env => Lens' env GlobalOpts
 globalOptsL = runnerL . lens (.globalOpts) (\x y -> x { globalOpts = y })
 
--- | See 'globalTerminal'
+-- | See the @terminal@ field of the 'GlobalOpts' data constructor.
 terminalL :: HasRunner env => Lens' env Bool
 terminalL =
   globalOptsL . lens (.terminal) (\x y -> x { terminal = y })
 
--- | See 'globalReExecVersion'
+-- | See the @reExecVersion@ field of the 'GlobalOpts' data constructor.
 reExecL :: HasRunner env => SimpleGetter env Bool
 reExecL = globalOptsL . to (isJust . (.reExecVersion))
 
+-- | See the @rslInLog@ field of the 'GlobalOpts' data constructor.
 rslInLogL :: HasRunner env => SimpleGetter env Bool
 rslInLogL = globalOptsL . to (.rslInLog)
+
+-- | See the @progNameL@ field of the 'GlobalOpts' data constructor.
+progNameL :: HasRunner env => SimpleGetter env String
+progNameL = globalOptsL . to (.progName)
+
+-- | See the @mExecutablePath@ field of the 'GlobalOpts' data constructor.
+mExecutablePathL :: HasRunner env => SimpleGetter env (Maybe (Path Abs File))
+mExecutablePathL = globalOptsL . to (.mExecutablePath)
+
+-- | Yield the path to the current Stack executable, if the operating system
+-- provides a reliable way to determine it. Otherwise throw
+-- 'Stack.Types.Config.Exception.NoExecutablePath'.
+viewExecutablePath :: HasRunner env => RIO env (Path Abs File)
+viewExecutablePath = view mExecutablePathL >>= \case
+    Nothing -> view progNameL >>= prettyThrowM . NoExecutablePath
+    Just executablePath -> pure executablePath
src/Stack/Types/SourceMap.hs view
@@ -3,11 +3,12 @@ {-# LANGUAGE NoFieldSelectors      #-}
 {-# LANGUAGE OverloadedRecordDot   #-}
 
--- | A sourcemap maps a package name to how it should be built, including source
--- code, flags, options, etc. This module contains various stages of source map
--- construction. See the @build_overview.md@ doc for details on these stages.
+-- | A source map maps a package name to how it should be built, including
+-- source code, flags and options. This module exports types used in various
+-- stages of source map construction. See @build_overview.md@ for details on
+-- these stages.
 module Stack.Types.SourceMap
-  ( -- * Different source map types
+  ( -- * Source map types
     SMWanted (..)
   , SMActual (..)
   , Target (..)
@@ -56,8 +57,8 @@     -- ^ Should Haddock documentation be built for this package?
   }
 
--- | Flag showing if package comes from a snapshot needed to ignore dependency
--- bounds between such packages
+-- | Flag showing if package comes from a snapshot. Used to ignore dependency
+-- bounds between such packages.
 data FromSnapshot
   = FromSnapshot
   | NotFromSnapshot
@@ -75,16 +76,20 @@     -- See https://github.com/commercialhaskell/stackage/issues/3185
   }
 
--- | A view of a project package needed for resolving components
+-- | A view of a project package. Used to resolve components.
 data ProjectPackage = ProjectPackage
   { projectCommon :: !CommonPackage
   , cabalFP :: !(Path Abs File)
   , resolvedDir :: !(ResolvedPath Dir)
   }
 
--- | A view of a package installed in the global package database also could
--- include marker for a replaced global package (could be replaced because of a
--- replaced dependency)
+-- | A type representing versions of packages in the global package database.
+newtype GlobalPackageVersion
+  = GlobalPackageVersion Version
+
+-- | A view of a package installed in the global package database or a marker
+-- for a replaced global package. A global package could be replaced because of
+-- a replaced dependency.
 data GlobalPackage
   = GlobalPackage !Version
   | ReplacedGlobalPackage ![PackageName]
@@ -94,6 +99,16 @@ isReplacedGlobal (ReplacedGlobalPackage _) = True
 isReplacedGlobal (GlobalPackage _) = False
 
+-- | A type representing how a package is intended to be built.
+data Target
+  = TargetAll !PackageType
+    -- ^ Build all of the default components.
+  | TargetComps !(Set NamedComponent)
+    -- ^ Only build specific components
+
+data PackageType = PTProject | PTDependency
+  deriving (Eq, Show)
+
 -- | A source map with information on the wanted (but not actual) compiler. This
 -- is derived by parsing the @stack.yaml@ file for @packages@, @extra-deps@,
 -- their configuration (e.g., flags and options), and parsing the snapshot it
@@ -110,8 +125,9 @@     -- ^ Where this snapshot is loaded from.
   }
 
--- | Adds in actual compiler information to 'SMWanted', in particular the
--- contents of the global package database.
+-- | A source map with information on the actual compiler, including the
+-- contents of its global package database. It does not include any information
+-- from the command line.
 --
 -- Invariant: a @PackageName@ appears in only one of the @Map@s.
 data SMActual global = SMActual
@@ -121,19 +137,6 @@   , globals :: !(Map PackageName global)
   }
 
-newtype GlobalPackageVersion
-  = GlobalPackageVersion Version
-
--- | How a package is intended to be built
-data Target
-  = TargetAll !PackageType
-  -- ^ Build all of the default components.
-  | TargetComps !(Set NamedComponent)
-  -- ^ Only build specific components
-
-data PackageType = PTProject | PTDependency
-  deriving (Eq, Show)
-
 -- | Builds on an 'SMActual' by resolving the targets specified on the command
 -- line, potentially adding in new dependency packages in the process.
 data SMTargets = SMTargets
@@ -143,6 +146,9 @@ 
 -- | The final source map, taking an 'SMTargets' and applying all command line
 -- flags and GHC options.
+--
+-- One source map value is distinguished from another by a hash of the parts of
+-- the value that are immutable.
 data SourceMap = SourceMap
   { targets :: !SMTargets
     -- ^ Doesn't need to be included in the hash, does not affect the source
src/Stack/Types/Storage.hs view
@@ -45,8 +45,8 @@            flow "This error can be caused by a bug that arises if GHC's \
                 \'--io-manager=native' RTS option is set using the GHCRTS \
                 \environment variable. As a workaround try setting the option \
-                \in the project's Cabal file, Stack's YAML configuration file \
-                \or at the command line."
+                \in the project's Cabal file, Stack's configuration file or at \
+                \the command line."
          else
            flow "As a workaround you may delete the database. This \
                 \will cause the database to be recreated."
src/Stack/Types/WantedCompilerSetter.hs view
@@ -13,5 +13,5 @@   | SnapshotAtCommandLine
     -- ^ At the command line with --snapshot (or --resolver) option.
   | YamlConfiguration (Maybe (Path Abs File))
-    -- ^ Via a YAML configuration file.
+    -- ^ Via a configuration file.
   deriving (Show, Typeable)
src/Stack/Uninstall.hs view
@@ -40,7 +40,7 @@              ]
          , hang 4 $ fillSep
              [ flow "(3) if different, the directory containing "
-             , flow "Stack's user-specific global YAML configuration file"
+             , flow "Stack's user-specific global configuration file"
              , parens userGlobalConfigFile' <> ";"
              , "and"
              ]
src/setup-shim/StackSetupShim.hs view
@@ -46,6 +46,10 @@ import Distribution.Types.ComponentLocalBuildInfo ( ComponentLocalBuildInfo )
 import Distribution.Types.LocalBuildInfo ( LocalBuildInfo )
 import Distribution.Types.PackageDescription ( PackageDescription )
+#if MIN_VERSION_Cabal(3,14,0)
+import Distribution.Utils.Path
+         ( interpretSymbolicPathCWD, makeSymbolicPath, relativeSymbolicPath )
+#endif
 import Distribution.Verbosity ( Verbosity )
 #endif
 import Distribution.Verbosity ( flagToVerbosity )
@@ -85,7 +89,12 @@             "stack-initial-build-steps, expected to parse Cabal verbosity: " <>
             msg1
           Right verbosity -> do
-            eFp <- findPackageDesc ""
+            eFp <-
+#if MIN_VERSION_Cabal(3,14,0)
+              findPackageDesc Nothing
+#else
+              findPackageDesc ""
+#endif
             case eFp of
               Left err -> fail $
                 "Unexpected happened running Setup.hs with " <>
@@ -99,9 +108,23 @@                 msg2 = err
 #endif
               Right fp -> do
-                gpd <- readGenericPackageDescription verbosity fp
+                gpd <-
+                  readGenericPackageDescription
+                    verbosity
+#if MIN_VERSION_Cabal(3,14,0)
+                    Nothing
+                    (relativeSymbolicPath fp)
+#else
+                    fp
+#endif
                 let pd = packageDescription gpd
-                lbi <- getPersistBuildConfig rawBuildDir
+                lbi <- getPersistBuildConfig
+#if MIN_VERSION_Cabal(3,14,0)
+                  Nothing
+                  (makeSymbolicPath rawBuildDir)
+#else
+                  rawBuildDir
+#endif
                 initialBuildSteps rawBuildDir pd lbi verbosity
 
 -- | Temporary, can be removed if initialBuildSteps restored to Cabal's API.
@@ -127,7 +150,14 @@   -> Verbosity -- ^The verbosity to use
   -> IO ()
 componentInitialBuildSteps _distPref pkg_descr lbi clbi verbosity = do
-  createDirectoryIfMissingVerbose verbosity True (componentBuildDir lbi clbi)
+  createDirectoryIfMissingVerbose
+    verbosity
+    True
+#if MIN_VERSION_Cabal(3,14,0)
+    (interpretSymbolicPathCWD $ componentBuildDir lbi clbi)
+#else
+    (componentBuildDir lbi clbi)
+#endif
   -- Cabal-3.10.3.0 used writeAutogenFiles, that generated and wrote out the
   -- Paths_<pkg>.hs, PackageInfo_<pkg>.hs, and cabal_macros.h files. This
   -- appears to be the equivalent function for Cabal-3.11.0.0.
stack.cabal view
@@ -1,6 +1,6 @@ cabal-version:      2.0 name:               stack-version:            3.1.1+version:            3.3.1 license:            BSD3 license-file:       LICENSE maintainer:         manny@fpcomplete.com@@ -126,6 +126,8 @@     doc/tutorial/installed_package_databases.md     doc/tutorial/locations_used_by_stack.md     doc/tutorial/multi-package_projects.md+    doc/tutorial/package_description.md+    doc/tutorial/project_configuration.md     doc/tutorial/stack_build_synonyms.md     doc/tutorial/stack_build_targets.md     doc/tutorial/stack_configuration.md@@ -149,7 +151,7 @@     setup-depends:         Cabal >=3.10.3.0 && <3.12,         base >=4.14.3.0 && <5,-        filepath >=1.4.300.1+        filepath >=1.4.301.0  flag developer-mode     description: By default, output extra developer information.@@ -410,35 +412,35 @@         aeson >=2.0.3.0,         aeson-warning-parser >=0.1.1,         ansi-terminal >=1.0.2,-        array >=0.5.6.0,+        array >=0.5.8.0,         async >=2.2.5,         attoparsec >=0.14.4,         base >=4.16.0.0 && <5,         base64-bytestring >=1.2.1.0,-        bytestring >=0.11.5.3,+        bytestring >=0.12.1.0,         casa-client >=0.0.2,         companion >=0.1.0,-        conduit >=1.3.5,+        conduit >=1.3.6,         conduit-extra >=1.3.6,-        containers >=0.6.7,-        crypton >=0.34,+        containers >=0.6.8,+        crypton >=1.0.1,         directory >=1.3.8.5,         echo >=0.1.4,         exceptions >=0.10.7,         extra >=1.7.16,         file-embed >=0.0.16.0,         filelock >=0.1.1.7,-        filepath >=1.4.300.1,+        filepath >=1.4.301.0,         fsnotify >=0.4.1,-        generic-deriving >=1.14.5,-        ghc-boot >=9.6.6,-        hashable >=1.4.4.0,-        hi-file-parser >=0.1.6.0,+        generic-deriving >=1.14.6,+        ghc-boot >=9.8.4,+        hashable >=1.4.7.0,+        hi-file-parser >=0.1.7.0,         hpack >=0.36.0,-        hpc >=0.6.2.0,+        hpc >=0.7.0.0,         http-client >=0.7.17,         http-client-tls >=0.3.6.2,-        http-conduit >=2.3.8.3,+        http-conduit >=2.3.9.1,         http-download >=0.2.1.0,         http-types >=0.12.4,         memory >=0.18.0,@@ -460,21 +462,21 @@         rio >=0.1.22.0,         rio-prettyprint >=0.1.8.0,         split >=0.2.5,-        stm >=2.5.1.0,+        stm >=2.5.3.1,         tar >=0.6.2.0,-        template-haskell >=2.20.0.0,-        text >=2.0.2,+        template-haskell >=2.21.0.0,+        text >=2.1.1,         time >=1.12.2,         transformers >=0.6.1.0,-        unix-compat >=0.7.2,+        unix-compat >=0.7.3,         unordered-containers >=0.2.20,-        vector >=0.13.1.0,+        vector >=0.13.2.0,         yaml >=0.11.11.2,-        zlib >=0.6.3.0+        zlib >=0.7.1.0      if os(windows)         cpp-options:   -DWINDOWS-        build-depends: Win32 >=2.13.3.0+        build-depends: Win32 >=2.13.4.0      else         build-tool-depends: hsc2hs:hsc2hs@@ -538,35 +540,35 @@         aeson >=2.0.3.0,         aeson-warning-parser >=0.1.1,         ansi-terminal >=1.0.2,-        array >=0.5.6.0,+        array >=0.5.8.0,         async >=2.2.5,         attoparsec >=0.14.4,         base >=4.16.0.0 && <5,         base64-bytestring >=1.2.1.0,-        bytestring >=0.11.5.3,+        bytestring >=0.12.1.0,         casa-client >=0.0.2,         companion >=0.1.0,-        conduit >=1.3.5,+        conduit >=1.3.6,         conduit-extra >=1.3.6,-        containers >=0.6.7,-        crypton >=0.34,+        containers >=0.6.8,+        crypton >=1.0.1,         directory >=1.3.8.5,         echo >=0.1.4,         exceptions >=0.10.7,         extra >=1.7.16,         file-embed >=0.0.16.0,         filelock >=0.1.1.7,-        filepath >=1.4.300.1,+        filepath >=1.4.301.0,         fsnotify >=0.4.1,-        generic-deriving >=1.14.5,-        ghc-boot >=9.6.6,-        hashable >=1.4.4.0,-        hi-file-parser >=0.1.6.0,+        generic-deriving >=1.14.6,+        ghc-boot >=9.8.4,+        hashable >=1.4.7.0,+        hi-file-parser >=0.1.7.0,         hpack >=0.36.0,-        hpc >=0.6.2.0,+        hpc >=0.7.0.0,         http-client >=0.7.17,         http-client-tls >=0.3.6.2,-        http-conduit >=2.3.8.3,+        http-conduit >=2.3.9.1,         http-download >=0.2.1.0,         http-types >=0.12.4,         memory >=0.18.0,@@ -589,21 +591,21 @@         rio-prettyprint >=0.1.8.0,         split >=0.2.5,         stack,-        stm >=2.5.1.0,+        stm >=2.5.3.1,         tar >=0.6.2.0,-        template-haskell >=2.20.0.0,-        text >=2.0.2,+        template-haskell >=2.21.0.0,+        text >=2.1.1,         time >=1.12.2,         transformers >=0.6.1.0,-        unix-compat >=0.7.2,+        unix-compat >=0.7.3,         unordered-containers >=0.2.20,-        vector >=0.13.1.0,+        vector >=0.13.2.0,         yaml >=0.11.11.2,-        zlib >=0.6.3.0+        zlib >=0.7.1.0      if os(windows)         cpp-options:   -DWINDOWS-        build-depends: Win32 >=2.13.3.0+        build-depends: Win32 >=2.13.4.0      else         build-tool-depends: hsc2hs:hsc2hs@@ -646,36 +648,36 @@         aeson >=2.0.3.0,         aeson-warning-parser >=0.1.1,         ansi-terminal >=1.0.2,-        array >=0.5.6.0,+        array >=0.5.8.0,         async >=2.2.5,         attoparsec >=0.14.4,         base >=4.16.0.0 && <5,         base64-bytestring >=1.2.1.0,-        bytestring >=0.11.5.3,+        bytestring >=0.12.1.0,         casa-client >=0.0.2,         companion >=0.1.0,-        conduit >=1.3.5,+        conduit >=1.3.6,         conduit-extra >=1.3.6,-        containers >=0.6.7,-        crypton >=0.34,+        containers >=0.6.8,+        crypton >=1.0.1,         directory >=1.3.8.5,         echo >=0.1.4,         exceptions >=0.10.7,         extra >=1.7.16,         file-embed >=0.0.16.0,         filelock >=0.1.1.7,-        filepath >=1.4.300.1,+        filepath >=1.4.301.0,         fsnotify >=0.4.1,-        generic-deriving >=1.14.5,-        ghc-boot >=9.6.6,-        hashable >=1.4.4.0,-        hi-file-parser >=0.1.6.0,+        generic-deriving >=1.14.6,+        ghc-boot >=9.8.4,+        hashable >=1.4.7.0,+        hi-file-parser >=0.1.7.0,         hpack >=0.36.0,-        hpc >=0.6.2.0,-        hspec >=2.11.9,+        hpc >=0.7.0.0,+        hspec >=2.11.10,         http-client >=0.7.17,         http-client-tls >=0.3.6.2,-        http-conduit >=2.3.8.3,+        http-conduit >=2.3.9.1,         http-download >=0.2.1.0,         http-types >=0.12.4,         memory >=0.18.0,@@ -698,21 +700,21 @@         rio >=0.1.22.0,         rio-prettyprint >=0.1.8.0,         split >=0.2.5,-        stm >=2.5.1.0,+        stm >=2.5.3.1,         tar >=0.6.2.0,-        template-haskell >=2.20.0.0,-        text >=2.0.2,+        template-haskell >=2.21.0.0,+        text >=2.1.1,         time >=1.12.2,         transformers >=0.6.1.0,-        unix-compat >=0.7.2,+        unix-compat >=0.7.3,         unordered-containers >=0.2.20,-        vector >=0.13.1.0,+        vector >=0.13.2.0,         yaml >=0.11.11.2,-        zlib >=0.6.3.0+        zlib >=0.7.1.0      if os(windows)         cpp-options:   -DWINDOWS-        build-depends: Win32 >=2.13.3.0+        build-depends: Win32 >=2.13.4.0      else         build-tool-depends: hsc2hs:hsc2hs@@ -772,36 +774,36 @@         aeson >=2.0.3.0,         aeson-warning-parser >=0.1.1,         ansi-terminal >=1.0.2,-        array >=0.5.6.0,+        array >=0.5.8.0,         async >=2.2.5,         attoparsec >=0.14.4,         base >=4.16.0.0 && <5,         base64-bytestring >=1.2.1.0,-        bytestring >=0.11.5.3,+        bytestring >=0.12.1.0,         casa-client >=0.0.2,         companion >=0.1.0,-        conduit >=1.3.5,+        conduit >=1.3.6,         conduit-extra >=1.3.6,-        containers >=0.6.7,-        crypton >=0.34,+        containers >=0.6.8,+        crypton >=1.0.1,         directory >=1.3.8.5,         echo >=0.1.4,         exceptions >=0.10.7,         extra >=1.7.16,         file-embed >=0.0.16.0,         filelock >=0.1.1.7,-        filepath >=1.4.300.1,+        filepath >=1.4.301.0,         fsnotify >=0.4.1,-        generic-deriving >=1.14.5,-        ghc-boot >=9.6.6,-        hashable >=1.4.4.0,-        hi-file-parser >=0.1.6.0,+        generic-deriving >=1.14.6,+        ghc-boot >=9.8.4,+        hashable >=1.4.7.0,+        hi-file-parser >=0.1.7.0,         hpack >=0.36.0,-        hpc >=0.6.2.0,-        hspec >=2.11.9,+        hpc >=0.7.0.0,+        hspec >=2.11.10,         http-client >=0.7.17,         http-client-tls >=0.3.6.2,-        http-conduit >=2.3.8.3,+        http-conduit >=2.3.9.1,         http-download >=0.2.1.0,         http-types >=0.12.4,         memory >=0.18.0,@@ -825,21 +827,21 @@         rio-prettyprint >=0.1.8.0,         split >=0.2.5,         stack,-        stm >=2.5.1.0,+        stm >=2.5.3.1,         tar >=0.6.2.0,-        template-haskell >=2.20.0.0,-        text >=2.0.2,+        template-haskell >=2.21.0.0,+        text >=2.1.1,         time >=1.12.2,         transformers >=0.6.1.0,-        unix-compat >=0.7.2,+        unix-compat >=0.7.3,         unordered-containers >=0.2.20,-        vector >=0.13.1.0,+        vector >=0.13.2.0,         yaml >=0.11.11.2,-        zlib >=0.6.3.0+        zlib >=0.7.1.0      if os(windows)         cpp-options:   -DWINDOWS-        build-depends: Win32 >=2.13.3.0+        build-depends: Win32 >=2.13.4.0      else         build-tool-depends: hsc2hs:hsc2hs
stack.yaml view
@@ -1,16 +1,8 @@-snapshot: lts-22.28 # GHC 9.6.6
-
-extra-deps:
-# lts-22.28 provides pantry-0.9.3.2.
-- pantry-0.10.0@sha256:6f99ee8d7cfeeb0e2513638618acf80c72d018e7f10120048fa120a409b9dcd2,7864
-# lts-22.28 provides tar-0.5.1.1, which does not support Unicode filenames:
-- tar-0.6.2.0@sha256:619828cae098a7b6deeb0316e12f55011101d88f756787ed024ceedb81cf1eba,4576
-# lts-22.28 provides hpack-0.36.0
-- hpack-0.37.0@sha256:b7c91b0416a55c134172a9fd9a02f3815ba68c4b92cca4e320c36906d5e970e0,5187
+snapshot: lts-23.0 # GHC 9.8.4
 
 docker:
   enable: false
-  repo: quay.io/benz0li/ghc-musl:9.6.6
+  repo: quay.io/benz0li/ghc-musl:9.8.4
 
 nix:
   # --nix on the command-line to enable.
tests/integration/lib/StackTest.hs view
@@ -362,7 +362,7 @@ -- the main @stack.yaml@.
 --
 defaultSnapshotArg :: String
-defaultSnapshotArg = "--snapshot=lts-22.28"
+defaultSnapshotArg = "--snapshot=lts-23.0"
 
 -- | Remove a file and ignore any warnings about missing files.
 removeFileIgnore :: HasCallStack => FilePath -> IO ()
tests/unit/Stack/ArgsSpec.hs view
@@ -1,4 +1,5 @@ {-# LANGUAGE NoImplicitPrelude #-}
+{-# LANGUAGE OverloadedLists   #-}
 
 -- | Args parser test suite.
 
@@ -12,8 +13,8 @@ import           Data.Attoparsec.Args ( EscapingMode (..), parseArgsFromString )
 import           Data.Attoparsec.Interpreter ( interpreterArgsParser )
 import qualified Data.Attoparsec.Text as P
+import qualified Data.List.NonEmpty as NE
 import           Data.Text ( pack )
-import           Prelude ( head )
 import           Stack.Constants ( stackProgName )
 import           Stack.Prelude
 import           Test.Hspec ( Spec, describe, it )
@@ -75,10 +76,10 @@       describe "Failure cases" $ do
         checkFailures
         describe "Bare directives in literate files" $ do
-          forM_ (interpreterGenValid lineComment []) $
-            testAndCheck (acceptFailure True) []
-          forM_ (interpreterGenValid blockComment []) $
-            testAndCheck (acceptFailure True) []
+          forM_ (interpreterGenValid lineComment "") $
+            testAndCheck (acceptFailure True) ""
+          forM_ (interpreterGenValid blockComment "") $
+            testAndCheck (acceptFailure True) ""
     where
       parse isLiterate s =
         P.parseOnly (interpreterArgsParser isLiterate stackProgName) (pack s)
@@ -115,60 +116,82 @@         (testAndCheck (acceptFailure False) "unused")
 
       -- Generate a set of acceptable inputs for given format and args
+      interpreterGenValid ::
+           (String -> NonEmpty String)
+        -> String
+        -> NonEmpty String
       interpreterGenValid fmt args = shebang <++> newLine <++> fmt args
 
-      interpreterGenInvalid :: [String]
+      interpreterGenInvalid :: NonEmpty String
       -- Generate a set of Invalid inputs
       interpreterGenInvalid =
         ["-stack\n"] -- random input
         -- just the shebang
-        <|> shebang <++> ["\n"]
+        <> shebang <++> ["\n"]
         -- invalid shebang
-        <|> blockSpace <++> [head (interpreterGenValid lineComment args)]
+        <> blockSpace <++> [NE.head (interpreterGenValid lineComment args)]
         -- something between shebang and Stack comment
-        <|> shebang
+        <> shebang
             <++> newLine
             <++> blockSpace
-            <++> ([head (lineComment args)] <|> [head (blockComment args)])
+            <++> ([NE.head (lineComment args)] <> [NE.head (blockComment args)])
         -- unterminated block comment
         -- just chop the closing chars from a valid block comment
-        <|> shebang
+        <> shebang
             <++> ["\n"]
-            <++> let c = head (blockComment args)
+            <++> let c = NE.head (blockComment args)
                      l = length c - 2
                  in  [assert (drop l c == "-}") (take l c)]
         -- nested block comment
-        <|> shebang
+        <> shebang
             <++> ["\n"]
-            <++> [head (blockComment "--x {- nested -} --y")]
+            <++> [NE.head (blockComment "--x {- nested -} --y")]
        where
         args = " --x --y"
-      (<++>) = liftA2 (++)
+      (<++>) = liftA2 (<>)
 
       -- Generative grammar for the interpreter comments
+      shebang :: NonEmpty String
       shebang = ["#!/usr/bin/env stack"]
-      newLine = ["\n"] <|> ["\r\n"]
 
+      newLine :: NonEmpty String
+      newLine = ["\n"] <> ["\r\n"]
+
       -- A comment may be the last line or followed by something else
-      postComment = [""] <|> newLine
+      postComment :: NonEmpty String
+      postComment = [""] <> newLine
 
       -- A command starts with zero or more whitespace followed by "stack"
+      makeComment ::
+           (String -> String)
+        -> NonEmpty String
+        -> String
+        -> NonEmpty String
       makeComment maker space args =
-        let makePrefix s = (s <|> [""]) <++> [stackProgName]
-        in  (maker <$> (makePrefix space <++> [args])) <++> postComment
+        let makePrefix :: NonEmpty String -> NonEmpty String
+            makePrefix s = (s <> [""]) <++> [stackProgName]
+        in  (maker <$> (makePrefix space <&> (++ args))) <++> postComment
 
-      lineSpace = [" "] <|> ["\t"]
+      lineSpace :: NonEmpty String
+      lineSpace = [" "] <> ["\t"]
+
+      lineComment :: String -> NonEmpty String
       lineComment = makeComment makeLine lineSpace
        where
         makeLine s = "--" ++ s
 
+      literateLineComment :: String -> NonEmpty String
       literateLineComment = makeComment ("> --" ++) lineSpace
 
-      blockSpace = lineSpace <|> newLine
+      blockSpace :: NonEmpty String
+      blockSpace = lineSpace <> newLine
+
+      blockComment :: String -> NonEmpty String
       blockComment = makeComment makeBlock blockSpace
        where
         makeBlock s = "{-" ++ s ++ "-}"
 
+      literateBlockComment :: String -> NonEmpty String
       literateBlockComment = makeComment
         (\s -> "> {-" ++ s ++ "-}")
-        (lineSpace <|> map (++ ">") newLine)
+        (lineSpace <> NE.map (++ ">") newLine)
tests/unit/Stack/ConfigSpec.hs view
@@ -53,12 +53,12 @@ 
 sampleConfig :: String
 sampleConfig =
-  "snapshot: lts-22.28\n" ++
+  "snapshot: lts-23.0\n" ++
   "packages: ['.']\n"
 
 buildOptsConfig :: String
 buildOptsConfig =
-  "snapshot: lts-22.28\n" ++
+  "snapshot: lts-23.0\n" ++
   "packages: ['.']\n" ++
   "build:\n" ++
   "  library-profiling: true\n" ++
@@ -104,7 +104,7 @@ 
 buildOptsHaddockForHackageConfig :: String
 buildOptsHaddockForHackageConfig =
-  "snapshot: lts-22.28\n" ++
+  "snapshot: lts-23.0\n" ++
   "packages: ['.']\n" ++
   "build:\n" ++
   "  haddock: true\n" ++
@@ -120,24 +120,24 @@ 
 hpackConfig :: String
 hpackConfig =
-  "snapshot: lts-22.28\n" ++
+  "snapshot: lts-23.0\n" ++
   "with-hpack: /usr/local/bin/hpack\n" ++
   "packages: ['.']\n"
 
 resolverConfig :: String
 resolverConfig =
-  "resolver: lts-22.28\n" ++
+  "resolver: lts-23.0\n" ++
   "packages: ['.']\n"
 
 snapshotConfig :: String
 snapshotConfig =
-  "snapshot: lts-22.28\n" ++
+  "snapshot: lts-23.0\n" ++
   "packages: ['.']\n"
 
 resolverSnapshotConfig :: String
 resolverSnapshotConfig =
-  "resolver: lts-22.28\n" ++
-  "snapshot: lts-22.28\n" ++
+  "resolver: lts-23.0\n" ++
+  "snapshot: lts-23.0\n" ++
   "packages: ['.']\n"
 
 stackDotYaml :: Path Rel File
@@ -168,7 +168,7 @@ 
   describe "parseProjectAndConfigMonoid" $ do
     let loadProject' fp inner = do
-          globalOpts <- globalOptsFromMonoid False mempty
+          globalOpts <- globalOptsFromMonoid "" Nothing False mempty
           withRunnerGlobal globalOpts { logLevel = logLevel } $ do
               iopc <- loadConfigYaml (
                 parseProjectAndConfigMonoid (parent fp)
@@ -187,11 +187,11 @@ 
     it "parses snapshot using 'resolver'" $ inTempDir $ do
       loadProject resolverConfig $ \project ->
-        project.snapshot `shouldBe` RSLSynonym (LTS 22 28)
+        project.snapshot `shouldBe` RSLSynonym (LTS 23 0)
 
     it "parses snapshot using 'snapshot'" $ inTempDir $ do
       loadProject snapshotConfig $ \project ->
-        project.snapshot `shouldBe` RSLSynonym (LTS 22 28)
+        project.snapshot `shouldBe` RSLSynonym (LTS 23 0)
 
     it "throws if both 'resolver' and 'snapshot' are present" $ inTempDir $ do
       loadProject resolverSnapshotConfig (const (pure ()))
@@ -199,7 +199,7 @@ 
   describe "loadConfig" $ do
     let loadConfig' inner = do
-          globalOpts <- globalOptsFromMonoid False mempty
+          globalOpts <- globalOptsFromMonoid "" Nothing False mempty
           withRunnerGlobal globalOpts { logLevel = logLevel } $
             loadConfig inner
     -- TODO(danburton): make sure parent dirs also don't have config file
@@ -255,14 +255,14 @@           { rerunTests = True
           , additionalArgs = ["-fprof"]
           , coverage = True
-          , disableRun = True
+          , runTests = False
           , maximumTimeSeconds = Nothing
           , allowStdin = True
           }
         bopts.benchmarks `shouldBe` True
         bopts.benchmarkOpts `shouldBe` BenchmarkOpts
            { additionalArgs = Just "-O2"
-           , disableRun = True
+           , runBenchmarks = False
            }
         bopts.reconfigure `shouldBe` True
         bopts.cabalVerbose `shouldBe` CabalVerbosity verbose
@@ -314,7 +314,7 @@             packageYaml =
               childRel </> either impureThrow id (parseRelFile "package.yaml")
         createDirectoryIfMissing True $ toFilePath $ parent yamlAbs
-        writeFile (toFilePath yamlAbs) "snapshot: ghc-9.6.6"
+        writeFile (toFilePath yamlAbs) "snapshot: ghc-9.8.4"
         writeFile (toFilePath packageYaml) "name: foo"
         withEnvVar "STACK_YAML" (toFilePath yamlRel) $
           loadConfig' $ \config -> liftIO $ do
tests/unit/Stack/NixSpec.hs view
@@ -53,7 +53,8 @@ spec = beforeAll setup $ do
   let loadConfig' :: ConfigMonoid -> (Config -> IO ()) -> IO ()
       loadConfig' cmdLineArgs inner = do
-        globalOpts <- globalOptsFromMonoid False mempty { configMonoid = cmdLineArgs }
+        globalOpts <-
+          globalOptsFromMonoid "" Nothing False mempty { configMonoid = cmdLineArgs }
         withRunnerGlobal globalOpts { GlobalOpts.logLevel = LevelOther "silent" } $
           loadConfig (liftIO . inner)
       inTempDir test = do