Merge branch 'stable'

Author: mpilgrem

doc/GUIDE.md

@@ -1665,79 +1665,85 @@ for future uses of Stack:
 
 ## Comparison to other tools
 
-Stack is not the only tool around for building Haskell code. Stack came into
-existence due to limitations with some of the existing tools. If you're
-unaffected by those limitations and are happily building Haskell code, you may
-not need Stack. If you're suffering from some of the common problems in other
-tools, give Stack a try instead.
-
-If you're a new user who has no experience with other tools, we recommend going
-with Stack. The defaults match modern best practices in Haskell development, and
-there are less corner cases you need to be aware of. You *can* develop Haskell
-code with other tools, but you probably want to spend your time writing code,
-not convincing a tool to do what you want.
-
-Before jumping into the differences, let me clarify an important similarity:
-
-__Same package format.__ Stack, Cabal (the tool), and presumably all other tools
-share the same underlying Cabal package format, consisting of a Cabal file,
-modules, etc. This is a Good Thing: we can share the same set of upstream
-libraries, and collaboratively work on the same project with Stack, Cabal (the
-tool), and NixOS. In that sense, we're sharing the same ecosystem.
-
-Now the differences:
-
-* __Curation vs dependency solving as a default__.
-    * Stack defaults to using curation (Stackage snapshots, LTS Haskell,
-      Nightly, etc) as a default instead of defaulting to dependency solving, as
-      Cabal (the tool) does. This is just a default: as described above, Stack
-      can use dependency solving if desired, and Cabal (the tool) can use
-      curation. However, most users will stick to the defaults. The Stack team
-      firmly believes that the majority of users want to simply ignore
-      dependency resolution nightmares and get a valid build plan from day one,
-      which is why we've made this selection of default behavior.
-* __Reproducible__.
-    * Stack goes to great lengths to ensure that `stack build` today does the
-      same thing tomorrow. Cabal (the tool) does not: build plans can be
-      affected by the presence of pre-installed packages, and running
-      `cabal update` can cause a previously successful build to fail. With
-      Stack, changing the build plan is always an explicit decision.
-* __Automatically building dependencies__.
-    * With Cabal (the tool), you need to use `cabal install` to trigger
-      dependency building. This is somewhat necessary due to the previous point,
-      since building dependencies can, in some cases, break existing installed
-      packages. So for example, in Stack, `stack test` does the same job as
-      `cabal install --run-tests`, though the latter *additionally* performs an
-      installation that you may not want. The closer equivalent command sequence
-      is: `cabal install --enable-tests --only-dependencies`,
-      `cabal configure --enable-tests`, `cabal build && cabal test` (newer
-      versions of Cabal (the tool) may make this command sequence shorter).
-* __Isolated by default__.
-    * This has been a pain point for new Stack users. In Cabal, the default
-      behavior is a non-isolated build where working on two projects can cause
-      the user package database to become corrupted. The Cabal solution to this
-      is sandboxes. Stack, however, provides this behavior by default via its
-      databases. In other words: when you use Stack, there's __no need for
-      sandboxes__, everything is (essentially) sandboxed by default.
-
-__Other tools for comparison (including active and historical)__
-
-* [cabal-dev](https://hackage.haskell.org/package/cabal-dev). This is deprecated
-  in favor of Cabal (the tool).
+Stack is not the only tool available for building Haskell code. Stack came into
+existence due to limitations at that time with some of the existing tools. If
+you are happily building Haskell code with other tools, you may not need Stack.
+If you're experiencing problems with other tools, give Stack a try instead.
+
+If you're a new user who has no experience with other tools, we recommend Stack.
+The defaults match modern best practices in Haskell development, and there are
+fewer corner cases you need to be aware of. You *can* develop Haskell code with
+other tools, but you probably want to spend your time writing code, not
+convincing a tool to do what you want.
+
+### Underlying package format
+
+Before turning to differences, we clarify an important similarity: Stack, Cabal
+(the tool), and presumably all other tools share the same underlying package
+format of Cabal (the library). This is a Good Thing: we can share the same set
+of upstream libraries, and collaboratively work on the same project with Stack,
+Cabal (the tool), and NixOS. In that sense, we're sharing the same ecosystem.
+
+### Curation vs dependency solving
+
+* Stack uses 'curation' (snapshots and Stack's project-level configuration file
+  (`stack.yaml`) define precisely the set of packages available for a project).
+  The Stack team firmly believes that the majority of users want to simply
+  ignore dependency resolution nightmares and get a valid build plan from day
+  one. That's why we've made 'curation' the focus of Stack.
+
+* Cabal (the tool) can use 'curation' too but its origins are in dependency
+  solving.
+
+### Emphasis on reproducibility
+
+* Stack goes to great lengths to ensure that `stack build` today does the
+  same thing tomorrow. With Stack, changing the build plan is always an explicit
+  decision.
+
+* Cabal (the tool) does not go to the same lengths: build plans can be affected
+  by the presence of pre-installed packages, and running `cabal update` can
+  cause a previously successful build to fail.
+
+### Automatic building of dependencies
+
+*   Stack's automatically builds dependencies. So for example, in Stack,
+    `stack test` does the same job as:
+
+    ~~~text
+    cabal install --enable-tests --only-dependencies
+    cabal configure --enable-tests
+    cabal build
+    cabal test
+    ~~~
+
+    (newer versions of Cabal (the tool) may make this command sequence shorter).
+
+*   With Cabal (the tool), you need to use `cabal install` to trigger dependency
+    building. This is somewhat necessary as building dependencies can, in some
+    cases, break existing installed packages.
+
+### Isolation
+
+* Stack is isolated - provides 'sandboxed' behaviour - by default, via its
+  databases. In other words: when you use Stack, there's
+  __no need for sandboxes__, everything is (essentially) sandboxed by default.
+
+* With Cabal (the tool), the default behavior is a non-isolated build where
+  working on two projects can cause the user package database to become
+  corrupted. The Cabal solution to this is sandboxes.
+
+### Tools other than Stack and Cabal (the tool)
+
 * [cabal-meta](https://hackage.haskell.org/package/cabal-meta) inspired a lot of
-  the multi-package functionality of Stack. If you're still using Cabal (the
-  tool), `cabal-meta` is relevant. For Stack work, the feature set is fully
-  subsumed by Stack.
-* [cabal-src](https://hackage.haskell.org/package/cabal-src) is mostly
-  irrelevant in the presence of both Stack and Cabal sandboxes, both of which
-  make it easier to add additional package sources easily. The mega-sdist
-  executable that ships with cabal-src is, however, still relevant. Its
-  functionality may some day be folded into Stack
-* [stackage-cli](https://hackage.haskell.org/package/stackage-cli) was an
-  initial attempt to make Cabal (the tool) work more easily with curated
-  snapshots, but due to a slight impedance mismatch between cabal.config
-  constraints and snapshots, it did not work as well as hoped. It is deprecated
-  in favor of Stack.
+  the multi-package functionality of Stack. Still relevant for Cabal (the
+  tool).
+* [cabal-src](https://hackage.haskell.org/package/cabal-src). Deprecated in
+  favor of Stack in 2016.
+* [stackage-cli](https://hackage.haskell.org/package/stackage-cli).Deprecated
+  in favor of Stack in 2015.
+* [cabal-dev](https://hackage.haskell.org/package/cabal-dev). Deprecated in
+  favor of Cabal (the tool) in 2013.
 
 ## More resources
 

doc/build_command.md

@@ -247,22 +247,53 @@ the `--watch-all` flag.
 
 Default: Enabled
 
-Set the flag to have the output of all packages being built scroll by in a
-streaming fashion. The output from each package built will be prefixed by the
-package name, e.g. `mtl> Building ...`. This will include the output from
-dependencies being built, not just targets.
-
-Unset the flag to disable this behaviour. When disabled:
-
-* When building a single target package (e.g., `stack build` in a project
-  with only one package, or `stack build <package_name>` in a multi-package
-  project), the build output from GHC will be hidden for building all
-  dependencies, and will be displayed for the one target package.
-* By default, when building multiple target packages, the output from these
-  will end up in a log file instead of on the console unless it contains
-  errors or warnings, to avoid problems of interleaved output and decrease
-  console noise. If you would like to see this content instead, you can use
-  the `dump-logs` option.
+Set the flag for interleaved output. With interleaved output, each line of
+output from each package being built (targets and dependencies) is sent to the
+console as it happens and output relating to different packages can be
+interleaved. Each line will be prefixed with the name of the relevant package.
+The spacing between the prefix and the output will be set based on the longest
+relevant package name, so that the start of the output itself aligns. For
+example (extract):
+
+~~~text
+hpack            > build
+mustache         > configure
+hpack            > Preprocessing library for hpack-0.35.0..
+hpack            > Building library for hpack-0.35.0..
+mustache         > Configuring mustache-2.4.1...
+hpack            > [ 1 of 29] Compiling Data.Aeson.Config.Key
+hpack            > [ 2 of 29] Compiling Data.Aeson.Config.KeyMap
+mustache         > build
+hpack            > [ 3 of 29] Compiling Data.Aeson.Config.Util
+mustache         > Preprocessing library for mustache-2.4.1..
+mustache         > Building library for mustache-2.4.1..
+hpack            > [ 4 of 29] Compiling Hpack.Haskell
+hpack            > [ 5 of 29] Compiling Hpack.Utf8
+mustache         > [1 of 8] Compiling Paths_mustache
+hpack            > [ 6 of 29] Compiling Imports
+hpack            > [ 7 of 29] Compiling Hpack.Util
+mustache         > [2 of 8] Compiling Text.Mustache.Internal
+~~~
+
+Unset the flag for non-interleaved output. With non-interleaved output, the
+build output from GHC (as opposed to from Stack) in respect of dependencies is
+ignored. The behaviour then depends whether there is one target package or more
+than one. There can be one target if the project has a single package or if one
+package is targetted in a multi-package project (for example, using
+`stack build <package_name>`).
+
+* **One target package:** The build output for the target package is sent to the
+  console as it happens.
+
+* **More than one target package:** The build output from GHC (as opposed to
+  from Stack) for each target package is sent to a log file for that package,
+  unless an error occurs. At the end of the build, the location of the directory
+  containing the log files is reported. To also output the contents of the log
+  files to the console at the end of the build, use Stack's `dump-logs` option.
+  For further information about that option, see the
+  [YAML configuration](yaml_configuration.md#dump-logs) documentation. The
+  default `dump-logs` mode is to output the contents of the log files that are
+  warnings.
 
 ### The `stack build --pedantic` flag
 

doc/maintainers/7zip.md

@@ -0,0 +1,92 @@
+<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>
+
+# Upgrading 7-Zip
+
+When installing GHC or MSYS2 on Windows, Stack will also install
+[7-Zip](https://www.7-zip.org/). 7-Zip is a file archiver and is used by Stack
+to extract files from archives. This section explains the steps required to
+upgrade the 7-Zip version used by Stack. The 7-Zip functionality used by Stack
+is mature and stable. It is anticipated that the Stack-supplied 7-Zip will not
+need to be updated frequently. On 10 September 2022, it was updated from 7-Zip
+9.20 (released on 18 November 2010) to 7-Zip 22.01 (released on 15 July 2022).
+
+1.  Download the latest installer for 64-bit x64 Windows from 7-Zip's website.
+
+2.  Run the installer and install to the default location
+    (`C:\C:\Program Files\7-Zip`). The four relevant files from those installed
+    will be:
+
+    ~~~text
+    7z.exe  # 7-Zip Console
+    7z.dll  # 7-Zip Engine
+    license.txt  # 7-Zip License
+    readme.txt  # 7-Zip Overview
+    ~~~
+
+3.  In the
+    [commercialhaskell/stackage-content](https://github.com/commercialhaskell/stackage-content)
+    GitHub repository, create a new draft release tagged and named `7z-XX.YY`,
+    where `XX.YY` is the 7-Zip version number.
+
+4.  Upload the four relevant files in step 2 above into the draft release.
+
+5.  Provide a description for the release. For example:
+
+    ~~~text
+    7-Zip 22.01 (2022-07-15) for Windows 64-bit x64.
+    ~~~
+
+6.  Publish the release.
+
+7.  Changes need to be made to the
+    [stackage-content/stack/stack-setup-2.yaml](https://github.com/commercialhaskell/stackage-content/blob/master/stack/stack-setup-2.yaml)
+    file, to switch over to using the newly uploaded files. For example
+    (extract):
+
+    ~~~yaml
+    sevenzexe-info:
+        url: "https://github.com/commercialhaskell/stackage-content/releases/download/7z-22.01/7z.exe"
+        content-length: 545280
+        sha256: 254cf6411d38903b2440819f7e0a847f0cfee7f8096cfad9e90fea62f42b0c23
+
+    sevenzdll-info:
+        url: "https://github.com/commercialhaskell/stackage-content/releases/download/7z-22.01/7z.dll"
+        content-length: 1814016
+        sha256: 73578f14d50f747efa82527a503f1ad542f9db170e2901eddb54d6bce93fc00e
+    ~~~
+
+    The `content-length:` key's value is the size of the file in bytes. It can
+    be obtained from the `Length` field of the `dir` command. The `sha256:`
+    key's value can be obtained from the commands (in PowerShell):
+
+    ~~~text
+    (Get-FileHash 7z.exe -Algorithm SHA256).Hash.ToLower()
+    (Get-FileHash 7z.dll -Algorithm SHA256).Hash.ToLower()
+    ~~~
+
+    The `sha256:` key only accepts lowercase hash results as values.
+
+8.  The changed `stack-setup-2.yaml` file should be tested locally. This can be
+    done by:
+
+    * temporarily disabling the existing local copy of 7-Zip by changing the
+      name of the `7z.exe` and `7z.dll` files in the `stack path --programs`
+      directory;
+
+    * identifying a version of GHC not already installed in the
+      `stack path --programs` directory; and
+
+    * executing the command:
+
+        ~~~text
+        stack --resolver <snapshot> setup --setup-info-yaml <path to local copy of stack-setup-2.yaml>
+        ~~~
+
+      where `<snapshot>` requires the missing version of GHC.
+
+    If all is well, the command should proceed to download the missing version
+    of GHC, download the `7z.exe` and `7z.dll` files, and use the 7-Zip version
+    to extract files from the GHC archive.
+
+9.  Raise a pull request on `commercialhaskell/stackage-contents` for the
+    changes to the locally-tested `stack-setup-2.yaml` file.

doc/yaml_configuration.md

@@ -620,17 +620,24 @@ Default: `warning`
 
 Command line equivalent (takes precedence): `--[no-]dump-logs` flag
 
-Control which log output from local non-dependency packages to print to the
-console. By default, Stack will only do this when building a single target
-package or if the log contains warnings, to avoid generating unnecessarily
-verbose output.
+In the case of *non-interleaved* output and *more than one* target package,
+Stack sends the build output from GHC for each target package to a log file,
+unless an error occurs. For further information, see the
+[`stack build --[no-]interleaved-output` flag](build_command.md#the-stack-build---no-interleaved-output-flag)
+documentation.
+
+The value of the `dump-logs` key controls what, if any, log file content is sent
+('dumped') to the console at the end of the build. Possible values are:
 
 ~~~yaml
-dump-logs: none      # don't dump logs even if they contain warnings
-dump-logs: warning   # dump logs that contain warnings
-dump-logs: all       # dump all logs for local non-dependency packages
+dump-logs: none      # don't dump the content of any log files
+dump-logs: warning   # dump the content of log files that are warnings
+dump-logs: all       # dump all of the content of log files
 ~~~
 
+At the command line, `--no-dump-logs` is equivalent to `dump-logs: none` and
+`--dump-logs` is equivalent to `dump-logs: all`.
+
 ### extra-include-dirs
 
 Default: `[]`

mkdocs.yml

@@ -57,6 +57,7 @@ nav:
     - Add GHC version: maintainers/ghc.md
     - Docker images: maintainers/docker.md
     - Upgrading MSYS2: maintainers/msys.md
+    - Upgrading 7-Zip: maintainers/7zip.md
     - HaskellStack.org: maintainers/haskellstack.org.md
 - Signing key: SIGNING_KEY.md
 - Glossary: glossary.md