Conform to PATH, where appropriate

mpilgrem · mpilgrem · commit 98025f5a7bd0 · 2022-07-30T23:48:57.000+01:00
Also makes other amendments in the affected passages.
diff --git a/doc/GUIDE.md b/doc/GUIDE.md
@@ -1146,7 +1146,7 @@ We've already used `stack exec` multiple times in this guide. As you've likely
 already guessed, it allows you to run executables, but with a slightly modified
 environment. In particular: `stack exec` looks for executables on Stack's bin
 paths, and sets a few additional environment variables (like adding those paths
-to `PATH`, and setting `GHC_PACKAGE_PATH`, which tells GHC which package
+to the PATH, and setting `GHC_PACKAGE_PATH`, which tells GHC which package
 databases to use).
 
 If you want to see exactly what the modified environment looks like, try:
diff --git a/doc/developing_on_windows.md b/doc/developing_on_windows.md
@@ -41,31 +41,26 @@ additional entries via a pull request.
 
 * For [text-icu](https://github.com/bos/text-icu) install `mingw64/mingw-w64-x86_64-icu`
 
-## Cmake ##
-
-Cmake has trouble finding other tools even if they are available on
-the `PATH`. Likely this is not a cmake problem but one of the
-environment not fully integrating. For example GHC comes with a copy
-of GCC which is not installed by MSYS2 itself. If you want to use this
-GCC you can provide a full path to it, or find it first with
-`System.Directory.findExecutable` if you want to launch GCC from a
-Haskell file such as `Setup.hs`.
-
-Experience tells that the `mingw-w64` versions of make and cmake are
-most likely to work. Though there are other versions available through
-pacman, so have a look to see what works for you. Both tools can be
-installed with the commands:
-
-```
-stack exec -- pacman -S mingw-w64-x86_64-make
-stack exec -- pacman -S mingw-w64-x86_64-cmake
-```
-
-Even though make and cmake are then both installed into the same
-environment. Cmake still seems to have trouble to find make. To help
-cmake find GCC and make supply the following flags:
-
-```
--DCMAKE_C_COMPILER=path
--DCMAKE_MAKE_PROGRAM=path
-```
+## CMake ##
+
+CMake has trouble finding other tools even if they are available on the PATH.
+Likely this is not a CMake problem but one of the environment not fully
+integrating. For example GHC comes with a copy of GCC which is not installed by
+MSYS2 itself. If you want to use this GCC you can provide a full path to it, or
+find it first with `System.Directory.findExecutable` if you want to launch GCC
+from a Haskell file such as `Setup.hs`.
+
+Experience tells that the `mingw-w64` versions of Make and CMake are most
+likely to work. Though there are other versions available through `pacman`, so
+have a look to see what works for you. Both tools can be installed with the
+commands:
+
+    stack exec -- pacman -S mingw-w64-x86_64-make
+    stack exec -- pacman -S mingw-w64-x86_64-cmake
+
+Even though Make and CMake are then both installed into the same
+environment, CMake still seems to have trouble to find Make. To help CMake
+find GCC and Make supply the following flags:
+
+    -DCMAKE_C_COMPILER=path
+    -DCMAKE_MAKE_PROGRAM=path
diff --git a/doc/faq.md b/doc/faq.md
@@ -196,41 +196,40 @@ the following line to your .cabal file:
 
 You could also use the [`--custom-preprocessor-extensions` flag](yaml_configuration.md#custom-preprocessor-extensions)
 
-## I already have GHC installed, can I still use stack?
+## I already have GHC installed, can I still use Stack?
 
-Yes. In its default configuration, stack will simply ignore any system GHC
-installation and use a sandboxed GHC that it has installed itself (typically
-via the `stack setup` command). You can find these sandboxed GHC installations
-in `~/.stack/programs/$platform/ghc-$version/`.
+Yes. In its default configuration, Stack will simply ignore any system GHC
+installation and use a sandboxed GHC that it has installed itself. You can find
+these sandboxed GHC installations in the `ghc-*` directories in the
+`stack path --programs` directory.
 
-If you would like stack to use your system GHC installation, use the
+If you would like Stack to use your system GHC installation, use the
 [`--system-ghc` flag](yaml_configuration.md#system-ghc) or run
-`stack config set system-ghc --global true` to make stack check your
-`PATH` for a suitable GHC by default.
+`stack config set system-ghc --global true` to make Stack check your PATH for a
+suitable GHC by default.
 
-Note that stack can only use a system GHC installation if its version is
-compatible with the configuration of the current project, particularly the
-[`resolver` setting](yaml_configuration.md#resolver).
+Stack can only use a system GHC installation if its version is compatible with
+the configuration of the current project, particularly the
+[`resolver` or `snapshot` setting](yaml_configuration.md#resolver).
 
-Note that GHC installation doesn't work for all OSes, so in some cases you
+GHC installation doesn't work for all operating systems, so in some cases you
 will need to use `system-ghc` and install GHC yourself.
 
-## How does stack determine what GHC to use?
+## How does Stack determine what GHC to use?
 
-In its default configuration, stack determines from the current project which
-GHC version, architecture etc. it needs. It then looks in
-`~/.stack/programs/$platform/ghc-$version/` for a compatible GHC, requesting
-to install one via `stack setup` if none is found.
+In its default configuration, Stack determines from the current project which
+GHC version, architecture etc it needs. It then looks in the `ghc-<version>`
+subdirectory of the `stack path --programs` directory for a compatible GHC,
+requesting to install one via `stack setup` if none is found.
 
 If you are using the [`--system-ghc` flag](yaml_configuration.md/#system-ghc) or
-have configured `system-ghc: true` either in the project `stack.yaml`
-or the global `~/.stack/config.yaml`, stack will use the first GHC that it finds
-on your `PATH`, falling back on its sandboxed installations only if the found GHC
-doesn't comply with the various requirements (version, architecture) that your
-project needs.
+have configured `system-ghc: true` either in the project `stack.yaml` or the
+global `config.yaml`, Stack will use the first GHC that it finds on your PATH,
+falling back on its sandboxed installations only if the found GHC doesn't comply
+with the various requirements (version, architecture) that your project needs.
 
 See [this issue](https://github.com/commercialhaskell/stack/issues/420) for a
-detailed discussion of stack's behavior when `system-ghc` is enabled.
+detailed discussion of Stack's behavior when `system-ghc` is enabled.
 
 ## How do I upgrade to GHC 7.10.2 with stack?
 
@@ -563,12 +562,12 @@ Yes:
 
 ## How do I resolve linker errors when running `stack setup` or `stack build` on macOS?
 
-This is likely to be caused by having a LLVM installation and default Apple
-Clang compiler both under the `PATH`. The symptom of this issue is a linker
-error "bad relocation (Invalid pointer diff)". The compiler picks up
-inconsistent versions of binaries and the mysterious error occurs.
+This is likely to be caused by having both a LLVM installation and default Apple
+Clang compiler on the PATH. The symptom of this issue is a linker error "bad
+relocation (Invalid pointer diff)". The compiler picks up inconsistent versions
+of binaries and the mysterious error occurs.
 
-The workaround is to remove LLVM binaries from the `PATH`.
+The workaround is to remove LLVM binaries from the PATH.
 
 ## How do I suppress `'-nopie'` warnings with `stack build` on macOS?
 
diff --git a/doc/glossary.md b/doc/glossary.md
@@ -9,6 +9,7 @@ The following terms are used in Stack's documentation.
 |Cabal              |The Haskell Common Architecture for Building Applications and Libraries, provided by the [`Cabal` package](https://hackage.haskell.org/package/Cabal). Also referred to as Cabal (the library) to distinguish it from Cabal (the tool).|
 |Cabal file|A file containing a [package description](https://cabal.readthedocs.io/en/stable/cabal-package.html) used by Cabal, named `<package_name>.cabal`.|
 |Cabal (the tool)|The Haskell build tool provided by the [`cabal-install` package](https://hackage.haskell.org/package/cabal-install).|
+|CMake              |A [system](https://cmake.org/) for managing build processes.|
 |`config.yaml`      |A non-project-specific configuration file used by Stack.  |
 |Docker             |A [platform](https://www.docker.com/) for developing,  shipping, and running applications. It can package and run an application in a loosely isolated environment called a _container_.|
 |Emacs              |[GNU Emacs](https://www.gnu.org/software/emacs/), an extensible, customisable text editor.|
@@ -26,6 +27,7 @@ The following terms are used in Stack's documentation.
 |Hpack              |A [format](https://github.com/sol/hpack) for Haskell packages or the executable `hpack` that produces a Cabal file from `package.yaml`.|
 |Linux              |A family of operating systems based on the Linux kernal.  |
 |macOS              |The primary operating system for Apple's Mac computers. Previously known as Mac OS X or OS X.|
+|Make               |A [build automation tool](https://www.gnu.org/software/make/).|
 |MSYS2              |The [MSYS2](https://www.msys2.org/) software distribution and building platform for Windows.|
 |Nix                |A purely functional [package manager](https://nixos.org/), available for Linux and macOS.|
 |`package.yaml`     |A file that describes a package in the Hpack format.      |
diff --git a/doc/install_and_upgrade.md b/doc/install_and_upgrade.md
@@ -319,7 +319,7 @@ If you're attempting to install stack from within China:
 
 ```
 ###ADD THIS IF YOU LIVE IN CHINA
-setup-info-locations: 
+setup-info-locations:
 - "http://mirrors.tuna.tsinghua.edu.cn/stackage/stack-setup.yaml"
 urls:
   latest-snapshot: http://mirrors.tuna.tsinghua.edu.cn/stackage/snapshots.json
@@ -341,47 +341,64 @@ package-indices:
         ignore-expiry: no
 ```
 
-## Using an http proxy
+## Using an HTTP proxy
 
-To use `stack` behind a http proxy with ip address *IP* and port *PORT*, first set up an environment variable `http_proxy` and then run the stack command. _e.g._
+To use Stack behind a HTTP proxy with IP address *IP* and port *PORT*, first set
+up an environment variable `http_proxy` and then run the Stack command. _eg_
 
-```
-$ export http_proxy=IP:PORT
-$ stack install
-```
+    $ export http_proxy=IP:PORT
+    $ stack install
 
-Note that on most operating systems, it is not mandatory for programs to follow the "system-wide" http proxy. Some programs, such as browsers, do honor this "system-wide" http proxy setting, while other programs, including bash, do not. That means configuring "http proxy setting" in your Control Panel (Windows) or System Preferences (Mac) would not result in `stack` traffic going through the proxy. 
+On most operating systems, it is not mandatory for programs to follow the
+"system-wide" HTTP proxy. Some programs, such as browsers, do honor this
+"system-wide" HTTP proxy setting, while other programs, including bash, do not.
+That means configuring "http proxy setting" in your Control Panel (Windows) or
+System Preferences (Mac) would not result in Stack traffic going through the
+proxy.
 
 ## Upgrade
 
 There are essentially four different approaches to upgrade:
 
-* The `stack` tool itself ships with an `upgrade` command, which download a `stack` binary or build it from source and install it to the default install path (e.g. `~/.local/bin` or `%APPDATA%\local\bin`; see the [Path](#Path) section above). You can use `stack upgrade` to get the latest official release, and `stack upgrade --git` to install from Git and live on the bleeding edge. Make sure the default install directory is on your `PATH` and takes precedence over the system installed `stack`, or copy `stack` from that directory to the system location afterward. For more information, see [this discussion](https://github.com/commercialhaskell/stack/issues/237#issuecomment-126793301).
+* Stack itself ships with an `upgrade` command, which downloads a `stack` binary
+  or builds it from source and install it to the default `install` directory (eg
+  `stack path --local-bin`; see the [Path](#Path) section above). You can use
+  `stack upgrade` to get the latest official release, and `stack upgrade --git`
+  to install from Git and live on the bleeding edge. Make sure the default
+  `install` directory is on your PATH and takes precedence over the system
+  installed `stack`, or copy `stack` from that directory to the system location
+  afterward. For more information, see
+  [this discussion](https://github.com/commercialhaskell/stack/issues/237#issuecomment-126793301).
 
-* If you're using a package manager and are happy with sticking with the officially released binaries from the distribution (which may the lag behind latest version of Stack significantly), simply follow your normal package manager strategies for upgrading (e.g. `apt-get update && apt-get upgrade`).
+* If you're using a package manager and are happy with sticking with the
+  officially released binaries from the distribution (which may the lag behind
+  latest version of Stack significantly), simply follow your normal package
+  manager strategies for upgrading (eg `apt-get update && apt-get upgrade`).
 
-* The get.haskellstack.org script supports the `-f` argument to over-write the current stack executable.  For example:
+* The `get.haskellstack.org` script supports the `-f` argument to over-write the
+  current Stack executable. For example:
 
       curl -sSL https://get.haskellstack.org/ | sh -s - -f
 
   or:
 
       wget -qO- https://get.haskellstack.org/ | sh -s - -f
 
-* Manually follow the steps above to download the newest binaries from the release page and replace the old binary.
+* Manually follow the steps above to download the newest binaries from the
+  release page and replace the old binary.
 
 ## Install Older Versions
 
-To install a specific version of stack, navigate to the desired version on 
+To install a specific version of stack, navigate to the desired version on
 [the GitHub release page](https://github.com/fpco/stack/releases),
 and click the appropriate link under its "Assets" drop-down menu.
 
-Alternatively, use the URL 
+Alternatively, use the URL
 `https://github.com/commercialhaskell/stack/releases/download/vVERSION/stack-VERSION-PLATFORM.EXTENSION`.
 For example, the tarball for stack 2.1.0.1, osx-x86_64 is at
 `https://github.com/commercialhaskell/stack/releases/download/v2.1.0.1/stack-2.1.0.1-osx-x86_64.tar.gz`.
 
-Here's a snippet for `appveyor.yml` files, borrowed from `dhall`'s 
+Here's a snippet for `appveyor.yml` files, borrowed from `dhall`'s
 [`appveyor.yml`](https://github.com/dhall-lang/dhall-haskell/blob/1079b7a3a7a6922f72a373e47daf6f1b74f128b1/appveyor.yml).
 Change the values of PATH and VERSION as needed.
 
diff --git a/doc/maintainers/docker.md b/doc/maintainers/docker.md
@@ -72,13 +72,21 @@ Replace `<N>` with major version of new LTS snapshot, and `<N-1>` with previous
 
 - 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.
+- 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: `(stack --resolver=nightly new image-test && cd image-test && stack --docker --docker-image=local/stack-build build)`. This should build without needing to install GHC.
+- Try building a test package with the new image:
+  `stack --resolver=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: `docker build -t local/stack-build-small --build-arg "VARIANT=small" lts-<N>.0/`.
+- Build the "small" variant:
+  `docker build -t local/stack-build-small --build-arg "VARIANT=small" lts-<N>.0/`.
 
-- Try building a test package with the new small image: `(stack --resolver=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.
+- Try building a test package with the new small image:
+  `stack --resolver=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
 
diff --git a/doc/nix_integration.md b/doc/nix_integration.md
@@ -154,8 +154,8 @@ By default, Stack will run the build in a *pure* Nix build environment (or
   installed elsewhere on your system. This behaviour enforces a complete
   description of the build environment to facilitate reproducibility.
 
-To override this behaviour, add `pure: false` to your `stack.yaml` or pass the
-`--no-nix-pure` option to the command line.
+To override this behaviour, add `pure: false` to your `stack.yaml` file or pass
+the `--no-nix-pure` option to the command line.
 
 **Note:** On macOS shells are non-pure by default currently. This is due soon to
 be resolved locale issues. So on macOS you'll need to be a bit more careful to
diff --git a/doc/yaml_configuration.md b/doc/yaml_configuration.md
@@ -1107,9 +1107,9 @@ Since 0.1.2.0
 
 ### extra-path
 
-This option specifies additional directories to prepend to the PATH environment
-variable.  These will be used when resolving the location of executables, and
-will also be visible in the `PATH` variable of processes run by stack.
+This option specifies additional directories to prepend to the PATH. These will
+be used when resolving the location of executables, and will also be visible in
+the PATH of processes run by Stack.
 
 For example, to prepend `/path-to-some-dep/bin` to your PATH:
 
@@ -1118,9 +1118,9 @@ extra-path:
 - /path-to-some-dep/bin
 ```
 
-One thing to note is that other paths added by stack - things like the project's
-bin dir and the compiler's bin dir - will take precedence over those specified
-here (the automatic paths get prepended).
+Other paths added by Stack - things like the project's binary directory and the
+compiler's binary directory - will take precedence over those specified here
+(the automatic paths get prepended).
 
 Since 0.1.4.0
 
