stack 3.5.1 → 3.7.1

raw patch · 255 files changed

+5072/−2361 lines, 255 filesdep ~cryptondep ~hspecdep ~http-clientsetup-changed

Dependency ranges changed: crypton, hspec, http-client, mustache, open-browser, pantry, persistent, rio, unix-compat

Files

• CONTRIBUTING.md +7/−3
• ChangeLog.md +93/−60
• LICENSE +798/−0
• README.md +1/−1
• Setup.hs +10/−3
• cabal.config +32/−21
• cabal.project +1/−1
• doc/CONTRIBUTING.md +7/−3
• doc/ChangeLog.md +93/−60
• doc/commands/ghci_command.md +1/−1
• doc/commands/list_command.md +5/−5
• doc/commands/script_command.md +72/−17
• doc/commands/setup_command.md +19/−0
• doc/configure/yaml/non-project.md +2/−2
• doc/configure/yaml/project.md +2/−2
• doc/maintainers/archive/docker.md +180/−0
• doc/maintainers/archive/docker_images.md +34/−0
• doc/maintainers/docker.md +0/−180
• doc/maintainers/docker_images.md +0/−34
• doc/maintainers/haskellstack.org.md +12/−6
• doc/maintainers/stack_errors.md +22/−23
• doc/topics/Stack_and_VS_Code.md +1/−1
• doc/topics/custom_snapshot.md +11/−11
• doc/topics/haskell_and_c_code.md +2/−2
• doc/topics/package_location.md +1/−1
• doc/topics/scripts.md +31/−11
• doc/topics/stack_yaml_vs_cabal_package_file.md +3/−3
• doc/tutorial/building_your_project.md +1/−1
• doc/tutorial/index.md +166/−22
• doc/tutorial/project_configuration.md +2/−2
• src/Control/Concurrent/Execute.hs +12/−5
• src/Data/Attoparsec/Args.hs +8/−1
• src/Data/Attoparsec/Combinators.hs +8/−1
• src/Data/Attoparsec/Interpreter.hs +31/−26
• src/Data/Monoid/Map.hs +5/−0
• src/GHC/Utils/GhcPkg/Main/Compat.hs +30/−124
• src/Network/HTTP/StackClient.hs +17/−9
• src/Options/Applicative/Args.hs +7/−1
• src/Options/Applicative/Builder/Extra.hs +10/−4
• src/Options/Applicative/Complicated.hs +12/−7
• src/Path/CheckInstall.hs +5/−0
• src/Path/Extended.hs +0/−26
• src/Path/Extra.hs +31/−13
• src/Path/Find.hs +7/−1
• src/Stack.hs +8/−1
• src/Stack/Build.hs +81/−77
• src/Stack/Build/Cache.hs +11/−3
• src/Stack/Build/ConstructPlan.hs +22/−15
• src/Stack/Build/Execute.hs +32/−41
• src/Stack/Build/ExecuteEnv.hs +24/−33
• src/Stack/Build/ExecutePackage.hs +63/−40
• src/Stack/Build/Haddock.hs +8/−1
• src/Stack/Build/Installed.hs +11/−1
• src/Stack/Build/Source.hs +23/−11
• src/Stack/Build/Target.hs +59/−48
• src/Stack/BuildInfo.hs +9/−2
• src/Stack/BuildOpts.hs +8/−1
• src/Stack/BuildPlan.hs +19/−11
• src/Stack/CLI.hs +27/−51
• src/Stack/Clean.hs +8/−1
• src/Stack/Component.hs +16/−9
• src/Stack/ComponentFile.hs +36/−2
• src/Stack/Config.hs +44/−45
• src/Stack/Config/Build.hs +8/−1
• src/Stack/Config/ConfigureScript.hs +7/−0
• src/Stack/Config/Docker.hs +8/−1
• src/Stack/Config/Nix.hs +10/−2
• src/Stack/ConfigCmd.hs +19/−162
• src/Stack/Constants.hs +8/−2
• src/Stack/Constants/Config.hs +5/−0
• src/Stack/Constants/StackProgName.hs +8/−3
• src/Stack/Coverage.hs +37/−45
• src/Stack/DefaultColorWhen.hs +5/−0
• src/Stack/DependencyGraph.hs +8/−2
• src/Stack/Docker.hs +10/−3
• src/Stack/DockerCmd.hs +9/−1
• src/Stack/Dot.hs +8/−1
• src/Stack/Eval.hs +9/−2
• src/Stack/Exec.hs +18/−5
• src/Stack/FileWatch.hs +5/−0
• src/Stack/GhcPkg.hs +27/−9
• src/Stack/Ghci.hs +58/−60
• src/Stack/Ghci/Script.hs +5/−0
• src/Stack/Hoogle.hs +8/−1
• src/Stack/IDE.hs +9/−16
• src/Stack/Init.hs +11/−4
• src/Stack/List.hs +9/−2
• src/Stack/Lock.hs +12/−2
• src/Stack/Ls.hs +19/−87
• src/Stack/New.hs +9/−2
• src/Stack/Nix.hs +11/−2
• src/Stack/Options/BenchParser.hs +8/−0
• src/Stack/Options/BuildMonoidParser.hs +9/−3
• src/Stack/Options/BuildParser.hs +11/−23
• src/Stack/Options/CleanParser.hs +5/−0
• src/Stack/Options/Completion.hs +12/−0
• src/Stack/Options/ConfigEnvParser.hs +29/−0
• src/Stack/Options/ConfigParser.hs +5/−0
• src/Stack/Options/ConfigSetParser.hs +143/−0
• src/Stack/Options/DockerParser.hs +5/−0
• src/Stack/Options/DotParser.hs +9/−3
• src/Stack/Options/EvalParser.hs +7/−1
• src/Stack/Options/ExecParser.hs +8/−2
• src/Stack/Options/FlagsParser.hs +37/−0
• src/Stack/Options/GhcBuildParser.hs +5/−0
• src/Stack/Options/GhcVariantParser.hs +5/−0
• src/Stack/Options/GhciParser.hs +13/−6
• src/Stack/Options/GlobalParser.hs +8/−1
• src/Stack/Options/HaddockParser.hs +5/−0
• src/Stack/Options/HpcReportParser.hs +10/−23
• src/Stack/Options/IdeParser.hs +64/−0
• src/Stack/Options/InitParser.hs +8/−2
• src/Stack/Options/LogLevelParser.hs +5/−0
• src/Stack/Options/LsParser.hs +11/−4
• src/Stack/Options/NewParser.hs +5/−0
• src/Stack/Options/NixParser.hs +9/−0
• src/Stack/Options/PackageParser.hs +5/−0
• src/Stack/Options/PackagesParser.hs +27/−0
• src/Stack/Options/PathParser.hs +8/−1
• src/Stack/Options/PvpBoundsParser.hs +46/−0
• src/Stack/Options/SDistParser.hs +12/−6
• src/Stack/Options/ScriptParser.hs +14/−9
• src/Stack/Options/SetupParser.hs +9/−2
• src/Stack/Options/SnapshotParser.hs +5/−0
• src/Stack/Options/TestParser.hs +5/−0
• src/Stack/Options/UnpackParser.hs +8/−1
• src/Stack/Options/UpgradeParser.hs +9/−2
• src/Stack/Options/UploadParser.hs +13/−22
• src/Stack/Options/Utils.hs +5/−0
• src/Stack/Package.hs +19/−12
• src/Stack/PackageDump.hs +8/−3
• src/Stack/PackageFile.hs +18/−1
• src/Stack/Path.hs +21/−8
• src/Stack/Prelude.hs +13/−5
• src/Stack/Query.hs +8/−1
• src/Stack/Runners.hs +17/−12
• src/Stack/SDist.hs +12/−17
• src/Stack/Script.hs +42/−12
• src/Stack/Setup.hs +49/−163
• src/Stack/Setup/Installed.hs +6/−1
• src/Stack/SetupCmd.hs +10/−13
• src/Stack/SourceMap.hs +36/−26
• src/Stack/Storage/Project.hs +15/−6
• src/Stack/Storage/User.hs +13/−5
• src/Stack/Storage/Util.hs +8/−1
• src/Stack/Templates.hs +8/−1
• src/Stack/Types/AddCommand.hs +11/−0
• src/Stack/Types/AllowNewerDeps.hs +10/−11
• src/Stack/Types/ApplyGhcOptions.hs +5/−0
• src/Stack/Types/ApplyProgOptions.hs +5/−0
• src/Stack/Types/Build.hs +11/−1
• src/Stack/Types/Build/ConstructPlan.hs +10/−3
• src/Stack/Types/Build/Exception.hs +8/−4
• src/Stack/Types/BuildConfig.hs +5/−0
• src/Stack/Types/BuildOpts.hs +8/−1
• src/Stack/Types/BuildOptsCLI.hs +8/−1
• src/Stack/Types/BuildOptsMonoid.hs +9/−2
• src/Stack/Types/CabalConfigKey.hs +5/−0
• src/Stack/Types/Cache.hs +7/−0
• src/Stack/Types/Casa.hs +7/−1
• src/Stack/Types/ColorWhen.hs +5/−0
• src/Stack/Types/CompCollection.hs +17/−13
• src/Stack/Types/Compiler.hs +5/−0
• src/Stack/Types/CompilerBuild.hs +5/−0
• src/Stack/Types/CompilerPaths.hs +6/−1
• src/Stack/Types/Component.hs +10/−3
• src/Stack/Types/ComponentUtils.hs +8/−2
• src/Stack/Types/Config.hs +6/−1
• src/Stack/Types/Config/Exception.hs +7/−0
• src/Stack/Types/ConfigMonoid.hs +51/−46
• src/Stack/Types/ConfigSetOpts.hs +46/−0
• src/Stack/Types/ConfigureOpts.hs +10/−8
• src/Stack/Types/Curator.hs +9/−3
• src/Stack/Types/Dependency.hs +5/−0
• src/Stack/Types/DependencyTree.hs +5/−0
• src/Stack/Types/Docker.hs +17/−10
• src/Stack/Types/DockerEntrypoint.hs +5/−0
• src/Stack/Types/DotConfig.hs +6/−0
• src/Stack/Types/DotOpts.hs +8/−2
• src/Stack/Types/DownloadInfo.hs +6/−1
• src/Stack/Types/DumpLogs.hs +5/−0
• src/Stack/Types/DumpPackage.hs +6/−1
• src/Stack/Types/EnvConfig.hs +10/−9
• src/Stack/Types/EnvSettings.hs +12/−4
• src/Stack/Types/ExtraDirs.hs +5/−0
• src/Stack/Types/FileDigestCache.hs +5/−0
• src/Stack/Types/GHCDownloadInfo.hs +5/−0
• src/Stack/Types/GHCVariant.hs +5/−0
• src/Stack/Types/GhcOptionKey.hs +12/−0
• src/Stack/Types/GhcOptions.hs +6/−0
• src/Stack/Types/GhcPkgExe.hs +135/−0
• src/Stack/Types/GhcPkgId.hs +7/−1
• src/Stack/Types/GhciOpts.hs +35/−0
• src/Stack/Types/GlobalOpts.hs +8/−1
• src/Stack/Types/GlobalOptsMonoid.hs +7/−2
• src/Stack/Types/HpcReportOpts.hs +25/−0
• src/Stack/Types/IdeOpts.hs +30/−0
• src/Stack/Types/Installed.hs +8/−2
• src/Stack/Types/InterfaceOpt.hs +8/−1
• src/Stack/Types/IsMutable.hs +5/−0
• src/Stack/Types/LockFileBehavior.hs +5/−0
• src/Stack/Types/LsOpts.hs +105/−0
• src/Stack/Types/MsysEnvironment.hs +8/−1
• src/Stack/Types/NamedComponent.hs +9/−2
• src/Stack/Types/Nix.hs +9/−2
• src/Stack/Types/Package.hs +9/−4
• src/Stack/Types/PackageFile.hs +11/−4
• src/Stack/Types/PackageName.hs +7/−1
• src/Stack/Types/ParentMap.hs +8/−1
• src/Stack/Types/Platform.hs +5/−0
• src/Stack/Types/Project.hs +5/−0
• src/Stack/Types/ProjectAndConfigMonoid.hs +5/−0
• src/Stack/Types/ProjectConfig.hs +12/−5
• src/Stack/Types/PvpBounds.hs +5/−0
• src/Stack/Types/Runner.hs +15/−10
• src/Stack/Types/SCM.hs +5/−0
• src/Stack/Types/SDistOpts.hs +31/−0
• src/Stack/Types/SetupInfo.hs +4/−0
• src/Stack/Types/SetupOpts.hs +25/−0
• src/Stack/Types/Snapshot.hs +5/−0
• src/Stack/Types/SourceMap.hs +23/−13
• src/Stack/Types/StackYamlLoc.hs +6/−1
• src/Stack/Types/Storage.hs +8/−1
• src/Stack/Types/TemplateName.hs +8/−1
• src/Stack/Types/UnusedFlags.hs +5/−0
• src/Stack/Types/UpgradeOpts.hs +46/−0
• src/Stack/Types/UploadOpts.hs +8/−1
• src/Stack/Types/Version.hs +8/−1
• src/Stack/Types/VersionedDownloadInfo.hs +5/−0
• src/Stack/Types/WantedCompilerSetter.hs +5/−0
• src/Stack/Uninstall.hs +8/−1
• src/Stack/Unpack.hs +8/−1
• src/Stack/Update.hs +8/−1
• src/Stack/Upgrade.hs +11/−34
• src/Stack/Upload.hs +26/−9
• src/System/Process/Pager.hs +8/−1
• src/unix/Stack/Constants/UsrLibDirs.hs +8/−2
• src/unix/Stack/Docker/Handlers.hs +8/−2
• src/unix/System/Info/ShortPathName.hs +8/−2
• src/unix/System/Permissions.hs +8/−2
• src/unix/System/Terminal.hsc +10/−7
• src/unix/System/Uname.hsc +8/−2
• src/windows/Stack/Constants/UsrLibDirs.hs +8/−2
• src/windows/Stack/Docker/Handlers.hs +8/−2
• src/windows/System/Info/ShortPathName.hs +8/−2
• src/windows/System/Permissions.hs +8/−2
• src/windows/System/Posix/User.hs +8/−3
• src/windows/System/Terminal.hs +10/−54
• src/windows/System/Uname.hs +8/−2
• stack.cabal +49/−34
• stack.yaml +10/−3
• tests/integration/IntegrationSpec.hs +24/−12
• tests/integration/lib/StackTest.hs +6/−88
• tests/integration/lib/StackTest/Repl.hs +135/−0
• tests/unit/Stack/ConfigSpec.hs +10/−10

@@ -348,9 +348,9 @@ 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 (March 2025) the package versions are
-primarily ones in Stackage snapshot LTS Haskell 23.14 (for GHC 9.8.4) and
-`hpack-0.38.0`.
+any time. At the time of writing (June 2025) the package versions are
+primarily ones in Stackage snapshot LTS Haskell 23.24 (for GHC 9.8.4) and
+`hpack-0.38.1`, `persistent-2.17.0.0` and `tls-2.1.8`.
 
 A Stack executable makes use of Cabal (the library) through a small 'Setup'
 executable that it compiles from Haskell source code. The executable compiles
@@ -581,6 +581,10 @@ 
 To disable folders named after `<PATTERN1>` and `<PATTERN2>`
 It's especially useful when some tests are taking a while to complete.
+
+On Linux, the `stack-integration-test` executable uses the `lld` linker and
+expects it to be on the PATH. The integration tests complete significantly
+quicker with `lld` than with the `ld.bfd` linker.
 
 ## Continuous integration (CI)
 

@@ -1,5 +1,32 @@ # Changelog
 
+## v3.7.1 - 2025-06-28
+
+**Changes since v3.5.1:**
+
+Other enhancements:
+
+* Bump to Hpack 0.38.1.
+* The `--extra-dep` option of Stack's `script` command now accepts a YAML value
+  specifying any immutable extra-dep. Previously only an extra-dep in the
+  package index that could be specified by a YAML string (for example,
+  `acme-missiles-0.3@rev:0`) was accepted.
+
+Bug fixes:
+
+* `stack script --package <pkg-name>` now uses GHC's `-package-id` option to
+  expose the installed package, rather than GHC's `-package` option. For
+  packages with public sub-libraries, `-package <pkg>` can expose an
+  installed package other than one listed by `ghc-pkg list <pkg>`.
+* Work around `ghc-pkg` bug where, on Windows only, it cannot register a package
+  into a package database that is also listed in the `GHC_PACKAGE_PATH`
+  environment variable. In previous versions of Stack, this affected
+  `stack script` when copying a pre-compiled package from another package
+  database.
+* On Windows, when decompressing, and extracting tools, from archive files,
+  Stack uses the system temporary directory, rather than the root of the
+  destination drive, if the former is on the destination drive.
+
 ## v3.5.1 - 2025-03-29
 
 **Changes since v3.3.1:**
@@ -342,9 +369,9 @@ Release notes:
 
 * Further to the release notes for Stack 2.3.1, the `-static` suffix has been
-  removed from the statically linked Linux/x86_64 binaries.
-* The binaries for Linux/Aarch64 are now statically linked.
-* Binaries are now provided for macOS/AArch64.
+  removed from the statically-linked Linux/x86_64 executables.
+* The executables for Linux/Aarch64 are now statically-linked.
+* Executables are now provided for macOS/AArch64.
 
 **Changes since v2.11.1:**
 
@@ -566,11 +593,11 @@ 
 * After an upgrade from an earlier version of Stack, on first use only,
   Stack 2.9.1 may warn that it had trouble loading the CompilerPaths cache.
-* The support from the Stack team for binary releases now includes Linux/AArch64
-  and is limited to:
+* The support from the Stack team for executable releases now includes
+  Linux/AArch64 and is limited to:
 
-    * Linux 64-bit/x86_64 (statically linked)
-    * Linux AArch64 (dynamically linked)
+    * Linux 64-bit/x86_64 (statically-linked)
+    * Linux AArch64 (dynamically-linked)
     * macOS x86_64
     * Windows 64-bit/x86_64
 
@@ -645,7 +672,7 @@ 
 Other enhancements:
 
-* `stack setup` supports installing GHC for macOS aarch64 (M1)
+* `stack setup` supports installing GHC for macOS/AArch64 (M1)
 * `stack upload` supports authentication with a Hackage API key (via
   `HACKAGE_KEY` environment variable).
 
@@ -815,26 +842,27 @@ 
 Release notes:
 
-* We have reduced the number of platforms that we support with binary releases.
-  The reason behind this is that we've been slowed down in our release process
-  until now with issues trying to build binaries for less common platforms. In
-  order to make sure we can address issues more quickly (like supporting new GHC
-  versions), we're limiting support from the Stack team to:
+* We have reduced the number of platforms that we support with executable
+  releases. The reason behind this is that we've been slowed down in our release
+  process until now with issues trying to build executables for less common
+  platforms. In order to make sure we can address issues more quickly (like
+  supporting new GHC versions), we're limiting support from the Stack team to:
 
-    * Linux 64-bit/x86_64 (statically linked)
+    * Linux 64-bit/x86_64 (statically-linked)
     * macOS x86_64
     * Windows 64-bit/x86_64
 
-  If others want to provide additional binaries, we will definitely be happy for
-  the support. But since our CI system is currently able to produce these three
-  bindists only, that's what we will be providing with the next release.
+  If others want to provide additional executables, we will definitely be happy
+  for the support. But since our CI system is currently able to produce these
+  three executables only, that's what we will be providing with the next
+  release.
 
-* Since we no longer have dynamically linked Linux binaries, we are removing the
-  `-static` suffix from the static Linux/x86_64 binaries. If you have scripts to
-  download the latest stable Linux/x86_64 binary, update them to use
-  `linux-x86_64` instead of `linux-x86_64-static` (if you are already using the
-  former, nothing needs to change). For this release, both are supported, but
-  the next release will no longer have the `-static` variant.
+* Since we no longer have dynamically-linked Linux executables, we are removing
+  the `-static` suffix from the static Linux/x86_64 executables. If you have
+  scripts to download the latest stable Linux/x86_64 executable, update them to
+  use `linux-x86_64` instead of `linux-x86_64-static` (if you are already using
+  the former, nothing needs to change). For this release, both are supported,
+  but the next release will no longer have the `-static` variant.
 
 * We are also deprecating the download links at https://stackage.org/stack. See
   this page for the current installation instructions:
@@ -1308,7 +1336,7 @@ * Help text for the `templates` subcommand now reflects behaviour in Stack 1.9
   — that it downloads and shows a help file, rather than listing available
   templates.
