Merge branch 'stable'

Author: mpilgrem

doc/GUIDE.md

@@ -6,7 +6,8 @@ Stack is a modern, cross-platform build tool for Haskell code.
 
 This guide takes a new Stack user through the typical workflows. This guide will
 not teach Haskell or involve much code, and it requires no prior experience with
-the Haskell packaging system or other build tools.
+the Haskell packaging system or other build tools. Terms used in the guide are
+defined in the [glossary](glossary.md).
 
 __NOTE__ This document is probably out of date in some places and deserves a
 refresh. If you find this document helpful, please drop a note on
@@ -651,21 +652,16 @@ _Duplicate package names_: If multiple packages under the directory tree have
 same name, `stack init` will report those and automatically ignore one of them.
 
 _Ignore subdirectories_: By default `stack init` searches all the subdirectories
-for `.cabal` files. If you do not want that then you can use `--ignore-subdirs`
+for Cabal files. If you do not want that then you can use `--ignore-subdirs`
 command line switch.
 
 _Cabal warnings_: `stack init` will show warnings if there were issues in
-reading a Cabal package file. You may want to pay attention to the warnings as
-sometimes they may result in incomprehensible errors later on during dependency
-solving.
+reading a Cabal file. You may want to pay attention to the warnings as sometimes
+they may result in incomprehensible errors later on during dependency solving.
 
 _Package naming_: If the `Name` field defined in a Cabal file does not match
 with the Cabal file name then `stack init` will refuse to continue.
 
-_Cabal install errors_: `stack init` uses `cabal-install` to determine external
-dependencies. When `cabal-install` encounters errors, Cabal errors are displayed
-as is by `stack init` for diagnostics.
-
 _User warnings_: When packages are excluded or external dependencies added
 Stack will show warnings every time configuration file is loaded. You can
 suppress the warnings by editing the config file and removing the warnings from
@@ -808,9 +804,9 @@ This will:
 
 ### install and copy-bins
 
-It's worth calling out the behavior of the install command and `--copy-bins`
+It's worth calling out the behavior of the `install` command and `--copy-bins`
 option, since this has confused a number of users (especially when compared to
-behavior of other tools like cabal-install). The `install` command does
+behavior of other tools like Cabal (the tool)). The `install` command does
 precisely one thing in addition to the build command: it copies any generated
 executables to the local bin path. You may recognize the default value for that
 path:
