Merge remote-tracking branch 'origin/stable' into xxx

Author: borsboom

doc/GUIDE.md

@@ -2030,6 +2030,23 @@ image:
 and then run `stack image container` and then `docker images` to list
 the images.
 
+Note that the executable will be built in the development environment 
+and copied to the container, so the dev OS must match that of the 
+container OS. This is easily accomplished using [Docker integration](docker_integration.md),
+under which the exe emitted by `stack build` will be built on the 
+Docker container, not the local OS. 
+
+The executable will be stored under `/usr/local/bin/<your-project>-exe`
+in the running container.
+
+If you want the container to run the executable immediately on startup
+then set an entrypoint as follows:
+
+```yaml
+entrypoints:
+    - <your-project>-exe
+```
+
 ### Nix
 
 stack provides an integration with [Nix](http://nixos.org/nix),

doc/README.md

@@ -23,22 +23,12 @@ or:
 
     wget -qO- https://get.haskellstack.org/ | sh
 
-For detailed instructions and downloads, instructions are available by
-operating system/distribution:
-
-* [Windows](install_and_upgrade.md#windows)
-* [macOS](install_and_upgrade.md#macos)
-* [Ubuntu](install_and_upgrade.md#ubuntu)
-* [Debian](install_and_upgrade.md#debian)
-* [CentOS / Red Hat / Amazon Linux](install_and_upgrade.md#centos)
-* [Fedora](install_and_upgrade.md#fedora)
-* [openSUSE / SUSE Linux Enterprise](install_and_upgrade.md#suse)
-* [Arch Linux](install_and_upgrade.md#arch-linux)
-* [NixOS](install_and_upgrade.md#nixos)
-* [Linux (general)](install_and_upgrade.md#linux)
-* [FreeBSD](install_and_upgrade.md#freebsd)
-
-[Upgrade instructions](install_and_upgrade.md#upgrade)
+On Windows, you can download and install the
+[Windows 64-bit Installer](https://www.stackage.org/stack/windows-x86_64-installer).
+
+For detailed instructions and downloads, including many additional
+operating systems, check out the
+[install and upgrade page](install_and_upgrade.md).
 
 #### Quick Start Guide
 
@@ -154,23 +144,33 @@ This repository also contains a complete [user guide to using stack
 * When using Stack Overflow, please use [the haskell-stack
   tag](http://stackoverflow.com/questions/tagged/haskell-stack).
 
-#### Why stack?
-
-stack is a project of the [Commercial Haskell](http://commercialhaskell.com/)
-group, spearheaded by [FP Complete](https://www.fpcomplete.com/). It is
-designed to answer the needs of commercial Haskell users, hobbyist Haskellers,
-and individuals and companies thinking about starting to use Haskell. It is
-intended to be easy to use for newcomers, while providing the customizability
-and power experienced developers need.
-
-While stack itself has been around since June of 2015, it is based on codebases
-used by FP Complete for its corporate customers and internally for years prior.
-stack is a refresh of that codebase combined with other open source efforts
-like [stackage-cli](https://github.com/fpco/stackage-cli) to meet the needs of
-users everywhere.
-
-A large impetus for the work on stack was a [large survey of people interested
-in
-Haskell](https://www.fpcomplete.com/blog/2015/05/thousand-user-haskell-survey),
-which rated build issues as a major concern. The stack team hopes that stack
-can address these concerns.
+#### Why Stack?
+
+Stack is a build tool for Haskell designed to answer the needs of
+Haskell users new and experienced alike. It has a strong focus on
+reproducible build plans, multi-package projects, and a consistent,
+easy-to-learn interface, while providing the customizability and
+power experienced developers need.  As a build tool, Stack does not
+stand alone. It is built on the great work provided by:
+
+* The __Glasgow Haskell Compiler__ (GHC), the premiere Haskell
+  compiler. Stack will manage your GHC installations and automatically
+  select the appropriate compiler version for your project.
+* The __Cabal build system__, a specification for defining Haskell
+  packages, together with a library for performing builds.
+* The __Hackage package repository__, providing more than ten thousand
+  open source libraries and applications to help you get your work
+  done.
+* The __Stackage package collection__, a curated set of packages from
+  Hackage which are regularly tested for compatibility. Stack defaults
+  to using Stackage package sets to avoid dependency problems.
+
+Stack is provided by a team of volunteers and companies under the
+auspices of the [Commercial Haskell](http://commercialhaskell.com/)
+group. The project was spearheaded by
+[FP Complete](https://www.fpcomplete.com/) to answer the needs of
+commercial Haskell users, and has since become a thriving open source
+project meeting the needs of Haskell users of all stripes.
+
+If you'd like to get involved with Stack, check out the
+[newcomers label on the Github issue tracker](https://github.com/commercialhaskell/stack/issues?q=is%3Aopen+is%3Aissue+label%3Anewcomer).

doc/custom_snapshot.md

@@ -113,7 +113,7 @@ it enables the `developer` cabal flag:
 resolver: lts-7.1
 packages:
   - text-1.2.2.1
-ghc-options:
+flags:
   text:
     developer: true
 ```

doc/docker_integration.md

@@ -1,6 +1,10 @@
 Docker integration
 ===============================================================================
 
+**Note:** This page is mainly about building Haskell packages inside docker containers.
+If you want to deploy your built Haskell programs into a docker container,
+look [here](GUIDE.md#docker) instead.
+
 `stack` has support for automatically performing builds inside a Docker
 container, using volume mounts and user ID switching to make it mostly seamless.
 FP Complete provides images for use with stack that include GHC, tools, and

doc/faq.md

@@ -4,6 +4,34 @@ So that this doesn't become repetitive: for the reasons behind the answers
 below, see the [Architecture](architecture.md) page. The goal of the answers
 here is to be as helpful and concise as possible.
 
+## What version of GHC is used when I run something like `stack ghci`?
+
+The version of GHC, as well as which packages can be installed, are
+specified by the _resolver_. This may be something like `lts-8.12`,
+which is from the
+[Long Term Support (LTS) Haskell](https://github.com/fpco/lts-haskell/)
+project. The [user guide](GUIDE.md) discusses resolvers in more
+detail.
+
+Which resolver is used is determined by finding the relevant
+`stack.yaml` configuration file for the directory you're running the
+command from. This essentially works by:
+
+1. Check for a `STACK_YAML` environment variable or the `--stack-yaml`
+   command line argument
+2. If none present, check for a `stack.yaml` file in the current
+   directory or any parents
+3. If no `stack.yaml` was found, use the _implicit global_
+
+The implicit global is a shared project used whenever you're outside
+of another project. It's a sort of "mutable shared state" that you
+should be aware of when working with Stack. The most recent request
+when working with the implicit global is how to move to a more recent
+LTS snapshot. You can do this by running the following from outside of
+a project:
+
+    stack config set resolver lts
+
 ## Where is stack installed and will it interfere with `ghc` (etc) I already have installed?
 
 Stack itself is installed in normal system locations based on the mechanism you

doc/install_and_upgrade.md

@@ -24,42 +24,26 @@ find links that always point to the latest bindists
 
 ## Windows
 
-*Note*: Due to specific Windows limitations,
- [some temporary workarounds](https://www.fpcomplete.com/blog/2015/08/stack-ghc-windows)
- may be required. It is strongly advised to set your `STACK_ROOT` environment
- variable similarly to your root (e.g., `set STACK_ROOT=c:\stack_root`) *before*
- running `stack`.
-
-*Note:* while generally 32-bit GHC is better tested on Windows, there are
-reports that recent versions of Windows only work with the 64-bit version of
-Stack (see
-[issue #393](https://github.com/commercialhaskell/stack/issues/393)).
-
-### Installer
-
 We recommend installing to the default location with these installers, as that
 will make `stack install` and `stack upgrade` work correctly out of the box.
 
-  * [Windows 32-bit Installer](https://www.stackage.org/stack/windows-i386-installer)
   * [Windows 64-bit Installer](https://www.stackage.org/stack/windows-x86_64-installer)
+  * [Windows 32-bit Installer](https://www.stackage.org/stack/windows-i386-installer)
+
+If in doubt: you should prefer the 64-bit installer.
 
 ### Manual download
 
 * Download the latest release:
 
-    * [Windows 32-bit](https://www.stackage.org/stack/windows-i386)
     * [Windows 64-bit](https://www.stackage.org/stack/windows-x86_64)
+    * [Windows 32-bit](https://www.stackage.org/stack/windows-i386)
 
 * Unpack the archive and place `stack.exe` somewhere on your `%PATH%` (see
   [Path section below](#path)) and you can then run `stack` on the command line.
 
 * Now you can run `stack` from the terminal.
 
-NOTE: These executables have been built and tested on a Windows 7, 8.1, and 10
-64-bit machines. They should run on older Windows installs as well, but have not
-been tested. If you do test, please edit and update this page to indicate as
-such.
-
 ## macOS
 
 We generally test on the current version of macOS, but Stack is known to work

doc/yaml_configuration.md

@@ -128,6 +128,11 @@ packages:
   - wai
 ```
 
+If unspecified, `subdirs` defaults to `['.']` (i.e. look only in the top-level
+directory).  Note that if you specify a value of `subdirs`, then `'.'` is _not_
+included by default and needs to be explicitly specified if a required package
+is found in the top-level directory of the repository.
+
 #### Local dependency packages (`extra-dep`)
 A `location` key can be accompanied by an `extra-dep` key.  When the
 `extra-dep` key is set to `true` it indicates that the package should be