-* Fix detection of aarch64 platform (this broke when we upgraded to a newer
+* Fix detection of AArch64 platform (this broke when we upgraded to a newer
   Cabal version).
 * Docker: fix detecting and pulling missing images with `--docker-auto-pull`.
   See
@@ -1362,7 +1390,7 @@ 
 Release notes:
 
-* Statically linked Linux bindists are back again, thanks to
+* Statically-linked Linux executables are back again, thanks to
   [@nh2](https://github.com/nh2).
 * We will be deleting the Ubuntu, Debian, CentOS, Fedora, and Arch package repos
   from `download.fpcomplete.com` soon. These have been deprecated for over a
@@ -1530,10 +1558,10 @@ 
 Release notes:
 
-* aarch64 (64-bit ARM) bindists are now available for the first time.
-* Statically linked Linux bindists are no longer available, due to difficulty
+* AArch64 (64-bit ARM) executables are now available for the first time.
+* Statically-linked Linux executables are no longer available, due to difficulty
   with GHC 8.2.2 on Alpine Linux.
-* 32-bit Linux GMP4 bindists for CentOS 6 are no longer available, since
+* 32-bit Linux GMP4 executables for CentOS 6 are no longer available, since
   GHC 8.2.2 is no longer being built for that platform.
 
 Major changes:
@@ -1560,8 +1588,8 @@   for details.
 * Specify User-Agent HTTP request header on every HTTP request.
   See [#3628](https://github.com/commercialhaskell/stack/issues/3628) for details.
-* `stack setup` looks for GHC bindists and installations by any OS key
-  that is compatible (rather than only checking a single one).   This is
+* `stack setup` looks for GHC binary distributions and installations by any OS
+  key that is compatible (rather than only checking a single one). This is
   relevant on Linux where different distributions may have different
   combinations of libtinfo 5/6, ncurses 5/6, and gmp 4/5, and will allow
   simplifying the setup-info metadata YAML for future GHC releases.
@@ -1673,7 +1701,8 @@   cases where HTTP servers mistakenly set the transfer encoding to `gzip`. See
   [#3647](https://github.com/commercialhaskell/stack/issues/3647).
 * Links to docs.haskellstack.org ignore Stack version patchlevel.
-* Downloading Docker-compatible `stack` binary ignores Stack version patchlevel.
+* Downloading Docker-compatible `stack` executable ignores Stack version
+  patchlevel.
 
 Bug fixes:
 
@@ -1828,8 +1857,8 @@ * Automatically run `autoreconf -i` as necessary when a `configure`
   script is missing. See
   [#3534](https://github.com/commercialhaskell/stack/issues/3534)
-* GHC bindists can now be identified by their SHA256 checksum in addition to
-  their SHA1 checksum, allowing for more security in download.
+* GHC binary distributions can now be identified by their SHA256 checksum in
+  addition to their SHA1 checksum, allowing for more security in download.
 * For filesystem setup-info paths, it's no longer assumed that the
   directory is writable, instead a temp dir is used.  See
   [#3188](https://github.com/commercialhaskell/stack/issues/3188).
@@ -2131,7 +2160,7 @@ 
 * `stack config set` can now be used without a compiler installed
   [#2852](https://github.com/commercialhaskell/stack/issues/2852).
-* `get-stack.sh` now installs correct binary on ARM for generic linux and
+* `get-stack.sh` now installs correct executable on ARM for generic Linux and
   raspbian, closing
   [#2856](https://github.com/commercialhaskell/stack/issues/2856).
 * Correct the testing of whether a package database exists by checking
@@ -2150,17 +2179,15 @@ 
 Release notes:
 
-* For the _next_ Stack release after this one, we are planning
-  changes to our Linux releases, including dropping our Ubuntu,
-  Debian, CentOS, and Fedora package repositories and switching to
-  statically linked binaries. See
+* For the _next_ Stack release after this one, we are planning changes to our
+  Linux releases, including dropping our Ubuntu, Debian, CentOS, and Fedora
+  package repositories and switching to statically-linked executables. See
   [#2534](https://github.com/commercialhaskell/stack/issues/2534).
-  Note that upgrading without a package manager has gotten easier
-  with new binary upgrade support in `stack upgrade` (see the Major
-  Changes section below for more information). In addition, the
-  get.haskellstack.org script no longer installs from Ubuntu,
-  Debian, CentOS, or Fedora package repositories. Instead it places
-  a generic binary in /usr/local/bin.
+  Note that upgrading without a package manager has gotten easier with new
+  binary upgrade support in `stack upgrade` (see the Major Changes section below
+  for more information). In addition, the get.haskellstack.org script no longer
+  installs from Ubuntu, Debian, CentOS, or Fedora package repositories. Instead
+  it places a generic executable in /usr/local/bin.
 
 Major changes:
 
@@ -2181,11 +2208,10 @@   because it should no longer be necessary. See
   [#1364](https://github.com/commercialhaskell/stack/issues/1364)
 
-* Stack is now capable of doing binary upgrades instead of always
-  recompiling a new version from source. Running `stack upgrade` will
-  now default to downloading a binary version of Stack from the most
-  recent release, if one is available. See `stack upgrade --help` for
-  more options.
+* Stack is now capable of doing binary upgrades instead of always recompiling a
+  new version from source. Running `stack upgrade` will now default to
+  downloading a Stack executable from the most recent release, if one is
+  available. See `stack upgrade --help` for more options.
   [#1238](https://github.com/commercialhaskell/stack/issues/1238)
 
 Behavior changes:
@@ -2321,13 +2347,16 @@   [store#37](https://github.com/fpco/store/issues/37)).  Please stay with
   version 1.1.2 for now on those architectures.  This will be rectified soon!
 
-* We are now releasing a statically linked Stack binary for
+* We are now releasing a statically-linked Stack executable for
   [64-bit Linux](https://get.haskellstack.org/stable/linux-x86_64-static.tar.gz).
   Please try it and let us know if you run into any trouble on your platform.
+  The executable is linked against a version of the GNU Multiple Precision
+  Arithmetic Library (GMP), which is licensed under the GNU Lesser General
+  Public License, Version 3, 29 June 2007 (LGPL).
 
 * We are planning some changes to our Linux releases, including dropping our
   Ubuntu, Debian, CentOS, and Fedora package repositories and switching to
-  statically linked binaries.  We would value your feedback in
+  statically-linked executables. We would value your feedback in
   [#2534](https://github.com/commercialhaskell/stack/issues/2534).
 
 Major changes:
@@ -2348,9 +2377,10 @@ * Support -ferror-spans syntax in GHC error messages.
 * Avoid unpacking ghc to `/tmp`
   [#996](https://github.com/commercialhaskell/stack/issues/996)
-* The Linux `gmp4` GHC bindist is no longer considered a full-fledged GHC
-  variant and can no longer be specified using the `ghc-variant` option,
-  and instead is treated more like a slightly different platform.
+* The Linux `gmp4` GHC binary distribution is no longer considered a
+  full-fledged GHC variant and can no longer be specified using the
+  `ghc-variant` option, and instead is treated more like a slightly different
+  platform.
 
 Other enhancements:
 
@@ -2377,9 +2407,11 @@ * `stack setup` no longer unpacks to the system temp dir on posix systems.
   [#996](https://github.com/commercialhaskell/stack/issues/996)
 * `stack setup` detects libtinfo6 and ncurses6 and can download alternate GHC
-  bindists [#257](https://github.com/commercialhaskell/stack/issues/257)
+  binary distributions
+  [#257](https://github.com/commercialhaskell/stack/issues/257)
   [#2302](https://github.com/commercialhaskell/stack/issues/2302).
-* `stack setup` detects Linux ARMv7 downloads appropriate GHC bindist
+* `stack setup` detects Linux ARMv7 downloads appropriate GHC binary
+  distribution
   [#2103](https://github.com/commercialhaskell/stack/issues/2103)
 * Custom `stack` binaries list dependency versions in output for `--version`.
   See [#2222](https://github.com/commercialhaskell/stack/issues/2222)
@@ -3123,8 +3155,8 @@     * `setup-info` in `stack.yaml`, to specify where to download custom binary
       distributions (also `--ghc-bindist` command-line option)
     * Note: On systems with libgmp4 (aka `libgmp.so.3`), such as CentOS 6, you
-      may need to re-run `stack setup` due to the centos6 GHC bindist being
-      treated like a variant
+      may need to re-run `stack setup` due to the centos6 GHC binary
+      distribution being treated like a variant
 * A new `--pvp-bounds` flag to the sdist and upload commands allows automatic
   adding of PVP upper and/or lower bounds to your dependencies
 
@@ -3322,8 +3354,9 @@   [#452](https://github.com/commercialhaskell/stack/issues/452)
 * Don't copy over executables excluded by component selection
   [#605](https://github.com/commercialhaskell/stack/issues/605)
-* Fix: Stack fails on Windows with git package in `stack.yaml` and no git binary
-  on path [#712](https://github.com/commercialhaskell/stack/issues/712)
+* Fix: Stack fails on Windows with git package in `stack.yaml` and no git
+  executable on the PATH
+  [#712](https://github.com/commercialhaskell/stack/issues/712)
 * Fixed GHCi issue: Specifying explicit package versions (#678)
 * Fixed GHCi issue: Specifying -odir and -hidir as .stack-work/odir (#529)
 * Fixed GHCi issue: Specifying A instead of A.ext for modules (#498)

@@ -1,3 +1,6 @@+Stack
+=====
+
 Copyright (c) 2015-2025, Stack contributors. All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification,
@@ -24,3 +27,798 @@ LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
 OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+--------------------------------------------------------------------------------
+
+The GNU Multiple Precision Arithmetic Library (GMP)
+===================================================
+
+Stack executables for Linux distributed under Releases at Stack's GitHub
+repository (https://github.com/commercialhaskell/stack) may be statically-linked
+(as indicted there or in Stack's Change Log) and may be linked against a version
+of GMP, which is licensed under the GNU Lesser General Public License,
+Version 3, 29 June 2007 (LGPL).
+
+In accordance with the LGPL, the full source code of Stack is provided at the
+same GitHub repository, allowing you to modify and relink the GMP portion, if
+desired.
+
+GMP source code is available at: https://gmplib.org/
+
+A copy of the LGPL is reproduced below.
+
+
+
+GNU LESSER GENERAL PUBLIC LICENSE
+=================================
+
+Version 3, 29 June 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+
+Everyone is permitted to copy and distribute verbatim copies of this license
+document, but changing it is not allowed.
+
+This version of the GNU Lesser General Public License incorporates the terms and
+conditions of version 3 of the GNU General Public License, supplemented by the
+additional permissions listed below.
+
+## 0. Additional Definitions.
+
+As used herein, "this License" refers to version 3 of the GNU Lesser General
+Public License, and the "GNU GPL" refers to version 3 of the GNU General Public
+License.
+
+"The Library" refers to a covered work governed by this License, other than an
+Application or a Combined Work as defined below.
+
+An "Application" is any work that makes use of an interface provided by the
+Library, but which is not otherwise based on the Library. Defining a subclass of
+a class defined by the Library is deemed a mode of using an interface provided
+by the Library.
+
+A "Combined Work" is a work produced by combining or linking an Application with
+the Library. The particular version of the Library with which the Combined Work
+was made is also called the "Linked Version".
+
+The "Minimal Corresponding Source" for a Combined Work means the Corresponding
+Source for the Combined Work, excluding any source code for portions of the
+Combined Work that, considered in isolation, are based on the Application, and
+not on the Linked Version.
+
+The "Corresponding Application Code" for a Combined Work means the object code
+and/or source code for the Application, including any data and utility programs
+needed for reproducing the Combined Work from the Application, but excluding the
+System Libraries of the Combined Work.
+
+## 1. Exception to Section 3 of the GNU GPL.
+
+You may convey a covered work under sections 3 and 4 of this License without
+being bound by section 3 of the GNU GPL.
+
+## 2. Conveying Modified Versions.
+
+If you modify a copy of the Library, and, in your modifications, a facility
+refers to a function or data to be supplied by an Application that uses the
+facility (other than as an argument passed when the facility is invoked), then
+you may convey a copy of the modified version:
+
+-   a) under this License, provided that you make a good faith effort to ensure
+    that, in the event an Application does not supply the function or data, the
+    facility still operates, and performs whatever part of its purpose remains
+    meaningful, or
+-   b) under the GNU GPL, with none of the additional permissions of this
+    License applicable to that copy.
+
+## 3. Object Code Incorporating Material from Library Header Files.
+
+The object code form of an Application may incorporate material from a header
+file that is part of the Library. You may convey such object code under terms of
+your choice, provided that, if the incorporated material is not limited to
+numerical parameters, data structure layouts and accessors, or small macros,
+inline functions and templates (ten or fewer lines in length), you do both of
+the following:
+
+-   a) Give prominent notice with each copy of the object code that the Library
+    is used in it and that the Library and its use are covered by this License.
+-   b) Accompany the object code with a copy of the GNU GPL and this license
+    document.
+
+## 4. Combined Works.
+
+You may convey a Combined Work under terms of your choice that, taken together,
+effectively do not restrict modification of the portions of the Library
+contained in the Combined Work and reverse engineering for debugging such
+modifications, if you also do each of the following:
+
+-   a) Give prominent notice with each copy of the Combined Work that the
+    Library is used in it and that the Library and its use are covered by this
+    License.
+-   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+    document.
+-   c) For a Combined Work that displays copyright notices during execution,
+    include the copyright notice for the Library among these notices, as well as
+    a reference directing the user to the copies of the GNU GPL and this license
+    document.
+-   d) Do one of the following:
+    -   0) Convey the Minimal Corresponding Source under the terms of this
+        License, and the Corresponding Application Code in a form suitable for,
+        and under terms that permit, the user to recombine or relink the
+        Application with a modified version of the Linked Version to produce a
+        modified Combined Work, in the manner specified by section 6 of the GNU
+        GPL for conveying Corresponding Source.
+    -   1) Use a suitable shared library mechanism for linking with the Library.
+        A suitable mechanism is one that (a) uses at run time a copy of the
+        Library already present on the user's computer system, and (b) will
+        operate properly with a modified version of the Library that is
+        interface-compatible with the Linked Version.
+-   e) Provide Installation Information, but only if you would otherwise be
+    required to provide such information under section 6 of the GNU GPL, and
+    only to the extent that such information is necessary to install and execute
+    a modified version of the Combined Work produced by recombining or relinking
+    the Application with a modified version of the Linked Version. (If you use
+    option 4d0, the Installation Information must accompany the Minimal
+    Corresponding Source and Corresponding Application Code. If you use option
+    4d1, you must provide the Installation Information in the manner specified
+    by section 6 of the GNU GPL for conveying Corresponding Source.)
+
+## 5. Combined Libraries.
+
+You may place library facilities that are a work based on the Library side by
+side in a single library together with other library facilities that are not
+Applications and are not covered by this License, and convey such a combined
+library under terms of your choice, if you do both of the following:
+
+-   a) Accompany the combined library with a copy of the same work based on the
+    Library, uncombined with any other library facilities, conveyed under the
+    terms of this License.
+-   b) Give prominent notice with the combined library that part of it is a work
+    based on the Library, and explaining where to find the accompanying
+    uncombined form of the same work.
+
+## 6. Revised Versions of the GNU Lesser General Public License.
+
+The Free Software Foundation may publish revised and/or new versions of the GNU
+Lesser General Public License from time to time. Such new versions will be
+similar in spirit to the present version, but may differ in detail to address
+new problems or concerns.
+
+Each version is given a distinguishing version number. If the Library as you
+received it specifies that a certain numbered version of the GNU Lesser General
+Public License "or any later version" applies to it, you have the option of
+following the terms and conditions either of that published version or of any
+later version published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser General Public
+License, you may choose any version of the GNU Lesser General Public License
+ever published by the Free Software Foundation.
+
+If the Library as you received it specifies that a proxy can decide whether
+future versions of the GNU Lesser General Public License shall apply, that
+proxy's public statement of acceptance of any version is permanent authorization
+for you to choose that version for the Library.
+
+
+
+GNU GENERAL PUBLIC LICENSE
+==========================
+
+Version 3, 29 June 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+
+Everyone is permitted to copy and distribute verbatim copies of this license
+document, but changing it is not allowed.
+
+## Preamble
+
+The GNU General Public License is a free, copyleft license for software and
+other kinds of works.
+
+The licenses for most software and other practical works are designed to take
+away your freedom to share and change the works. By contrast, the GNU General
+Public License is intended to guarantee your freedom to share and change all
+versions of a program--to make sure it remains free software for all its users.
+We, the Free Software Foundation, use the GNU General Public License for most of
+our software; it applies also to any other work released this way by its
+authors. You can apply it to your programs, too.
+
+When we speak of free software, we are referring to freedom, not price. Our
+General Public Licenses are designed to make sure that you have the freedom to
+distribute copies of free software (and charge for them if you wish), that you
+receive source code or can get it if you want it, that you can change the
+software or use pieces of it in new free programs, and that you know you can do
+these things.
+
+To protect your rights, we need to prevent others from denying you these rights
+or asking you to surrender the rights. Therefore, you have certain
+responsibilities if you distribute copies of the software, or if you modify it:
+responsibilities to respect the freedom of others.
+
+For example, if you distribute copies of such a program, whether gratis or for a
+fee, you must pass on to the recipients the same freedoms that you received. You
+must make sure that they, too, receive or can get the source code. And you must
+show them these terms so they know their rights.
+
+Developers that use the GNU GPL protect your rights with two steps: (1) assert
+copyright on the software, and (2) offer you this License giving you legal
+permission to copy, distribute and/or modify it.
+
+For the developers' and authors' protection, the GPL clearly explains that there
+is no warranty for this free software. For both users' and authors' sake, the
+GPL requires that modified versions be marked as changed, so that their problems
+will not be attributed erroneously to authors of previous versions.
+
+Some devices are designed to deny users access to install or run modified
+versions of the software inside them, although the manufacturer can do so. This
+is fundamentally incompatible with the aim of protecting users' freedom to
+change the software. The systematic pattern of such abuse occurs in the area of
+products for individuals to use, which is precisely where it is most
+unacceptable. Therefore, we have designed this version of the GPL to prohibit
+the practice for those products. If such problems arise substantially in other
+domains, we stand ready to extend this provision to those domains in future
+versions of the GPL, as needed to protect the freedom of users.
+
+Finally, every program is threatened constantly by software patents. States
+should not allow patents to restrict development and use of software on
+general-purpose computers, but in those that do, we wish to avoid the special
+danger that patents applied to a free program could make it effectively
+proprietary. To prevent this, the GPL assures that patents cannot be used to
+render the program non-free.
+
+The precise terms and conditions for copying, distribution and modification
+follow.
+
+## TERMS AND CONDITIONS
+
+### 0. Definitions.
+
+"This License" refers to version 3 of the GNU General Public License.
+
+"Copyright" also means copyright-like laws that apply to other kinds of works,
+such as semiconductor masks.
+
+"The Program" refers to any copyrightable work licensed under this License. Each
+licensee is addressed as "you". "Licensees" and "recipients" may be individuals
+or organizations.
+
+To "modify" a work means to copy from or adapt all or part of the work in a
+fashion requiring copyright permission, other than the making of an exact copy.
+The resulting work is called a "modified version" of the earlier work or a work
+"based on" the earlier work.
+
+A "covered work" means either the unmodified Program or a work based on the
+Program.
+
+To "propagate" a work means to do anything with it that, without permission,
+would make you directly or secondarily liable for infringement under applicable
+copyright law, except executing it on a computer or modifying a private copy.
+Propagation includes copying, distribution (with or without modification),
+making available to the public, and in some countries other activities as well.
+
+To "convey" a work means any kind of propagation that enables other parties to
+make or receive copies. Mere interaction with a user through a computer network,
+with no transfer of a copy, is not conveying.
+
+An interactive user interface displays "Appropriate Legal Notices" to the extent
+that it includes a convenient and prominently visible feature that (1) displays
+an appropriate copyright notice, and (2) tells the user that there is no
+warranty for the work (except to the extent that warranties are provided), that
+licensees may convey the work under this License, and how to view a copy of this
+License. If the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+### 1. Source Code.
+
+The "source code" for a work means the preferred form of the work for making
+modifications to it. "Object code" means any non-source form of a work.
+
+A "Standard Interface" means an interface that either is an official standard
+defined by a recognized standards body, or, in the case of interfaces specified
+for a particular programming language, one that is widely used among developers
+working in that language.
+
+The "System Libraries" of an executable work include anything, other than the
+work as a whole, that (a) is included in the normal form of packaging a Major
+Component, but which is not part of that Major Component, and (b) serves only to
+enable use of the work with that Major Component, or to implement a Standard
+Interface for which an implementation is available to the public in source code
+form. A "Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system (if any) on
+which the executable work runs, or a compiler used to produce the work, or an
+object code interpreter used to run it.
+
+The "Corresponding Source" for a work in object code form means all the source
+code needed to generate, install, and (for an executable work) run the object
+code and to modify the work, including scripts to control those activities.
+However, it does not include the work's System Libraries, or general-purpose
+tools or generally available free programs which are used unmodified in
+performing those activities but which are not part of the work. For example,
+Corresponding Source includes interface definition files associated with source
+files for the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require, such as by
+intimate data communication or control flow between those subprograms and other
+parts of the work.
+
+The Corresponding Source need not include anything that users can regenerate
+automatically from other parts of the Corresponding Source.
+
+The Corresponding Source for a work in source code form is that same work.
+
+### 2. Basic Permissions.
+
+All rights granted under this License are granted for the term of copyright on
+the Program, and are irrevocable provided the stated conditions are met. This
+License explicitly affirms your unlimited permission to run the unmodified
+Program. The output from running a covered work is covered by this License only
+if the output, given its content, constitutes a covered work. This License
+acknowledges your rights of fair use or other equivalent, as provided by
+copyright law.
+
+You may make, run and propagate covered works that you do not convey, without
+conditions so long as your license otherwise remains in force. You may convey
+covered works to others for the sole purpose of having them make modifications
+exclusively for you, or provide you with facilities for running those works,
+provided that you comply with the terms of this License in conveying all
+material for which you do not control copyright. Those thus making or running
+the covered works for you must do so exclusively on your behalf, under your
+direction and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+Conveying under any other circumstances is permitted solely under the conditions
+stated below. Sublicensing is not allowed; section 10 makes it unnecessary.
+
+### 3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+No covered work shall be deemed part of an effective technological measure under
+any applicable law fulfilling obligations under article 11 of the WIPO copyright
+treaty adopted on 20 December 1996, or similar laws prohibiting or restricting
+circumvention of such measures.
+
+When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention is
+effected by exercising rights under this License with respect to the covered
+work, and you disclaim any intention to limit operation or modification of the
+work as a means of enforcing, against the work's users, your or third parties'
+legal rights to forbid circumvention of technological measures.
+
+### 4. Conveying Verbatim Copies.
+
+You may convey verbatim copies of the Program's source code as you receive it,
+in any medium, provided that you conspicuously and appropriately publish on each
+copy an appropriate copyright notice; keep intact all notices stating that this
+License and any non-permissive terms added in accord with section 7 apply to the
+code; keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+You may charge any price or no price for each copy that you convey, and you may
+offer support or warranty protection for a fee.
+
+### 5. Conveying Modified Source Versions.
+
+You may convey a work based on the Program, or the modifications to produce it
+from the Program, in the form of source code under the terms of section 4,
+provided that you also meet all of these conditions:
+
+-   a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+-   b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under
+    section 7. This requirement modifies the requirement in section 4
+    to "keep intact all notices".
+-   c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy. This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged. This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+-   d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+A compilation of a covered work with other separate and independent works, which
+are not by their nature extensions of the covered work, and which are not
+combined with it such as to form a larger program, in or on a volume of a
+storage or distribution medium, is called an "aggregate" if the compilation and
+its resulting copyright are not used to limit the access or legal rights of the
+compilation's users beyond what the individual works permit. Inclusion of a
+covered work in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+### 6. Conveying Non-Source Forms.
+
+You may convey a covered work in object code form under the terms of sections 4
+and 5, provided that you also convey the machine-readable Corresponding Source
+under the terms of this License, in one of these ways:
+
+-   a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+-   b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the Corresponding
+    Source from a network server at no charge.
+-   c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source. This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+-   d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge. You need not require recipients to copy the
+    Corresponding Source along with the object code. If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source. Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+-   e) Convey the object code using peer-to-peer transmission,
+    provided you inform other peers where the object code and
+    Corresponding Source of the work are being offered to the general
+    public at no charge under subsection 6d.
+
+A separable portion of the object code, whose source code is excluded from the
+Corresponding Source as a System Library, need not be included in conveying the
+object code work.
+
+A "User Product" is either (1) a "consumer product", which means any tangible
+personal property which is normally used for personal, family, or household
+purposes, or (2) anything designed or sold for incorporation into a dwelling. In
+determining whether a product is a consumer product, doubtful cases shall be
+resolved in favor of coverage. For a particular product received by a particular
+user, "normally used" refers to a typical or common use of that class of
+product, regardless of the status of the particular user or of the way in which
+the particular user actually uses, or expects or is expected to use, the
+product. A product is a consumer product regardless of whether the product has
+substantial commercial, industrial or non-consumer uses, unless such uses
+represent the only significant mode of use of the product.
+
+"Installation Information" for a User Product means any methods, procedures,
+authorization keys, or other information required to install and execute
+modified versions of a covered work in that User Product from a modified version
+of its Corresponding Source. The information must suffice to ensure that the
+continued functioning of the modified object code is in no case prevented or
+interfered with solely because modification has been made.
+
+If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as part of a
+transaction in which the right of possession and use of the User Product is
+transferred to the recipient in perpetuity or for a fixed term (regardless of
+how the transaction is characterized), the Corresponding Source conveyed under
+this section must be accompanied by the Installation Information. But this
+requirement does not apply if neither you nor any third party retains the
+ability to install modified object code on the User Product (for example, the
+work has been installed in ROM).
+
+The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates for a
+work that has been modified or installed by the recipient, or for the User
+Product in which it has been modified or installed. Access to a network may be
+denied when the modification itself materially and adversely affects the
+operation of the network or violates the rules and protocols for communication
+across the network.
+
+Corresponding Source conveyed, and Installation Information provided, in accord
+with this section must be in a format that is publicly documented (and with an
+implementation available to the public in source code form), and must require no
+special password or key for unpacking, reading or copying.
+
+### 7. Additional Terms.
+
+"Additional permissions" are terms that supplement the terms of this License by
+making exceptions from one or more of its conditions. Additional permissions
+that are applicable to the entire Program shall be treated as though they were
+included in this License, to the extent that they are valid under applicable
+law. If additional permissions apply only to part of the Program, that part may
+be used separately under those permissions, but the entire Program remains
+governed by this License without regard to the additional permissions.
+
+When you convey a copy of a covered work, you may at your option remove any
+additional permissions from that copy, or from any part of it. (Additional
+permissions may be written to require their own removal in certain cases when
+you modify the work.) You may place additional permissions on material, added by
+you to a covered work, for which you have or can give appropriate copyright
+permission.
+
+Notwithstanding any other provision of this License, for material you add to a
+covered work, you may (if authorized by the copyright holders of that material)
+supplement the terms of this License with terms:
+
+-   a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+-   b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+-   c) Prohibiting misrepresentation of the origin of that material,
+    or requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+-   d) Limiting the use for publicity purposes of names of licensors
+    or authors of the material; or
+-   e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+-   f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions
+    of it) with contractual assumptions of liability to the recipient,
+    for any liability that these contractual assumptions directly
+    impose on those licensors and authors.
+
+All other non-permissive additional terms are considered "further restrictions"
+within the meaning of section 10. If the Program as you received it, or any part
+of it, contains a notice stating that it is governed by this License along with
+a term that is a further restriction, you may remove that term. If a license
+document contains a further restriction but permits relicensing or conveying
+under this License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does not survive
+such relicensing or conveying.
+
+If you add terms to a covered work in accord with this section, you must place,
+in the relevant source files, a statement of the additional terms that apply to
+those files, or a notice indicating where to find the applicable terms.
+
+Additional terms, permissive or non-permissive, may be stated in the form of a
+separately written license, or stated as exceptions; the above requirements
+apply either way.
+
+### 8. Termination.
+
+You may not propagate or modify a covered work except as expressly provided
+under this License. Any attempt otherwise to propagate or modify it is void, and
+will automatically terminate your rights under this License (including any
+patent licenses granted under the third paragraph of section 11).
+
+However, if you cease all violation of this License, then your license from a
+particular copyright holder is reinstated (a) provisionally, unless and until
+the copyright holder explicitly and finally terminates your license, and (b)
+permanently, if the copyright holder fails to notify you of the violation by
+some reasonable means prior to 60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is reinstated
+permanently if the copyright holder notifies you of the violation by some
+reasonable means, this is the first time you have received notice of violation
+of this License (for any work) from that copyright holder, and you cure the
+violation prior to 30 days after your receipt of the notice.
+
+Termination of your rights under this section does not terminate the licenses of
+parties who have received copies or rights from you under this License. If your
+rights have been terminated and not permanently reinstated, you do not qualify
+to receive new licenses for the same material under section 10.
+
+### 9. Acceptance Not Required for Having Copies.
+
+You are not required to accept this License in order to receive or run a copy of
+the Program. Ancillary propagation of a covered work occurring solely as a
+consequence of using peer-to-peer transmission to receive a copy likewise does
+not require acceptance. However, nothing other than this License grants you
+permission to propagate or modify any covered work. These actions infringe
+copyright if you do not accept this License. Therefore, by modifying or
+propagating a covered work, you indicate your acceptance of this License to do
+so.
+
+### 10. Automatic Licensing of Downstream Recipients.
+
+Each time you convey a covered work, the recipient automatically receives a
+license from the original licensors, to run, modify and propagate that work,
+subject to this License. You are not responsible for enforcing compliance by
+third parties with this License.
+
+An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations. If propagation of a covered work results
+from an entity transaction, each party to that transaction who receives a copy
+of the work also receives whatever licenses to the work the party's predecessor
+in interest had or could give under the previous paragraph, plus a right to
+possession of the Corresponding Source of the work from the predecessor in
+interest, if the predecessor has it or can get it with reasonable efforts.
+
+You may not impose any further restrictions on the exercise of the rights
+granted or affirmed under this License. For example, you may not impose a
+license fee, royalty, or other charge for exercise of rights granted under this
+License, and you may not initiate litigation (including a cross-claim or
+counterclaim in a lawsuit) alleging that any patent claim is infringed by
+making, using, selling, offering for sale, or importing the Program or any
+portion of it.
+
+### 11. Patents.
+
+A "contributor" is a copyright holder who authorizes use under this License of
+the Program or a work on which the Program is based. The work thus licensed is
+called the contributor's "contributor version".
+
+A contributor's "essential patent claims" are all patent claims owned or
+controlled by the contributor, whether already acquired or hereafter acquired,
+that would be infringed by some manner, permitted by this License, of making,
+using, or selling its contributor version, but do not include claims that would
+be infringed only as a consequence of further modification of the contributor
+version. For purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of this License.
+
+Each contributor grants you a non-exclusive, worldwide, royalty-free patent
+license under the contributor's essential patent claims, to make, use, sell,
+offer for sale, import and otherwise run, modify and propagate the contents of
+its contributor version.
+
+In the following three paragraphs, a "patent license" is any express agreement
+or commitment, however denominated, not to enforce a patent (such as an express
+permission to practice a patent or covenant not to sue for patent infringement).
+To "grant" such a patent license to a party means to make such an agreement or
+commitment not to enforce a patent against the party.
+
+If you convey a covered work, knowingly relying on a patent license, and the
+Corresponding Source of the work is not available for anyone to copy, free of
+charge and under the terms of this License, through a publicly available network
+server or other readily accessible means, then you must either (1) cause the
+Corresponding Source to be so available, or (2) arrange to deprive yourself of
+the benefit of the patent license for this particular work, or (3) arrange, in a
+manner consistent with the requirements of this License, to extend the patent
+license to downstream recipients. "Knowingly relying" means you have actual
+knowledge that, but for the patent license, your conveying the covered work in a
+country, or your recipient's use of the covered work in a country, would
+infringe one or more identifiable patents in that country that you have reason
+to believe are valid.
+
+If, pursuant to or in connection with a single transaction or arrangement, you
+convey, or propagate by procuring conveyance of, a covered work, and grant a
+patent license to some of the parties receiving the covered work authorizing
+them to use, propagate, modify or convey a specific copy of the covered work,
+then the patent license you grant is automatically extended to all recipients of
+the covered work and works based on it.
+
+A patent license is "discriminatory" if it does not include within the scope of
+its coverage, prohibits the exercise of, or is conditioned on the non-exercise
+of one or more of the rights that are specifically granted under this License.
+You may not convey a covered work if you are a party to an arrangement with a
+third party that is in the business of distributing software, under which you
+make payment to the third party based on the extent of your activity of
+conveying the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory patent
+license (a) in connection with copies of the covered work conveyed by you (or
+copies made from those copies), or (b) primarily for and in connection with
+specific products or compilations that contain the covered work, unless you
+entered into that arrangement, or that patent license was granted, prior to
+28 March 2007.
+
+Nothing in this License shall be construed as excluding or limiting any implied
+license or other defenses to infringement that may otherwise be available to you
+under applicable patent law.
+
+### 12. No Surrender of Others' Freedom.
+
+If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not excuse
+you from the conditions of this License. If you cannot convey a covered work so
+as to satisfy simultaneously your obligations under this License and any other
+pertinent obligations, then as a consequence you may not convey it at all. For
+example, if you agree to terms that obligate you to collect a royalty for
+further conveying from those to whom you convey the Program, the only way you
+could satisfy both those terms and this License would be to refrain entirely
+from conveying the Program.
+
+### 13. Use with the GNU Affero General Public License.
+
+Notwithstanding any other provision of this License, you have permission to link
+or combine any covered work with a work licensed under version 3 of the GNU
+Affero General Public License into a single combined work, and to convey the
+resulting work. The terms of this License will continue to apply to the part
+which is the covered work, but the special requirements of the GNU Affero
+General Public License, section 13, concerning interaction through a network
+will apply to the combination as such.
+
+### 14. Revised Versions of this License.
+
+The Free Software Foundation may publish revised and/or new versions of the GNU
+General Public License from time to time. Such new versions will be similar in
+spirit to the present version, but may differ in detail to address new problems
+or concerns.
+
+Each version is given a distinguishing version number. If the Program specifies
+that a certain numbered version of the GNU General Public License "or any later
+version" applies to it, you have the option of following the terms and
+conditions either of that numbered version or of any later version published by
+the Free Software Foundation. If the Program does not specify a version number
+of the GNU General Public License, you may choose any version ever published by
+the Free Software Foundation.
+
+If the Program specifies that a proxy can decide which future versions of the
+GNU General Public License can be used, that proxy's public statement of
+acceptance of a version permanently authorizes you to choose that version for
+the Program.
+
+Later license versions may give you additional or different permissions.
+However, no additional obligations are imposed on any author or copyright holder
+as a result of your choosing to follow a later version.
+
+### 15. Disclaimer of Warranty.
+
+THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
+PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
+EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE
+QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE
+DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+### 16. Limitation of Liability.
+
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY
+COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS
+PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
+INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
+THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
+INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE
+PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY
+HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+### 17. Interpretation of Sections 15 and 16.
+
+If the disclaimer of warranty and limitation of liability provided above cannot
+be given local legal effect according to their terms, reviewing courts shall
+apply local law that most closely approximates an absolute waiver of all civil
+liability in connection with the Program, unless a warranty or assumption of
+liability accompanies a copy of the Program in return for a fee.
+
+END OF TERMS AND CONDITIONS
+
+## How to Apply These Terms to Your New Programs
+
+If you develop a new program, and you want it to be of the greatest possible use
+to the public, the best way to achieve this is to make it free software which
+everyone can redistribute and change under these terms.
+
+To do so, attach the following notices to the program. It is safest to attach
+them to the start of each source file to most effectively state the exclusion of
+warranty; and each file should have at least the "copyright" line and a pointer
+to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program does terminal interaction, make it output a short notice like
+this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands \`show w' and \`show c' should show the appropriate
+parts of the General Public License. Of course, your program's commands might be
+different; for a GUI interface, you would use an "about box".
+
+You should also get your employer (if you work as a programmer) or school, if
+any, to sign a "copyright disclaimer" for the program, if necessary. For more
+information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+The GNU General Public License does not permit incorporating your program into
+proprietary programs. If your program is a subroutine library, you may consider
+it more useful to permit linking proprietary applications with the library. If
+this is what you want to do, use the GNU Lesser General Public License instead
+of this License. But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.

@@ -11,7 +11,7 @@ 
 ### Learning to use Stack
 
-If are learning to use Stack and have questions, a discussion at the
+If you are learning to use Stack and have questions, a discussion at the
 [Haskell Community](https://discourse.haskell.org/) forum may help. See its
 'Learn' category.
 

@@ -50,12 +50,19 @@   let dir = autogenPackageModulesDir lbi
   createDirectoryIfMissingVerbose verbosity True dir
   withLibLBI pkg lbi $ \_ libcfg -> do
-    withExeLBI pkg lbi $ \exe clbi ->
-      rewriteFileEx normal (dir </> "Build_" ++ exeName' exe ++ ".hs") $ unlines
-        [ "module Build_" ++ exeName' exe
+    withExeLBI pkg lbi $ \exe clbi -> do
+      let name = exeName' exe
+      rewriteFileEx normal (dir </> "Build_" ++ name ++ ".hs") $ unlines
+        [ "{-|"
+        , "Module      : Build_" ++ name
+        , "License     : BSD-3-Clause"
+        , "-}"
+        , ""
+        , "module Build_" ++ name
         , "  ( deps"
         , "  ) where"
         , ""
+        , "-- | The dependencies against which \\'" ++ name ++ "\\' is built."
         , "deps :: [String]"
         , "deps = " ++ show (formatdeps (transDeps libcfg clbi))
         ]

@@ -29,7 +29,7 @@   , bifunctors ==5.6.2
   , binary ==0.8.9.1
   , bitvec ==1.1.5.0
-  , blaze-builder ==0.4.2.3
+  , blaze-builder ==0.4.3
   , blaze-html ==0.9.2.0
   , blaze-markup ==0.8.3.0
   , byteorder ==1.0.4
@@ -50,11 +50,11 @@   , conduit-extra ==1.3.7
   , containers ==0.6.8
   , contravariant ==1.5.5
-  , cookie ==0.5.0
+  , cookie ==0.5.1
   , cryptohash-sha256 ==0.11.102.1
-  , crypton ==1.0.1
+  , crypton ==1.0.4
   , crypton-conduit ==0.2.3
-  , crypton-connection ==0.4.3
+  , crypton-connection ==0.4.4
   , crypton-x509 ==1.7.7
   , crypton-x509-store ==1.6.10
   , crypton-x509-system ==1.6.7
@@ -79,7 +79,7 @@   , file-embed ==0.0.16.0
   , filelock ==0.1.1.7
   , filepath ==1.4.301.0
-  , fsnotify ==0.4.1.0
+  , fsnotify ==0.4.3.0
   , generic-deriving ==1.14.6
   , generically ==0.1.1
   , ghc-bignum ==1.3
@@ -87,15 +87,19 @@   , ghc-boot-th ==9.8.4
   , ghc-prim ==0.11.0
   , githash ==0.1.7.0
-  , hackage-security ==0.6.2.6
+  , hackage-security ==0.6.3.0
   , half ==0.3.2
+  , happy ==2.0.2
+  , happy-lib ==2.0.2
   , hashable ==1.4.7.0
+  , haskell-src-exts ==1.23.1
+  , haskell-src-meta ==0.8.15
   , hi-file-parser ==0.1.7.0
   , hourglass ==0.2.12
-  , hpack ==0.38.0
+  , hpack ==0.38.1
   , hpc ==0.7.0.0
-  , http-api-data ==0.6.1
-  , http-client ==0.7.18
+  , http-api-data ==0.6.2
+  , http-client ==0.7.19
   , http-client-tls ==0.3.6.4
   , http-conduit ==2.3.9.1
   , http-download ==0.2.1.0
@@ -111,7 +115,6 @@   , libyaml-clib ==0.2.5
   , lift-type ==0.1.2.0
   , lifted-base ==0.2.3.12
-  , lukko ==0.1.2
   , megaparsec ==9.6.1
   , memory ==0.18.0
   , microlens ==0.4.13.1
@@ -120,38 +123,39 @@   , mime-types ==0.1.2.0
   , mintty ==0.1.4
   , monad-control ==1.0.3.1
-  , monad-logger ==0.3.41
+  , monad-logger ==0.3.42
   , monad-loops ==0.4.3
   , mono-traversable ==1.0.21.0
   , mtl ==2.3.1
   , mtl-compat ==0.2.2
-  , mustache ==2.4.2
+  , mustache ==2.4.3.1
   , neat-interpolation ==0.5.1.4
   , 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
+  , open-browser ==0.2.1.1
   , optparse-applicative ==0.18.1.0
   , optparse-simple ==0.1.1.4
   , os-string ==2.0.7
-  , pantry ==0.10.0
+  , pantry ==0.10.1
   , parsec ==3.1.17.0
   , parser-combinators ==1.3.0
   , path ==0.9.5
   , path-io ==1.8.2
   , path-pieces ==0.2.1
   , pem ==0.2.4
-  , persistent ==2.14.6.3
+  , persistent ==2.17.0.0
   , 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.9.0.0
+  , primitive ==0.9.1.0
   , process ==1.6.25.0
   , project-template ==0.2.1.0
   , random ==1.2.1.3
+  , replace-megaparsec ==1.5.0.1
   , resource-pool ==0.4.0.0
   , resourcet ==1.3.0
   , retry ==0.9.3.1
@@ -169,12 +173,14 @@   , socks ==0.6.1
   , split ==0.2.5
   , splitmix ==0.1.1
-  , stack ==3.5.1
+  , stack ==3.7.1
   , static-bytes ==0.1.1
   , stm ==2.5.3.1
   , stm-chans ==3.0.0.9
   , streaming-commons ==0.2.3.0
   , strict ==0.5.1
+  , string-interpolate ==0.3.4.0
+  , syb ==0.7.2.4
   , tagged ==0.8.8
   , tar ==0.6.3.0
   , tar-conduit ==0.4.1
@@ -182,27 +188,32 @@   , template-haskell ==2.21.0.0
   , temporary ==1.3
   , text ==2.1.1
+  , text-conversions ==0.3.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-expand-syns ==0.4.12.0
   , th-lift ==0.8.6
   , th-lift-instances ==0.1.20
+  , th-orphans ==0.13.16
+  , th-reify-many ==0.1.10
   , these ==1.2.1
   , time ==1.12.2
   , time-compat ==1.9.7
-  , tls ==2.1.1
+  , tls ==2.1.8
   , transformers ==0.6.1.0
   , transformers-base ==0.4.6
   , transformers-compat ==0.7.2
-  , typed-process ==0.2.12.0
+  , typed-process ==0.2.13.0
   , unix ==2.8.6.0
-  , unix-compat ==0.7.3
+  , unix-compat ==0.7.4
   , unix-time ==0.4.16
-  , unliftio ==0.2.25.0
+  , unliftio ==0.2.25.1
   , unliftio-core ==0.2.1.0
   , unordered-containers ==0.2.20
+  , utf8-string ==1.0.2
   , uuid-types ==1.0.6
   , vault ==0.3.1.5
   , vector ==0.13.2.0

@@ -33,7 +33,7 @@ -- 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-23.14/cabal.config.
+-- https://www.stackage.org/lts-23.24/cabal.config.
 --
 with-compiler: ghc-9.8.4
 import: cabal.config

@@ -348,9 +348,9 @@ 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 (March 2025) the package versions are
-primarily ones in Stackage snapshot LTS Haskell 23.14 (for GHC 9.8.4) and
-`hpack-0.38.0`.
+any time. At the time of writing (June 2025) the package versions are
+primarily ones in Stackage snapshot LTS Haskell 23.24 (for GHC 9.8.4) and
+`hpack-0.38.1`, `persistent-2.17.0.0` and `tls-2.1.8`.
 
 A Stack executable makes use of Cabal (the library) through a small 'Setup'
 executable that it compiles from Haskell source code. The executable compiles
@@ -581,6 +581,10 @@ 
 To disable folders named after `<PATTERN1>` and `<PATTERN2>`
 It's especially useful when some tests are taking a while to complete.
+
+On Linux, the `stack-integration-test` executable uses the `lld` linker and
+expects it to be on the PATH. The integration tests complete significantly
+quicker with `lld` than with the `ld.bfd` linker.
 
 ## Continuous integration (CI)
 

@@ -1,5 +1,32 @@ # Changelog
 
+## v3.7.1 - 2025-06-28
+
+**Changes since v3.5.1:**
+
+Other enhancements:
+
+* Bump to Hpack 0.38.1.
+* The `--extra-dep` option of Stack's `script` command now accepts a YAML value
+  specifying any immutable extra-dep. Previously only an extra-dep in the
+  package index that could be specified by a YAML string (for example,
+  `acme-missiles-0.3@rev:0`) was accepted.
+
+Bug fixes:
+
+* `stack script --package <pkg-name>` now uses GHC's `-package-id` option to
+  expose the installed package, rather than GHC's `-package` option. For
+  packages with public sub-libraries, `-package <pkg>` can expose an
+  installed package other than one listed by `ghc-pkg list <pkg>`.
+* Work around `ghc-pkg` bug where, on Windows only, it cannot register a package
+  into a package database that is also listed in the `GHC_PACKAGE_PATH`
+  environment variable. In previous versions of Stack, this affected
+  `stack script` when copying a pre-compiled package from another package
+  database.
+* On Windows, when decompressing, and extracting tools, from archive files,
+  Stack uses the system temporary directory, rather than the root of the
+  destination drive, if the former is on the destination drive.
+
 ## v3.5.1 - 2025-03-29
 
 **Changes since v3.3.1:**
@@ -342,9 +369,9 @@ Release notes:
 
 * Further to the release notes for Stack 2.3.1, the `-static` suffix has been
-  removed from the statically linked Linux/x86_64 binaries.
-* The binaries for Linux/Aarch64 are now statically linked.
-* Binaries are now provided for macOS/AArch64.
+  removed from the statically-linked Linux/x86_64 executables.
+* The executables for Linux/Aarch64 are now statically-linked.
+* Executables are now provided for macOS/AArch64.
 
 **Changes since v2.11.1:**
 
@@ -566,11 +593,11 @@ 
 * After an upgrade from an earlier version of Stack, on first use only,
   Stack 2.9.1 may warn that it had trouble loading the CompilerPaths cache.
-* The support from the Stack team for binary releases now includes Linux/AArch64
-  and is limited to:
+* The support from the Stack team for executable releases now includes
+  Linux/AArch64 and is limited to:
 
-    * Linux 64-bit/x86_64 (statically linked)
-    * Linux AArch64 (dynamically linked)
+    * Linux 64-bit/x86_64 (statically-linked)
+    * Linux AArch64 (dynamically-linked)
     * macOS x86_64
     * Windows 64-bit/x86_64
 
@@ -645,7 +672,7 @@ 
 Other enhancements:
 
-* `stack setup` supports installing GHC for macOS aarch64 (M1)
+* `stack setup` supports installing GHC for macOS/AArch64 (M1)
 * `stack upload` supports authentication with a Hackage API key (via
   `HACKAGE_KEY` environment variable).
 
@@ -815,26 +842,27 @@ 
 Release notes:
 
-* We have reduced the number of platforms that we support with binary releases.
-  The reason behind this is that we've been slowed down in our release process
-  until now with issues trying to build binaries for less common platforms. In
-  order to make sure we can address issues more quickly (like supporting new GHC
-  versions), we're limiting support from the Stack team to:
+* We have reduced the number of platforms that we support with executable
+  releases. The reason behind this is that we've been slowed down in our release
+  process until now with issues trying to build executables for less common
+  platforms. In order to make sure we can address issues more quickly (like
+  supporting new GHC versions), we're limiting support from the Stack team to:
 
-    * Linux 64-bit/x86_64 (statically linked)
+    * Linux 64-bit/x86_64 (statically-linked)
     * macOS x86_64
     * Windows 64-bit/x86_64
 
-  If others want to provide additional binaries, we will definitely be happy for
-  the support. But since our CI system is currently able to produce these three
-  bindists only, that's what we will be providing with the next release.
+  If others want to provide additional executables, we will definitely be happy
+  for the support. But since our CI system is currently able to produce these
+  three executables only, that's what we will be providing with the next
+  release.
 
-* Since we no longer have dynamically linked Linux binaries, we are removing the
-  `-static` suffix from the static Linux/x86_64 binaries. If you have scripts to
-  download the latest stable Linux/x86_64 binary, update them to use
-  `linux-x86_64` instead of `linux-x86_64-static` (if you are already using the
-  former, nothing needs to change). For this release, both are supported, but
-  the next release will no longer have the `-static` variant.
+* Since we no longer have dynamically-linked Linux executables, we are removing
+  the `-static` suffix from the static Linux/x86_64 executables. If you have
+  scripts to download the latest stable Linux/x86_64 executable, update them to
+  use `linux-x86_64` instead of `linux-x86_64-static` (if you are already using
+  the former, nothing needs to change). For this release, both are supported,
+  but the next release will no longer have the `-static` variant.
 
 * We are also deprecating the download links at https://stackage.org/stack. See
   this page for the current installation instructions:
@@ -1308,7 +1336,7 @@ * Help text for the `templates` subcommand now reflects behaviour in Stack 1.9
   — that it downloads and shows a help file, rather than listing available
   templates.
-* Fix detection of aarch64 platform (this broke when we upgraded to a newer
+* Fix detection of AArch64 platform (this broke when we upgraded to a newer
   Cabal version).
 * Docker: fix detecting and pulling missing images with `--docker-auto-pull`.
   See
@@ -1362,7 +1390,7 @@ 
 Release notes:
 
-* Statically linked Linux bindists are back again, thanks to
+* Statically-linked Linux executables are back again, thanks to
   [@nh2](https://github.com/nh2).
 * We will be deleting the Ubuntu, Debian, CentOS, Fedora, and Arch package repos
   from `download.fpcomplete.com` soon. These have been deprecated for over a
@@ -1530,10 +1558,10 @@ 
 Release notes:
 
-* aarch64 (64-bit ARM) bindists are now available for the first time.
-* Statically linked Linux bindists are no longer available, due to difficulty
+* AArch64 (64-bit ARM) executables are now available for the first time.
+* Statically-linked Linux executables are no longer available, due to difficulty
   with GHC 8.2.2 on Alpine Linux.
-* 32-bit Linux GMP4 bindists for CentOS 6 are no longer available, since
+* 32-bit Linux GMP4 executables for CentOS 6 are no longer available, since
   GHC 8.2.2 is no longer being built for that platform.
 
 Major changes:
@@ -1560,8 +1588,8 @@   for details.
 * Specify User-Agent HTTP request header on every HTTP request.
   See [#3628](https://github.com/commercialhaskell/stack/issues/3628) for details.
-* `stack setup` looks for GHC bindists and installations by any OS key
-  that is compatible (rather than only checking a single one).   This is
+* `stack setup` looks for GHC binary distributions and installations by any OS
+  key that is compatible (rather than only checking a single one). This is
   relevant on Linux where different distributions may have different
   combinations of libtinfo 5/6, ncurses 5/6, and gmp 4/5, and will allow
   simplifying the setup-info metadata YAML for future GHC releases.
@@ -1673,7 +1701,8 @@   cases where HTTP servers mistakenly set the transfer encoding to `gzip`. See
   [#3647](https://github.com/commercialhaskell/stack/issues/3647).
 * Links to docs.haskellstack.org ignore Stack version patchlevel.
-* Downloading Docker-compatible `stack` binary ignores Stack version patchlevel.
+* Downloading Docker-compatible `stack` executable ignores Stack version
+  patchlevel.
 
 Bug fixes:
 
@@ -1828,8 +1857,8 @@ * Automatically run `autoreconf -i` as necessary when a `configure`
   script is missing. See
   [#3534](https://github.com/commercialhaskell/stack/issues/3534)
-* GHC bindists can now be identified by their SHA256 checksum in addition to
-  their SHA1 checksum, allowing for more security in download.
+* GHC binary distributions can now be identified by their SHA256 checksum in
+  addition to their SHA1 checksum, allowing for more security in download.
 * For filesystem setup-info paths, it's no longer assumed that the
   directory is writable, instead a temp dir is used.  See
   [#3188](https://github.com/commercialhaskell/stack/issues/3188).
@@ -2131,7 +2160,7 @@ 
 * `stack config set` can now be used without a compiler installed
   [#2852](https://github.com/commercialhaskell/stack/issues/2852).
-* `get-stack.sh` now installs correct binary on ARM for generic linux and
+* `get-stack.sh` now installs correct executable on ARM for generic Linux and
   raspbian, closing
   [#2856](https://github.com/commercialhaskell/stack/issues/2856).
 * Correct the testing of whether a package database exists by checking
@@ -2150,17 +2179,15 @@ 
 Release notes:
 
-* For the _next_ Stack release after this one, we are planning
-  changes to our Linux releases, including dropping our Ubuntu,
-  Debian, CentOS, and Fedora package repositories and switching to
-  statically linked binaries. See
+* For the _next_ Stack release after this one, we are planning changes to our
+  Linux releases, including dropping our Ubuntu, Debian, CentOS, and Fedora
+  package repositories and switching to statically-linked executables. See
   [#2534](https://github.com/commercialhaskell/stack/issues/2534).
-  Note that upgrading without a package manager has gotten easier
-  with new binary upgrade support in `stack upgrade` (see the Major
-  Changes section below for more information). In addition, the
-  get.haskellstack.org script no longer installs from Ubuntu,
-  Debian, CentOS, or Fedora package repositories. Instead it places
-  a generic binary in /usr/local/bin.
+  Note that upgrading without a package manager has gotten easier with new
+  binary upgrade support in `stack upgrade` (see the Major Changes section below
+  for more information). In addition, the get.haskellstack.org script no longer
+  installs from Ubuntu, Debian, CentOS, or Fedora package repositories. Instead
+  it places a generic executable in /usr/local/bin.
 
 Major changes:
 
@@ -2181,11 +2208,10 @@   because it should no longer be necessary. See
   [#1364](https://github.com/commercialhaskell/stack/issues/1364)
 
-* Stack is now capable of doing binary upgrades instead of always
-  recompiling a new version from source. Running `stack upgrade` will
-  now default to downloading a binary version of Stack from the most
-  recent release, if one is available. See `stack upgrade --help` for
-  more options.
+* Stack is now capable of doing binary upgrades instead of always recompiling a
+  new version from source. Running `stack upgrade` will now default to
+  downloading a Stack executable from the most recent release, if one is
+  available. See `stack upgrade --help` for more options.
   [#1238](https://github.com/commercialhaskell/stack/issues/1238)
 
 Behavior changes:
@@ -2321,13 +2347,16 @@   [store#37](https://github.com/fpco/store/issues/37)).  Please stay with
   version 1.1.2 for now on those architectures.  This will be rectified soon!
 
-* We are now releasing a statically linked Stack binary for
+* We are now releasing a statically-linked Stack executable for
   [64-bit Linux](https://get.haskellstack.org/stable/linux-x86_64-static.tar.gz).
   Please try it and let us know if you run into any trouble on your platform.
+  The executable is linked against a version of the GNU Multiple Precision
+  Arithmetic Library (GMP), which is licensed under the GNU Lesser General
+  Public License, Version 3, 29 June 2007 (LGPL).
 
 * We are planning some changes to our Linux releases, including dropping our
   Ubuntu, Debian, CentOS, and Fedora package repositories and switching to
-  statically linked binaries.  We would value your feedback in
+  statically-linked executables. We would value your feedback in
   [#2534](https://github.com/commercialhaskell/stack/issues/2534).
 
 Major changes:
@@ -2348,9 +2377,10 @@ * Support -ferror-spans syntax in GHC error messages.
 * Avoid unpacking ghc to `/tmp`
   [#996](https://github.com/commercialhaskell/stack/issues/996)
-* The Linux `gmp4` GHC bindist is no longer considered a full-fledged GHC
-  variant and can no longer be specified using the `ghc-variant` option,
-  and instead is treated more like a slightly different platform.
+* The Linux `gmp4` GHC binary distribution is no longer considered a
+  full-fledged GHC variant and can no longer be specified using the
+  `ghc-variant` option, and instead is treated more like a slightly different
+  platform.
 
 Other enhancements:
 
@@ -2377,9 +2407,11 @@ * `stack setup` no longer unpacks to the system temp dir on posix systems.
   [#996](https://github.com/commercialhaskell/stack/issues/996)
 * `stack setup` detects libtinfo6 and ncurses6 and can download alternate GHC
-  bindists [#257](https://github.com/commercialhaskell/stack/issues/257)
+  binary distributions
+  [#257](https://github.com/commercialhaskell/stack/issues/257)
   [#2302](https://github.com/commercialhaskell/stack/issues/2302).
-* `stack setup` detects Linux ARMv7 downloads appropriate GHC bindist
+* `stack setup` detects Linux ARMv7 downloads appropriate GHC binary
+  distribution
   [#2103](https://github.com/commercialhaskell/stack/issues/2103)
 * Custom `stack` binaries list dependency versions in output for `--version`.
   See [#2222](https://github.com/commercialhaskell/stack/issues/2222)
@@ -3123,8 +3155,8 @@     * `setup-info` in `stack.yaml`, to specify where to download custom binary
       distributions (also `--ghc-bindist` command-line option)
     * Note: On systems with libgmp4 (aka `libgmp.so.3`), such as CentOS 6, you
-      may need to re-run `stack setup` due to the centos6 GHC bindist being
-      treated like a variant
+      may need to re-run `stack setup` due to the centos6 GHC binary
+      distribution being treated like a variant
 * A new `--pvp-bounds` flag to the sdist and upload commands allows automatic
   adding of PVP upper and/or lower bounds to your dependencies
 
@@ -3322,8 +3354,9 @@   [#452](https://github.com/commercialhaskell/stack/issues/452)
 * Don't copy over executables excluded by component selection
   [#605](https://github.com/commercialhaskell/stack/issues/605)
-* Fix: Stack fails on Windows with git package in `stack.yaml` and no git binary
-  on path [#712](https://github.com/commercialhaskell/stack/issues/712)
+* Fix: Stack fails on Windows with git package in `stack.yaml` and no git
+  executable on the PATH
+  [#712](https://github.com/commercialhaskell/stack/issues/712)
 * Fixed GHCi issue: Specifying explicit package versions (#678)
 * Fixed GHCi issue: Specifying -odir and -hidir as .stack-work/odir (#529)
 * Fixed GHCi issue: Specifying A instead of A.ext for modules (#498)

@@ -106,7 +106,7 @@ 
 *   If there are multiple definitions for the `Main` module, Stack will ask you
     to select one from a list of options. Pass the `--main-is <target>` option
-    to specific which `Main` module to load.
+    to specify which `Main` module to load.
 
 Stack combines all of the GHC options of components.
 

@@ -34,7 +34,7 @@ unix-2.8.6.0
 Win32-2.14.1.0
 acme-missiles-0.3
-pantry-0.10.0
+pantry-0.10.1
 
 stack list paltry
 Could not find package paltry, updating
@@ -45,17 +45,17 @@          tasty, retry, path, pretty, pasty, xattr, alloy, para, pappy and
          alure.
 
-stack --snapshot lts-23.14 list base unix Win32 acme-missiles pantry
+stack --snapshot lts-23.24 list base unix Win32 acme-missiles pantry
 Error: [S-4926]
        * Package does not appear in snapshot (directly or indirectly): acme-missiles.
 
-stack --snapshot lts-23.14 list base unix Win32 pantry
+stack --snapshot lts-23.24 list base unix Win32 pantry
 base-4.19.2.0
 unix-2.8.6.0
 Win32-2.13.4.0
-pantry-0.10.0
+pantry-0.10.1
 
-stack --snapshot lts-23.14 list
+stack --snapshot lts-23.24 list
 AC-Angle-1.0
 ALUT-2.4.0.3
 ...

@@ -6,7 +6,7 @@ stack script [--package PACKAGE] FILE
              [-- ARGUMENT(S) (e.g. stack script X.hs -- argument(s) to program).]
              [--compile | --optimize] [--[no-]use-root] [--ghc-options OPTIONS]
-             [--extra-dep PACKAGE-VERSION] [--no-run]
+             [--extra-dep EXTRA-DEP] [--no-run]
 ~~~
 
 The `stack script` command either runs a specified Haskell source file (using
@@ -49,12 +49,25 @@ For example:
 
 ~~~text
-stack script --snapshot lts-23.14 MyScript.hs
+stack script --snapshot lts-23.24 MyScript.hs
 ~~~
 
-A package version can be added to the snapshot on the command line with the
+An immutable extra-dep can be added to the snapshot on the command line with the
 `--extra-dep` option (which can be specified multiple times).
 
+An extra-dep is specified using a valid YAML value. For further information, see
+the [package location](../topics/package_location.md) documentation. Examples
+are:
+
+~~~text
+--extra-dep acme-missiles-0.3@rev:0
+--extra-dep '{git: git@github.com:yesodweb/wai, commit: '2f8a8e1b771829f4a8a77c0111352ce45a14c30f', subdirs: [auto-update, wai]}
+--extra-dep acme-missiles-0.3.tar.gz
+~~~
+
+Relative paths to local archive files are assumed to be relative to the
+directory in which the script file is located.
+
 GHC boot packages that have been 'replaced' (see further below) can be specified
 as an `--extra-dep`.
 
@@ -85,6 +98,11 @@     The first time that Stack deduces package names from module names can take
     some time. Use the `--verbose` option to understand Stack's progress.
 
+!!! note
+
+    The installed packages of modules exposed by public sub-libraries will not
+    be deduced, because those installed packages are hidden.
+
 !!! info
 
     Certain packages are blacklisted because they expose one or more modules
@@ -105,6 +123,11 @@ by a space or comma character. If the package is not in the snapshot, the most
 recent version in the package index (e.g. Hackage) will be obtained.
 
+In the case of a named public sub-library of a Cabal package, the required
+installed package is specified by the 'munged' package name. For example, for
+public sub-library `my-library` of Cabal package `my-package` the munged name of
+the installed package is `z-my-library-z-my-package`.
+
 If a required package is a GHC boot package, the behaviour can be complex. If
 the boot package has not been 'replaced', then it will be used in Stack's build
 plan. However, if the boot package has been 'replaced', the latest version of
@@ -117,7 +140,7 @@ particular, some snapshots include directly `Win32` (which is a boot package on
 Windows) while others do not.
 
-!!! warning
+!!! info
 
     GHC has the concept of 'installed packages' (which differ from 'Cabal
     packages') in package databases. An installed package has a name. An
@@ -128,16 +151,17 @@     installed package corresponding to a sub-library also has a `package-name`,
     which is the name of the Cabal package.
 
-    The `--package` option of `stack script` makes use of GHC's `-package`
-    option to expose an installed package. Unfortunately, the latter treats
-    `package-name` (if it exists) as if it were also the name of the installed
-    package. That means, for a Cabal package with one or more sub-libraries, the
-    GHC option `-package=<name>` cannot distinguish between (a) the installed
-    package `<name>` corresponding to the main library of Cabal package `<name>`
-    and (b) an installed package corresponding to a sub-library of that Cabal
-    package. The installed package that GHC picks to expose is indeterminate.
-    This can cause GHC to pick the wrong installed package and to report that it
-    cannot load a module because it is a member of a hidden package.
+    The `--package` option of `stack script` makes use of GHC's `-package-id`
+    option to expose an installed package, rather than its `-package` option.
+    The latter option treats `package-name` (if it exists) as if it were also
+    the name of the installed package. That means, for a Cabal package with one
+    or more sub-libraries, the GHC option `-package=<name>` cannot distinguish
+    between (a) the installed package `<name>` corresponding to the main library
+    of Cabal package `<name>` and (b) an installed package corresponding to a
+    sub-library of that Cabal package. The installed package that GHC picks to
+    expose is indeterminate. This can cause GHC to pick the wrong installed
+    package and to report that it cannot load a module because it is a member of
+    a hidden package.
 
 ## Compilation
 
@@ -187,7 +211,7 @@ can be compiled and run, with arguments, with:
 
 ~~~text
-stack --snapshot lts-23.14 script --package acme-missiles --compile MyScript.hs -- "Don't panic!" "Duck and cover!"
+stack --snapshot lts-23.24 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 +231,7 @@ 
 ~~~haskell
 {- stack script
-   -- snapshot lts-23.14
+   -- snapshot lts-23.24
    -- extra-dep acme-missiles-0.2
    -- package acme-missiles
 -}
@@ -309,7 +333,7 @@ 
 ~~~haskell
 {- stack script
-   --snapshot lts-23.14
+   --snapshot lts-23.24
 -}
 
 {-# LANGUAGE OverloadedStrings #-}
@@ -327,3 +351,34 @@ directly or indirectly, in the specified snapshot (`incipit-base`,
 `incipit-core`, `relude` and `text`), `PackageImports` and `"text"` are required
 to specify which module is being imported.
+
+### Example 5
+
+Stackage snapshot LTS Haskell 23.18 specifies Cabal package `vector-0.13.2.0`
+which includes public sub-library `benchmarks-O2`. The sub-library exposes
+module `Bench.Vector.TestData.ParenTree` which exports `parenTree`. The
+following is a valid script:
+
+~~~haskell
+{- stack script
+   --snapshot lts-23.18
+   --package z-vector-z-benchmarks-O2
+-}
+{-# LANGUAGE LambdaCase #-}
+
+import Bench.Vector.TestData.ParenTree ( parenTree )
+import System.Environment ( getArgs )
+
+main :: IO ()
+main = getArgs >>= \case
+  [] -> putStrLn "An initial argument is required."
+  (arg:_) -> do
+    let n = read arg
+    if n >= 0 && even n
+      then do
+        putStrLn "A balanced binary tree structure"
+        putStrLn $ "with " <> show n <> " parentheses positions:"
+        print $ parenTree n
+      else
+        putStrLn "A positive even integer argument is required."
+~~~

@@ -94,3 +94,22 @@     * the `tinfo6` and `tinfo6-libc6-pre232` builds with the 'Fedora 27' binary
       distribution of GHC 9.4.4 to 9.4.8. Those binary distributions require
       versions of `libc6` that are compatible with `libc6` 2.26.
+
+=== "Windows"
+
+    Since Windows 10 version 1607, Windows has been 'long file paths' capable
+    but that capability is not enabled by default. Consequently, Stack does not
+    assume that it is being used on a system that is 'long file paths' enabled.
+
+    Stack uses the 7-Zip tool to decompress, and extract tools from, downloaded
+    archive files. Aiming to avoid long file paths, Stack does so in a temporary
+    directory (named `stack-tmp-<hash>`) on the drive of the final destination
+    (either in the system temporary directory, where applicable, or the root of
+    the drive). Consequently, Stack needs permission to create a directory in
+    that location.
+
+    A Windows user account will usually have permission to create a directory in
+    the system temporary directory. A Windows user account of type Administrator
+    will have permission to create a directory in the root of the system drive
+    (`C:\`, by convention) but a Standard user account may well not have
+    permission.

@@ -299,7 +299,7 @@ Stackage snapshot, like this:
 
 ~~~yaml
-snapshot: lts-23.14
+snapshot: lts-23.24
 compiler: ghc-9.8.3
 compiler-check: match-exact
 ~~~
@@ -1525,7 +1525,7 @@ (as set in the `pantry` library)
 
 Command line equivalent (takes precedence):
-[`--snapshot-location-base`](../global_flags.md#--snapshot-location-base-command-option)
+[`--snapshot-location-base`](../global_flags.md#-snapshot-location-base-command-option)
 option
 
 Sets the base location of the LTS Haskell or Stackage Nightly snapshots.

@@ -40,8 +40,8 @@ resolver since a snapshot states how dependencies are resolved. There are
 currently four snapshot types:
 
-* LTS Haskell snapshots, e.g. `snapshot: lts-23.14`
-* Stackage Nightly snapshots, e.g. `snapshot: nightly-2025-02-15`
+* LTS Haskell snapshots, e.g. `snapshot: lts-23.24`
+* Stackage Nightly snapshots, e.g. `snapshot: nightly-2025-06-15`
 * No snapshot, just use packages shipped with the compiler. For GHC this looks
   like `snapshot: ghc-9.8.4`
 * Custom snapshot, via a URL or relative file path. For further information, see

@@ -0,0 +1,180 @@+<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>
+
+# Docker images
+
+Each Stackage LTS release has two corresponding docker images in the
+[fpco/stack-build](https://hub.docker.com/r/fpco/stack-build/) and
+[fpco/stack-build-small](https://hub.docker.com/r/fpco/stack-build-small/)
+repositories. The former contains every system library needed to build any
+package in the snapshot, while the latter only contains a minimal set of system
+libraries for basic programs.
+
+The Dockerfiles for building these images are in
+[stackage/automated/dockerfiles](https://github.com/commercialhaskell/stackage/tree/master/automated/dockerfiles/).
+There is also a
+[build.sh](https://github.com/commercialhaskell/stackage/tree/master/automated/dockerfiles/build.sh)
+script to help with building and pushing the images (see the
+[README](https://github.com/commercialhaskell/stackage/tree/master/automated/dockerfiles/README.md)
+for usage instructions).
+
+## Build images for new minor LTS snapshot
+
+In most cases, a new minor LTS snapshot just needs the previous LTS image to be
+re-tagged and pushed. If the image needs a patch for the new minor LTS snapshot,
+see the next section.
+
+Below, replace `<N>.<M>` with the minor LTS snapshot version.
+
+- Check out the `stable` branch of the
+  [Stack repository](https://github.com/commercialhaskell/stack/).
+
+- Build and push the images (both standard and `small` variants) using the
+  [build.sh](https://github.com/commercialhaskell/stackage/tree/master/automated/dockerfiles/build.sh)
+  script:
+
+    ~~~text
+    ./build.sh --push lts-<N>.<M>
+    ./build.sh --push --small lts-<N>.<M>
+    ~~~
+
+## Patch images for new minor LTS snapshot
+
+Below, replace `<N>.<M>` with the minor LTS snapshot version. and `<N>.<M-1>`
+with the previous minor LTS snapshot version.
+
+- Check out the `stable` branch of the
+  [Stack repository](https://github.com/commercialhaskell/stack/).
+
+- In `stackage/automated/dockerfiles`, create a new `lts-<N>.<M>` directory.
+
+- Create `lts-<N>.<M>/Dockerfile`, starting with:
+
+    ~~~dockerfile
+    FROM $DOCKER_REPO:lts-<N>.<M-1>
+    ~~~
+
+- Add layers for any changes that need to be made to the image.
+
+- Build the new image using the
+  [build.sh](https://github.com/commercialhaskell/stackage/tree/master/automated/dockerfiles/build.sh)
+  script:
+
+    ~~~text
+    ./build.sh lts-<N>.<M>
+    ./build.sh --small lts-<N>.<M>
+    ~~~
+
+- Test the new image. For example, command:
+
+    ~~~text
+    stack --snapshot=lts-<N>.<M> new image-test
+    cd image-test
+    stack --docker build
+    ~~~
+
+  This should use the image you just built. Make sure you test that the new
+  image actually contains the desired changes.
+
+- Follow the process in the previous section to push the images.
+
+## Build images for new major LTS snapshot release
+
+### Test a Dockerfile prior to new major LTS snapshot release
+
+Replace `<N>` with major version of new LTS snapshot, and `<N-1>` with previous
+major LTS snapshot version.
+
+- Check out the `stable` branch of the
+  [Stack repository](https://github.com/commercialhaskell/stack/).
+
+- In `stackage/automated/dockerfiles`, create a new `lts-<N>.0` directory.
+
+- Copy `lts-<N-1>.0/Dockerfile` to `lts-<N>.0/Dockerfile`.
+
+- Check the `FROM` statement, make sure the Ubuntu version matches the Ubuntu
+  version used in the
+  [Stackage Dockerfile](https://github.com/commercialhaskell/stackage/blob/master/Dockerfile).
+
+- Update `GHC_VERSION` to match the version used by the
+  [latest nightly snapshot](https://www.stackage.org/nightly).
+
+- Set `LTS_SLUG` to the
+  [latest nightly snapshot](https://www.stackage.org/nightly) (this will be
+  temporary until the major LTS snapshot is actually released, at which point it
+  will be updated to `lts-<N>.0`).
+
+- Update `PID1_VERSION` and `STACK_VERSION` to the latest versions of those
+  tools.
+
+- Make sure `CUDA_VERSION` and `JVM_PATH` match what
+  [debian-bootstrap.sh](https://github.com/commercialhaskell/stackage/blob/master/debian-bootstrap.sh)
+  uses.
+
+- Update `LLVM_PATH` to the version required for the GHC version. This will be
+  shown on the download page for the GHC version, which you can reach from
+  https://www.haskell.org/ghc/. It should match the base directory used in
+  `CLANG_PURE_LLVM_INCLUDE_DIR` in
+  [debian-bootstrap.sh](https://github.com/commercialhaskell/stackage/blob/master/debian-bootstrap.sh)
+  (leaving off the `/include` suffix).
+
+- Update `BOOTSTRAP_COMMIT` to the Git commit ID of the latest
+  [debian-bootstrap.sh](https://github.com/commercialhaskell/stackage/blob/master/debian-bootstrap.sh).
+
+- Check for any other `lts-<N>.*/Dockerfile`s and make sure
+  `lts-<N>.0/Dockerfile` includes anything that was updated in those, if they're
+  still relevant for LTS-15 (note that a newer
+  [debian-bootstrap.sh](https://github.com/commercialhaskell/stackage/blob/master/debian-bootstrap.sh)
+  may already include those changes, so check there first).
+
+### Perform basic tests
+
+- Build the image: `docker build -t local/stack-build lts-<N>.0/`.
+
+- Ensure that all the directories listed in `PATH`, `CUDA_PATH`, and `CPATH` and
+  any other path-like environment variables actually exist in the image.
+
+- Try building a test package with the new image. Command:
+
+    ~~~text
+    stack --snapshot=nightly new image-test`
+    cd image-test
+    stack --docker --docker-image=local/stack-build build
+    ~~~
+
+  This should build without needing to install GHC.
+
+- Build the "small" variant. Command:
+
+    ~~~text
+    docker build -t local/stack-build-small --build-arg "VARIANT=small" lts-<N>.0/
+    ~~~
+
+- Try building a test package with the new small image. Command:
+
+    ~~~text
+    stack --snapshot=nightly new small-image-test
+    cd small-image-test
+    stack --docker --docker-image=local/stack-build-small build
+    ~~~
+
+  This should build without needing to install GHC.
+
+### Build real image once major LTS snapshot has been released
+
+- Update `LTS_SLUG` to `lts-<N>.0`
+
+- Update `BOOTSTRAP_COMMIT` to the git commit ID of the latest
+  [debian-bootstrap.sh](https://github.com/commercialhaskell/stackage/blob/master/debian-bootstrap.sh).
+
+- Repeat the tests above, except use `lts-<N>.0` instead of `nightly`.
+
+- Build and push the real images (both standard and `small` variants) using the
+  [build.sh](https://github.com/commercialhaskell/stackage/tree/master/automated/dockerfiles/build.sh)
+  script:
+
+    ~~~text
+    ./build.sh --push lts-<N>.0
+    ./build.sh --push --small lts-<N>.0
+    ~~~
+
+- Commit and push the new Dockerfile to the `stable` branch.

@@ -0,0 +1,34 @@+<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>
+
+# Docker images
+
+Docker Hub includes Docker images under
+[`fpco/stack-build'](https://hub.docker.com/r/fpco/stack-build).
+
+To update those images with a new version of Stack:
+
+1.  Under
+    [commercialhaskell/stackage/automated/dockerfiles](https://github.com/commercialhaskell/stackage/tree/master/automated/dockerfiles/),
+    add `lts-X.Y/Dockerfile` (where `X.Y` is the latest Stackage Haskell LTS
+    version), containing (where `X.Z` is the previous Haskell LTS version,
+    and `X.Y.Z` is the newly released Stack version):
+
+    ~~~dockerfile
+    FROM $DOCKER_REPO:lts-X.Z
+    ARG STACK_VERSION=X.Y.Z
+    RUN wget -qO- https://github.com/commercialhaskell/stack/releases/download/v$STACK_VERSION/stack-$STACK_VERSION-linux-x86_64.tar.gz | tar xz --wildcards --strip-components=1 -C /usr/local/bin '*/stack'
+    ~~~
+
+2.  Run `./build.sh lts-X.Y`. Then test that the new image has the new
+    version of Stack. For example, command:
+
+    ~~~text
+    docker run --rm fpco/stack-build:lts stack --version
+    ~~~
+
+3.  Use the following commands to push the new image to the registry:
+
+    ~~~text
+    ./build.sh --push lts-X.Y
+    ./build.sh --push --small lts-X.Y
+    ~~~

@@ -1,180 +0,0 @@-<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>
-
-# Docker images
-
-Each Stackage LTS release has two corresponding docker images in the
-[fpco/stack-build](https://hub.docker.com/r/fpco/stack-build/) and
-[fpco/stack-build-small](https://hub.docker.com/r/fpco/stack-build-small/)
-repositories. The former contains every system library needed to build any
-package in the snapshot, while the latter only contains a minimal set of system
-libraries for basic programs.
-
-The Dockerfiles for building these images are in
-[stackage/automated/dockerfiles](https://github.com/commercialhaskell/stackage/tree/master/automated/dockerfiles/).
-There is also a
-[build.sh](https://github.com/commercialhaskell/stackage/tree/master/automated/dockerfiles/build.sh)
-script to help with building and pushing the images (see the
-[README](https://github.com/commercialhaskell/stackage/tree/master/automated/dockerfiles/README.md)
-for usage instructions).
-
-## Build images for new minor LTS snapshot
-
-In most cases, a new minor LTS snapshot just needs the previous LTS image to be
-re-tagged and pushed. If the image needs a patch for the new minor LTS snapshot,
-see the next section.
-
-Below, replace `<N>.<M>` with the minor LTS snapshot version.
-
-- Check out the `stable` branch of the
-  [Stack repository](https://github.com/commercialhaskell/stack/).
-
-- Build and push the images (both standard and `small` variants) using the
-  [build.sh](https://github.com/commercialhaskell/stackage/tree/master/automated/dockerfiles/build.sh)
-  script:
-
-    ~~~text
-    ./build.sh --push lts-<N>.<M>
-    ./build.sh --push --small lts-<N>.<M>
-    ~~~
-
-## Patch images for new minor LTS snapshot
-
-Below, replace `<N>.<M>` with the minor LTS snapshot version. and `<N>.<M-1>`
-with the previous minor LTS snapshot version.
-
-- Check out the `stable` branch of the
-  [Stack repository](https://github.com/commercialhaskell/stack/).
-
-- In `stackage/automated/dockerfiles`, create a new `lts-<N>.<M>` directory.
-
-- Create `lts-<N>.<M>/Dockerfile`, starting with:
-
-    ~~~dockerfile
-    FROM $DOCKER_REPO:lts-<N>.<M-1>
-    ~~~
-
-- Add layers for any changes that need to be made to the image.
-
-- Build the new image using the
-  [build.sh](https://github.com/commercialhaskell/stackage/tree/master/automated/dockerfiles/build.sh)
-  script:
-
-    ~~~text
-    ./build.sh lts-<N>.<M>
-    ./build.sh --small lts-<N>.<M>
-    ~~~
-
-- Test the new image. For example, command:
-
-    ~~~text
-    stack --snapshot=lts-<N>.<M> new image-test
-    cd image-test
-    stack --docker build
-    ~~~
-
-  This should use the image you just built. Make sure you test that the new
-  image actually contains the desired changes.
-
-- Follow the process in the previous section to push the images.
-
-## Build images for new major LTS snapshot release
-
-### Test a Dockerfile prior to new major LTS snapshot release
-
-Replace `<N>` with major version of new LTS snapshot, and `<N-1>` with previous
-major LTS snapshot version.
-
-- Check out the `stable` branch of the
-  [Stack repository](https://github.com/commercialhaskell/stack/).
-
-- In `stackage/automated/dockerfiles`, create a new `lts-<N>.0` directory.
-
-- Copy `lts-<N-1>.0/Dockerfile` to `lts-<N>.0/Dockerfile`.
-
-- Check the `FROM` statement, make sure the Ubuntu version matches the Ubuntu
-  version used in the
-  [Stackage Dockerfile](https://github.com/commercialhaskell/stackage/blob/master/Dockerfile).
-
-- Update `GHC_VERSION` to match the version used by the
-  [latest nightly snapshot](https://www.stackage.org/nightly).
-
-- Set `LTS_SLUG` to the
-  [latest nightly snapshot](https://www.stackage.org/nightly) (this will be
-  temporary until the major LTS snapshot is actually released, at which point it
-  will be updated to `lts-<N>.0`).
-
-- Update `PID1_VERSION` and `STACK_VERSION` to the latest versions of those
-  tools.
-
-- Make sure `CUDA_VERSION` and `JVM_PATH` match what
-  [debian-bootstrap.sh](https://github.com/commercialhaskell/stackage/blob/master/debian-bootstrap.sh)
-  uses.
-
-- Update `LLVM_PATH` to the version required for the GHC version. This will be
-  shown on the download page for the GHC version, which you can reach from
-  https://www.haskell.org/ghc/. It should match the base directory used in
-  `CLANG_PURE_LLVM_INCLUDE_DIR` in
-  [debian-bootstrap.sh](https://github.com/commercialhaskell/stackage/blob/master/debian-bootstrap.sh)
-  (leaving off the `/include` suffix).
-
-- Update `BOOTSTRAP_COMMIT` to the Git commit ID of the latest
-  [debian-bootstrap.sh](https://github.com/commercialhaskell/stackage/blob/master/debian-bootstrap.sh).
-
-- Check for any other `lts-<N>.*/Dockerfile`s and make sure
-  `lts-<N>.0/Dockerfile` includes anything that was updated in those, if they're
-  still relevant for LTS-15 (note that a newer
-  [debian-bootstrap.sh](https://github.com/commercialhaskell/stackage/blob/master/debian-bootstrap.sh)
-  may already include those changes, so check there first).
-
-### Perform basic tests
-
-- Build the image: `docker build -t local/stack-build lts-<N>.0/`.
-
-- Ensure that all the directories listed in `PATH`, `CUDA_PATH`, and `CPATH` and
-  any other path-like environment variables actually exist in the image.
-
-- Try building a test package with the new image. Command:
-
-    ~~~text
-    stack --snapshot=nightly new image-test`
-    cd image-test
-    stack --docker --docker-image=local/stack-build build
-    ~~~
-
-  This should build without needing to install GHC.
-
-- Build the "small" variant. Command:
-
-    ~~~text
-    docker build -t local/stack-build-small --build-arg "VARIANT=small" lts-<N>.0/
-    ~~~
-
-- Try building a test package with the new small image. Command:
-
-    ~~~text
-    stack --snapshot=nightly new small-image-test
-    cd small-image-test
-    stack --docker --docker-image=local/stack-build-small build
-    ~~~
-
-  This should build without needing to install GHC.
-
-### Build real image once major LTS snapshot has been released
-
-- Update `LTS_SLUG` to `lts-<N>.0`
-
-- Update `BOOTSTRAP_COMMIT` to the git commit ID of the latest
-  [debian-bootstrap.sh](https://github.com/commercialhaskell/stackage/blob/master/debian-bootstrap.sh).
-
-- Repeat the tests above, except use `lts-<N>.0` instead of `nightly`.
-
-- Build and push the real images (both standard and `small` variants) using the
-  [build.sh](https://github.com/commercialhaskell/stackage/tree/master/automated/dockerfiles/build.sh)
-  script:
-
-    ~~~text
-    ./build.sh --push lts-<N>.0
-    ./build.sh --push --small lts-<N>.0
-    ~~~
-
-- Commit and push the new Dockerfile to the `stable` branch.

@@ -1,34 +0,0 @@-<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>
-
-# Docker images
-
-Docker Hub includes Docker images under
-[`fpco/stack-build'](https://hub.docker.com/r/fpco/stack-build).
-
-To update those images with a new version of Stack:
-
-1.  Under
-    [commercialhaskell/stackage/automated/dockerfiles](https://github.com/commercialhaskell/stackage/tree/master/automated/dockerfiles/),
-    add `lts-X.Y/Dockerfile` (where `X.Y` is the latest Stackage Haskell LTS
-    version), containing (where `X.Z` is the previous Haskell LTS version,
-    and `X.Y.Z` is the newly released Stack version):
-
-    ~~~dockerfile
-    FROM $DOCKER_REPO:lts-X.Z
-    ARG STACK_VERSION=X.Y.Z
-    RUN wget -qO- https://github.com/commercialhaskell/stack/releases/download/v$STACK_VERSION/stack-$STACK_VERSION-linux-x86_64.tar.gz | tar xz --wildcards --strip-components=1 -C /usr/local/bin '*/stack'
-    ~~~
-
-2.  Run `./build.sh lts-X.Y`. Then test that the new image has the new
-    version of Stack. For example, command:
-
-    ~~~text
-    docker run --rm fpco/stack-build:lts stack --version
-    ~~~
-
-3.  Use the following commands to push the new image to the registry:
-
-    ~~~text
-    ./build.sh --push lts-X.Y
-    ./build.sh --push --small lts-X.Y
-    ~~~

@@ -47,9 +47,9 @@ ## MkDocs
 
 The `doc/requirements.txt` file pins the version of MkDocs. As at
-2 September 2021 it is set to:
+13 April 2025 it is set to:
 
-    mkdocs==1.3.1
+    mkdocs==1.6.0
 
 A configuration file, `mkdocs.yml` is included in the repository root directory.
 See https://www.mkdocs.org/user-guide/configuration/.
@@ -57,8 +57,6 @@ `site_dir: _site` specifies the directory where the output HTML and other files
 are created. This directory is added to the `.gitignore` file.
 
-MkDocs 1.3.0 replaced the `pages:` key with the `nav:` key.
-
 ## Material for MkDocs
 
 Stack moved from the default `readthedocs` theme to Material for MkDocs after
@@ -77,8 +75,16 @@   palette:
     primary: 'deep purple'
     accent: 'deep purple'
-  icon:
-    logo: material/language-haskell
+  logo: img/stack-logo-white.svg
+  favicon: img/stack-favicon.svg
+  features:
+  - content.code.annotate
+  - content.code.copy
+  - content.code.select
+  - content.tabs.link
+  - navigation.indexes
+  - navigation.tabs
+  - navigation.top
 ~~~
 
 Read the Docs requires [JQuery](https://jquery.com/) for its JavaScript code to

@@ -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-09-07.
+`master` branch of the Stack repository. Last updated: 2025-05-12.
 
 *   `Stack.main`: catches exceptions from action `commandLineHandler`.
 
@@ -28,18 +28,6 @@         [S-2816] = InconsistentDependenciesBug
         ~~~
 
-    -   `GHC.GHC.Utils.GhcPkg.Main.Compat`
-
-        ~~~haskell
-        [S-6512] = CannotParse String String String
-        [S-3384] | CannotOpenDBForModification FilePath IOException
-        [S-1430] | SingleFileDBUnsupported FilePath
-        [S-5996] | ParsePackageInfoExceptions String
-        [S-3189] | CannotFindPackage PackageArg (Maybe FilePath)
-        [S-9323] | CannotParseRelFileBug String
-        [S-7651] | CannotParseDirectoryWithDBug String
-        ~~~
-
     -   `Options.Applicative.Builder.Extra.OptionsApplicativeExtraException`
 
         ~~~haskell
@@ -58,6 +46,10 @@         [S-1727] = NotOnlyLocal [PackageName] [Text]
         ~~~
 
+    -   `Stack.Build.ExecutePackage`
+
+        `[S-4541]` used in `copyPreCompiled`
+
     -   `Stack.BuildPlan.BuildPlanException`
 
         ~~~haskell
@@ -140,21 +132,15 @@ 
         `[S-6716]` used in `unregisterGhcPkgIds`
 
-    -   `Stack.Ghci.GhciException`
-
-        ~~~haskell
-        [S-6716] = InvalidPackageOption String
-        [S-9632] | LoadingDuplicateModules
-        [S-3600] | MissingFileTarget String
-        [S-9906] | Can'tSpecifyFilesAndTargets
-        [S-5188] | Can'tSpecifyFilesAndMainIs
-        ~~~
-
     -   `Stack.Ghci.GhciPrettyException`
 
         ~~~haskell
         [S-6948] = GhciTargetParseException [StyleDoc]
         [S-1939] | CandidatesIndexOutOfRangeBug
+        [S-6716] | InvalidPackageOption String
+        [S-3600] | FileTargetIsInvalidAbsFile String
+        [S-9906] | Can'tSpecifyFilesAndTargets
+        [S-5188] | Can'tSpecifyFilesAndMainIs
         ~~~
 
     -   `Stack.Hoogle.HoogleException`
@@ -455,6 +441,19 @@         [S-7058] | DockerNotInstalledException
         [S-6894] | UnsupportedStackExeHostPlatformException
         [S-1512] | DockerStackExeParseException String
+        ~~~
+
+    -   `Stack.Types.GhcPkgExe`
+
+        ~~~haskell
+        [S-6512] = CannotParse String String String
+        [S-3384] | CannotOpenDBForModification FilePath IOException
+        [S-1430] | SingleFileDBUnsupported FilePath
+        [S-5996] | ParsePackageInfoExceptions String
+        [S-3189] | CannotFindPackage PackageArg (Maybe FilePath)
+        [S-9323] | CannotParseRelFileBug String
+        [S-7651] | CannotParseDirectoryWithDBug String
+        [S-6590] | CannotRecacheAfterUnregister (Path Abs Dir) SomeException
         ~~~
 
     -   `Stack.Types.GhcPkgId.GhcPkgIdParseFail`

@@ -150,7 +150,7 @@ 
         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.14`
+        installed that version). For example, to use `snapshot: lts-23.24`
         (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

@@ -18,7 +18,7 @@     for snapshot specification.
 
 ~~~yaml
-snapshot: lts-23.14 # Inherits GHC version and package set
+snapshot: lts-23.24 # Inherits GHC version and package set
 compiler: ghc-9.8.3 # Overwrites GHC version in the snapshot, optional
 
 # Additional packages, follows extra-deps syntax
@@ -62,35 +62,35 @@ 
 ### Overriding the compiler
 
-The following snapshot specification will be identical to `lts-23.14`, but
+The following snapshot specification will be identical to `lts-23.24`, but
 instead use `ghc-9.8.3` instead of `ghc-9.8.4`:
 
 ~~~yaml
-snapshot: lts-23.14
+snapshot: lts-23.24
 compiler: ghc-9.8.3
 ~~~
 
 ### Dropping packages
 
-The following snapshot specification will be identical to `lts-23.14`, but
+The following snapshot specification will be identical to `lts-23.24`, 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-23.14
+snapshot: lts-23.24
 drop-packages:
 - text
 ~~~
 
 ### Hiding packages
 
-The following snapshot specification will be identical to `lts-23.14`, but the
+The following snapshot specification will be identical to `lts-23.24`, but the
 `text` package will be hidden when registering. This will affect, for example,
 the import parser in the script command.
 
 ~~~yaml
-snapshot: lts-23.14
+snapshot: lts-23.24
 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-23.14`, but
+The following snapshot specification will be identical to `lts-23.24`, but
 provides `-O1` as a ghc-option for `text`:
 
 ~~~yaml
-snapshot: lts-23.14
+snapshot: lts-23.24
 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-23.14`, but
+following snapshot specification will be identical to `lts-23.24`, but
 it enables the `developer` Cabal flag:
 
 ~~~yaml
-snapshot: lts-23.14
+snapshot: lts-23.24
 packages:
 - text-2.0.2
 flags:

@@ -83,7 +83,7 @@ 
 The project's `stack.yaml` file only needs to identify a snapshot:
 ~~~yaml
-snapshot: lts-23.14 # GHC 9.8.4
+snapshot: lts-23.24 # 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-23.14 # GHC 9.8.4
+snapshot: lts-23.24 # GHC 9.8.4
 ~~~
 
 This example project can be built with Stack in the normal way (`stack build`),

@@ -62,7 +62,7 @@ 
 ~~~yaml
 extra-deps:
-- acme-missiles-0.3@sha256:2ba66a092a32593880a87fb00f3213762d7bca65a687d45965778deb8694c5d1,631
+- acme-missiles-0.3@sha256:2ba66a092a32593880a87fb00f3213762d7bca65a687d45965778deb8694c5d1,613
 ~~~
 
 Optionally, you can specify also the Pantry tree information. For example:

@@ -19,7 +19,7 @@ 
 ~~~haskell
 #!/usr/bin/env stack
--- stack script --snapshot lts-23.14 --package turtle
+-- stack script --snapshot lts-23.24 --package turtle
 {-# LANGUAGE OverloadedStrings #-}
 import Turtle (echo)
 main = echo "Hello World!"
@@ -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 23.14 snapshot
-(`--snapshot lts-23.14`) and ensuring the
+command with the options of a LTS Haskell 23.24 snapshot
+(`--snapshot lts-23.24`) 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-23.14` provides `turtle-1.6.2`).
+snapshot (`lts-23.24` provides `turtle-1.6.2`).
 
 ## Arguments and interpreter options and arguments
 
@@ -117,7 +117,7 @@ ~~~haskell
 #!/usr/bin/env stack
 {- stack script
-   --snapshot lts-23.14
+   --snapshot lts-23.24
    --
    +RTS -s -RTS
 -}
@@ -133,12 +133,14 @@ is equivalent to the following command at the command line:
 
 ~~~text
-stack script --snapshot lts-23.14 -- MyScript.hs arg1 arg2 +RTS -s -RTS
+stack script --snapshot lts-23.24 -- MyScript.hs arg1 arg2 +RTS -s -RTS
 ~~~
 
 where `+RTS -s -RTS` are some of GHC's
 [runtime system (RTS) options](https://downloads.haskell.org/~ghc/latest/docs/users_guide/runtime_control.html).
 
+Arguments that include spaces can be quoted using double quotation marks.
+
 ## Just-in-time compilation
 
 As with using [`stack script`](../commands/script_command.md) at the command
@@ -162,13 +164,31 @@ ~~~haskell
 #!/usr/bin/env stack
 {- stack script
-   --snapshot lts-23.14
+   --snapshot lts-23.24
    --package turtle
    --package "stm async"
    --package http-client,http-conduit
 -}
 ~~~
 
+## Using extra-deps
+
+As with using [`stack script`](../commands/script_command.md) at the command
+line, you can also specify one or more extra-deps using a valid YAML value for
+each. For example:
+
+~~~haskell
+#!/usr/bin/env stack
+{- stack script
+   --snapshot lts-23.24
+   --extra-dep acme-missiles-0.3@rev:0
+   --extra-dep "{git: git@github.com:yesodweb/wai, commit: '2f8a8e1b771829f4a8a77c0111352ce45a14c30f', subdirs: [auto-update, wai]}"
+-}
+~~~
+
+Relative paths to local archive files are assumed to be relative to the
+directory in which the script file is located.
+
 ## Stack configuration for scripts
 
 When using the [`stack script`](../commands/script_command.md) command, as when
@@ -207,7 +227,7 @@ 
 ~~~haskell
 {- stack script
-   --snapshot lts-23.14
+   --snapshot lts-23.24
    --package acme-missiles
 -}
 import Acme.Missiles (launchMissiles)
@@ -218,7 +238,7 @@ 
 The command `stack --script-no-run-compile Script.hs` then behaves as if the
 command
-`stack script --snapshot lts-23.14 --package acme-missiles --no-run --compile -- Script.hs`
+`stack script --snapshot lts-23.24 --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 +280,7 @@ {- stack
   runghc
   --install-ghc
-  --snapshot lts-23.14
+  --snapshot lts-23.24
   --package base
   --package turtle
   --
@@ -284,7 +304,7 @@ {- stack
    exec ghci
    --install-ghc
-   --snapshot lts-23.14
+   --snapshot lts-23.24
    --package turtle
 -}
 ~~~

@@ -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-23.14>, you will see a list of 3,198 packages at
-specific version numbers. When you then specify `snapshot: lts-23.14` or,
-alternatively, `resolver: lts-23.14`, you're telling Stack to use those package
+<https://www.stackage.org/lts-23.24>, you will see a list of 3,212 packages at
+specific version numbers. When you then specify `snapshot: lts-23.24` or,
+alternatively, `resolver: lts-23.24`, 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

@@ -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-23.14`, as is currently the latest LTS)
+* The appropriate value (`lts-23.24`, 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

@@ -12,34 +12,178 @@ is typically used. It will not teach Haskell or involve much code, and it
 requires no prior experience of Stack or other Haskell tools.
 
-??? question "What are other Haskell tools?"
-
-    Haskell code is compiled by the
-    [Glasgow Haskell Compiler](https://www.haskell.org/ghc/) (GHC), which can
-    also be used interactively. Stack can manage versions of GHC. GHC provides
-    commands such as `ghc`, `ghci`, `runghc` and `ghc-pkg`.
-
-    Cabal (the tool) is a tool provided by the
-    [`cabal-install`](https://hackage.haskell.org/package/cabal-install) Haskell
-    package. It aims to simplify the process of managing Haskell software by
-    automating the fetching, configuration, compilation and installation of
-    Haskell libraries and programs. These are goals that Stack shares. Stack can
-    be used independently of Cabal (the tool) but users can also use both, if
-    they wish.
-
-    Haskell Language Server (HLS) is an implementation of the Language Server
-    Protocol for Haskell and used by Haskell extensions for code editors.
-
-    [GHCup](https://www.haskell.org/ghcup/) is a tool that can manage other
-    Haskell tools, including Stack, GHC, HLS and Cabal (the tool). Stack can use
-    GHCup to manage versions of GHC, as well as manage GHC directly.
-
 Terms used in the guide will be explained as they are introduced and are also
 defined in the [glossary](../glossary.md).
 
 Some of Stack's features will not be needed regularly or by all users. Other
 parts of Stack's documentation include its [commands](../commands/index.md) and
 its [configuration](../configure/index.md).
+
+## Other Haskell tools
+
+First, simplifying greatly, lets briefly place Stack and other Haskell tools in
+the Haskell landscape.
+
+Haskell was specified in the
+[Haskell 98 Language and Library Reports](https://www.haskell.org/onlinereport/),
+first published in February 1999, and further specified in the
+[Haskell 2010 Language Report](https://www.haskell.org/onlinereport/haskell2010/),
+published in April 2010. Extensions to the language have been developed (see
+below).
+
+The Haskell compiler is **GHC** (the
+[Glasgow Haskell Compiler](https://www.haskell.org/ghc/)). It can compile
+Haskell code into executable and other binary files. GHC can also be used
+interactively (**GHCi**) and Stack supports such use.
+
+~~~mermaid
+flowchart LR
+  code@{ shape: docs, label: "Haskell code" }
+  ghc[GHC]
+  binaries@{ shape: docs, label: "Executable and other binary files" }
+  code --> ghc --> binaries
+~~~
+
+Haskell code can be organised into *packages*. A Haskell package also includes a
+file that describes the package's contents. The most established description
+format is known as a
+[Cabal file](https://cabal.readthedocs.io/en/stable/file-format-changelog.html).
+The [**Hpack** project](https://github.com/sol/hpack) provides a modern
+alternative format (in a file named `package.yaml`) and a library and
+application that translates from that format to the legacy format. Stack has
+built-in support for Hpack. Other build tools (see below) do not.
+
+~~~mermaid
+flowchart LR
+  packageYaml@{ shape: doc, label: "package.yaml" }
+  hpack[Hpack]
+  cabalFile@{ shape: doc, label: "Cabal file" }
+  packageYaml --> hpack --> cabalFile
+~~~
+
+The code in a Haskell package is organised into *components*, including
+components known as *libraries*. Historically, a package had no more than one
+library component. The Cabal specification has developed to allow a package to
+have named *sub-library* components as well as a main library.
+
+The code in a Haskell package can depend on the libraries in the same package
+or in another package. These are known as its *dependencies*.
+
+Two important public databases are **Hackage**
+[(the  Haskell Package Repository)](https://hackage.haskell.org/) and
+[**Stackage**](https://hackage.haskell.org/).
+
+~~~mermaid
+flowchart LR
+  hackage@{ shape: lin-cyl, label: "Hackage
+    (packages)" }
+  stackage@{ shape: lin-cyl, label: "Stackage
+    (snapshots)" }
+  hackage --> stackage
+~~~
+
+Hackage is a database of Haskell packages, each identified by a name and version
+number. Stackage is a database of collections of Haskell package versions on
+Hackage that are known, by testing, to work well together and with a specific
+version of GHC. Those collections are known as *snapshots*. Stack can unpack
+packages from, and upload packages to, Hackage and builds making use of
+snapshots from Stackage.
+
+GHC comes with the libraries of certain Haskell packages (known as
+*boot packages*) already installed in its global database of installed
+libraries. These include the library of the
+[package `base`](https://hackage.haskell.org/package/base), which
+is a dependency of almost all other packages, and the library of
+[package `Cabal`](https://hackage.haskell.org/package/Cabal), which provides
+code to build packages and components of packages using GHC.
+
+GHC comes with an application
+[**Haddock**](https://haskell-haddock.readthedocs.io/latest/) that automatically
+generates web page and other documentation from annotated Haskell code. The
+Hackage and Stackage websites display that documentation. Stack supports the use
+of Haddock.
+
+~~~mermaid
+flowchart LR
+  code@{ shape: docs, label: "Haskell code" }
+  haddock[Haddock]
+  docs@{ shape: docs, label: "Documentation" }
+  code --> haddock --> docs
+~~~
+
+**Hoogle** is a [website](https://hoogle.haskell.org/) and an
+[application](https://hackage.haskell.org/package/hoogle) that allows its users
+to search for the library components of Haskell packages, the modules they
+expose, and functions and types exported by modules. Stack supports the use of
+Hoogle on the command line.
+
+GHC is described in its
+[User Guide](https://downloads.haskell.org/ghc/latest/docs/users_guide/). It can
+be used directly but it is a complex application with many flags and options.
+These include flags to specify extensions to the Haskell language.  Haskell
+*build tools* are applications that make it easier to use GHC, including by
+applying sensible defaults. Stack is such a build tool. Stack itself uses
+the Cabal library to build.
+
+~~~mermaid
+flowchart LR
+  stack[Stack]
+  cabal["Cabal (the library)"]
+  code@{ shape: docs, label: "Haskell code" }
+  ghc[GHC]
+  binaries@{ shape: docs, label: "Executable and other files" }
+  subgraph buildtool ["Build tool"]
+      direction TB
+      stack --> cabal --> ghc
+  end
+  code --> buildtool --> binaries
+~~~
+
+When Haskell code changes, GHC and build tools aim to minimise what needs to be
+re-compiled.
+
+A Stack project may comprise only a single package, but Stack can also handle
+multi-package projects.
+
+Another build tool is **Cabal** (the tool) (named after the library). It is
+provided by the
+[`cabal-install`](https://hackage.haskell.org/package/cabal-install)
+Haskell package. Stack can be used independently of Cabal (the tool) but users
+can also use both, if they wish.
+
+Some popular code editors (including
+[Visual Studio Code](https://code.visualstudio.com/)) have extensions that
+support Haskell coding by providing an integrated development environment (IDE).
+Those extensions use **HLS** (the
+[Haskell Language Server](https://haskell-language-server.readthedocs.io/en/stable/)),
+an application that implements the Language Server Protocol for Haskell.
+
+Stack can manage versions of GHC and upgrade/downgrade Stack itself and is, in
+that sense, an *installer* of those applications as well as a build tool.
+However, Cabal (the tool) is not an installer and versions of HLS applicable to
+versions of GHC also need to be installed.
+[**GHCup**](https://www.haskell.org/ghcup/) is an installer of versions of GHC,
+HLS, Stack and Cabal (the tool) built for various operating systems and machine
+architectures. Stack can be configured to manage versions of GHC by using GHCup.
+
+~~~mermaid
+flowchart TD
+  ghcUp["GHCup
+    installer"]
+  ghc["GHC
+    compiler"]
+  hls["HLS
+    IDE tool"]
+  stack["Stack
+    build tool, installer"]
+  cabal["Cabal (the tool)
+    build tool"]
+  ghcUp -.-> ghc
+  ghcUp -.-> hls
+  ghcUp -.-> stack
+  stack -- "(optional) to fetch GHC" --> ghcUp
+  ghcUp -.-> cabal
+~~~
 
 ## Setting up
 

@@ -35,7 +35,7 @@ 
 ~~~yaml
 snapshot:
-  url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/23/8.yaml
+  url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/23/24.yaml
 packages:
 - .
 ~~~
@@ -44,7 +44,7 @@ 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.14](https://www.stackage.org/lts-23.14), which implies GHC 9.8.4
+[LTS Haskell 23.24](https://www.stackage.org/lts-23.24), 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.

@@ -3,8 +3,15 @@ {-# LANGUAGE NoFieldSelectors      #-}
 {-# LANGUAGE OverloadedRecordDot   #-}
 
--- Concurrent execution with dependencies. Types currently hard-coded for needs
--- of stack, but could be generalized easily.
+{-|
+Module      : Control.Concurrent.Execute
+Description : Concurrent execution with dependencies.
+License     : BSD-3-Clause
+
+Concurrent execution with dependencies. Types currently hard-coded for needs of
+stack, but could be generalized easily.
+-}
+
 module Control.Concurrent.Execute
     ( ActionType (..)
     , ActionId (..)
@@ -34,9 +41,9 @@ data ActionType
   = ATBuild
     -- ^ Action for building a package's library and executables. If
-    -- 'taskAllInOne' is 'True', then this will also build benchmarks and tests.
-    -- It is 'False' when the library's benchmarks or test-suites have cyclic
-    -- dependencies.
+    -- 'Stack.Types.Build.Task.allInOne' is 'True', then this will also build
+    -- benchmarks and tests. It is 'False' when the library's benchmarks or
+    -- test-suites have cyclic dependencies.
   | ATBuildFinal
     -- ^ Task for building the package's benchmarks and test-suites. Requires
     -- that the library was already built.

@@ -1,7 +1,14 @@ {-# LANGUAGE NoImplicitPrelude #-}
 {-# LANGUAGE OverloadedStrings #-}
 
--- | Parsing of Stack command line arguments
+{-|
+Module      : Data.Attoparsec.Args
+Description : Parsing of Stack command line arguments.
+License     : BSD-3-Clause
+
+Parsing of Stack command line arguments.
+-}
+
 module Data.Attoparsec.Args
   ( EscapingMode (..)
   , argsParser

@@ -1,6 +1,13 @@ {-# LANGUAGE NoImplicitPrelude #-}
 
--- | More readable combinators for writing parsers.
+{-|
+Module      : Data.Attoparsec.Combinators
+Description : More readable combinators for writing parsers.
+License     : BSD-3-Clause
+
+More readable combinators for writing parsers.
+-}
+
 module Data.Attoparsec.Combinators
   ( alternating
   , appending

@@ -1,36 +1,41 @@ {-# LANGUAGE NoImplicitPrelude #-}
 {-# LANGUAGE OverloadedStrings #-}
 
-{- |  This module implements parsing of additional arguments embedded in a
-      comment when Stack is invoked as a script interpreter
+{-|
+Module      : Data.Attoparsec.Interpreter
+License     : BSD-3-Clause
 
-  ===Specifying arguments in script interpreter mode
-  @/stack/@ can execute a Haskell source file using @/runghc/@ and if required
-  it can also install and setup the compiler and any package dependencies
-  automatically.
+This module implements parsing of additional arguments embedded in a comment
+when Stack is invoked as a script interpreter
 
-  For using a Haskell source file as an executable script on a Unix like OS,
-  the first line of the file must specify @stack@ as the interpreter using a
-  shebang directive e.g.
+=== Specifying arguments in script interpreter mode
 
-  > #!/usr/bin/env stack
+@/stack/@ can execute a Haskell source file using @/runghc/@ and if required it
+can also install and setup the compiler and any package dependencies
+automatically.
 
-  Additional arguments can be specified in a haskell comment following the
-  @#!@ line. The contents inside the comment must be a single valid stack
-  command line, starting with @stack@ as the command and followed by the
-  options to use for executing this file.
+For using a Haskell source file as an executable script on a Unix like OS, the
+first line of the file must specify @stack@ as the interpreter using a shebang
+directive e.g.
 
-  The comment must be on the line immediately following the @#!@ line. The
-  comment must start in the first column of the line. When using a block style
-  comment the command can be split on multiple lines.
+> #!/usr/bin/env stack
 
-  Here is an example of a single line comment:
+Additional arguments can be specified in a haskell comment following the @#!@
+line. The contents inside the comment must be a single valid stack command line,
+starting with @stack@ as the command and followed by the options to use for
+executing this file.
 
-  > #!/usr/bin/env stack
-  > -- stack --snapshot lts-3.14 --install-ghc runghc --package random
+The comment must be on the line immediately following the @#!@ line. The
+comment must start in the first column of the line. When using a block style
+comment the command can be split on multiple lines.
 
-  Here is an example of a multi line block comment:
+Here is an example of a single line comment:
 
+> #!/usr/bin/env stack
+> -- stack --snapshot lts-3.14 --install-ghc runghc --package random
+
+Here is an example of a multi line block comment:
+
 @
   #!\/usr\/bin\/env stack
   {\- stack
@@ -41,13 +46,13 @@   -\}
 @
 
-  When the @#!@ line is not present, the file can still be executed
-  using @stack \<file name\>@ command if the file starts with a valid stack
-  interpreter comment. This can be used to execute the file on Windows for
-  example.
+When the @#!@ line is not present, the file can still be executed using
+@stack \<file name\>@ command if the file starts with a valid stack interpreter
+comment. This can be used to execute the file on Windows for example.
 
-  Nested block comments are not supported.
+Nested block comments are not supported.
 -}
+
 module Data.Attoparsec.Interpreter
   ( interpreterArgsParser -- for unit tests
   , getInterpreterArgs

@@ -1,3 +1,8 @@+{-|
+Module      : Data.Monoid.Map
+License     : BSD-3-Clause
+-}
+
 module Data.Monoid.Map
   ( MonoidMap (..)
   ) where

@@ -10,25 +10,31 @@ {-# LANGUAGE ScopedTypeVariables   #-}
 {-# LANGUAGE TupleSections         #-}
 
--- This module is based on GHC's utils\ghc-pkg\Main.hs at
--- commit f66fc15f2e6849125074bcfeb44334a663323ca6 (see GHC merge request
--- !11142), with:
--- * changeDBDir' does not perform an effective @ghc-pkg recache@,
--- * the cache is not used,
--- * consistency checks are not performed,
--- * use Stack program name,
--- * use "Stack.Prelude" rather than "Prelude",
--- * use 'RIO' @env@ monad,
--- * use well-typed representations of paths from the @path@ package,
--- * add pretty messages and exceptions,
--- * redundant code deleted,
--- * Hlint applied, and
--- * explicit import lists.
---
--- The version of the ghc-pkg executable supplied with GHCs published before
--- 28 August 2023 does not efficiently bulk unregister. This module exports a
--- function that does efficiently bulk unregister.
+{-|
+Module      : GHC.Utils.GhcPkg.Main.Compat
+License     : BSD-3-Clause
 
+This module is based on GHC's utils\ghc-pkg\Main.hs at
+commit f66fc15f2e6849125074bcfeb44334a663323ca6 (see GHC merge request !11142),
+with:
+
+* changeDBDir' does not perform an effective @ghc-pkg recache@,
+* the cache is not used,
+* consistency checks are not performed,
+* use Stack program name,
+* use "Stack.Prelude" rather than "Prelude",
+* use t'RIO' @env@ monad,
+* use well-typed representations of paths from the @path@ package,
+* add pretty messages and exceptions,
+* redundant code deleted,
+* Hlint applied, and
+* explicit import lists.
+
+The version of the ghc-pkg executable supplied with GHCs published before
+28 August 2023 does not efficiently bulk unregister. This module exports a
+function that does efficiently bulk unregister.
+-}
+
 module GHC.Utils.GhcPkg.Main.Compat
   ( ghcPkgUnregisterForce
   ) where
@@ -63,6 +69,10 @@ import qualified RIO.NonEmpty as NE
 import           Stack.Constants ( relFilePackageCache )
 import           Stack.Prelude hiding ( display )
+import           Stack.Types.GhcPkgExe
+                   ( GhcPkgPrettyException (..), GlobPackageIdentifier (..)
+                   , PackageArg (..)
+                   )
 import           System.Environment ( getEnv )
 import           System.FilePath as FilePath
 import           System.IO ( readFile )
@@ -91,83 +101,6 @@  where
   as_arg = if hasIpid then AsUnitId else AsDefault
 
--- | Type representing \'pretty\' exceptions thrown by functions exported by the
--- "GHC.Utils.GhcPkg.Main.Compat" module.
-data GhcPkgPrettyException
-  = CannotParse !String !String !String
-  | CannotOpenDBForModification !(SomeBase Dir) !IOException
-  | SingleFileDBUnsupported !(SomeBase Dir)
-  | ParsePackageInfoExceptions !String
-  | CannotFindPackage !PackageArg !(Maybe (SomeBase Dir))
-  | CannotParseRelFileBug !String
-  | CannotParseDirectoryWithDBug !String
-  deriving (Show, Typeable)
-
-instance Pretty GhcPkgPrettyException where
-  pretty (CannotParse str what e) =
-    "[S-6512]"
-    <> line
-    <> fillSep
-         [ flow "cannot parse"
-         , style Current (fromString str)
-         , flow "as a"
-         , fromString what <> ":"
-         ]
-    <> blankLine
-    <> fromString e
-  pretty (CannotOpenDBForModification db_path e) =
-    "[S-3384]"
-    <> line
-    <> fillSep
-         [ flow "Couldn't open database"
-         , pretty db_path
-         , flow "for modification:"
-         ]
-    <> blankLine
-    <> string (displayException e)
-  pretty (SingleFileDBUnsupported path) =
-    "[S-1430]"
-    <> line
-    <> fillSep
-         [ flow "ghc no longer supports single-file style package databases"
-         , parens (pretty path)
-         , "use"
-         , style Shell (flow "ghc-pkg init")
-         , flow "to create the database with the correct format."
-         ]
-  pretty (ParsePackageInfoExceptions errs) =
-    "[S-5996]"
-    <> line
-    <> flow errs
-  pretty (CannotFindPackage pkgarg mdb_path) =
-    "[S-3189]"
-    <> line
-    <> fillSep
-         [ flow "cannot find package"
-         , style Current (pkg_msg pkgarg)
-         , maybe
-             ""
-             (\db_path -> fillSep ["in", pretty db_path])
-             mdb_path
-         ]
-   where
-    pkg_msg (Substring pkgpat _) = fillSep ["matching", fromString pkgpat]
-    pkg_msg pkgarg' = fromString $ show pkgarg'
-  pretty (CannotParseRelFileBug relFileName) = bugPrettyReport "[S-9323]" $
-    fillSep
-      [ flow "changeDBDir': Could not parse"
-      , style File (fromString relFileName)
-      , flow "as a relative path to a file."
-      ]
-  pretty (CannotParseDirectoryWithDBug dirName) = bugPrettyReport "[S-7651]" $
-    fillSep
-      [ flow "adjustOldDatabasePath: Could not parse"
-      , style Dir (fromString dirName)
-      , flow "as a directory."
-      ]
-
-instance Exception GhcPkgPrettyException
-
 -- -----------------------------------------------------------------------------
 -- Do the business
 
@@ -176,39 +109,12 @@   = AsUnitId
   | AsDefault
 
--- | Represents how a package may be specified by a user on the command line.
-data PackageArg
-    -- | A package identifier foo-0.1, or a glob foo-*
-  = Id GlobPackageIdentifier
-    -- | An installed package ID foo-0.1-HASH.  This is guaranteed to uniquely
-    -- match a single entry in the package database.
-  | IUId UnitId
-    -- | A glob against the package name.  The first string is the literal
-    -- glob, the second is a function which returns @True@ if the argument
-    -- matches.
-  | Substring String (String -> Bool)
-
-instance Show PackageArg where
-  show (Id pkgid) = displayGlobPkgId pkgid
-  show (IUId ipid) = display ipid
-  show (Substring pkgpat _) = pkgpat
-
 parseCheck :: Cabal.Parsec a => String -> String -> RIO env a
 parseCheck str what =
   case Cabal.eitherParsec str of
     Left e  -> prettyThrowIO $ CannotParse str what e
     Right x -> pure x
 
--- | Either an exact 'PackageIdentifier', or a glob for all packages
--- matching 'PackageName'.
-data GlobPackageIdentifier
-  = ExactPackageIdentifier MungedPackageId
-  | GlobPackageIdentifier  MungedPackageName
-
-displayGlobPkgId :: GlobPackageIdentifier -> String
-displayGlobPkgId (ExactPackageIdentifier pid) = display pid
-displayGlobPkgId (GlobPackageIdentifier pn) = display pn ++ "-*"
-
 readGlobPkgId :: String -> RIO env GlobPackageIdentifier
 readGlobPkgId str = case stripSuffix "-*" str of
   Nothing ->
@@ -237,8 +143,8 @@ -- | A stack of package databases. Convention: head is the topmost in the stack.
 type PackageDBStack = [PackageDB 'GhcPkg.DbReadOnly]
 
--- | Selector for picking the right package DB to modify as 'modify' changes the
--- first database that contains a specific package.
+-- | Selector for picking the right package DB to modify as \'modify\' changes
+-- the first database that contains a specific package.
 newtype DbModifySelector = ContainsPkg PackageArg
 
 getPkgDatabases ::

@@ -2,9 +2,14 @@ {-# LANGUAGE LambdaCase        #-}
 {-# LANGUAGE OverloadedStrings #-}
 
--- |
--- Wrapper functions of 'Network.HTTP.Simple' and 'Network.HTTP.Client' to
--- add the 'User-Agent' HTTP request header to each request.
+{-|
+Module      : Network.HTTP.StackClient
+License     : BSD-3-Clause
+
+Wrapper functions of 'Network.HTTP.Simple' and 'Network.HTTP.Client' to add the
+'User-Agent' HTTP request header to each request.
+-}
+
 module Network.HTTP.StackClient
   ( httpJSON
   , httpLbs
@@ -112,22 +117,24 @@ import           RIO.PrettyPrint ( HasTerm )
 import           Text.Printf ( printf )
 
+-- | Set the User-Agent request header to @The Haskell Stack@.
 setUserAgent :: Request -> Request
 setUserAgent = setRequestHeader "User-Agent" ["The Haskell Stack"]
 
-
+-- | Like 'Network.HTTP.Simple.httpJSON' but sets the User-Agent request header.
 httpJSON :: (MonadIO m, FromJSON a) => Request -> m (Response a)
 httpJSON = Network.HTTP.Simple.httpJSON . setUserAgent
 
-
+-- | Like 'Network.HTTP.Simple.httpLbs' but sets the User-Agent request header.
 httpLbs :: MonadIO m => Request -> m (Response LByteString)
 httpLbs = Network.HTTP.Simple.httpLbs . setUserAgent
 
-
+-- | Like 'Network.HTTP.Simple.httpNoBody' but sets the User-Agent request
+-- header.
 httpNoBody :: MonadIO m => Request -> m (Response ())
 httpNoBody = Network.HTTP.Simple.httpNoBody . setUserAgent
 
-
+-- | Like 'Network.HTTP.Simple.httpSink' but sets the User-Agent request header.
 httpSink ::
      MonadUnliftIO m
   => Request
@@ -135,7 +142,8 @@   -> m a
 httpSink = Network.HTTP.Simple.httpSink . setUserAgent
 
-
+-- | Like 'Network.HTTP.Simple.withResponse' but sets the User-Agent request
+-- header.
 withResponse ::
      (MonadUnliftIO m, MonadIO n)
   => Request
@@ -143,7 +151,7 @@   -> m a
 withResponse = Network.HTTP.Simple.withResponse . setUserAgent
 
--- | Set the user-agent request header
+-- | Set the Accept request header to specify GitHub API v3.
 setGitHubHeaders :: Request -> Request
 setGitHubHeaders = setRequestHeader "Accept" ["application/vnd.github.v3+json"]
 

@@ -1,7 +1,13 @@ {-# LANGUAGE NoImplicitPrelude #-}
 {-# LANGUAGE OverloadedStrings #-}
 
--- | Accepting arguments to be passed through to a sub-process.
+{-|
+Module      : Options.Applicative.Args
+Description : Accepting arguments to be passed through to a sub-process.
+License     : BSD-3-Clause
+
+Accepting arguments to be passed through to a sub-process.
+-}
 
 module Options.Applicative.Args
   ( argsArgument

@@ -2,8 +2,14 @@ {-# LANGUAGE NoFieldSelectors    #-}
 {-# LANGUAGE OverloadedRecordDot #-}
 
--- | Extra functions for optparse-applicative.
+{-|
+Module      : Options.Applicative.Builder.Extra
+Description : Extra functions for optparse-applicative.
+License     : BSD-3-Clause
 
+Extra functions for optparse-applicative.
+-}
+
 module Options.Applicative.Builder.Extra
   ( boolFlags
   , boolFlagsNoDefault
@@ -245,15 +251,15 @@ textArgument :: Mod ArgumentFields Text -> Parser Text
 textArgument = argument (T.pack <$> readerAsk)
 
--- | Like 'optional', but returning a 'First'.
+-- | Like 'optional', but returning a t'First'.
 optionalFirst :: Alternative f => f a -> f (First a)
 optionalFirst = fmap First . optional
 
--- | Like 'optional', but returning a 'FirstTrue'.
+-- | Like 'optional', but returning a t'FirstTrue'.
 optionalFirstTrue :: Alternative f => f Bool -> f FirstTrue
 optionalFirstTrue = fmap FirstTrue . optional
 
--- | Like 'optional', but returning a 'FirstFalse'.
+-- | Like 'optional', but returning a t'FirstFalse'.
 optionalFirstFalse :: Alternative f => f Bool -> f FirstFalse
 optionalFirstFalse = fmap FirstFalse . optional
 

@@ -1,12 +1,17 @@ {-# LANGUAGE NoImplicitPrelude #-}
 
--- | Simple interface to complicated program arguments.
---
--- This is a "fork" of the @optparse-simple@ package that has some workarounds
--- for optparse-applicative issues that become problematic with programs that
--- have many options and subcommands. Because it makes the interface more
--- complex, these workarounds are not suitable for pushing upstream to
--- optparse-applicative.
+{-|
+Module      : Options.Applicative.Complicated
+Description : Simple interface to complicated program arguments.
+License     : BSD-3-Clause
+
+Simple interface to complicated program arguments.
+
+This is a "fork" of the @optparse-simple@ package that has some workarounds for
+optparse-applicative issues that become problematic with programs that have many
+options and subcommands. Because it makes the interface more complex, these
+workarounds are not suitable for pushing upstream to optparse-applicative.
+-}
 
 module Options.Applicative.Complicated
   ( addCommand

@@ -1,6 +1,11 @@ {-# LANGUAGE NoImplicitPrelude #-}
 {-# LANGUAGE OverloadedStrings #-}
 
+{-|
+Module      : Path.CheckInstall
+License     : BSD-3-Clause
+-}
+
 module Path.CheckInstall
   ( warnInstallSearchPathIssues
   ) where

@@ -1,26 +0,0 @@-module Path.Extended
-  ( fileExtension
-  , addExtension
-  , replaceExtension
-  ) where
-
-import           Control.Monad.Catch ( MonadThrow )
-import qualified Path ( addExtension, fileExtension, replaceExtension )
-import           Path ( File, Path )
-
-fileExtension :: MonadThrow m => Path b File -> m String
-fileExtension = Path.fileExtension
-
-addExtension ::
-     MonadThrow m
-  => String
-  -> Path b File
-  -> m (Path b File)
-addExtension = Path.addExtension
-
-replaceExtension ::
-     MonadThrow m
-  => String
-  -> Path b File
-  -> m (Path b File)
-replaceExtension ext = Path.replaceExtension ('.' : ext)

@@ -1,7 +1,12 @@ {-# LANGUAGE NoImplicitPrelude #-}
 {-# LANGUAGE ViewPatterns      #-}
 
--- | Extra Path utilities.
+{-|
+Module      : Path.Extra
+Description : Extra Path utilities.
+License     : BSD-3-Clause
+-}
+
 module Path.Extra
   ( toFilePathNoTrailingSep
   , parseCollapsedAbsDir
@@ -88,16 +93,16 @@   checkPathSeparator _ = False
 
 -- | If given file in 'Maybe' does not exist, ensure we have 'Nothing'. This
--- is to be used in conjunction with 'forgivingAbsence' and
--- 'resolveFile'.
+-- is to be used in conjunction with 'Path.IO.forgivingAbsence' and
+-- 'Path.IO.resolveFile'.
 --
--- Previously the idiom @forgivingAbsence (resolveFile …)@ alone was used,
--- which relied on 'canonicalizePath' throwing 'isDoesNotExistError' when
--- path does not exist. As it turns out, this behavior is actually not
--- intentional and unreliable, see
--- <https://github.com/haskell/directory/issues/44>. This was “fixed” in
--- version @1.2.3.0@ of @directory@ package (now it never throws). To make
--- it work with all versions, we need to use the following idiom:
+-- Previously the idiom @forgivingAbsence (resolveFile …)@ alone was used, which
+-- relied on 'Path.IO.canonicalizePath' throwing 'isDoesNotExistError' when path
+-- does not exist. As it turns out, this behavior is actually not intentional
+-- and unreliable, see <https://github.com/haskell/directory/issues/44>. This
+-- was “fixed” in version @1.2.3.0@ of @directory@ package (now it never
+-- throws). To make it work with all versions, we need to use the following
+-- idiom:
 --
 -- > forgivingAbsence (resolveFile …) >>= rejectMissingFile
 
@@ -125,15 +130,26 @@ pathToByteString :: Path b t -> BS.ByteString
 pathToByteString = T.encodeUtf8 . pathToText
 
+-- | Convert to a 'T.Text' type.
 pathToText :: Path b t -> T.Text
 pathToText = T.pack . toFilePath
 
+-- | Attempt to get the time at which the given file was last modified. Yields
+-- `Left ()` if the file does not exist.
+--
+-- The operation may fail with 'System.IO.Error.isPermissionError' if the user
+-- is not permitted to read the modification time.
+--
+-- Caveat for POSIX systems: This function returns a timestamp with sub-second
+-- resolution only if this package is compiled against `unix-2.6.0.0` or later
+-- and the underlying filesystem supports them.
 tryGetModificationTime :: MonadIO m => Path Abs File -> m (Either () UTCTime)
 tryGetModificationTime =
   liftIO . tryJust (guard . isDoesNotExistError) . getModificationTime
 
 -- | 'Path.IO.resolveDir' (@path-io@ package) throws 'InvalidAbsDir' (@path@
--- package) if the directory does not exist; this function yields 'Nothing'.
+-- package) in certain circumstances; this function yields 'Nothing' in those
+-- circumstances.
 forgivingResolveDir ::
      MonadIO m
   => Path Abs Dir
@@ -151,7 +167,8 @@       )
 
 -- | 'Path.IO.resolveFile' (@path-io@ package) throws 'InvalidAbsFile' (@path@
--- package) if the file does not exist; this function yields 'Nothing'.
+-- package) in certain circumstances; this function yields 'Nothing' in those
+-- circumstances.
 forgivingResolveFile ::
      MonadIO m
   => Path Abs Dir
@@ -169,7 +186,8 @@       )
 
 -- | 'Path.IO.resolveFile'' (@path-io@ package) throws 'InvalidAbsFile' (@path@
--- package) if the file does not exist; this function yields 'Nothing'.
+-- package) in certain circumstances; this function yields 'Nothing' in those
+-- circumstances.
 forgivingResolveFile' ::
      MonadIO m
   => FilePath

@@ -1,7 +1,13 @@ {-# LANGUAGE NoImplicitPrelude #-}
 {-# LANGUAGE DataKinds         #-}
 
--- | Finding files.
+{-|
+Module      : Path.Find
+Description : Finding files.
+License     : BSD-3-Clause
+
+Finding files.
+-}
 
 module Path.Find
   ( findFileUp

@@ -3,8 +3,14 @@ {-# LANGUAGE OverloadedRecordDot #-}
 {-# LANGUAGE OverloadedStrings   #-}
 
--- | Main Stack tool entry point.
+{-|
+Module      : Stack
+Description : Main Stack tool entry point.
+License     : BSD-3-Clause
 
+Main Stack tool entry point.
+-}
+
 module Stack
   ( main
   ) where
@@ -51,6 +57,7 @@     , actual
     ]
 
+-- | Main Stack tool entry point.
 main :: IO ()
 main = do
   -- Line buffer the output by default, particularly for non-terminal runs.

@@ -3,8 +3,14 @@ {-# LANGUAGE OverloadedRecordDot   #-}
 {-# LANGUAGE OverloadedStrings     #-}
 
--- | Build the project.
+{-|
+Module      : Stack.Build
+Description : Build the project.
+License     : BSD-3-Clause
 
+Build the project.
+-}
+
 module Stack.Build
   ( buildCmd
   , build
@@ -49,7 +55,6 @@                    ( buildOptsMonoidBenchmarksL, buildOptsMonoidHaddockL
                    , buildOptsMonoidInstallExesL, buildOptsMonoidTestsL
                    )
-import           Stack.Types.Compiler ( getGhcVersion )
 import           Stack.Types.CompilerPaths ( HasCompiler, cabalVersionL )
 import           Stack.Types.ComponentUtils
                    ( StackUnqualCompName, unqualCompToString )
@@ -71,7 +76,6 @@ import           Stack.Types.Runner ( Runner, globalOptsL )
 import           Stack.Types.SourceMap
                    ( SMTargets (..), SourceMap (..), Target (..) )
-import           System.Terminal ( fixCodePage )
 
 newtype CabalVersionPrettyException
   = CabalVersionNotSupported Version
@@ -150,91 +154,90 @@       => Maybe (Set (Path Abs File) -> IO ()) -- ^ callback after discovering all local files
       -> RIO env ()
 build msetLocalFiles = do
-  mcp <- view $ configL . to (.modifyCodePage)
-  ghcVersion <- view $ actualCompilerVersionL . to getGhcVersion
-  fixCodePage mcp ghcVersion $ do
-    bopts <- view buildOptsL
-    sourceMap <- view $ envConfigL . to (.sourceMap)
-    locals <- projectLocalPackages
-    depsLocals <- localDependencies
-    boptsCli <- view $ envConfigL . to (.buildOptsCLI)
-    -- Set local files, necessary for file watching
-    configFile <- view configFileL
-    let allLocals = locals <> depsLocals
-        -- We are indifferent as to whether the configuration file is a
-        -- user-specifc global or a project-level one.
-        eitherConfigFile = EE.fromEither configFile
-    for_ msetLocalFiles $ \setLocalFiles -> do
-      files <-
-        if boptsCli.watchAll
-        then sequence [lpFiles lp | lp <- allLocals]
-        else forM allLocals $ \lp -> do
-          let pn = lp.package.name
-          case Map.lookup pn sourceMap.targets.targets of
-            Nothing ->
-              pure Set.empty
-            Just (TargetAll _) ->
-              lpFiles lp
-            Just (TargetComps components) ->
-              lpFilesForComponents components lp
-      liftIO $ setLocalFiles $ Set.insert eitherConfigFile $ Set.unions files
+  bopts <- view buildOptsL
+  sourceMap <- view $ envConfigL . to (.sourceMap)
+  locals <- projectLocalPackages
+  depsLocals <- localDependencies
+  boptsCli <- view $ envConfigL . to (.buildOptsCLI)
+  -- Set local files, necessary for file watching
+  configFile <- view configFileL
+  let allLocals = locals <> depsLocals
+      -- We are indifferent as to whether the configuration file is a
+      -- user-specifc global or a project-level one.
+      eitherConfigFile = EE.fromEither configFile
+  for_ msetLocalFiles $ \setLocalFiles -> do
+    files <-
+      if boptsCli.watchAll
+      then sequence [lpFiles lp | lp <- allLocals]
+      else forM allLocals $ \lp -> do
+        let pn = lp.package.name
+        case Map.lookup pn sourceMap.targets.targets of
+          Nothing ->
+            pure Set.empty
+          Just (TargetAll _) ->
+            lpFiles lp
+          Just (TargetComps components) ->
+            lpFilesForComponents components lp
+    liftIO $ setLocalFiles $ Set.insert eitherConfigFile $ Set.unions files
 
-    checkComponentsBuildable allLocals
+  checkComponentsBuildable allLocals
 
-    installMap <- toInstallMap sourceMap
-    (installedMap, globalDumpPkgs, snapshotDumpPkgs, localDumpPkgs) <-
-        getInstalled installMap
+  installMap <- toInstallMap sourceMap
+  (installedMap, globalDumpPkgs, snapshotDumpPkgs, localDumpPkgs) <-
+      getInstalled installMap
 
-    baseConfigOpts <- mkBaseConfigOpts boptsCli
-    plan <- constructPlan
-              baseConfigOpts
-              localDumpPkgs
-              loadPackage
-              sourceMap
-              installedMap
-              boptsCli.initialBuildSteps
+  baseConfigOpts <- mkBaseConfigOpts boptsCli
+  plan <- constructPlan
+            baseConfigOpts
+            localDumpPkgs
+            loadPackage
+            sourceMap
+            installedMap
+            boptsCli.initialBuildSteps
 
-    allowLocals <- view $ configL . to (.allowLocals)
-    unless allowLocals $ case justLocals plan of
-      [] -> pure ()
-      localsIdents -> throwM $ LocalPackagesPresent localsIdents
+  allowLocals <- view $ configL . to (.allowLocals)
+  unless allowLocals $ case justLocals plan of
+    [] -> pure ()
+    localsIdents -> throwM $ LocalPackagesPresent localsIdents
 
-    checkCabalVersion
-    haddockCompsSupported <- warnAboutHaddockComps bopts
-    let disableHaddockComps =
-          local $ over buildOptsL $ \bo ->
-            bo
-              { haddockExecutables = False
-              , haddockTests = False
-              , haddockBenchmarks = False
-              }
-        withHaddockCompsGuarded = if haddockCompsSupported
-          then id
-          else disableHaddockComps
-    warnAboutSplitObjs bopts
-    warnIfExecutablesWithSameNameCouldBeOverwritten locals plan
+  checkCabalVersion
+  haddockCompsSupported <- warnAboutHaddockComps bopts
+  let disableHaddockComps =
+        local $ over buildOptsL $ \bo ->
+          bo
+            { haddockExecutables = False
+            , haddockTests = False
+            , haddockBenchmarks = False
+            }
+      withHaddockCompsGuarded = if haddockCompsSupported
+        then id
+        else disableHaddockComps
+  warnAboutSplitObjs bopts
+  warnIfExecutablesWithSameNameCouldBeOverwritten locals plan
 
-    when bopts.preFetch $
-        preFetch plan
+  when bopts.preFetch $
+      preFetch plan
 
-    if boptsCli.dryrun
-      then
-        printPlan plan
-      else
-        withHaddockCompsGuarded $ executePlan
-          boptsCli
-          baseConfigOpts
-          locals
-          globalDumpPkgs
-          snapshotDumpPkgs
-          localDumpPkgs
-          installedMap
-          sourceMap.targets.targets
-          plan
+  if boptsCli.dryrun
+    then
+      printPlan plan
+    else
+      withHaddockCompsGuarded $ executePlan
+        boptsCli
+        baseConfigOpts
+        locals
+        globalDumpPkgs
+        snapshotDumpPkgs
+        localDumpPkgs
+        installedMap
+        sourceMap.targets.targets
+        plan
 
+-- | Build one or more local targets.
 buildLocalTargets ::
      HasEnvConfig env
   => NonEmpty Text
+     -- ^ Local targets to build.
   -> RIO env (Either SomeException ())
 buildLocalTargets targets =
   tryAny $ withNewLocalBuildTargets (NE.toList targets) $ build Nothing
@@ -376,6 +379,7 @@     ]
 warnAboutSplitObjs _ = pure ()
 
+-- | Text warning about the experimental nature of Stack's @--split-objs@ flag.
 splitObjsWarning :: String
 splitObjsWarning =
   "Note that this feature is EXPERIMENTAL, and its behavior may be changed and \

@@ -3,7 +3,14 @@ {-# LANGUAGE OverloadedRecordDot #-}
 {-# LANGUAGE OverloadedStrings   #-}
 
--- | Cache information about previous builds
+{-|
+Module      : Stack.Build.Cache
+Description : Cache information about previous builds.
+License     : BSD-3-Clause
+
+Cache information about previous builds.
+-}
+
 module Stack.Build.Cache
   ( tryGetBuildCache
   , tryGetConfigCache
@@ -252,7 +259,7 @@   writeBinaryFileAtomic fp "Just used for its modification time"
   liftIO $ setFileTimes (toFilePath fp) x x
 
--- | See 'tryGetPackageProjectRoot'
+-- | See 'tryGetPackageProjectRoot'.
 writePackageProjectRoot ::
      HasEnvConfig env
   => Path Abs Dir
@@ -281,7 +288,7 @@     Executable ident -> pure $
       configCacheKey installationRoot (ConfigCacheTypeFlagExecutable ident)
 
--- | Loads the flag cache for the given installed extra-deps
+-- | Loads the flag cache for the given installed extra-deps.
 tryGetFlagCache ::
      HasEnvConfig env
   => Installed
@@ -290,6 +297,7 @@   key <- flagCacheKey gid
   loadConfigCache key
 
+-- | Write the flag cache for the given installed extra-deps.
 writeFlagCache ::
      HasEnvConfig env
   => Installed

@@ -5,7 +5,14 @@ {-# LANGUAGE OverloadedStrings     #-}
 {-# LANGUAGE ViewPatterns          #-}
 
--- | Construct a @Plan@ for how to build
+{-|
+Module      : Stack.Build.ConstructPlan
+Description : Construct a @Plan@ for how to build.
+License     : BSD-3-Clause
+
+Construct a @Plan@ for how to build.
+-}
+
 module Stack.Build.ConstructPlan
   ( constructPlan
   ) where
@@ -94,14 +101,14 @@                    )
 import           System.Environment ( lookupEnv )
 
--- | Computes a build plan. This means figuring out which build 'Task's to take,
--- and the interdependencies among the build 'Task's. In particular:
+-- | Computes a build plan. This means figuring out which build t'Task's to
+-- take, and the interdependencies among the build t'Task's. In particular:
 --
 -- 1) It determines which packages need to be built, based on the transitive
 -- deps of the current targets. For project packages, this is indicated by the
--- 'lpWanted' boolean. For extra packages to build, this comes from the
--- @extraToBuild0@ argument of type @Set PackageName@. These are usually
--- packages that have been specified on the command line.
+-- 'Stack.Types.Package.wanted' boolean. For extra packages to build, this comes
+-- from the @extraToBuild0@ argument of type @Set PackageName@. These are
+-- usually packages that have been specified on the command line.
 --
 -- 2) It will only rebuild an upstream package if it isn't present in the
 -- 'InstalledMap', or if some of its dependencies have changed.
@@ -415,8 +422,8 @@       relevantPkgName :: PackageName
       relevantPkgName = maybe (pkgName ident) pkgName mParentLibId
 
--- | Given a 'LocalPackage' and its 'lpTestBench', adds a 'Task' for running its
--- tests and benchmarks.
+-- | Given a t'LocalPackage' and its 'testBench', adds a t'Task' for running
+-- its tests and benchmarks.
 --
 -- If @isAllInOne@ is 'True', then this means that the build step will also
 -- build the tests. Otherwise, this indicates that there's a cyclic dependency
@@ -590,10 +597,10 @@       p <- ctx.loadPackage pkgLoc flags [] []
       tellExecutablesPackage loc p
 
--- | For given 'InstallLocation' and 'Package' values, adds relevant executables
--- to the collected output. In most cases, the relevant executables are all the
--- executables of the package. If the package is a wanted local one, the
--- executables are those executables that are wanted executables.
+-- | For given 'InstallLocation' and t'Package' values, adds relevant
+-- executables to the collected output. In most cases, the relevant executables
+-- are all the executables of the package. If the package is a wanted local one,
+-- the executables are those executables that are wanted executables.
 tellExecutablesPackage :: InstallLocation -> Package -> M ()
 tellExecutablesPackage loc p = do
   cm <- asks (.combinedMap)
@@ -619,8 +626,8 @@     | Set.null myComps = x
     | otherwise = Set.intersection x myComps
 
--- | Given a 'PackageSource' and perhaps an 'Installed' value, adds build
--- 'Task's for the package and its dependencies.
+-- | Given a 'PackageSource' and perhaps an 'Installed' value, adds
+-- build t'Task's for the package and its dependencies.
 installPackage ::
      PackageName
   -> PackageSource
@@ -715,7 +722,7 @@         installPackageGivenDeps
           isAllInOne buildHaddocks ps package minstalled deps
 
--- | Checks if we need to install the given 'Package', given the results of
+-- | Checks if we need to install the given t'Package', given the results of
 -- 'addPackageDeps'. If dependencies are missing, the package is dirty, or it is
 -- not installed, then it needs to be installed.
 installPackageGivenDeps ::

@@ -4,7 +4,14 @@ {-# LANGUAGE OverloadedStrings   #-}
 {-# LANGUAGE TypeFamilies        #-}
 
--- | Perform a build
+{-|
+Module      : Stack.Build.Execute
+Description : Perform a build.
+License     : BSD-3-Clause
+
+Perform a build.
+-}
+
 module Stack.Build.Execute
   ( printPlan
   , preFetch
@@ -28,7 +35,6 @@ import qualified Data.Text as T
 import           Data.Tuple ( swap )
 import           Distribution.System ( OS (..), Platform (..) )
-import           Distribution.Version ( mkVersion )
 import           Path ( (</>),  parent )
 import           Path.CheckInstall ( warnInstallSearchPathIssues )
 import           Path.Extra ( forgivingResolveFile, rejectMissingFile )
@@ -62,7 +68,6 @@                    ( 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 )
@@ -70,9 +75,9 @@ import           Stack.Types.ConfigureOpts ( BaseConfigOpts (..) )
 import           Stack.Types.DumpPackage ( DumpPackage (..) )
 import           Stack.Types.EnvConfig
-                   ( HasEnvConfig (..), actualCompilerVersionL
-                   , bindirCompilerTools, installationRootDeps
-                   , installationRootLocal, packageDatabaseLocal
+                   ( HasEnvConfig (..), bindirCompilerTools
+                   , installationRootDeps, installationRootLocal
+                   , packageDatabaseLocal
                    )
 import           Stack.Types.EnvSettings ( EnvSettings (..) )
 import           Stack.Types.GhcPkgId ( GhcPkgId )
@@ -385,10 +390,9 @@       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
     localDB <- packageDatabaseLocal
-    unregisterPackages cv localDB ids
+    unregisterPackages localDB ids
 
   liftIO $ atomically $ modifyTVar' ee.localDumpPkgs $ \initMap ->
     foldl' (flip Map.delete) initMap $ Map.keys plan.unregisterLocal
@@ -518,11 +522,10 @@ 
 unregisterPackages ::
      (HasCompiler env, HasPlatform env, HasProcessContext env, HasTerm env)
-  => ActualCompiler
-  -> Path Abs Dir
+  => Path Abs Dir
   -> NonEmpty (GhcPkgId, (PackageIdentifier, Text))
   -> RIO env ()
-unregisterPackages cv localDB ids = do
+unregisterPackages localDB ids = do
   let logReason ident reason =
         prettyInfoL
           (  [ fromString (packageIdentifierString ident) <> ":"
@@ -530,36 +533,24 @@              ]
           <> [ parens (flow $ T.unpack reason) | not $ T.null reason ]
           )
-  let unregisterSinglePkg select (gid, (ident, reason)) = do
-        logReason ident reason
-        pkg <- getGhcPkgExe
-        unregisterGhcPkgIds True pkg localDB $ select ident gid :| []
-  case cv of
-    -- GHC versions >= 8.2.1 support batch unregistering of packages. See
-    -- https://gitlab.haskell.org/ghc/ghc/issues/12637
-    ACGhc v | v >= mkVersion [8, 2, 1] -> do
-      platform <- view platformL
-      -- According to
-      -- https://support.microsoft.com/en-us/help/830473/command-prompt-cmd-exe-command-line-string-limitation
-      -- the maximum command line length on Windows since XP is 8191 characters.
-      -- We use conservative batch size of 100 ids on this OS thus argument name
-      -- '-ipid', package name, its version and a hash should fit well into this
-      -- limit. On Unix-like systems we're limited by ARG_MAX which is normally
-      -- hundreds of kilobytes so batch size of 500 should work fine.
-      let batchSize = case platform of
-            Platform _ Windows -> 100
-            _ -> 500
-      let chunksOfNE size = mapMaybe nonEmpty . chunksOf size . NE.toList
-      for_ (chunksOfNE batchSize ids) $ \batch -> do
-        for_ batch $ \(_, (ident, reason)) -> logReason ident reason
-        pkg <- getGhcPkgExe
-        unregisterGhcPkgIds True pkg localDB $ fmap (Right . fst) batch
-
-    -- GHC versions >= 7.9 support unregistering of packages via their GhcPkgId.
-    ACGhc v | v >= mkVersion [7, 9] ->
-      for_ ids . unregisterSinglePkg $ \_ident gid -> Right gid
-
-    _ -> for_ ids . unregisterSinglePkg $ \ident _gid -> Left ident
+  -- GHC versions >= 8.2.1 support batch unregistering of packages. See
+  -- https://gitlab.haskell.org/ghc/ghc/issues/12637
+  platform <- view platformL
+  -- According to
+  -- https://support.microsoft.com/en-us/help/830473/command-prompt-cmd-exe-command-line-string-limitation
+  -- the maximum command line length on Windows since XP is 8191 characters. We
+  -- use conservative batch size of 100 ids on this OS thus argument name
+  -- '-ipid', package name, its version and a hash should fit well into this
+  -- limit. On Unix-like systems we're limited by ARG_MAX which is normally
+  -- hundreds of kilobytes so batch size of 500 should work fine.
+  let batchSize = case platform of
+        Platform _ Windows -> 100
+        _ -> 500
+  let chunksOfNE size = mapMaybe nonEmpty . chunksOf size . NE.toList
+  for_ (chunksOfNE batchSize ids) $ \batch -> do
+    for_ batch $ \(_, (ident, reason)) -> logReason ident reason
+    pkg <- getGhcPkgExe
+    unregisterGhcPkgIds True pkg localDB $ fmap (Right . fst) batch
 
 toActions ::
      HasEnvConfig env

@@ -6,8 +6,14 @@ {-# LANGUAGE OverloadedStrings     #-}
 {-# LANGUAGE TypeFamilies          #-}
 
--- | Provides all the necessary types and functions for running cabal Setup.hs
--- commands. Only used in the "Execute" and "ExecutePackage" modules
+{-|
+Module      : Stack.Build.ExecuteEnv
+License     : BSD-3-Clause
+
+Provides all the necessary types and functions for running cabal Setup.hs
+commands. Only used in the "Execute" and "ExecutePackage" modules.
+-}
+
 module Stack.Build.ExecuteEnv
   ( ExecuteEnv (..)
   , withExecuteEnv
@@ -49,7 +55,6 @@ import           Distribution.System ( OS (..), Platform (..) )
 import           Distribution.Types.PackageName ( mkPackageName )
 import           Distribution.Verbosity ( showForCabal )
-import           Distribution.Version ( mkVersion )
 import           Path
                    ( PathException, (</>), parent, parseRelDir, parseRelFile )
 import           Path.Extra ( forgivingResolveFile, toFilePathNoTrailingSep )
@@ -83,9 +88,7 @@ import           Stack.Types.BuildOptsCLI ( BuildOptsCLI (..) )
 import           Stack.Types.BuildOptsMonoid ( CabalVerbosity (..) )
 import           Stack.Types.Compiler
-                   ( ActualCompiler (..), WhichCompiler (..)
-                   , compilerVersionString, getGhcVersion, whichCompilerL
-                   )
+                   ( WhichCompiler (..), compilerVersionString, whichCompilerL )
 import           Stack.Types.CompilerPaths
                    ( CompilerPaths (..), HasCompiler (..), cabalVersionL
                    , getCompilerPath
@@ -112,6 +115,8 @@ import           System.FileLock
                    ( SharedExclusive (..), withFileLock, withTryFileLock )
 
+-- | Type representing environments in which the @Setup.hs@ commands of Cabal
+-- (the library) can be executed.
 data ExecuteEnv = ExecuteEnv
   { installLock    :: !(MVar ())
   , buildOpts      :: !BuildOpts
@@ -250,7 +255,7 @@       renameFile tmpExePath exePath
       pure $ Just exePath
 
--- | Execute a function that takes an 'ExecuteEnv'.
+-- | Execute a function that takes an t'ExecuteEnv'.
 withExecuteEnv ::
      forall env a. HasEnvConfig env
   => BuildOpts
@@ -425,12 +430,11 @@            : [ pretty filepath <> "." ]
            )
       <> line
-    compilerVer <- view actualCompilerVersionL
     withSourceFile (toFilePath filepath) $ \src ->
          runConduit
        $ src
       .| CT.decodeUtf8Lenient
-      .| mungeBuildOutput ExcludeTHLoading ConvertPathsToAbsolute pkgDir compilerVer
+      .| mungeBuildOutput ExcludeTHLoading ConvertPathsToAbsolute pkgDir
       .| CL.mapM_ (logInfo . display)
     prettyNote $
          fillSep
@@ -838,8 +842,7 @@ 
           runExe :: Path Abs File -> [String] -> RIO env ()
           runExe exeName fullArgs = do
-            compilerVer <- view actualCompilerVersionL
-            runAndOutput compilerVer `catch` \ece -> do
+            runAndOutput `catch` \ece -> do
               (mlogFile, bss) <-
                 case outputType of
                   OTConsole _ -> pure (Nothing, [])
@@ -854,14 +857,13 @@                              runConduit
                            $ src
                           .| CT.decodeUtf8Lenient
-                          .| mungeBuildOutput
-                               stripTHLoading makeAbsolute pkgDir compilerVer
+                          .| mungeBuildOutput stripTHLoading makeAbsolute pkgDir
                           .| CL.consume
               prettyThrowM $ CabalExitedUnsuccessfully
                 (eceExitCode ece) pkgId exeName fullArgs mlogFile bss
            where
-            runAndOutput :: ActualCompiler -> RIO env ()
-            runAndOutput compilerVer = withWorkingDir (toFilePath pkgDir) $
+            runAndOutput :: RIO env ()
+            runAndOutput = withWorkingDir (toFilePath pkgDir) $
               withProcessContext menv $ case outputType of
                 OTLogFile _ h -> do
                   let prefixWithTimestamps =
@@ -876,18 +878,17 @@                   in  void $ sinkProcessStderrStdout
                         (toFilePath exeName)
                         fullArgs
-                        (outputSink KeepTHLoading LevelWarn compilerVer prefix)
-                        (outputSink stripTHLoading LevelInfo compilerVer prefix)
+                        (outputSink KeepTHLoading LevelWarn prefix)
+                        (outputSink stripTHLoading LevelInfo prefix)
             outputSink ::
                  HasCallStack
               => ExcludeTHLoading
               -> LogLevel
-              -> ActualCompiler
               -> Utf8Builder
               -> ConduitM S.ByteString Void (RIO env) ()
-            outputSink excludeTH level compilerVer prefix =
+            outputSink excludeTH level prefix =
               CT.decodeUtf8Lenient
-              .| mungeBuildOutput excludeTH makeAbsolute pkgDir compilerVer
+              .| mungeBuildOutput excludeTH makeAbsolute pkgDir
               .| CL.mapM_ (logGeneric "" level . (prefix <>) . display)
             -- If users want control, we should add a config option for this
             makeAbsolute :: ConvertPathsToAbsolute
@@ -954,10 +955,8 @@      -- ^ convert paths to absolute?
   -> Path Abs Dir
      -- ^ package's root directory
-  -> ActualCompiler
-     -- ^ compiler we're building with
   -> ConduitM Text Text m ()
-mungeBuildOutput excludeTHLoading makeAbsolute pkgDir compilerVer = void $
+mungeBuildOutput excludeTHLoading makeAbsolute pkgDir = void $
   CT.lines
   .| CL.map stripCR
   .| CL.filter (not . isTHLoading)
@@ -974,18 +973,10 @@       ("done." `T.isSuffixOf` bs || "done.\r" `T.isSuffixOf` bs)
 
   filterLinkerWarnings :: ConduitM Text Text m ()
-  filterLinkerWarnings
+  filterLinkerWarnings =
     -- Check for ghc 7.8 since it's the only one prone to producing
     -- linker warnings on Windows x64
-    | getGhcVersion compilerVer >= mkVersion [7, 8] = doNothing
-    | otherwise = CL.filter (not . isLinkerWarning)
-
-  isLinkerWarning :: Text -> Bool
-  isLinkerWarning str =
-       (  "ghc.exe: warning:" `T.isPrefixOf` str
-       || "ghc.EXE: warning:" `T.isPrefixOf` str
-       )
-    && "is linked instead of __imp_" `T.isInfixOf` str
+    doNothing
 
   -- | Convert GHC error lines with file paths to have absolute file paths
   toAbsolute :: ConduitM Text Text m ()

@@ -1,11 +1,19 @@ {-# LANGUAGE NoImplicitPrelude     #-}
 {-# LANGUAGE DataKinds             #-}
 {-# LANGUAGE DuplicateRecordFields #-}
+{-# LANGUAGE LambdaCase            #-}
 {-# LANGUAGE OverloadedRecordDot   #-}
 {-# LANGUAGE OverloadedStrings     #-}
 {-# LANGUAGE TypeFamilies          #-}
 
--- | Perform a build
+{-|
+Module      : Stack.Build.ExecutePackage
+Description : Perform a build.
+License     : BSD-3-Clause
+
+Perform a build.
+-}
+
 module Stack.Build.ExecutePackage
   ( singleBuild
   , singleTest
@@ -32,7 +40,6 @@ import qualified Distribution.Text as C
 import           Distribution.Types.MungedPackageName
                    ( encodeCompatPackageName )
-import           Distribution.Version ( mkVersion )
 import           Path
                    ( (</>), addExtension, filename, isProperPrefixOf, parent
                    , parseRelDir, parseRelFile, stripProperPrefix
@@ -44,10 +51,11 @@                    )
 import           RIO.NonEmpty ( nonEmpty )
 import           RIO.Process
-                   ( byteStringInput, findExecutable, getStderr, getStdout
-                   , inherit, modifyEnvVars, proc, setStderr, setStdin
-                   , setStdout, showProcessArgDebug, useHandleOpen, waitExitCode
-                   , withProcessWait, withWorkingDir, HasProcessContext
+                   ( HasProcessContext, byteStringInput, findExecutable
+                   , getStderr, getStdout, inherit, modifyEnvVars, proc
+                   , setStderr, setStdin, setStdout, showProcessArgDebug
+                   , useHandleOpen, waitExitCode, withModifyEnvVars
+                   , withProcessWait, withWorkingDir
                    )
 import           Stack.Build.Cache
                    ( TestStatus (..), deleteCaches, getTestStatus
@@ -71,7 +79,7 @@                    , hpcRelativeDir, setupConfigFromDir
                    )
 import           Stack.Coverage ( generateHpcReport, updateTixFile )
-import           Stack.GhcPkg ( ghcPkg, unregisterGhcPkgIds )
+import           Stack.GhcPkg ( ghcPkg, ghcPkgPathEnvVar, unregisterGhcPkgIds )
 import           Stack.Package
                    ( buildLogPath, buildableExes, buildableSubLibs
                    , hasBuildableMainLibrary, mainLibraryHasExposedModules
@@ -80,9 +88,9 @@ import           Stack.Prelude
 import           Stack.Types.Build
                    ( ConfigCache (..), PrecompiledCache (..), Task (..)
-                   , TaskConfigOpts (..), TaskType (..), taskAnyMissing
-                   , taskIsTarget, taskLocation, taskProvides
-                   , taskTargetIsMutable, taskTypePackageIdentifier
+                   , TaskConfigOpts (..), TaskType (..), taskIsTarget
+                   , taskLocation, taskProvides, taskTargetIsMutable
+                   , taskTypePackageIdentifier
                    )
 import qualified Stack.Types.Build as ConfigCache ( ConfigCache (..) )
 import           Stack.Types.Build.Exception
@@ -99,9 +107,7 @@                    , foldComponentToAnotherCollection, getBuildableListText
                    )
 import           Stack.Types.Compiler
-                   ( ActualCompiler (..), WhichCompiler (..), getGhcVersion
-                   , whichCompilerL
-                   )
+                   ( WhichCompiler (..), whichCompiler, whichCompilerL )
 import           Stack.Types.CompilerPaths
                    ( CompilerPaths (..), GhcPkgExe (..), HasCompiler (..)
                    , cpWhich, getGhcPkgExe
@@ -118,7 +124,7 @@ import           Stack.Types.Curator ( Curator (..) )
 import           Stack.Types.DumpPackage ( DumpPackage (..) )
 import           Stack.Types.EnvConfig
-                   ( HasEnvConfig (..), actualCompilerVersionL
+                   ( EnvConfig (..), HasEnvConfig (..), actualCompilerVersionL
                    , appropriateGhcColorFlag
                    )
 import           Stack.Types.EnvSettings ( EnvSettings (..) )
@@ -140,6 +146,7 @@                    )
 import           Stack.Types.PackageFile ( PackageWarning (..) )
 import           Stack.Types.Runner ( HasRunner, globalOptsL )
+import           Stack.Types.SourceMap ( SourceMap (..) )
 import           System.IO.Error ( isDoesNotExistError )
 import           System.PosixCompat.Files
                    ( createLink, getFileStatus, modificationTime )
@@ -240,10 +247,6 @@           (getFileStatus (toFilePath setupConfigfp))
   newSetupConfigMod <- getNewSetupConfigMod
   newConfigFileRoot <- S8.pack . toFilePath <$> view configFileRootL
-  -- See https://github.com/commercialhaskell/stack/issues/3554. This can be
-  -- dropped when Stack drops support for GHC < 8.4.
-  taskAnyMissingHackEnabled <-
-    view $ actualCompilerVersionL . to getGhcVersion . to (< mkVersion [8, 4])
   needConfig <-
     if buildOpts.reconfigure
           -- The reason 'taskAnyMissing' is necessary is a bug in Cabal. See:
@@ -253,7 +256,6 @@           -- check, Stack would think that a reconfigure is unnecessary, when in
           -- fact we _do_ need to reconfigure. The details here suck. We really
           -- need proper hashes for package identifiers.
-       || (taskAnyMissingHackEnabled && taskAnyMissing task)
       then pure True
       else do
         -- We can ignore the components portion of the config
@@ -345,22 +347,24 @@        (packageNamePrefix ee (pkgName (taskTypePackageIdentifier taskType)))
   <> action
 
--- Implements running a package's build, used to implement 'ATBuild' and
--- 'ATBuildFinal' tasks.  In particular this does the following:
+-- | Implements running a package's build, used to implement
+-- 'Control.Concurrent.Execute.ATBuild' and
+-- 'Control.Concurrent.Execute.ATBuildFinal' tasks. In particular this does the
+-- following:
 --
--- * Checks if the package exists in the precompiled cache, and if so,
---   add it to the database instead of performing the build.
+-- * Checks if the package exists in the precompiled cache, and if so, add it to
+--   the database instead of performing the build.
 --
--- * Runs the configure step if needed ('ensureConfig')
+-- * Runs the configure step if needed (@ensureConfig@)
 --
 -- * Runs the build step
 --
 -- * Generates haddocks
 --
--- * Registers the library and copies the built executables into the
---   local install directory. Note that this is literally invoking Cabal
---   with @copy@, and not the copying done by @stack install@ - that is
---   handled by 'copyExecutables'.
+-- * Registers the library and copies the built executables into the local
+--   install directory. Note that this is literally invoking Cabal with @copy@,
+--   and not the copying done by @stack install@ - that is handled by
+--   'Stack.Build.copyExecutables'.
 singleBuild ::
      forall env. (HasEnvConfig env, HasRunner env)
   => ActionContext
@@ -600,11 +604,7 @@         else "haddock"
 
       -- For GHC 8.4 and later, provide the --quickjump option.
-      let quickjump =
-            case actualCompiler of
-              ACGhc ghcVer
-                | ghcVer >= mkVersion [8, 4] -> ["--haddock-option=--quickjump"]
-              _ -> []
+      let quickjump = ["--haddock-option=--quickjump"]
 
       fulfillHaddockExpectations pname mcurator $ \keep -> do
         let args = concat
@@ -878,13 +878,36 @@       let pkgDb = ee.baseConfigOpts.snapDB
       ghcPkgExe <- getGhcPkgExe
       -- First unregister, silently, everything that needs to be unregistered.
-      whenJust (nonEmpty allToUnregister) $ \allToUnregister' -> catchAny
-        (unregisterGhcPkgIds False ghcPkgExe pkgDb allToUnregister')
-        (const (pure ()))
-      -- Now, register the cached conf files.
-      forM_ allToRegister $ \libpath ->
-        ghcPkg ghcPkgExe [pkgDb] ["register", "--force", toFilePath libpath]
-
+      whenJust (nonEmpty allToUnregister) $ \allToUnregister' -> do
+        logLevel <- view $ globalOptsL . to (.logLevel)
+        let isDebug = logLevel == LevelDebug
+        catchAny
+          (unregisterGhcPkgIds isDebug ghcPkgExe pkgDb allToUnregister')
+          (const (pure ()))
+      -- There appears to be a bug in the ghc-pkg executable such that, on
+      -- Windows only, it cannot register a package into a package database that
+      -- is also listed in the GHC_PACKAGE_PATH environment variable. See:
+      -- https://gitlab.haskell.org/ghc/ghc/-/issues/25962. We work around that
+      -- by removing GHC_PACKAGE_PATH from the environment for the register
+      -- step.
+      wc <- view $ envConfigL . to (.sourceMap.compiler) . to whichCompiler
+      withModifyEnvVars (Map.delete $ ghcPkgPathEnvVar wc) $
+        forM_ allToRegister $ \libpath -> do
+          let args = ["register", "--force", toFilePath libpath]
+          ghcPkg ghcPkgExe [pkgDb] args >>= \case
+            Left e -> prettyWarn $
+              "[S-4541]"
+              <> line
+              <> fillSep
+                   [ flow "While registering"
+                   , pretty libpath
+                   , "in"
+                   , pretty pkgDb <> ","
+                   , flow "Stack encountered the following error:"
+                   ]
+              <> blankLine
+              <> string (displayException e)
+            Right _ -> pure ()
   liftIO $ forM_ exes $ \exe -> do
     ensureDir bindir
     let dst = bindir </> filename exe

@@ -3,7 +3,14 @@ {-# LANGUAGE OverloadedRecordDot #-}
 {-# LANGUAGE OverloadedStrings   #-}
 
--- | Generate haddocks
+{-|
+Module      : Stack.Build.Haddock
+Description : Generate Haddock documentation.
+License     : BSD-3-Clause
+
+Generate Haddock documentation.
+-}
+
 module Stack.Build.Haddock
   ( generateDepsHaddockIndex
   , generateLocalHaddockIndex

@@ -4,7 +4,14 @@ {-# LANGUAGE OverloadedStrings     #-}
 {-# LANGUAGE ScopedTypeVariables   #-}
 
--- Determine which packages are already installed
+{-|
+Module      : Stack.Build.Installed
+Description : Determine which packages are already installed.
+License     : BSD-3-Clause
+
+Determine which packages are already installed.
+-}
+
 module Stack.Build.Installed
   ( getInstalled
   , toInstallMap
@@ -37,6 +44,9 @@ import           Stack.Types.SourceMap
                    ( DepPackage (..), ProjectPackage (..), SourceMap (..) )
 
+-- | For the given t'SourceMap', yield a dictionary of package names for a
+-- project's packages and dependencies, and pairs of their relevant database
+-- (write-only or mutable) and package versions.
 toInstallMap :: MonadIO m => SourceMap -> m InstallMap
 toInstallMap sourceMap = do
   projectInstalls <-

@@ -3,7 +3,14 @@ {-# LANGUAGE OverloadedRecordDot   #-}
 {-# LANGUAGE OverloadedStrings     #-}
 
--- Load information on package sources
+{-|
+Module      : Stack.Build.Source
+Description : Load information on package sources.
+License     : BSD-3-Clause
+
+Load information on package sources.
+-}
+
 module Stack.Build.Source
   ( projectLocalPackages
   , localDependencies
@@ -67,7 +74,7 @@ import           Stack.Types.SourceMap
                    ( CommonPackage (..), DepPackage (..), ProjectPackage (..)
                    , SMActual (..), SMTargets (..), SourceMap (..)
-                   , SourceMapHash (..), Target (..), ppGPD, ppRoot
+                   , SourceMapHash (..), Target (..), ppRoot
                    )
 import           Stack.Types.UnusedFlags ( FlagSource (..), UnusedFlags (..) )
 import           System.FilePath ( takeFileName )
@@ -205,7 +212,7 @@       else
         pure $ Left $ UFFlagsNotDefined FSCommandLine name pkgFlags unusedByName
 
--- | Get a 'SourceMapHash' for a given 'SourceMap'
+-- | Get a t'SourceMapHash' for a given t'SourceMap'
 --
 -- Basic rules:
 --
@@ -323,18 +330,28 @@       AGOLocals -> isLocal
       AGOEverything -> True
 
+-- | Yield a t'Package' from the settings common to dependency and project
+-- packages.
 loadCommonPackage ::
      forall env. (HasBuildConfig env, HasSourceMap env)
   => CommonPackage
   -> RIO env Package
 loadCommonPackage common = do
+  (_, _, pkg) <- loadCommonPackage' common
+  pure pkg
+
+loadCommonPackage' ::
+     forall env. (HasBuildConfig env, HasSourceMap env)
+  => CommonPackage
+  -> RIO env (PackageConfig, C.GenericPackageDescription, Package)
+loadCommonPackage' common = do
   config <-
     getPackageConfig
       common.flags
       common.ghcOptions
       common.cabalConfigOpts
   gpkg <- liftIO common.gpd
-  pure $ resolvePackage config gpkg
+  pure (config, gpkg, resolvePackage config gpkg)
 
 -- | Upgrade the initial project package info to a full-blown @LocalPackage@
 -- based on the selected components
@@ -347,11 +364,7 @@   let common = pp.projectCommon
   bopts <- view buildOptsL
   mcurator <- view $ buildConfigL . to (.curator)
-  config <- getPackageConfig
-              common.flags
-              common.ghcOptions
-              common.cabalConfigOpts
-  gpkg <- ppGPD pp
+  (config, gpkg, pkg) <- loadCommonPackage' common
   let name = common.name
       mtarget = M.lookup name sm.targets.targets
       (exeCandidates, testCandidates, benchCandidates) =
@@ -419,7 +432,6 @@       -- --enable-benchmarks or --enable-tests are configured. This allows us to
       -- do an optimization where these are passed if the deps are present. This
       -- can avoid doing later unnecessary reconfigures.
-      pkg = resolvePackage config gpkg
       btpkg
         | Set.null tests && Set.null benches = Nothing
         | otherwise = Just (resolvePackage btconfig gpkg)
@@ -566,7 +578,7 @@     (Just <$> readFileDigest cache fp)
     (\e -> if isDoesNotExistError e then pure Nothing else throwM e)
 
--- | Get 'PackageConfig' for package given its name.
+-- | Get t'PackageConfig' for package given its name.
 getPackageConfig ::
      (HasBuildConfig env, HasSourceMap env)
   => Map FlagName Bool

@@ -8,57 +8,62 @@ {-# LANGUAGE OverloadedStrings     #-}
 {-# LANGUAGE ViewPatterns          #-}
 
--- | Parsing command line targets
---
--- There are two relevant data sources for performing this parsing: the project
--- configuration, and command line arguments. Project configurations includes
--- the snapshot (defining a LoadedSnapshot of global and snapshot packages),
--- local dependencies, and project packages. It also defines local flag
--- overrides.
---
--- The command line arguments specify both additional local flag overrides and
--- targets in their raw form.
---
--- Flags are simple: we just combine CLI flags with config flags and make one
--- big map of flags, preferring CLI flags when present.
---
--- Raw targets can be a package name, a package name with component, just a
--- component, or a package name and version number. We first must resolve these
--- raw targets into both simple targets and additional dependencies. This works
--- as follows:
---
--- * If a component is specified, find a unique project package which defines
---   that component, and convert it into a name+component target.
---
--- * Ensure that all name+component values refer to valid components in the
---   given project package.
---
--- * For names, check if the name is present in the snapshot, local deps, or
---   project packages. If it is not, then look up the most recent version in the
---   package index and convert to a name+version.
---
--- * For name+version, first ensure that the name is not used by a project
---   package. Next, if that name+version is present in the snapshot or local
---   deps _and_ its location is PLIndex, we have the package. Otherwise, add to
---   local deps with the appropriate PLIndex.
---
--- If in either of the last two bullets we added a package to local deps, print
--- a warning to the user recommending modifying the extra-deps.
---
--- Combine the various 'ResolveResults's together into 'Target' values, by
--- combining various components for a single package and ensuring that no
--- conflicting statements were made about targets.
---
--- At this point, we now have a Map from package name to SimpleTarget, and an
--- updated Map of local dependencies. We still have the aggregated flags, and
--- the snapshot and project packages.
---
--- Finally, we upgrade the snapshot by using calculatePackagePromotion.
+{-|
+Module      : Stack.Build.Target
+Description : Parsing command line targets.
+License     : BSD-3-Clause
+
+Parsing command line targets
+
+There are two relevant data sources for performing this parsing: the project
+configuration, and command line arguments. Project configurations includes the
+snapshot (defining a LoadedSnapshot of global and snapshot packages), local
+dependencies, and project packages. It also defines local flag overrides.
+
+The command line arguments specify both additional local flag overrides and
+targets in their raw form.
+
+Flags are simple: we just combine CLI flags with config flags and make one big
+map of flags, preferring CLI flags when present.
+
+Raw targets can be a package name, a package name with component, just a
+component, or a package name and version number. We first must resolve these raw
+targets into both simple targets and additional dependencies. This works as
+follows:
+
+* If a component is specified, find a unique project package which defines that
+  component, and convert it into a name+component target.
+
+* Ensure that all name+component values refer to valid components in the given
+  project package.
+
+* For names, check if the name is present in the snapshot, local deps, or
+  project packages. If it is not, then look up the most recent version in the
+  package index and convert to a name+version.
+
+* For name+version, first ensure that the name is not used by a project
+  package. Next, if that name+version is present in the snapshot or local deps
+  _and_ its location is PLIndex, we have the package. Otherwise, add to local
+  deps with the appropriate PLIndex.
+
+If in either of the last two bullets we added a package to local deps, print a
+warning to the user recommending modifying the extra-deps.
+
+Combine the various t'ResolveResult's together into t'Target' values, by
+combining various components for a single package and ensuring that no
+conflicting statements were made about targets.
+
+At this point, we now have a Map from package name to SimpleTarget, and an
+updated Map of local dependencies. We still have the aggregated flags, and the
+snapshot and project packages.
+
+Finally, we upgrade the snapshot by using calculatePackagePromotion.
+-}
+
 module Stack.Build.Target
   ( -- * Types
     Target (..)
   , NeedTargets (..)
-  , PackageType (..)
   , parseTargets
     -- * Convenience helpers
   , gpdVersion
@@ -66,6 +71,8 @@   , parseRawTarget
   , RawTarget (..)
   , UnresolvedComponent (..)
+  , ComponentName
+  , ResolveResult
   ) where
 
 import qualified Data.Map as Map
@@ -237,6 +244,7 @@ -- Resolve the raw targets
 --------------------------------------------------------------------------------
 
+-- | A type representing results of resolving a raw target.
 data ResolveResult = ResolveResult
   { name :: !PackageName
   , rawInput :: !RawInput
@@ -247,7 +255,7 @@   , packageType :: !PackageType
   }
 
--- | Convert a 'RawTarget' into a 'ResolveResult' (see description on the
+-- | Convert a 'RawTarget' into a t'ResolveResult' (see description on the
 -- module).
 resolveRawTarget ::
      (HasLogFunc env, HasPantryConfig env, HasProcessContext env)
@@ -551,10 +559,13 @@ -- OK, let's do it!
 --------------------------------------------------------------------------------
 
+-- | Parse targets and dependencies from the given command line arguments and
+-- source map.
 parseTargets ::
      HasBuildConfig env
   => NeedTargets
   -> Bool
+     -- ^ Should Haddock documentation be built for the package?
   -> BuildOptsCLI
   -> SMActual GlobalPackage
   -> RIO env SMTargets

@@ -6,8 +6,14 @@ {-# LANGUAGE TemplateHaskell   #-}
 #endif
 
--- Extracted from "Stack" so that module does not use CPP or Template Haskell,
--- and therefore doesn't need to be recompiled as often.
+{-|
+Module      : Stack.BuildInfo
+License     : BSD-3-Clause
+
+Extracted from "Stack" so that module does not use CPP or Template Haskell, and
+therefore doesn't need to be recompiled as often.
+-}
+
 module Stack.BuildInfo
   ( versionString'
   , hpackVersion
@@ -31,6 +37,7 @@ import           Stack.Types.Version ( showStackVersion )
 #endif
 
+-- | The output of @stack --version@.
 versionString' :: String
 #ifdef USE_GIT_INFO
 versionString' = concat $ concat

@@ -2,7 +2,14 @@ {-# LANGUAGE DuplicateRecordFields #-}
 {-# LANGUAGE OverloadedRecordDot   #-}
 
--- | Default configuration options for building.
+{-|
+Module      : Stack.BuildOpts
+Description : Default configuration options for building.
+License     : BSD-3-Clause
+
+Default configuration options for building.
+-}
+
 module Stack.BuildOpts
   ( defaultBuildOpts
   , defaultTestOpts

@@ -5,8 +5,13 @@ {-# LANGUAGE OverloadedRecordDot   #-}
 {-# LANGUAGE OverloadedStrings     #-}
 
--- | Resolving a build plan for a set of packages in a given Stackage snapshot.
+{-|
+Module      : Stack.BuildPlan
+License     : BSD-3-Clause
 
+Resolving a build plan for a set of packages in a given Stackage snapshot.
+-}
+
 module Stack.BuildPlan
   ( BuildPlanException (..)
   , BuildPlanCheck (..)
@@ -15,7 +20,6 @@   , DepErrors
   , removeSrcPkgDefaultFlags
   , selectBestSnapshot
-  , showItems
   ) where
 
 import qualified Data.Foldable as F
@@ -189,8 +193,8 @@     , platform
     }
 
--- Remove any src package flags having default values
--- Remove any package entries with no flags set
+-- | For the given list of packages and dictionary of packages and Cabal flags,
+-- remove flags that have defaults and packages with no remaining flags.
 removeSrcPkgDefaultFlags ::
      [C.GenericPackageDescription]
   -> Map PackageName (Map FlagName Bool)
@@ -205,12 +209,8 @@     in  Just $ Map.differenceWith diff f1 f2
 
   gpdDefaultFlags gpd =
-    let tuples = map getDefault (C.genPackageFlags gpd)
-    in  Map.singleton (gpdPackageName gpd) (Map.fromList tuples)
-
-  getDefault f
-    | C.flagDefault f = (C.flagName f, True)
-    | otherwise       = (C.flagName f, False)
+    let pairs = map (C.flagName &&& C.flagDefault) (C.genPackageFlags gpd)
+    in  Map.singleton (gpdPackageName gpd) (Map.fromList pairs)
 
 -- | Find the set of @FlagName@s necessary to get the given
 -- @GenericPackageDescription@ to compile against the given @BuildPlan@. Will
@@ -300,15 +300,21 @@             , neededBy = Map.singleton myName range
             }
 
+-- | A type synoynm for a dictionary of packages and failures to satisfy
+-- packages' dependency constraints.
 type DepErrors = Map PackageName DepError
 
+-- | A type representing failures to satisfy packages' dependency constraints.
 data DepError = DepError
   { version :: !(Maybe Version)
+    -- ^ If available, the available version of the package.
   , neededBy :: !(Map PackageName VersionRange)
+    -- ^ A dictionary of the packages requiring the package and the permitted
+    -- range of versions.
   }
   deriving Show
 
--- | Combine two 'DepError's for the same 'Version'.
+-- | Combine two t'DepError's for the same 'Version'.
 combineDepError :: DepError -> DepError -> DepError
 combineDepError (DepError a x) (DepError b y) =
   assert (a == b) $ DepError a (Map.unionWith C.intersectVersionRanges x y)
@@ -339,6 +345,8 @@ 
   dupError _ _ = impureThrow DuplicatePackagesBug
 
+-- | A type representing the results of evaluating how well a snapshot satisfies
+-- the dependencies of a set of packages and a set of Cabal flags.
 data BuildPlanCheck
   = BuildPlanCheckOk (Map PackageName (Map FlagName Bool))
   | BuildPlanCheckPartial (Map PackageName (Map FlagName Bool)) DepErrors

@@ -1,6 +1,11 @@ {-# LANGUAGE NoImplicitPrelude   #-}
 {-# LANGUAGE OverloadedRecordDot #-}
 
+{-|
+Module      : Stack.CLI
+License     : BSD-3-Clause
+-}
+
 module Stack.CLI
   ( commandLineHandler
   ) where
@@ -10,9 +15,10 @@ import qualified Data.List as L
 import           Data.List.NonEmpty ( prependList )
 import           Options.Applicative
-                   ( Parser, ParserFailure, ParserHelp, ParserResult (..), flag, switch
+                   ( Parser, ParserFailure, ParserHelp, ParserResult (..)
                    , handleParseResult, help, helpError, idm, long, metavar
-                   , overFailure, renderFailure, strArgument, switch )
+                   , overFailure, renderFailure, strArgument, switch
+                   )
 import           Options.Applicative.Help ( errorHelp, stringChunk, vcatChunks )
 import           Options.Applicative.Builder.Extra
                    ( boolFlags, extraHelpOption )
@@ -28,8 +34,7 @@ import           Stack.Clean ( CleanCommand (..), cleanCmd )
 import           Stack.ConfigCmd
                    ( cfgCmdBuildFiles, cfgCmdBuildFilesName, cfgCmdEnv
-                   , cfgCmdEnvName, configCmdEnvParser, cfgCmdName, cfgCmdSet
-                   , cfgCmdSetName, configCmdSetParser
+                   , cfgCmdEnvName, cfgCmdName, cfgCmdSet, cfgCmdSetName
                    )
 import           Stack.Constants
                    ( globalFooter, osIsWindows, relFileStack, relFileStackDotExe
@@ -44,10 +49,7 @@ import           Stack.Eval ( evalCmd )
 import           Stack.Ghci ( ghciCmd )
 import           Stack.Hoogle ( hoogleCmd )
-import           Stack.IDE
-                   ( ListPackagesCmd (..), OutputStream (..), idePackagesCmd
-                   , ideTargetsCmd
-                   )
+import           Stack.IDE ( idePackagesCmd, ideTargetsCmd )
 import           Stack.Init ( initCmd )
 import           Stack.List ( listCmd )
 import           Stack.Ls ( lsCmd )
@@ -55,12 +57,15 @@ import qualified Stack.Nix as Nix
 import           Stack.Options.BuildParser ( buildOptsParser )
 import           Stack.Options.CleanParser ( cleanOptsParser )
+import           Stack.Options.ConfigEnvParser ( configCmdEnvParser )
+import           Stack.Options.ConfigSetParser ( configCmdSetParser )
 import           Stack.Options.DotParser ( dotOptsParser )
 import           Stack.Options.EvalParser ( evalOptsParser )
 import           Stack.Options.ExecParser ( execOptsParser )
 import           Stack.Options.GhciParser ( ghciOptsParser )
 import           Stack.Options.GlobalParser ( globalOptsParser )
 import           Stack.Options.HpcReportParser ( hpcReportOptsParser )
+import           Stack.Options.IdeParser ( idePackagesParser, ideTargetsParser )
 import           Stack.Options.InitParser ( initOptsParser )
 import           Stack.Options.LsParser ( lsOptsParser )
 import           Stack.Options.NewParser ( newOptsParser )
@@ -352,46 +357,17 @@   ide = addSubCommands'
     "ide"
     "IDE-specific commands."
-    ( let outputFlag = flag
-            OutputLogInfo
-            OutputStdout
-            (  long "stdout"
-            <> help "Send output to the standard output stream instead of the \
-                    \default, the standard error stream."
-            )
-          cabalFileFlag = flag
-            ListPackageNames
-            ListPackageCabalFiles
-            (  long "cabal-files"
-            <> help "Print paths to package Cabal files instead of package \
-                    \names."
-            )
-          exeFlag = switch
-            (  long "exes"
-            <> help "Include executables."
-            )
-          testFlag = switch
-            (  long "tests"
-            <> help "Include test suites."
-            )
-          benchFlag = switch
-            (  long "benchmarks"
-            <> help "Include benchmarks."
-            )
-       in  do
-             addCommand'
-               "packages"
-               "List all available local loadable packages."
-               idePackagesCmd
-               ((,) <$> outputFlag <*> cabalFileFlag)
-             addCommand'
-               "targets"
-               "List all targets or pick component types to list."
-               ideTargetsCmd
-                 (   (,)
-                 <$> ((,,) <$> exeFlag <*> testFlag <*> benchFlag)
-                 <*> outputFlag
-                 )
+    ( do
+        addCommand'
+          "packages"
+          "List all available local loadable packages."
+          idePackagesCmd
+          idePackagesParser
+        addCommand'
+          "targets"
+          "List all targets or pick component types to list."
+          ideTargetsCmd
+          ideTargetsParser
     )
 
   init = addCommand'
@@ -670,9 +646,9 @@    where
     hide = kind /= OuterGlobalOpts
 
--- | fall-through to external executables in `git` style if they exist
--- (i.e. `stack something` looks for `stack-something` before
--- failing with "Invalid argument `something'")
+-- | fall-through to external executables in \'git\' style if they exist
+-- (i.e. @stack something@ looks for @stack-something@ before failing with
+-- "Invalid argument \'something\'".)
 secondaryCommandHandler ::
      NonEmpty String
   -> ParserFailure ParserHelp

@@ -2,7 +2,14 @@ {-# LANGUAGE OverloadedRecordDot #-}
 {-# LANGUAGE OverloadedStrings   #-}
 
--- | Types and functions related to Stack's @clean@ and @purge@ commands.
+{-|
+Module      : Stack.Clean
+Description : Types and functions related to Stack's @clean@ and @purge@ commands.
+License     : BSD-3-Clause
+
+Types and functions related to Stack's @clean@ and @purge@ commands.
+-}
+
 module Stack.Clean
   ( CleanOpts (..)
   , CleanCommand (..)

@@ -8,12 +8,17 @@ {-# LANGUAGE OverloadedStrings        #-}
 {-# LANGUAGE ScopedTypeVariables      #-}
 
--- | All utility functions for Components in Stack (library, internal library,
--- foreign library, executable, tests, benchmarks). In particular, this module
--- gathers all the Cabal-to-Stack component translations, which previously
--- occurred in the "Stack.Package" module. See "Stack.Types.Component" for more
--- details about the design choices.
+{-|
+Module      : Stack.Component
+License     : BSD-3-Clause
 
+All utility functions for Components in Stack (library, internal library,
+foreign library, executable, tests, benchmarks). In particular, this module
+gathers all the Cabal-to-Stack component translations, which previously occurred
+in the "Stack.Package" module. See "Stack.Types.Component" for more details
+about the design choices.
+-}
+
 module Stack.Component
   ( isComponentBuildable
   , stackLibraryFromCabal
@@ -125,10 +130,12 @@     }
 
 -- | Iterate on all three dependency list given, and transform and sort them
--- between 'sbiUnknownTools' and legitimate 'DepValue' sbiDependency. Bear in
--- mind that this only gathers the component level dependencies.
-gatherComponentToolsAndDepsFromCabal
-  :: [Cabal.LegacyExeDependency]
+-- between 'Stack.Types.Component.unknownTools' and
+-- legitimate t'Stack.Types.Dependency.DepValue'
+-- 'Stack.Types.Component.dependency'. Bear in mind that this only gathers the
+-- component level dependencies.
+gatherComponentToolsAndDepsFromCabal ::
+    [Cabal.LegacyExeDependency]
      -- ^ Legacy build tools dependency from
      -- 'Distribution.Types.BuildInfo.buildTools'.
   -> [Cabal.ExeDependency]

@@ -3,9 +3,14 @@ {-# LANGUAGE OverloadedRecordDot #-}
 {-# LANGUAGE OverloadedStrings   #-}
 
--- | A module which exports all component-level file-gathering logic. It also
--- includes utility functions for handling paths and directories.
+{-|
+Module      : Stack.ComponentFile
+License     : BSD-3-Clause
 
+A module which exports all component-level file-gathering logic. It also
+includes utility functions for handling paths and directories.
+-}
+
 module Stack.ComponentFile
   ( resolveOrWarn
   , componentOutputDir
@@ -81,12 +86,19 @@ stackBenchmarkFiles bench =
   resolveComponentFiles (CBench bench.name) build names
  where
+  names :: [DotCabalDescriptor]
   names = bnames <> exposed
+
+  exposed :: [DotCabalDescriptor]
   exposed =
     case bench.interface of
       BenchmarkExeV10 _ fp -> [DotCabalMain fp]
       BenchmarkUnsupported _ -> []
+
+  bnames :: [DotCabalDescriptor]
   bnames = map DotCabalModule build.otherModules
+
+  build :: StackBuildInfo
   build = bench.buildInfo
 
 -- | Get all files referenced by the test.
@@ -96,13 +108,20 @@ stackTestSuiteFiles test =
   resolveComponentFiles (CTest test.name) build names
  where
+  names :: [DotCabalDescriptor]
   names = bnames <> exposed
+
+  exposed :: [DotCabalDescriptor]
   exposed =
     case test.interface of
       TestSuiteExeV10 _ fp -> [DotCabalMain fp]
       TestSuiteLibV09 _ mn -> [DotCabalModule mn]
       TestSuiteUnsupported _ -> []
+
+  bnames :: [DotCabalDescriptor]
   bnames = map DotCabalModule build.otherModules
+
+  build :: StackBuildInfo
   build = test.buildInfo
 
 -- | Get all files referenced by the executable.
@@ -112,7 +131,10 @@ stackExecutableFiles exe =
   resolveComponentFiles (CExe exe.name) build names
  where
+  build :: StackBuildInfo
   build = exe.buildInfo
+
+  names :: [DotCabalDescriptor]
   names =
     map DotCabalModule build.otherModules ++ [DotCabalMain exe.modulePath]
 
@@ -124,13 +146,24 @@ stackLibraryFiles lib =
   resolveComponentFiles componentName build names
  where
+  componentRawName :: StackUnqualCompName
   componentRawName = lib.name
+
+  componentName :: NamedComponent
   componentName
     | componentRawName == emptyCompName = CLib
     | otherwise = CSubLib componentRawName
+
+  build :: StackBuildInfo
   build = lib.buildInfo
+
+  names :: [DotCabalDescriptor]
   names = bnames ++ exposed
+
+  exposed :: [DotCabalDescriptor]
   exposed = map DotCabalModule lib.exposedModules
+
+  bnames :: [DotCabalDescriptor]
   bnames = map DotCabalModule build.otherModules
 
 -- | Get all files referenced by the component.
@@ -154,6 +187,7 @@   cfiles <- buildOtherSources build
   pure (component, ComponentFile modules (files <> cfiles) warnings)
  where
+  autogenDirs :: RIO GetPackageFileContext [Path Abs Dir]
   autogenDirs = do
     distDir <- asks (.distDir)
     let compDir = componentAutogenDir component distDir

@@ -6,20 +6,25 @@ {-# LANGUAGE OverloadedStrings     #-}
 {-# LANGUAGE TypeFamilies          #-}
 
--- | The general Stack configuration that starts everything off. This should be
--- smart to fallback if there is no stack.yaml, instead relying on whatever
--- files are available.
---
--- If there is no stack.yaml, and there is a cabal.config, we read in those
--- constraints, and if there's a cabal.sandbox.config, we read any constraints
--- from there and also find the package database from there, etc. And if there's
--- nothing, we should probably default to behaving like cabal, possibly with
--- spitting out a warning that "you should run `stk init` to make things
--- better".
+{-|
+Module      : Stack.Config
+Description : The general Stack configuration.
+License     : BSD-3-Clause
+
+The general Stack configuration that starts everything off. This should be smart
+to fallback if there is no stack.yaml, instead relying on whatever files are
+available.
+
+If there is no stack.yaml, and there is a cabal.config, we read in those
+constraints, and if there's a cabal.sandbox.config, we read any constraints from
+there and also find the package database from there, etc. And if there's
+nothing, we should probably default to behaving like cabal, possibly with
+spitting out a warning that "you should run `stk init` to make things better".
+-}
+
 module Stack.Config
   ( loadConfig
   , loadConfigYaml
-  , packagesParser
   , getImplicitGlobalProjectDir
   , getSnapshots
   , makeConcreteSnapshot
@@ -61,7 +66,6 @@ import           GHC.Conc ( getNumProcessors )
 import           Network.HTTP.StackClient
                    ( httpJSON, parseUrlThrow, getResponseBody )
-import           Options.Applicative ( Parser, help, long, metavar, strOption )
 import           Pantry ( loadSnapshot )
 import           Path
                    ( PathException (..), (</>), parent, parseAbsDir
@@ -160,7 +164,7 @@ getImplicitGlobalProjectDir :: HasConfig env => RIO env (Path Abs Dir)
 getImplicitGlobalProjectDir = view $ stackRootL . to implicitGlobalProjectDir
 
--- | Download the 'Snapshots' value from stackage.org.
+-- | Download the t'Snapshots' value from stackage.org.
 getSnapshots :: HasConfig env => RIO env Snapshots
 getSnapshots = do
   latestUrlText <- askLatestSnapshotUrl
@@ -649,7 +653,7 @@ withLocalLogFunc :: HasLogFunc env => LogFunc -> RIO env a -> RIO env a
 withLocalLogFunc logFunc = local (set logFuncL logFunc)
 
--- | Runs the provided action with a new 'LogFunc', given a 'StylesUpdate'.
+-- | Runs the provided action with a new 'LogFunc', given a t'StylesUpdate'.
 withNewLogFunc ::
      MonadUnliftIO m
   => GlobalOpts
@@ -874,7 +878,7 @@  where
   getEmptyProject ::
        Maybe RawSnapshotLocation
-    -> [PackageIdentifierRevision]
+    -> [RawPackageLocationImmutable]
     -> RIO Config Project
   getEmptyProject mSnapshot extraDeps = do
     snapshot <- case mSnapshot of
@@ -895,7 +899,7 @@     pure Project
       { userMsg = Nothing
       , packages = []
-      , extraDeps = map (RPLImmutable . flip RPLIHackage Nothing) extraDeps
+      , extraDeps = map RPLImmutable extraDeps
       , flagsByPkg = mempty
       , snapshot
       , compiler = Nothing
@@ -1145,8 +1149,8 @@     ownership <- isOwnedByUser dir
     pure (dir, ownership)
 
--- | Check whether the current user (determined with 'getEffectiveUserId') is
--- the owner for the given path.
+-- | Check whether the current user (determined with
+-- 'System.Posix.User.getEffectiveUserId') is the owner for the given path.
 --
 -- Will always pure 'True' on Windows.
 isOwnedByUser :: MonadIO m => Path Abs t -> m Bool
@@ -1285,32 +1289,27 @@     liftIO $ writeBinaryFileAtomic userConfigPath defaultConfigYaml
   pure userConfigPath
 
-packagesParser :: Parser [String]
-packagesParser = many (strOption
-                   (long "package" <>
-                     metavar "PACKAGE" <>
-                     help "Add a package (can be specified multiple times)"))
-
+-- | The contents of the default Stack global configuration file.
 defaultConfigYaml :: (IsString s, Semigroup s) => s
 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/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/configure/yaml/non-project/#templates\n" <>
-  "templates:\n" <>
-  "  params:\n" <>
-  "#    author-name:\n" <>
-  "#    author-email:\n" <>
-  "#    copyright:\n" <>
-  "#    github-username:\n" <>
-  "\n" <>
-  "# The following parameter specifies Stack's output styles; STYLES is a\n" <>
-  "# colon-delimited sequence of key=value, where 'key' is a style name and\n" <>
-  "# 'value' is a semicolon-delimited list of 'ANSI' SGR (Select Graphic\n" <>
-  "# Rendition) control codes (in decimal). Use 'stack ls stack-colors --basic'\n" <>
-  "# to see the current sequence.\n" <>
-  "# stack-colors: STYLES\n"
+  "# 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/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/configure/yaml/non-project/#templates\n\
+  \templates:\n\
+  \  params:\n\
+  \#    author-name:\n\
+  \#    author-email:\n\
+  \#    copyright:\n\
+  \#    github-username:\n\
+  \\n\
+  \# The following parameter specifies Stack's output styles; STYLES is a\n\
+  \# colon-delimited sequence of key=value, where 'key' is a style name and\n\
+  \# 'value' is a semicolon-delimited list of 'ANSI' SGR (Select Graphic\n\
+  \# Rendition) control codes (in decimal). Use 'stack ls stack-colors --basic'\n\
+  \# to see the current sequence.\n\
+  \# stack-colors: STYLES\n"

@@ -2,7 +2,14 @@ {-# LANGUAGE DuplicateRecordFields #-}
 {-# LANGUAGE OverloadedRecordDot   #-}
 
--- | Build configuration
+{-|
+Module      : Stack.Config.Build
+Description : Build configuration.
+License     : BSD-3-Clause
+
+Build configuration.
+-}
+
 module Stack.Config.Build
  ( buildOptsFromMonoid
  , haddockOptsFromMonoid

@@ -1,6 +1,11 @@ {-# LANGUAGE NoImplicitPrelude #-}
 {-# LANGUAGE OverloadedStrings #-}
 
+{-|
+Module      : Stack.Config.ConfigureScript
+License     : BSD-3-Clause
+-}
+
 module Stack.Config.ConfigureScript
   ( ensureConfigureScript
   ) where
@@ -12,6 +17,8 @@ import           Stack.Prelude
 import           RIO.Process ( HasProcessContext, withWorkingDir )
 
+-- | For the given directory, yields an action that trys to generate a
+-- @configure@ script with @autoreconf@, if one does not exist in the directory.
 ensureConfigureScript ::
      (HasProcessContext env, HasTerm env)
   => Path b Dir

@@ -3,7 +3,14 @@ {-# LANGUAGE OverloadedRecordDot   #-}
 {-# LANGUAGE OverloadedStrings     #-}
 
--- | Docker configuration
+{-|
+Module      : Stack.Config.Docker
+Description : Docker configuration.
+License     : BSD-3-Clause
+
+Docker configuration.
+-}
+
 module Stack.Config.Docker
   ( ConfigDockerException (..)
   , addDefaultTag

@@ -3,9 +3,17 @@ {-# LANGUAGE OverloadedRecordDot   #-}
 {-# LANGUAGE OverloadedStrings     #-}
 
--- | Nix configuration
+{-|
+Module      : Stack.Config.Nix
+Description : Nix configuration.
+License     : BSD-3-Clause
+
+Nix configuration.
+-}
+
 module Stack.Config.Nix
-  ( nixCompiler
+  ( ConfigNixException
+  , nixCompiler
   , nixCompilerVersion
   , nixOptsFromMonoid
   ) where

@@ -4,13 +4,17 @@ {-# LANGUAGE OverloadedRecordDot #-}
 {-# LANGUAGE OverloadedStrings   #-}
 
--- | Make changes to project or global configuration.
+{-|
+Module      : Stack.ConfigCmd
+Description : Make changes to project or global configuration.
+License     : BSD-3-Clause
+
+Make changes to project or global configuration.
+-}
+
 module Stack.ConfigCmd
-  ( ConfigCmdSet (..)
-  , configCmdSetParser
-  , cfgCmdSet
+  ( cfgCmdSet
   , cfgCmdSetName
-  , configCmdEnvParser
   , cfgCmdEnv
   , cfgCmdEnvName
   , cfgCmdBuildFiles
@@ -27,9 +31,6 @@ import qualified Data.Map.Merge.Strict as Map
 import qualified Data.Text as T
 import qualified Data.Yaml as Yaml
-import qualified Options.Applicative as OA
-import           Options.Applicative.Builder.Extra
-import qualified Options.Applicative.Types as OA
 import           Pantry ( loadSnapshot )
 import           Path ( (</>), parent )
 import qualified RIO.Map as Map
@@ -50,13 +51,15 @@                    , configMonoidRecommendStackUpgradeName
                    , configMonoidSystemGHCName
                    )
+import           Stack.Types.ConfigSetOpts
+                   ( CommandScope (..), ConfigCmdSet (..) ,configCmdSetScope )
 import           Stack.Types.EnvConfig ( EnvConfig )
 import           Stack.Types.EnvSettings ( EnvSettings (..) )
 import           Stack.Types.GHCVariant ( HasGHCVariant )
 import           Stack.Types.GlobalOpts ( GlobalOpts (..) )
 import           Stack.Types.ProjectConfig ( ProjectConfig (..) )
 import           Stack.Types.Runner ( globalOptsL )
-import           Stack.Types.Snapshot ( AbstractSnapshot, readAbstractSnapshot )
+import           Stack.Types.Snapshot ( AbstractSnapshot )
 import           System.Environment ( getEnvironment )
 
 -- | Type repesenting exceptions thrown by functions exported by the
@@ -70,31 +73,7 @@     "Error: [S-3136]\n"
     ++ "'config' command used when no project configuration available."
 
-data ConfigCmdSet
-  = ConfigCmdSetSnapshot !(Unresolved AbstractSnapshot)
-  | ConfigCmdSetResolver !(Unresolved AbstractSnapshot)
-  | ConfigCmdSetSystemGhc !CommandScope !Bool
-  | ConfigCmdSetInstallGhc !CommandScope !Bool
-  | ConfigCmdSetInstallMsys !CommandScope !Bool
-  | ConfigCmdSetRecommendStackUpgrade !CommandScope !Bool
-  | ConfigCmdSetDownloadPrefix !CommandScope !Text
-
-data CommandScope
-  = CommandScopeGlobal
-    -- ^ Apply changes to the global configuration,
-    --   typically at @~/.stack/config.yaml@.
-  | CommandScopeProject
-    -- ^ Apply changes to the project @stack.yaml@.
-
-configCmdSetScope :: ConfigCmdSet -> CommandScope
-configCmdSetScope (ConfigCmdSetSnapshot _) = CommandScopeProject
-configCmdSetScope (ConfigCmdSetResolver _) = CommandScopeProject
-configCmdSetScope (ConfigCmdSetSystemGhc scope _) = scope
-configCmdSetScope (ConfigCmdSetInstallGhc scope _) = scope
-configCmdSetScope (ConfigCmdSetInstallMsys scope _) = scope
-configCmdSetScope (ConfigCmdSetRecommendStackUpgrade scope _) = scope
-configCmdSetScope (ConfigCmdSetDownloadPrefix scope _) = scope
-
+-- | Function underlying Stack's @config set@ command.
 cfgCmdSet ::
      (HasConfig env, HasGHCVariant env)
   => ConfigCmdSet -> RIO env ()
@@ -301,148 +280,26 @@ cfgCmdSetKeys (ConfigCmdSetDownloadPrefix _ _) =
   [["package-index", "download-prefix"]]
 
+-- | The name of Stack's @config@ command.
 cfgCmdName :: String
 cfgCmdName = "config"
 
+-- | The name of Stack's @config@ command's @set@ subcommand.
 cfgCmdSetName :: String
 cfgCmdSetName = "set"
 
+-- | The name of Stack's @config@ command's @env@ subcommand.
 cfgCmdEnvName :: String
 cfgCmdEnvName = "env"
 
+-- | The name of Stack's @config@ command's @build-files@ subcommand.
 cfgCmdBuildFilesName :: String
 cfgCmdBuildFilesName = "build-files"
 
-configCmdSetParser :: OA.Parser ConfigCmdSet
-configCmdSetParser =
-  OA.hsubparser $
-    mconcat
-      [ OA.command "snapshot"
-          ( OA.info
-              (   ConfigCmdSetSnapshot
-              <$> OA.argument
-                    readAbstractSnapshot
-                    (  OA.metavar "SNAPSHOT"
-                    <> OA.help "E.g. \"nightly\" or \"lts-22.8\"" ))
-              ( OA.progDesc
-                  "Change the snapshot of the current project." ))
-      , OA.command "resolver"
-          ( OA.info
-              (   ConfigCmdSetResolver
-              <$> OA.argument
-                    readAbstractSnapshot
-                    (  OA.metavar "SNAPSHOT"
-                    <> OA.help "E.g. \"nightly\" or \"lts-22.8\"" ))
-              ( OA.progDesc
-                  "Change the snapshot of the current project, using the \
-                  \resolver key." ))
-      , OA.command (T.unpack configMonoidSystemGHCName)
-          ( OA.info
-              (   ConfigCmdSetSystemGhc
-              <$> globalScopeFlag
-              <*> boolArgument )
-              ( OA.progDesc
-                  "Configure whether or not Stack should use a system GHC \
-                  \installation." ))
-      , OA.command (T.unpack configMonoidInstallGHCName)
-          ( OA.info
-              (   ConfigCmdSetInstallGhc
-              <$> globalScopeFlag
-              <*> boolArgument )
-              ( OA.progDesc
-                  "Configure whether or not Stack should automatically install \
-                  \GHC when necessary." ))
-      , OA.command (T.unpack configMonoidInstallMsysName)
-          ( OA.info
-              (   ConfigCmdSetInstallMsys
-              <$> globalScopeFlag
-              <*> boolArgument )
-              ( OA.progDesc
-                  "Configure whether or not Stack should automatically install \
-                  \MSYS2 when necessary." ))
-      , OA.command (T.unpack configMonoidRecommendStackUpgradeName)
-          ( OA.info
-              (   ConfigCmdSetRecommendStackUpgrade
-              <$> projectScopeFlag
-              <*> boolArgument )
-              ( OA.progDesc
-                  "Configure whether or not Stack should notify the user if it \
-                  \identifes a new version of Stack is available." ))
-      , OA.command "package-index"
-          ( OA.info
-              ( OA.hsubparser $
-                  OA.command "download-prefix"
-                    ( OA.info
-                        (   ConfigCmdSetDownloadPrefix
-                        <$> globalScopeFlag
-                        <*> urlArgument )
-                        ( OA.progDesc
-                            "Configure download prefix for Stack's package \
-                            \index." )))
-              ( OA.progDesc
-                  "Configure Stack's package index" ))
-      ]
-
-globalScopeFlag :: OA.Parser CommandScope
-globalScopeFlag = OA.flag
-  CommandScopeProject
-  CommandScopeGlobal
-  (  OA.long "global"
-  <> OA.help
-       "Modify the user-specific global configuration file ('config.yaml') \
-       \instead of the project-level configuration file ('stack.yaml')."
-  )
-
-projectScopeFlag :: OA.Parser CommandScope
-projectScopeFlag = OA.flag
-  CommandScopeGlobal
-  CommandScopeProject
-  (  OA.long "project"
-  <> OA.help
-       "Modify the project-level configuration file ('stack.yaml') instead of \
-       \the user-specific global configuration file ('config.yaml')."
-  )
-
-readBool :: OA.ReadM Bool
-readBool = do
-  s <- OA.readerAsk
-  case s of
-    "true" -> pure True
-    "false" -> pure False
-    _ -> OA.readerError ("Invalid value " ++ show s ++
-           ": Expected \"true\" or \"false\"")
-
-boolArgument :: OA.Parser Bool
-boolArgument = OA.argument
-  readBool
-  (  OA.metavar "true|false"
-  <> OA.completeWith ["true", "false"]
-  )
-
-urlArgument :: OA.Parser Text
-urlArgument = OA.strArgument
-  (  OA.metavar "URL"
-  <> OA.value defaultDownloadPrefix
-  <> OA.showDefault
-  <> OA.help
-       "Location of package index. It is highly recommended to use only the \
-       \official Hackage server or a mirror."
-  )
-
-configCmdEnvParser :: OA.Parser EnvSettings
-configCmdEnvParser = EnvSettings
-  <$> boolFlags True "locals" "include information about local packages" mempty
-  <*> boolFlags True
-        "ghc-package-path" "set GHC_PACKAGE_PATH environment variable" mempty
-  <*> boolFlags True "stack-exe" "set STACK_EXE environment variable" mempty
-  <*> boolFlags False
-        "locale-utf8" "set the GHC_CHARENC environment variable to UTF-8" mempty
-  <*> boolFlags False
-        "keep-ghc-rts" "keep any GHCRTS environment variable" mempty
-
 data EnvVarAction = EVASet !Text | EVAUnset
   deriving Show
 
+-- | Function underlying Stack's @config env@ command.
 cfgCmdEnv :: EnvSettings -> RIO EnvConfig ()
 cfgCmdEnv es = do
   origEnv <- liftIO $ Map.fromList . map (first fromString) <$> getEnvironment
@@ -469,6 +326,6 @@   putBuilder $ Map.foldMapWithKey toLine actions
 
 -- | This function takes no settings and yields no action of interest. It is
--- 'withBuildConfig' that yields the desired actions.
+-- 'Stack.Config.withBuildConfig' that yields the desired actions.
 cfgCmdBuildFiles :: () -> RIO BuildConfig ()
 cfgCmdBuildFiles () = pure ()

@@ -3,8 +3,14 @@ {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE TemplateHaskell   #-} -- keep TH usage here
 
--- | Constants used throughout the project.
+{-|
+Module      : Stack.Constants
+Description : Constants used throughout the project.
+License     : BSD-3-Clause
 
+Constants used throughout the project.
+-}
+
 module Stack.Constants
   ( buildPlanDir
   , buildPlanCacheDir
@@ -191,7 +197,7 @@ haskellDefaultPreprocessorExts :: [Text]
 haskellDefaultPreprocessorExts = ["gc", "chs", "hsc", "x", "y", "ly", "cpphs"]
 
--- | Name of the 'stack' program, uppercased
+-- | Name of the \'stack\' program, uppercased
 stackProgNameUpper :: String
 stackProgNameUpper = map toUpper stackProgName
 

@@ -2,6 +2,11 @@ {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE TemplateHaskell   #-}
 
+{-|
+Module      : Stack.Constants.Config
+License     : BSD-3-Clause
+-}
+
 module Stack.Constants.Config
   ( buildCachesDir
   , configCabalMod

@@ -1,5 +1,13 @@ {-# LANGUAGE NoImplicitPrelude #-}
 
+{-|
+Module      : Stack.Constants.StackProgName
+License     : BSD-3-Clause
+
+'stackProgName' is defined in this module rather than in "Stack.Constants", due
+to GHC stage restrictions and the use of Template Haskell.
+-}
+
 module Stack.Constants.StackProgName
   ( stackProgName
   ) where
@@ -7,8 +15,5 @@ import           Stack.Prelude ( String )
 
 -- | Name of the Stack program.
-
--- NOTE: Defined in this module rather than in "Stack.Constants", due to
--- GHC stage restrictions and the use of Template Haskell.
 stackProgName :: String
 stackProgName = "stack"

@@ -5,14 +5,19 @@ {-# LANGUAGE OverloadedRecordDot   #-}
 {-# LANGUAGE OverloadedStrings     #-}
 
--- | Generate HPC (Haskell Program Coverage) reports
+{-|
+Module      : Stack.Coverage
+Description : Generate HPC (Haskell Program Coverage) reports.
+License     : BSD-3-Clause
+
+Generate HPC (Haskell Program Coverage) reports.
+-}
+
 module Stack.Coverage
-  ( HpcReportOpts (..)
-  , hpcReportCmd
+  ( hpcReportCmd
   , deleteHpcReports
   , updateTixFile
   , generateHpcReport
-  , generateHpcReportForTargets
   , generateHpcUnifiedReport
   , generateHpcMarkupIndex
   ) where
@@ -27,7 +32,6 @@ import           Distribution.Types.MungedPackageId ( computeCompatPackageId )
 import           Distribution.Types.UnqualComponentName
                    ( mkUnqualComponentName )
-import           Distribution.Version ( mkVersion )
 import           Path
                    ( (</>), dirname, parent, parseAbsFile, parseRelDir
                    , parseRelFile, stripProperPrefix
@@ -54,16 +58,14 @@ import           Stack.Runners ( ShouldReexec (..), withConfig, withEnvConfig )
 import           Stack.Types.BuildConfig
                    ( BuildConfig (..), HasBuildConfig (..) )
-import           Stack.Types.Compiler ( getGhcVersion )
 import           Stack.Types.CompilerPaths ( getGhcPkgExe )
 import           Stack.Types.CompCollection ( getBuildableSetText )
 import           Stack.Types.ComponentUtils ( unqualCompToString )
 import           Stack.Types.BuildOptsCLI
                    ( BuildOptsCLI (..), defaultBuildOptsCLI )
 import           Stack.Types.EnvConfig
-                   ( EnvConfig (..), HasEnvConfig (..), actualCompilerVersionL
-                   , hpcReportDir
-                   )
+                   ( EnvConfig (..), HasEnvConfig (..), hpcReportDir )
+import           Stack.Types.HpcReportOpts ( HpcReportOpts (..) )
 import           Stack.Types.NamedComponent ( NamedComponent (..) )
 import           Stack.Types.Package ( Package (..), packageIdentifier )
 import           Stack.Types.Runner ( Runner )
@@ -109,15 +111,6 @@ 
 instance Exception CoveragePrettyException
 
--- | Type representing command line options for the @stack hpc report@ command.
-data HpcReportOpts = HpcReportOpts
-  { inputs :: [Text]
-  , all :: Bool
-  , destDir :: Maybe String
-  , openBrowser :: Bool
-  }
-  deriving Show
-
 -- | Function underlying the @stack hpc report@ command.
 hpcReportCmd :: HpcReportOpts -> RIO Runner ()
 hpcReportCmd hropts = do
@@ -184,40 +177,37 @@   tixRel <- parseRelFile (testName ++ "/" ++ testName ++ ".tix")
   pure (pkgPath </> tixRel)
 
--- | Generates the HTML coverage report and shows a textual coverage summary for a package.
+-- | Generates the HTML coverage report and shows a textual coverage summary for
+-- a package.
 generateHpcReport :: HasEnvConfig env
                   => Path Abs Dir -> Package -> [Text] -> RIO env ()
 generateHpcReport pkgDir package tests = do
-  compilerVersion <- view actualCompilerVersionL
-  -- If we're using > GHC 7.10, the hpc 'include' parameter must specify a ghc package key. See
+  -- If we're using > GHC 7.10, the hpc 'include' parameter must specify a ghc
+  -- package key. See
   -- https://github.com/commercialhaskell/stack/issues/785
-  let pkgId = packageIdentifierString $ packageIdentifier package
-      pkgName' = packageNameString package.name
-      ghcVersion = getGhcVersion compilerVersion
+  let pkgName' = packageNameString package.name
       hasLibrary = hasBuildableMainLibrary package
       subLibs = package.subLibraries
   eincludeName <-
-    -- Pre-7.8 uses plain PKG-version in tix files.
-    if ghcVersion < mkVersion [7, 10] then pure $ Right $ Just [pkgId]
-    -- We don't expect to find a package key if there is no library.
-    else if not hasLibrary && null subLibs then pure $ Right Nothing
-    -- Look in the inplace DB for the package key.
-    -- See https://github.com/commercialhaskell/stack/issues/1181#issuecomment-148968986
-    else do
-      -- GHC 8.0 uses package id instead of package key.
-      -- See https://github.com/commercialhaskell/stack/issues/2424
-      let hpcNameField = if ghcVersion >= mkVersion [8, 0] then "id" else "key"
-      eincludeName <-
-        findPackageFieldForBuiltPackage
-          pkgDir
-          (packageIdentifier package)
-          (getBuildableSetText subLibs)
-          hpcNameField
-      case eincludeName of
-        Left err -> do
-          logError $ display err
-          pure $ Left err
-        Right includeNames -> pure $ Right $ Just $ map T.unpack includeNames
+    if not hasLibrary && null subLibs
+      -- We don't expect to find a package key if there is no library.
+      then pure $ Right Nothing
+      -- Look in the inplace DB for the package key.
+      -- See https://github.com/commercialhaskell/stack/issues/1181#issuecomment-148968986
+      else do
+        eincludeName <-
+          findPackageFieldForBuiltPackage
+            pkgDir
+            (packageIdentifier package)
+            (getBuildableSetText subLibs)
+            -- GHC 8.0 uses package id instead of package key.
+            -- See https://github.com/commercialhaskell/stack/issues/2424
+            "id"
+        case eincludeName of
+          Left err -> do
+            logError $ display err
+            pure $ Left err
+          Right includeNames -> pure $ Right $ Just $ map T.unpack includeNames
   forM_ tests $ \testName -> do
     tixSrc <- tixFilePath package.name (T.unpack testName)
     let report = fillSep
@@ -431,6 +421,7 @@         void $ liftIO $ openBrowser (toFilePath reportPath)
       else displayReportPath "The" report (pretty reportPath)
 
+-- | Generates the HTML unified coverage report.
 generateHpcUnifiedReport :: HasEnvConfig env => RIO env ()
 generateHpcUnifiedReport = do
   outputDir <- hpcReportDir
@@ -528,6 +519,7 @@         Right (TixModule k hash1 len1 (zipWith (+) tix1 tix2))
   merge _ _ = Left ()
 
+-- | Generates the HTML index report.
 generateHpcMarkupIndex :: HasEnvConfig env => RIO env ()
 generateHpcMarkupIndex = do
   outputDir <- hpcReportDir

@@ -1,5 +1,10 @@ {-# LANGUAGE LambdaCase #-}
 
+{-|
+Module      : Stack.DefaultColorWhen
+License     : BSD-3-Clause
+-}
+
 module Stack.DefaultColorWhen
   ( defaultColorWhen
   ) where

@@ -4,8 +4,14 @@ {-# LANGUAGE OverloadedRecordDot   #-}
 {-# LANGUAGE OverloadedStrings     #-}
 
--- | Module exporting a function to create a pruned dependency graph given a
--- 'DotOpts' value.
+{-|
+Module      : Stack.DependencyGraph
+License     : BSD-3-Clause
+
+Module exporting a function to create a pruned dependency graph given
+a t'DotOpts' value.
+-}
+
 module Stack.DependencyGraph
   ( createPrunedDependencyGraph
   , resolveDependencies

@@ -3,7 +3,14 @@ {-# LANGUAGE OverloadedRecordDot #-}
 {-# LANGUAGE OverloadedStrings   #-}
 
--- | Run commands in Docker containers
+{-|
+Module      : Stack.Docker
+Description : Run commands in Docker containers.
+License     : BSD-3-Clause
+
+Run commands in Docker containers.
+-}
+
 module Stack.Docker
   ( dockerCmdName
   , dockerHelpOptName
@@ -584,7 +591,7 @@                         (removeFile f))
 
 -- | Produce a strict 'S.ByteString' from the stdout of a process. Throws a
--- 'ReadProcessException' exception if the process fails.
+-- 'Rio.Process.ReadProcessException' exception if the process fails.
 --
 -- The stderr output is passed straight through, which is desirable for some
 -- cases e.g. docker pull, in which docker uses stderr for progress output.
@@ -599,7 +606,7 @@ homeDirName :: Path Rel Dir
 homeDirName = relDirUnderHome
 
--- | Directory where 'stack' executable is bind-mounted in Docker container
+-- | Directory where \'stack\' executable is bind-mounted in Docker container
 -- This refers to a path in the Linux *container*, and so should remain a
 -- 'FilePath' (not 'Path Abs Dir') so that it works when the host runs Windows.
 hostBinDir :: FilePath

@@ -1,6 +1,14 @@ {-# LANGUAGE NoImplicitPrelude #-}
 
--- | Functions related to Stack's @docker pull@ and @docker reset@ commands.
+{-|
+Module      : Stack.DockerCmd
+Description : Functions related to Stack's @docker pull@ and @docker reset@
+              commands.
+License     : BSD-3-Clause
+
+Functions related to Stack's @docker pull@ and @docker reset@ commands.
+-}
+
 module Stack.DockerCmd
   ( dockerPullCmd
   , dockerResetCmd

@@ -2,7 +2,14 @@ {-# LANGUAGE OverloadedRecordDot #-}
 {-# LANGUAGE OverloadedStrings   #-}
 
--- | Functions related to Stack's @dot@ command.
+{-|
+Module      : Stack.Dot
+Description : Functions related to Stack's @dot@ command.
+License     : BSD-3-Clause
+
+Functions related to Stack's @dot@ command.
+-}
+
 module Stack.Dot
   ( dotCmd
   , printGraph

@@ -3,7 +3,14 @@ {-# LANGUAGE NoFieldSelectors      #-}
 {-# LANGUAGE OverloadedRecordDot   #-}
 
--- | Types and functions related to Stack's @eval@ command.
+{-|
+Module      : Stack.Eval
+Description : Types and functions related to Stack's @eval@ command.
+License     : BSD-3-Clause
+
+Types and functions related to Stack's @eval@ command.
+-}
+
 module Stack.Eval
   ( EvalOpts (..)
   , evalCmd
@@ -16,7 +23,7 @@ import           Stack.Prelude
 import           Stack.Types.Runner ( Runner )
 
--- Type representing command line options for the @stack eval@ command.
+-- | Type representing command line options for the @stack eval@ command.
 data EvalOpts = EvalOpts
   { arg :: !String
   , extra :: !ExecOptsExtra

@@ -2,8 +2,16 @@ {-# LANGUAGE OverloadedRecordDot #-}
 {-# LANGUAGE OverloadedStrings   #-}
 
--- | Types and function related to Stack's @exec@, @ghc@, @run@, @runghc@ and
--- @runhaskell@ commands.
+{-|
+Module      : Stack.Exec
+Description : Types and function related to Stack's @exec@, @ghc@, @run@,
+              @runghc@ and @runhaskell@ commands.
+License     : BSD-3-Clause
+
+Types and function related to Stack's @exec@, @ghc@, @run@, @runghc@ and
+@runhaskell@ commands.
+-}
+
 module Stack.Exec
   ( ExecOpts (..)
   , SpecialExecCmd (..)
@@ -94,14 +102,19 @@ 
 instance Exception ExecPrettyException
 
--- Type representing Stack's execution commands.
+-- | Type representing Stack's execution commands.
 data SpecialExecCmd
   = ExecCmd String
+    -- ^ @stack exec@ command.
   | ExecRun
+    -- ^ @stack run@ command.
   | ExecGhc
+    -- ^ @stack ghc@ command.
   | ExecRunGhc
+    -- ^ @stack runghc@ or @stack runhaskell@ command.
   deriving (Eq, Show)
 
+-- | Type representing extra Stack options for Stack's execution commands.
 data ExecOptsExtra = ExecOptsExtra
   { envSettings :: !EnvSettings
   , packages :: ![String]
@@ -110,7 +123,7 @@   }
   deriving Show
 
--- Type representing options for Stack's execution commands.
+-- | Type representing options for Stack's execution commands.
 data ExecOpts = ExecOpts
   { cmd :: !SpecialExecCmd
   , args :: ![String]
@@ -118,7 +131,7 @@   }
   deriving Show
 
--- Type representing valid targets for --package option.
+-- | Type representing valid targets for @--package@ option.
 data ExecTarget = ExecTarget PackageName (Maybe Version)
 
 -- | The function underlying Stack's @exec@, @ghc@, @run@, @runghc@ and

@@ -2,6 +2,11 @@ {-# LANGUAGE OverloadedRecordDot #-}
 {-# LANGUAGE OverloadedStrings   #-}
 
+{-|
+Module      : Stack.FileWatch
+License     : BSD-3-Clause
+-}
+
 module Stack.FileWatch
   ( WatchMode (WatchModePoll)
   , fileWatch

@@ -3,8 +3,14 @@ {-# LANGUAGE OverloadedRecordDot #-}
 {-# LANGUAGE OverloadedStrings   #-}
 
--- | Functions for the GHC package database.
+{-|
+Module      : Stack.GhcPkg
+Description : Functions for the GHC package database.
+License     : BSD-3-Clause
 
+Functions for the GHC package database.
+-}
+
 module Stack.GhcPkg
   ( createDatabase
   , findGhcPkgField
@@ -33,6 +39,7 @@                    ( CompilerPaths (..), GhcPkgExe (..), HasCompiler
                    , compilerPathsL
                    )
+import           Stack.Types.GhcPkgExe ( GhcPkgPrettyException (..) )
 import           Stack.Types.GhcPkgId ( GhcPkgId, ghcPkgIdString )
 import           System.FilePath ( searchPathSeparator )
 
@@ -65,7 +72,16 @@ ghcPkg pkgexe@(GhcPkgExe pkgPath) pkgDbs args = do
   eres <- go
   case eres of
-    Left _ -> do
+    Left e -> do
+      prettyDebug $
+           fillSep
+             [ flow "While using"
+             , style Shell "ghc-pkg" <>","
+             , flow "Stack encountered the following error:"
+             ]
+        <> blankLine
+        <> string (displayException e)
+        <> flow "Trying again after considering database creation..."
       mapM_ (createDatabase pkgexe) pkgDbs
       go
     Right _ -> pure eres
@@ -145,7 +161,7 @@ -- using GHC package id where available (from GHC 7.9)
 --
 -- The version of the ghc-pkg executable supplied with GHCs published before
--- 28 August 2023 does not efficiently bulk unregister. Until an 'efficient'
+-- 28 August 2023 does not efficiently bulk unregister. Until an \'efficient\'
 -- ghc-pkg is available, this function no longer uses:
 --
 -- >   eres <- ghcPkg pkgexe [pkgDb] args
@@ -170,13 +186,9 @@   -> RIO env ()
 unregisterGhcPkgIds isWarn pkgexe pkgDb epgids = do
   globalDb <- view $ compilerPathsL . to (.globalDB)
-  eres <- try $ do
+  eresUnregister <- try $ do
     ghcPkgUnregisterForce globalDb pkgDb hasIpid pkgarg_strs
-    -- ghcPkgUnregisterForce does not perform an effective
-    -- 'ghc-pkg recache', as that depends on a specific version of the Cabal
-    -- package.
-    ghcPkg pkgexe [pkgDb] ["recache"]
-  case eres of
+  case eresUnregister of
     Left (PrettyException e) -> when isWarn $
       prettyWarn $
         "[S-8729]"
@@ -185,6 +197,12 @@                 \error:"
         <> blankLine
         <> pretty e
+    Right _ -> pure ()
+  -- ghcPkgUnregisterForce does not perform an effective 'ghc-pkg recache', as
+  -- that depends on a specific version of the Cabal package.
+  eresRecache <- ghcPkg pkgexe [pkgDb] ["recache"]
+  case eresRecache of
+    Left err -> prettyThrowM $ CannotRecacheAfterUnregister pkgDb err
     Right _ -> pure ()
  where
   (idents, gids) = partitionEithers $ toList epgids

@@ -4,12 +4,18 @@ {-# LANGUAGE OverloadedRecordDot   #-}
 {-# LANGUAGE OverloadedStrings     #-}
 
--- | Types and functions related to Stack's @ghci@ and @repl@ commands.
+{-|
+Module      : Stack.Ghci
+License     : BSD-3-Clause
+
+Types and functions related to Stack's @ghci@ and @repl@ commands.
+-}
+
 module Stack.Ghci
   ( GhciOpts (..)
   , GhciPkgInfo (..)
-  , GhciException (..)
   , GhciPrettyException (..)
+  , ModuleMap
   , ghciCmd
   , ghci
   ) where
@@ -73,6 +79,7 @@                    , shaPathForBytes
                    )
 import           Stack.Types.EnvSettings ( defaultEnvSettings )
+import           Stack.Types.GhciOpts ( GhciOpts (..) )
 import           Stack.Types.Installed ( InstallMap, InstalledMap )
 import           Stack.Types.NamedComponent
                    ( NamedComponent (..), isCLib, isCSubLib, renderComponentTo
@@ -94,42 +101,15 @@ import           System.IO ( putStrLn )
 import           System.Permissions ( setScriptPerms )
 
--- | Type representing exceptions thrown by functions exported by the
--- "Stack.Ghci" module.
-data GhciException
-  = InvalidPackageOption !String
-  | LoadingDuplicateModules
-  | MissingFileTarget !String
-  | Can'tSpecifyFilesAndTargets
-  | Can'tSpecifyFilesAndMainIs
-  deriving (Show, Typeable)
-
-instance Exception GhciException where
-  displayException (InvalidPackageOption name) =
-    "Error: [S-6716]\n"
-    ++ "Failed to parse '--package' option " ++ name ++ "."
-  displayException LoadingDuplicateModules = unlines
-    [ "Error: [S-9632]"
-    , "Not attempting to start ghci due to these duplicate modules."
-    , "Use '--no-load' to try to start it anyway, without loading any \
-      \modules (but these are still likely to cause errors)."
-    ]
-  displayException (MissingFileTarget name) =
-    "Error: [S-3600]\n"
-    ++ "Cannot find file target " ++ name ++ "."
-  displayException Can'tSpecifyFilesAndTargets =
-    "Error: [S-9906]\n"
-    ++ "Cannot use 'stack ghci' with both file targets and package targets."
-  displayException Can'tSpecifyFilesAndMainIs =
-    "Error: [S-5188]\n"
-    ++ "Cannot use 'stack ghci' with both file targets and '--main-is' \
-       \flag."
-
 -- | Type representing \'pretty\' exceptions thrown by functions exported by the
 -- "Stack.Ghci" module.
 data GhciPrettyException
   = GhciTargetParseException ![StyleDoc]
   | CandidatesIndexOutOfRangeBug
+  | InvalidPackageOption !String
+  | FileTargetIsInvalidAbsFile !String
+  | Can'tSpecifyFilesAndTargets
+  | Can'tSpecifyFilesAndMainIs
   deriving (Show, Typeable)
 
 instance Pretty GhciPrettyException where
@@ -144,27 +124,43 @@          ]
   pretty CandidatesIndexOutOfRangeBug = bugPrettyReport "[S-1939]" $
     flow "figureOutMainFile: index out of range."
+  pretty (InvalidPackageOption name) =
+       "[S-6716]"
+    <> line
+    <> fillSep
+         [ flow "Failed to parse"
+         , style Shell "--package"
+         , "option"
+         , style Target (fromString name) <> "."
+         ]
+  pretty (FileTargetIsInvalidAbsFile name) =
+       "[S-3600]"
+    <> line
+    <> fillSep
+         [ flow "Cannot work out a valid path for file target"
+         , style File (fromString name) <> "."
+         ]
+  pretty Can'tSpecifyFilesAndTargets =
+       "[S-9906]"
+    <> line
+    <> fillSep
+         [ flow "Cannot use"
+         , style Shell "stack ghci"
+         , flow "with both file targets and package targets."
+         ]
+  pretty Can'tSpecifyFilesAndMainIs =
+       "[S-5188]"
+    <> line
+    <> fillSep
+         [ flow "Cannot use"
+         , style Shell "stack ghci"
+         , flow "with both file targets and"
+         , style Shell "--main-is"
+         , "flag."
+         ]
 
 instance Exception GhciPrettyException
 
--- | Typre respresenting command line options for the @stack ghci@ and
--- @stack repl@ commands.
-data GhciOpts = GhciOpts
-  { targets            :: ![Text]
-  , args               :: ![String]
-  , ghcOptions         :: ![String]
-  , flags              :: !(Map ApplyCLIFlag (Map FlagName Bool))
-  , ghcCommand         :: !(Maybe FilePath)
-  , noLoadModules      :: !Bool
-  , additionalPackages :: ![String]
-  , mainIs             :: !(Maybe Text)
-  , loadLocalDeps      :: !Bool
-  , hidePackages       :: !(Maybe Bool)
-  , noBuild            :: !Bool
-  , onlyMain           :: !Bool
-  }
-  deriving Show
-
 -- | Type representing information required to load a package or its components.
 --
 -- NOTE: GhciPkgInfo has paths as list instead of a Set to preserve files order
@@ -188,8 +184,10 @@   , target :: !Target
   }
 
--- Mapping from a module name to a map with all of the paths that use that name.
--- Each of those paths is associated with a set of components that contain it.
+-- | Type synonym representing maps from a module name to a map with all of the
+-- paths that use that name. Each of those paths is associated with a set of
+-- components that contain it.
+
 -- The purpose of this complex structure is for use in
 -- 'checkForDuplicateModules'.
 type ModuleMap =
@@ -247,7 +245,7 @@   (inputTargets, mfileTargets) <- case etargets of
     Right packageTargets -> pure (packageTargets, Nothing)
     Left rawFileTargets -> do
-      whenJust mainIsTargets $ \_ -> throwM Can'tSpecifyFilesAndMainIs
+      whenJust mainIsTargets $ \_ -> prettyThrowM Can'tSpecifyFilesAndMainIs
       -- Figure out targets based on filepath targets
       (targetMap, fileInfo, extraFiles) <- findFileTargets locals rawFileTargets
       pure (targetMap, Just (fileInfo, extraFiles))
@@ -315,7 +313,7 @@         let fp = T.unpack fp0
         mpath <- forgivingResolveFile' fp
         case mpath of
-          Nothing -> throwM (MissingFileTarget fp)
+          Nothing -> prettyThrowM (FileTargetIsInvalidAbsFile fp)
           Just path -> pure path
       pure (Left fileTargets)
     else do
@@ -328,7 +326,7 @@             Just (TargetParseException xs) ->
               prettyThrowM $ GhciTargetParseException xs
             _ -> throwM pex
-      unless (null fileTargetsRaw) $ throwM Can'tSpecifyFilesAndTargets
+      unless (null fileTargetsRaw) $ prettyThrowM Can'tSpecifyFilesAndTargets
       pure (Right normalTargets.targets)
 
 parseMainIsTargets ::
@@ -482,7 +480,7 @@ checkAdditionalPackages pkgs = forM pkgs $ \name -> do
   let mres = (pkgName <$> parsePackageIdentifier name)
         <|> parsePackageNameThrowing name
-  maybe (throwM $ InvalidPackageOption name) pure mres
+  maybe (prettyThrowM $ InvalidPackageOption name) pure mres
 
 runGhci ::
      HasEnvConfig env
@@ -1091,14 +1089,14 @@ checkForDuplicateModules :: HasTerm env => [GhciPkgInfo] -> RIO env ()
 checkForDuplicateModules pkgs =
   unless (null duplicates) $
+    -- Two or more files with the same module name are treated as a warning
+    -- rather than an error. See:
+    -- https://github.com/commercialhaskell/stack/issues/5407#issuecomment-707339928
     prettyWarn $
          flow "Multiple files use the same module name:"
       <> line
       <> bulletedList (map prettyDuplicate duplicates)
       <> line
-    -- MSS 2020-10-13 Disabling, may remove entirely in the future
-    -- See: https://github.com/commercialhaskell/stack/issues/5407#issuecomment-707339928
-    -- throwM LoadingDuplicateModules
  where
   duplicates ::
     [(ModuleName, Map (Path Abs File) (Set (PackageName, NamedComponent)))]

@@ -2,6 +2,11 @@ {-# LANGUAGE OverloadedRecordDot #-}
 {-# LANGUAGE OverloadedStrings   #-}
 
+{-|
+Module      : Stack.Ghci.Script
+License     : BSD-3-Clause
+-}
+
 module Stack.Ghci.Script
   ( GhciScript
   , ModuleName

@@ -3,7 +3,14 @@ {-# LANGUAGE OverloadedRecordDot   #-}
 {-# LANGUAGE OverloadedStrings     #-}
 
--- | A wrapper around hoogle.
+{-|
+Module      : Stack.Hoogle
+Description : A wrapper around hoogle.
+License     : BSD-3-Clause
+
+A wrapper around hoogle.
+-}
+
 module Stack.Hoogle
   ( hoogleCmd
   ) where

@@ -2,7 +2,14 @@ {-# LANGUAGE OverloadedRecordDot #-}
 {-# LANGUAGE OverloadedStrings   #-}
 
--- | Types and functions related to Stack's @ide@ command.
+{-|
+Module      : Stack.IDE
+Description : Types and functions related to Stack's @ide@ command.
+License     : BSD-3-Clause
+
+Types and functions related to Stack's @ide@ command.
+-}
+
 module Stack.IDE
   ( OutputStream (..)
   , ListPackagesCmd (..)
@@ -21,6 +28,7 @@                    ( ShouldReexec (..), withBuildConfig, withConfig )
 import           Stack.Types.BuildConfig
                    ( BuildConfig (..), HasBuildConfig (..) )
+import           Stack.Types.IdeOpts ( ListPackagesCmd (..), OutputStream (..) )
 import           Stack.Types.NamedComponent
                    ( NamedComponent, isCBench, isCExe, isCTest
                    , renderPkgComponent
@@ -29,21 +37,6 @@ import           Stack.Types.SourceMap
                    ( ProjectPackage (..), SMWanted (..), ppComponentsMaybe )
 import           System.IO ( putStrLn )
-
--- Type representing output stream choices for the @stack ide packages@ and
--- @stack ide targets@ commands.
-data OutputStream
-  = OutputLogInfo
-    -- ^ To the same output stream as other log information.
-  | OutputStdout
-    -- ^ To the standard output stream.
-
--- Type representing output choices for the @stack ide packages@ command.
-data ListPackagesCmd
-  = ListPackageNames
-    -- ^ Package names.
-  | ListPackageCabalFiles
-    -- ^ Paths to Cabal files.
 
 -- | Function underlying the @stack ide packages@ command. List packages in the
 -- project.

@@ -4,7 +4,14 @@ {-# LANGUAGE OverloadedStrings     #-}
 {-# LANGUAGE TypeFamilies          #-}
 
--- | Types and functions related to Stack's @init@ command.
+{-|
+Module      : Stack.Init
+Description : Types and functions related to Stack's @init@ command.
+License     : BSD-3-Clause
+
+Types and functions related to Stack's @init@ command.
+-}
+
 module Stack.Init
   ( InitOpts (..)
   , initCmd
@@ -430,8 +437,8 @@     , "A snapshot resolver dictates the compiler version and the set of packages"
     , "to be used for project dependencies. For example:"
     , ""
-    , "snapshot: lts-23.14"
-    , "snapshot: nightly-2025-02-15"
+    , "snapshot: lts-23.24"
+    , "snapshot: nightly-2025-06-15"
     , "snapshot: ghc-9.8.4"
     , ""
     , "The location of a snapshot can be provided as a file or url. Stack assumes"
@@ -536,7 +543,7 @@        , Map PackageName (Map FlagName Bool)
        , Map PackageName Version
        , Map PackageName (ResolvedPath Dir))
-     -- ^ ( SnapshotDef
+     -- ^ ( Raw snapshot location
      --   , Flags for src packages and extra deps
      --   , Extra dependencies
      --   , Src packages actually considered)

@@ -1,7 +1,14 @@ {-# LANGUAGE NoImplicitPrelude   #-}
 {-# LANGUAGE OverloadedStrings   #-}
 
--- | Types and functions related to Stack's @list@ command.
+{-|
+Module      : Stack.List
+Description : Types and functions related to Stack's @list@ command.
+License     : BSD-3-Clause
+
+Types and functions related to Stack's @list@ command.
+-}
+
 module Stack.List
   ( listCmd
   , listPackages
@@ -104,7 +111,7 @@   toLocSnapshot snapshot name =
     case Map.lookup name (rsPackages snapshot) of
       Nothing -> case Map.lookup name =<< mGlobals of
-        Nothing -> 
+        Nothing ->
           pure $ Left $ fillSep
             [ flow "Package does not appear in snapshot (directly or \
                    \indirectly):"

@@ -3,6 +3,11 @@ {-# LANGUAGE OverloadedRecordDot #-}
 {-# LANGUAGE OverloadedStrings   #-}
 
+{-|
+Module      : Stack.Lock
+License     : BSD-3-Clause
+-}
+
 module Stack.Lock
   ( lockCachedWanted
   , LockedLocation (..)
@@ -19,8 +24,7 @@ import qualified Data.Text as T
 import qualified Data.Yaml as Yaml
 import qualified RIO.NonEmpty as NE
-import           Path ( parent )
-import           Path.Extended ( addExtension )
+import           Path ( addExtension, parent )
 import           Path.IO ( doesFileExist )
 import           Stack.Prelude
 import           Stack.SourceMap ( snapToDepPackage )
@@ -52,6 +56,7 @@ 
 instance Exception LockPrettyException
 
+-- | Type representing locked locations.
 data LockedLocation a b = LockedLocation
   { original :: a
   , completed :: b
@@ -85,6 +90,7 @@       let withWarnings x = WithJSONWarnings x ws
       pure $ withWarnings $ SingleRPLI . NE.head <$> unresolvedRPLIs
 
+-- | Type representing the contents of lock files.
 data Locked = Locked
   { snapshotLocations :: [LockedLocation RawSnapshotLocation SnapshotLocation]
   , pkgImmutableLocations :: [LockedLocation RawPackageLocationImmutable PackageLocationImmutable]
@@ -122,10 +128,14 @@         logJSONWarnings (toFilePath path) warnings
         pure res
 
+-- | Yields a t'Stack.Types.SourceMap.SMWanted' taking into account the relevant
+-- lock file, if one is applicable and it exists.
 lockCachedWanted ::
      (HasPantryConfig env, HasRunner env)
   => Path Abs File
+     -- ^ The relevant Stack project-level configuration file.
   -> RawSnapshotLocation
+     -- ^ The relevant snapshot.
   -> (  Map RawPackageLocationImmutable PackageLocationImmutable
      -> WantedCompiler
      -> Map PackageName (Bool -> RIO env DepPackage)

@@ -3,20 +3,16 @@ {-# LANGUAGE OverloadedRecordDot #-}
 {-# LANGUAGE OverloadedStrings   #-}
 
--- | Types and functions related to Stack's @ls@ command.
+{-|
+Module      : Stack.Ls
+Description : Types and functions related to Stack's @ls@ command.
+License     : BSD-3-Clause
+
+Types and functions related to Stack's @ls@ command.
+-}
+
 module Stack.Ls
-  ( LsCmdOpts (..)
-  , LsCmds (..)
-  , SnapshotOpts (..)
-  , LsView (..)
-  , ListDepsOpts (..)
-  , ListDepsFormat (..)
-  , ListDepsFormatOpts (..)
-  , ListDepsTextFilter (..)
-  , ListGlobalsOpts (..)
-  , ListStylesOpts (..)
-  , ListToolsOpts (..)
-  , lsCmd
+  ( lsCmd
   ) where
 
 import           Control.Monad.Extra ( whenJust )
@@ -50,7 +46,7 @@ import           Stack.Setup.Installed
                    ( Tool (..), filterTools, listInstalled, toolString )
 import           Stack.SourceMap ( globalsFromHints )
-import           Stack.Types.BuildConfig 
+import           Stack.Types.BuildConfig
                    ( BuildConfig (..), HasBuildConfig (..) )
 import           Stack.Types.Config ( Config (..), HasConfig (..) )
 import           Stack.Types.DependencyTree
@@ -60,6 +56,13 @@ import           Stack.Types.DotOpts ( DotOpts (..) )
 import           Stack.Types.DumpPackage ( DumpPackage (..) )
 import           Stack.Types.EnvConfig ( EnvConfig (..), installationRootDeps )
+import           Stack.Types.LsOpts
+                   ( LsCmdOpts (..), LsCmds (..), ListDepsFormat (..)
+                   , ListDepsFormatOpts (..), ListDepsOpts (..)
+                   , ListDepsTextFilter (..), ListGlobalsOpts (..)
+                   , ListStylesOpts (..), ListToolsOpts (..), LsView (..)
+                   , SnapshotOpts (..)
+                   )
 import           Stack.Types.Runner ( HasRunner, Runner, terminalL )
 import           Stack.Types.SourceMap ( SMWanted (..) )
 import           System.Console.ANSI.Codes
@@ -80,33 +83,6 @@     ++ "Failure to parse values as a snapshot: "
     ++ show val
 
--- | Type representing command line options for the @stack ls@ command.
-newtype LsCmdOpts
-  = LsCmdOpts { lsCmds :: LsCmds }
-
--- | Type representing subcommands for the @stack ls@ command.
-data LsCmds
-  = LsSnapshot SnapshotOpts
-  | LsGlobals ListGlobalsOpts
-  | LsDependencies ListDepsOpts
-  | LsStyles ListStylesOpts
-  | LsTools ListToolsOpts
-
--- | Type representing command line options for the @stack ls snapshots@
--- command.
-data SnapshotOpts = SnapshotOpts
-  { viewType :: LsView
-  , ltsSnapView :: Bool
-  , nightlySnapView :: Bool
-  }
-  deriving (Eq, Ord, Show)
-
--- | Type representing subcommands for the @stack ls snapshots@ command.
-data LsView
-  = Local
-  | Remote
-  deriving (Eq, Ord, Show)
-
 -- | Type representing Stackage snapshot types.
 data SnapshotType
   = Lts
@@ -115,51 +91,6 @@     -- ^ Stackage Nightly
   deriving (Eq, Ord, Show)
 
-newtype ListGlobalsOpts = ListGlobalsOpts
-  { globalHints :: Bool
-    -- ^ Use global hints instead of relying on an actual GHC installation.
-  }
-
-data ListDepsOpts = ListDepsOpts
-  { format :: !ListDepsFormat
-    -- ^ Format of printing dependencies
-  , dotOpts :: !DotOpts
-    -- ^ The normal dot options.
-  }
-
-data ListDepsFormat
-  = ListDepsText ListDepsFormatOpts [ListDepsTextFilter]
-  | ListDepsTree ListDepsFormatOpts
-  | ListDepsJSON
-  | ListDepsConstraints
-
-data ListDepsFormatOpts = ListDepsFormatOpts
-  { sep :: !Text
-    -- ^ Separator between the package name and details.
-  , license :: !Bool
-    -- ^ Print dependency licenses instead of versions.
-  }
-
--- | Type representing items to filter the results of @stack ls dependencies@.
-data ListDepsTextFilter
-  = FilterPackage PackageName
-    -- ^ Item is a package name.
-  | FilterLocals
-    -- ^ Item represents all project packages.
-
--- | Type representing command line options for the @stack ls stack-colors@ and
--- @stack ls stack-colours@ commands.
-data ListStylesOpts = ListStylesOpts
-  { basic   :: Bool
-  , sgr     :: Bool
-  , example :: Bool
-  }
-  deriving (Eq, Ord, Show)
-
--- | Type representing command line options for the @stack ls tools@ command.
-newtype ListToolsOpts
-  = ListToolsOpts { filter  :: String }
-
 data Snapshot = Snapshot
   { snapId :: Text
   , title :: Text
@@ -294,6 +225,7 @@  where
   urlInfo = "https://www.stackage.org/snapshots"
 
+-- | Function underlying the @stack ls@ command.
 lsCmd :: LsCmdOpts -> RIO Runner ()
 lsCmd lsOpts =
   case lsOpts.lsCmds of
@@ -333,7 +265,7 @@     ansi = fromString $ setSGRCode sgrs
     reset = fromString $ setSGRCode [Reset]
 
--- | List Stack's installed tools, sorted (see instance of 'Ord' for 'Tool').
+-- | List Stack's installed tools, sorted (see instance of 'Ord' for t'Tool').
 listToolsCmd :: ListToolsOpts -> RIO Config ()
 listToolsCmd opts = do
   localPrograms <- view $ configL . to (.localPrograms)

@@ -3,7 +3,14 @@ {-# LANGUAGE OverloadedRecordDot #-}
 {-# LANGUAGE OverloadedStrings   #-}
 
--- | Types and functions related to Stack's @new@ command.
+{-|
+Module      : Stack.New
+Description : Types and functions related to Stack's @new@ command.
+License     : BSD-3-Clause
+
+Types and functions related to Stack's @new@ command.
+-}
+
 module Stack.New
   ( NewOpts (..)
   , TemplateName
@@ -409,7 +416,7 @@ data TemplateDownloadSettings = TemplateDownloadSettings
   { downloadUrl :: String
   , basicAuth :: Maybe (ByteString, ByteString)
-    -- ^ Optional HTTP 'Basic' authentication (type, credentials)
+    -- ^ Optional HTTP \'Basic\' authentication (type, credentials)
   , extract :: ByteString -> Either String Text
   }
 

@@ -3,7 +3,14 @@ {-# LANGUAGE OverloadedRecordDot #-}
 {-# LANGUAGE OverloadedStrings   #-}
 
--- | Run commands in a nix-shell
+{-|
+Module      : Stack.Nix
+Description : Run commands in a nix-shell.
+License     : BSD-3-Clause
+
+Run commands in a nix-shell.
+-}
+
 module Stack.Nix
   ( nixCmdName
   , nixHelpOptName
@@ -42,6 +49,7 @@     "Error: [S-7384]\n"
     ++ "Cannot determine project root directory."
 
+-- | Execute @nix-shell@, replacing the current process.
 runShellAndExit :: RIO Config void
 runShellAndExit = do
   inContainer <- getInContainer -- TODO we can probably assert that this is False based on Stack.Runners now
@@ -155,9 +163,10 @@   ++ foldr (\c -> if c == '\'' then ("'\"'\"'"++) else (c:)) "" str
   ++ "'"
 
--- | Command-line argument for "nix"
+-- | Command-line argument for "nix".
 nixCmdName :: String
 nixCmdName = "nix"
 
+-- | Command-line option to show only @--nix-*@ options.
 nixHelpOptName :: String
 nixHelpOptName = nixCmdName ++ "-help"

@@ -1,6 +1,14 @@ {-# LANGUAGE NoImplicitPrelude #-}
 {-# LANGUAGE OverloadedStrings #-}
 
+{-|
+Module      : Stack.Options.BenchParser
+Description : Parser for benchmark arguments.
+License     : BSD-3-Clause
+
+Parser for benchmark arguments.
+-}
+
 module Stack.Options.BenchParser
  ( benchOptsParser
  ) where

@@ -1,10 +1,15 @@ {-# LANGUAGE NoImplicitPrelude #-}
 
+{-|
+Module      : Stack.Options.BuildMonoidParser
+Description : Parse arguments for Stack's build configuration.
+License     : BSD-3-Clause
+
+Parse arguments for Stack's build configuration.
+-}
+
 module Stack.Options.BuildMonoidParser
   ( buildOptsMonoidParser
-  , cabalVerboseParser
-  , cabalVerbosityOptsParser
-  , cabalVerbosityParser
   ) where
 
 import           Distribution.Parsec ( eitherParsec )
@@ -28,6 +33,7 @@                    )
 import           Stack.Types.ComponentUtils ( unqualCompFromString )
 
+-- | Parse command line arguments for build configuration.
 buildOptsMonoidParser :: GlobalOptsContext -> Parser BuildOptsMonoid
 buildOptsMonoidParser hide0 = BuildOptsMonoid
   <$> trace'

@@ -1,30 +1,31 @@ {-# LANGUAGE NoImplicitPrelude #-}
 {-# LANGUAGE OverloadedStrings #-}
 
+{-|
+Module      : Stack.Options.BuildParser
+License     : BSD-3-Clause
+-}
+
 module Stack.Options.BuildParser
   ( buildOptsParser
-  , flagsParser
-  , targetsParser
   ) where
 
 import qualified Data.List as L
-import qualified Data.Map as Map
 import qualified Data.Text as T
 import           Options.Applicative
                    ( Parser, completer, flag, flag', help, internal, long
-                   , metavar, option, strOption, switch, value
+                   , metavar, strOption, switch, value
                    )
 import           Options.Applicative.Args ( cmdOption )
 import           Options.Applicative.Builder.Extra
                    ( firstBoolFlagsNoDefault, textArgument, textOption )
-import           Stack.Options.Completion
-                   ( flagCompleter, ghcOptsCompleter, targetCompleter )
-import           Stack.Options.PackageParser ( readFlag )
+import           Stack.Options.Completion ( ghcOptsCompleter, targetCompleter )
+import           Stack.Options.FlagsParser ( flagsParser )
 import           Stack.Options.Utils ( hideMods )
 import           Stack.Prelude
 import           Stack.Types.BuildOptsCLI
-                   ( ApplyCLIFlag, BuildCommand, BuildOptsCLI (..)
-                   , BuildSubset (..), FileWatchOpts (..)
+                   ( BuildCommand, BuildOptsCLI (..), BuildSubset (..)
+                   , FileWatchOpts (..)
                    )
 
 -- | Parser for CLI-only build arguments
@@ -122,6 +123,7 @@         <> internal
         )
 
+-- | Parser for build targets.
 targetsParser :: Parser [Text]
 targetsParser =
   many (textArgument
@@ -132,20 +134,6 @@             \https://docs.haskellstack.org/en/stable/commands/build_command/#target-syntax \
             \for details."
     ))
-
-flagsParser :: Parser (Map.Map ApplyCLIFlag (Map.Map FlagName Bool))
-flagsParser = Map.unionsWith Map.union
-  <$> many (option readFlag
-       (  long "flag"
-       <> completer flagCompleter
-       <> metavar "PACKAGE:[-]FLAG"
-       <> help "Set (or unset) the Cabal flag for the package (or use '*' for \
-               \all packages) (can be specified multiple times). Applies to \
-               \project packages, packages included directly in the snapshot, \
-               \and extra-deps. Takes precedence over any Cabal flags \
-               \specified for the package in the snapshot or in the \
-               \project-level configuration file (stack.yaml)."
-       ))
 
 progsOptionsParser :: Parser [(Text, [Text])]
 progsOptionsParser =

@@ -1,5 +1,10 @@ {-# LANGUAGE NoImplicitPrelude #-}
 
+{-|
+Module      : Stack.Options.CleanParser
+License     : BSD-3-Clause
+-}
+
 module Stack.Options.CleanParser
   ( cleanOptsParser
   ) where

@@ -2,6 +2,14 @@ {-# LANGUAGE OverloadedRecordDot #-}
 {-# LANGUAGE OverloadedStrings   #-}
 
+{-|
+Module      : Stack.Options.Completion
+Description : Completers for command line arguments.
+License     : BSD-3-Clause
+
+Completers for command line arguments or arguments of command line options.
+-}
+
 module Stack.Options.Completion
   ( ghcOptsCompleter
   , targetCompleter
@@ -33,6 +41,7 @@ import           Stack.Types.NamedComponent ( renderPkgComponent )
 import           Stack.Types.SourceMap ( SMWanted (..), ppComponents, ppGPD )
 
+-- | A completer for @--ghc-options@ or @--ghci-options@.
 ghcOptsCompleter :: Completer
 ghcOptsCompleter = mkCompleter $ \inputRaw -> pure $
   let input = unescapeBashArg inputRaw
@@ -62,6 +71,7 @@       let go = go' { logLevel = LevelOther "silent" }
       withRunnerGlobal go $ withConfig NoReexec $ withDefaultEnvConfig $ inner input
 
+-- | A completer for components of project packages.
 targetCompleter :: Completer
 targetCompleter = buildConfigCompleter $ \input -> do
   packages <- view $ buildConfigL . to (.smWanted.project)
@@ -74,6 +84,7 @@   allComponentNames (name, comps) =
     map (T.unpack . renderPkgComponent . (name,)) (Set.toList comps)
 
+-- | A completer for Cabal flags of project packages.
 flagCompleter :: Completer
 flagCompleter = buildConfigCompleter $ \input -> do
   bconfig <- view buildConfigL
@@ -106,6 +117,7 @@       ('*' : _) -> wildcardFlags
       _ -> normalFlags
 
+-- | A completer for executable components of project packages.
 projectExeCompleter :: Completer
 projectExeCompleter = buildConfigCompleter $ \input -> do
   packages <- view $ buildConfigL . to (.smWanted.project)

@@ -0,0 +1,29 @@+{-# LANGUAGE NoImplicitPrelude #-}
+
+{-|
+Module      : Stack.Options.ConfigEnvParser
+License     : BSD-3-Clause
+
+Functions to parse command line arguments for Stack's @config env@ command.
+-}
+
+module Stack.Options.ConfigEnvParser
+  ( configCmdEnvParser
+  ) where
+
+import qualified Options.Applicative as OA
+import           Options.Applicative.Builder.Extra ( boolFlags )
+import           Stack.Prelude
+import           Stack.Types.EnvSettings ( EnvSettings (..) )
+
+-- | Parse command line arguments for Stack's @config env@ command.
+configCmdEnvParser :: OA.Parser EnvSettings
+configCmdEnvParser = EnvSettings
+  <$> boolFlags True "locals" "include information about local packages" mempty
+  <*> boolFlags True
+        "ghc-package-path" "set GHC_PACKAGE_PATH environment variable" mempty
+  <*> boolFlags True "stack-exe" "set STACK_EXE environment variable" mempty
+  <*> boolFlags False
+        "locale-utf8" "set the GHC_CHARENC environment variable to UTF-8" mempty
+  <*> boolFlags False
+        "keep-ghc-rts" "keep any GHCRTS environment variable" mempty

@@ -1,6 +1,11 @@ {-# LANGUAGE NoImplicitPrelude     #-}
 {-# LANGUAGE DuplicateRecordFields #-}
 
+{-|
+Module      : Stack.Options.ConfigParser
+License     : BSD-3-Clause
+-}
+
 module Stack.Options.ConfigParser
   ( configOptsParser
   ) where

@@ -0,0 +1,143 @@+{-# LANGUAGE NoImplicitPrelude #-}
+
+{-|
+Module      : Stack.Options.ConfigSetParser
+License     : BSD-3-Clause
+
+Functions to parse command line arguments for Stack's @config set@ command.
+-}
+
+module Stack.Options.ConfigSetParser
+  ( configCmdSetParser
+  ) where
+
+import qualified Data.Text as T
+import qualified Options.Applicative as OA
+import qualified Options.Applicative.Types as OA
+import           Stack.Prelude
+import           Stack.Types.ConfigMonoid
+                   ( configMonoidInstallGHCName
+                   , configMonoidInstallMsysName
+                   , configMonoidRecommendStackUpgradeName
+                   , configMonoidSystemGHCName
+                   )
+import           Stack.Types.ConfigSetOpts
+                   ( CommandScope (..), ConfigCmdSet (..) )
+import           Stack.Types.Snapshot ( readAbstractSnapshot )
+
+-- | Parse command line arguments for Stack's @config set@ command.
+configCmdSetParser :: OA.Parser ConfigCmdSet
+configCmdSetParser =
+  OA.hsubparser $
+    mconcat
+      [ OA.command "snapshot"
+          ( OA.info
+              (   ConfigCmdSetSnapshot
+              <$> OA.argument
+                    readAbstractSnapshot
+                    (  OA.metavar "SNAPSHOT"
+                    <> OA.help "E.g. \"nightly\" or \"lts-22.8\"" ))
+              ( OA.progDesc
+                  "Change the snapshot of the current project." ))
+      , OA.command "resolver"
+          ( OA.info
+              (   ConfigCmdSetResolver
+              <$> OA.argument
+                    readAbstractSnapshot
+                    (  OA.metavar "SNAPSHOT"
+                    <> OA.help "E.g. \"nightly\" or \"lts-22.8\"" ))
+              ( OA.progDesc
+                  "Change the snapshot of the current project, using the \
+                  \resolver key." ))
+      , OA.command (T.unpack configMonoidSystemGHCName)
+          ( OA.info
+              (   ConfigCmdSetSystemGhc
+              <$> globalScopeFlag
+              <*> boolArgument )
+              ( OA.progDesc
+                  "Configure whether or not Stack should use a system GHC \
+                  \installation." ))
+      , OA.command (T.unpack configMonoidInstallGHCName)
+          ( OA.info
+              (   ConfigCmdSetInstallGhc
+              <$> globalScopeFlag
+              <*> boolArgument )
+              ( OA.progDesc
+                  "Configure whether or not Stack should automatically install \
+                  \GHC when necessary." ))
+      , OA.command (T.unpack configMonoidInstallMsysName)
+          ( OA.info
+              (   ConfigCmdSetInstallMsys
+              <$> globalScopeFlag
+              <*> boolArgument )
+              ( OA.progDesc
+                  "Configure whether or not Stack should automatically install \
+                  \MSYS2 when necessary." ))
+      , OA.command (T.unpack configMonoidRecommendStackUpgradeName)
+          ( OA.info
+              (   ConfigCmdSetRecommendStackUpgrade
+              <$> projectScopeFlag
+              <*> boolArgument )
+              ( OA.progDesc
+                  "Configure whether or not Stack should notify the user if it \
+                  \identifes a new version of Stack is available." ))
+      , OA.command "package-index"
+          ( OA.info
+              ( OA.hsubparser $
+                  OA.command "download-prefix"
+                    ( OA.info
+                        (   ConfigCmdSetDownloadPrefix
+                        <$> globalScopeFlag
+                        <*> urlArgument )
+                        ( OA.progDesc
+                            "Configure download prefix for Stack's package \
+                            \index." )))
+              ( OA.progDesc
+                  "Configure Stack's package index" ))
+      ]
+
+globalScopeFlag :: OA.Parser CommandScope
+globalScopeFlag = OA.flag
+  CommandScopeProject
+  CommandScopeGlobal
+  (  OA.long "global"
+  <> OA.help
+       "Modify the user-specific global configuration file ('config.yaml') \
+       \instead of the project-level configuration file ('stack.yaml')."
+  )
+
+projectScopeFlag :: OA.Parser CommandScope
+projectScopeFlag = OA.flag
+  CommandScopeGlobal
+  CommandScopeProject
+  (  OA.long "project"
+  <> OA.help
+       "Modify the project-level configuration file ('stack.yaml') instead of \
+       \the user-specific global configuration file ('config.yaml')."
+  )
+
+boolArgument :: OA.Parser Bool
+boolArgument = OA.argument
+  readBool
+  (  OA.metavar "true|false"
+  <> OA.completeWith ["true", "false"]
+  )
+
+readBool :: OA.ReadM Bool
+readBool = do
+  s <- OA.readerAsk
+  case s of
+    "true" -> pure True
+    "false" -> pure False
+    _ -> OA.readerError ("Invalid value " ++ show s ++
+           ": Expected \"true\" or \"false\"")
+
+urlArgument :: OA.Parser Text
+urlArgument = OA.strArgument
+  (  OA.metavar "URL"
+  <> OA.value defaultDownloadPrefix
+  <> OA.showDefault
+  <> OA.help
+       "Location of package index. It is highly recommended to use only the \
+       \official Hackage server or a mirror."
+  )