@@ -820,13 +816,13 @@ michael@d30748af6d3d:~/helloworld$ stack path --local-bin
 /home/michael/.local/bin
 ```
 
-That's why the download page recommends adding that directory to your `PATH`
-environment variable. This feature is convenient, because now you can simply
-run `executable-name` in your shell instead of having to run
-`stack exec executable-name` from inside your project directory.
+That's why the download page recommends adding that directory to your PATH. This
+feature is convenient, because now you can simply run `executable-name` in your
+shell instead of having to run `stack exec executable-name` from inside your
+project directory.
 
 Since it's such a point of confusion, let me list a number of things Stack does
-*not* do specially for the install command:
+*not* do specially for the `install` command:
 
 * Stack will always build any necessary dependencies for your code. The install
   command is not necessary to trigger this behavior. If you just want to build a
@@ -1175,12 +1171,12 @@ Flags worth mentioning:
 * `--package foo` can be used to force a package to be installed before running
   the given command.
 * `--no-ghc-package-path` can be used to stop the `GHC_PACKAGE_PATH` environment
-  variable from being set. Some tools — notably cabal-install — do not behave
+  variable from being set. Some tools — notably Cabal (the tool) — do not behave
   well with that variable set.
 
 You may also find it convenient to use `stack exec` to launch a subshell
 (substitute `bash` with your preferred shell) where your compiled executable is
-available at the front of your `PATH`:
+available at the front of your PATH:
 
     stack exec bash
 
@@ -1391,7 +1387,7 @@ that project. See the next section for more information on configuration files.
 
 ### Platform-specific script issues
 
-On Mac OSX:
+On macOS:
 
 - Avoid `{-# LANGUAGE CPP #-}` in Stack scripts; it breaks the hashbang line
   ([GHC #6132](https://gitlab.haskell.org/ghc/ghc/issues/6132))
@@ -1494,38 +1490,39 @@ 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-install, and presumably all other tools
-share the same underlying Cabal package format, consisting of a `.cabal` file,
+__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-install, and NixOS. In that sense, we're sharing the same ecosystem.
+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-install does. This is just a default: as described above, Stack can
-      use dependency solving if desired, and cabal-install 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 1, which is why
-      we've made this selection of default behavior.
+      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-install does not: build plans can be affected
-      by the presence of preinstalled packages, and running `cabal update` can
-      cause a previously successful build to fail. With Stack, changing the
-      build plan is always an explicit decision.
+      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__.
-    * In cabal-install, 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
+    * 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 command equivalent is
-      `cabal install --enable-tests --only-dependencies && cabal configure --enable-tests && cabal build && cabal test`
-      (newer versions of cabal-install may make this command shorter).
+      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
@@ -1536,22 +1533,22 @@ Now the differences:
 
 __Other tools for comparison (including active and historical)__
 
-* [cabal-dev](https://hackage.haskell.org/package/cabal-dev) (deprecated in
-  favor of cabal-install)
+* [cabal-dev](https://hackage.haskell.org/package/cabal-dev). This is deprecated
+  in favor of 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-install,
-  cabal-meta is relevant. For Stack work, the feature set is fully subsumed by
-  Stack.
+  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-install 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.
+  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.
 
 ## Fun features
 
@@ -1697,7 +1694,7 @@ the Nixpkgs.
 Both Docker and Nix are methods to *isolate* builds and thereby make them more
 reproducible. They just differ in the means of achieving this isolation. Nix
 provides slightly weaker isolation guarantees than Docker, but is more
-lightweight and more portable (Linux and OS X mainly, but also Windows). For
+lightweight and more portable (Linux and macOS mainly, but also Windows). For
 more on Nix, its command-line interface and its package description language,
 read the [Nix manual](http://nixos.org/nix/manual). But keep in mind that the
 point of Stack's support is to obviate the need to write any Nix code in the

doc/README.md

@@ -154,7 +154,8 @@ Stack. If you want to go further, we highly recommend you read the
 ## Complete guide to Stack
 
 A complete [user guide to Stack](GUIDE.md) is available, covering all of
-the most common ways to use Stack.
+the most common ways to use Stack. Terms used in Stack's documentation are also
+explained in the [glossary](glossary.md).
 
 ## Why Stack?
 

doc/docker_integration.md

@@ -199,7 +199,7 @@ otherwise noted.
       # What to name the Docker container.  Only useful with `detach` or
       # `persist` true.  (default none)
       container-name: "example-name"
-      
+
       # Sets the network used by docker. Gets directly passed to dockers `net`
       # argument (default: host)
       network: host
@@ -263,8 +263,8 @@ Image Repositories
 FP Complete provides the following public image repositories on Docker Hub:
 
 - [fpco/stack-build](https://registry.hub.docker.com/u/fpco/stack-build/) (the
-  default) - GHC (patched), tools (stack, cabal-install, happy, alex, etc.), and
-  system developer libraries required to build all Stackage packages.
+  default) - GHC (patched), tools (Stack, Cabal (the tool), happy, alex, etc.),
+  and system developer libraries required to build all Stackage packages.
 
 FP Complete also builds custom variants of these images for their clients.
 

doc/faq.md

@@ -42,31 +42,32 @@ installs the Stackage libraries in `~/.stack` and any project libraries or
 extra dependencies in a `.stack-work` directory within each project's
 directory. None of this should affect any existing Haskell tools at all.
 
-## What is the relationship between stack and cabal?
-
-* 'Cabal' can refer to the `Cabal` library or to the `cabal` command-line tool
-  (provided by the `cabal-install` package). Cabal-the-library is used by stack
-  to build your Haskell code.
-* A `.cabal` file is provided for each package. It  defines all package-level
-  metadata, just like it does in the `cabal-install` world: modules,
-  executables, test suites, etc. No change at all on this front.
+## What is the relationship between Stack and Cabal (the tool)?
+
+* 'Cabal' can refer to Cabal (the library) or to Cabal (the tool). Cabal (the
+  library) is used by Stack to build your Haskell code. Cabal (the tool) is
+  provided by the `cabal-install` package.
+* A Cabal file is provided for each package, named `<package_name>.cabal`. It
+  defines all package-level metadata, just like it does in the world of Cabal
+  (the tool): modules, executables, test suites, etc. No change at all on this
+  front.
 * A `stack.yaml` file references one or more packages, and provides information
   on where dependencies come from.
 * The `stack init` command initializes a `stack.yaml` file from an existing
-  `.cabal` file.
-* Stack uses `Cabal` via an executable. For `build-type: Simple` (the most
-  common case), stack builds that executable using the version of `Cabal` which
-  came with the compiler. Stack caches such executables, in the stack root under
-  folder `setup-exe-cache`.
-* In rare or complex cases, a different version of `Cabal` to the one that came
+  Cabal file.
+* Stack uses Cabal (the library) via an executable. For `build-type: Simple`
+  (the most common case), Stack builds that executable using the version of
+  Cabal which came with the compiler. Stack caches such executables, in the
+  Stack root under directory `setup-exe-cache`.
+* In rare or complex cases, a different version of Cabal to the one that came
   with the compiler may be needed. `build-type: Custom` and a `setup-custom`
-  stanza in the `.cabal` file, and a `Setup.hs` file in the package folder, can
-  be specified. The `stack.yaml` file can then specify the version of `Cabal`
-  that stack will use to build the executable (named `setup`) from `Setup.hs`.
-  Stack will use `Cabal` via `setup`.
+  stanza in the Cabal file, and a `Setup.hs` file in the package directory, can
+  be specified. The `stack.yaml` file can then specify the version of Cabal
+  that Stack will use to build the executable (named `setup`) from `Setup.hs`.
+  Stack will use Cabal via `setup`.
 
-For detail on the differences between a `stack.yaml` and Cabal package file, see
-[stack.yaml vs cabal package file](stack_yaml_vs_cabal_package_file.md).
+For detail on the differences between a `stack.yaml` file and a Cabal file, see
+[stack.yaml vs Cabal package file](stack_yaml_vs_cabal_package_file.md).
 
 ## I need to use a different version of a package than what is provided by the LTS Haskell snapshot I'm using, what should I do?
 
@@ -140,27 +141,27 @@ installed packages with actions taken in other projects.
 
 ## Can I run `cabal` commands inside `stack exec`?
 
-With a recent enough version of cabal-install (>= 1.22), you can. For older
-versions, due to
-[haskell/cabal#1800](https://github.com/haskell/cabal/issues/1800), this does
-not work. Note that even with recent versions, for some commands you may need
-this extra level of indirection:
-```
-$ stack exec -- cabal exec -- cabal <command>
-```
+With a recent enough version of Cabal (the tool) (1.22 or later), you can. For
+earlier versions this does not work, due to
+[haskell/cabal#1800](https://github.com/haskell/cabal/issues/1800). Note that
+even with recent versions, for some commands you may need this extra level of
+indirection:
+
+    $ stack exec -- cabal exec -- cabal <command>
+
+However, virtually all `cabal` commands have an equivalent in Stack, so this
+should not be necessary. In particular, users of Cabal (the tool) may be
+accustomed to the `cabal run` command. In Stack:
+
+    $ stack build
+    $ stack exec <program-name>
 
-However, virtually all `cabal` commands have an equivalent in stack, so this
-should not be necessary. In particular, `cabal` users may be accustomed to the
-`cabal run` command. In stack:
-```
-$ stack build && stack exec <program-name>
-```
 Or, if you want to install the binaries in a shared location:
-```
-$ stack install
-$ <program-name>
-```
-assuming your `$PATH` has been set appropriately.
+
+    $ stack install
+    $ <program-name>
+
+assuming your PATH has been set appropriately.
 
 ## Using custom preprocessors
 

doc/glossary.md

@@ -30,7 +30,8 @@ The following terms are used in Stack's documentation.
 |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.      |
 |Pantry             |A library for content-addressable Haskell package management, provided by the [`pantry` package](https://hackage.haskell.org/package/pantry). A dependency of Stack.|
-|REPL               | An interactive (run-eval-print loop) programming environment.|
+|PATH               |The `PATH` environment variable, specifying a list of directories searched for executable files.|
+|REPL               |An interactive (run-eval-print loop) programming environment.|
 |resolver           |A synonym for snapshot.                                   |
 |`Setup.hs`         |A project-specific file used by Cabal to perform setup tasks.|
 |snapshot           |A snapshot defines a GHC version, a set of packages, and build flags or other settings.|

doc/maintainers/releases.md

@@ -439,7 +439,7 @@ Now continue to the **General Windows setup** subsection below.
     Binary: get an [existing `stack` binary](https://github.com/commercialhaskell/stack/releases)
 and put it in `~/.local/bin`.
 
-    From source (using cabal-install):
+    From source, using Cabal (the tool):
 
     ```
     wget http://downloads.haskell.org/~ghc/7.10.3/ghc-7.10.3-armv7-deb8-linux.tar.xz && \

doc/nonstandard_project_init.md

@@ -4,18 +4,17 @@
 
 ## Introduction
 The purpose of this page is to collect information about issues that arise when
-users either have an existing cabal project or another nonstandard setup such
-as a private hackage database.
+users either have an existing Cabal project or another nonstandard setup such
+as a private Hackage database.
 
-## Using a Cabal File
+## Using a Cabal file
 
-New users may be confused by the fact that you must add
-dependencies to the package's cabal file, even in the case when you have
-already listed the package in the `stack.yaml`. In most cases, dependencies for
-your package that are in the Stackage snapshot need *only* be added to the
-cabal file. stack makes heavy use of Cabal the library under the hood. In
-general, your stack packages should also end up being valid cabal-install
-packages.
+New users may be confused by the fact that you must add dependencies to the
+package's Cabal file, even in the case when you have already listed the package
+in the `stack.yaml` file. In most cases, dependencies for your package that are
+in the Stackage snapshot need *only* be added to the Cabal file. Stack makes
+heavy use of Cabal under the hood. In general, your Stack packages should also
+end up being valid packages for Cabal (the tool).
 
 ### Issues Referenced
   - <https://github.com/commercialhaskell/stack/issues/105>
@@ -44,7 +43,7 @@ It is also possible to pass the same flag to multiple packages, i.e.
 `stack build --flag *:necessary`
 
 Currently one needs to list all of your modules that interpret flags in the
-`other-modules` section of a cabal file. `cabal-install` has a different
+`other-modules` section of a cabal file. Cabal (the tool) has a different
 behavior currently and doesn't require that the modules be listed. This may
 change in a future release.