Update docs for 8.4.3/8.2.2 and Stack FAQ.

jbleduigou · Jun 5, 2018 · 6f8168f · 6f8168f
1 parent 19a084b
commit 6f8168f
Show file tree

Hide file tree

Showing 2 changed files with 40 additions and 11 deletions.
diff --git a/haskell/content.md b/haskell/content.md
@@ -10,24 +10,17 @@ A large number of production-quality Haskell libraries are available from [Hacka
 
 ## About this image
 
-This image ships a minimal Haskell toolchain with the following packages from the [hvr PPA](https://launchpad.net/~hvr/+archive/ubuntu/ghc):
+This image ships a minimal Haskell toolchain (`ghc` and `cabal-install`) from the upstream [downloads.haskell.org](https://launchpad.net/~hvr/+archive/ubuntu/ghc) Debian repository as well as the Stack tool ([https://www.haskellstack.org/](https://www.haskellstack.org/)).
 
--	`ghc`
--	`alex`
--	`cabal-install`
--	`happy`
-
-As of `7.10.3`, the `stack` tool is included.
-
-Note: The GHC developers do not support legacy release branches (i.e. `7.8.x`). While older GHC release tags are available in this DockerHub repository, only the latest stable release (or upcoming release candidates) will be shown in the "Supported tags ..." section at the top of this page.
+Note: The GHC developers do not support legacy release branches (i.e. `7.8.x`). While older GHC release tags are available in this DockerHub repository, only the two most recent minor releases will receive updates or be shown in the "Supported tags ..." section at the top of this page.
 
 ## How to use this image
 
 Start an interactive interpreter session with `ghci`:
 
 ```console
 $ docker run -it --rm %%IMAGE%%:8
-GHCi, version 8.0.2: http://www.haskell.org/ghc/  :? for help
+GHCi, version 8.4.3: http://www.haskell.org/ghc/  :? for help
 Prelude>
 ```
 
@@ -74,3 +67,39 @@ CMD ["snap-example"]
 ### Examples
 
 See the application snippet above in more detail in the [example snap application](https://github.com/freebroccolo/docker-haskell/tree/master/examples/7.10/snap).
+
+### Considerations for `happy`, `alex`, etc
+
+Some packages that also act as build dependencies, such as `happy` and `alex`, are no longer included in this image (as of `%%IMAGE%%:8.2.2` & `%%IMAGE%%:8.4.3`). There is a bootstrapping problem where one or more of these tools may be assumed to be available. If you run in to an error about missing dependencies that are not explicitly called out in a Cabal package, you will need to explicitly mark them for installation.
+
+### Considerations for Stack
+
+The Stack tool is primarily designed to run directly on the host and comes with many advanced features such as GHC bootstrapping and Docker integration. Within the context of a container image, some of these features clash with the Docker abstraction and should be avoided. Another common scenario that can be confusing is the default Stackage snapshot.
+
+A Stackage snapshot is a collection of Haskell packages pinned to specific versions for compatibility with a particular GHC release. When you ask Stack to resolve dependencies it refers to a particular snapshot via the `resolver` value. While you should be specifying a `resolver` explicitly in your projects, it is possible to run with the auto-generated default. That default is determined by the value obtained from the upstream Stackage server at the time it was requested, and points to the latest "LTS" snapshot. If the snapshot refers to a different version of GHC than is provided in the Docker image, you may see a message like the following:
+
+```console
+Step 2/3 : RUN stack install pandoc
+ ---> Running in e20466d52060
+Writing implicit global project config file to: /root/.stack/global-project/stack.yaml
+Note: You can change the snapshot via the resolver field there.
+Using latest snapshot resolver: lts-11.11
+Downloading lts-11.11 build plan ...
+Downloaded lts-11.11 build plan.
+Compiler version mismatched, found ghc-8.4.3 (x86_64), but expected minor version match with ghc-8.2.2 (x86_64) (based on resolver setting in /root/.stack/global-project/stack.yaml).
+To install the correct GHC into /root/.stack/programs/x86_64-linux/, try running "stack setup" or use the "--install-ghc" flag.
+```
+
+In this case, the GHC release in the `%%IMAGE%%` Docker image got ahead of the default Stack resolver expected version of GHC. As the output suggests, manually setting the resolver (typically via `stack.yml`) is the recommended approach.
+
+```console
+Step 2/3 : RUN stack install --resolver ghc-8.4.3 pandoc
+ ---> Running in 0bd7f1fcc8b2
+Writing implicit global project config file to: /root/.stack/global-project/stack.yaml
+Note: You can change the snapshot via the resolver field there.
+Using resolver: ghc-8.4.3 specified on command line
+Updating package index Hackage (mirrored at https://s3.amazonaws.com/hackage.fpcomplete.com/) ...
+Selected mirror https://s3.amazonaws.com/hackage.fpcomplete.com/
+```
+
+The alternative to use `--install-ghc` doesn't make sense in a Docker image context, and in fact the global `install-ghc` flag has been set to `false` (as of `%%IMAGE%%:8.2.2` & `%%IMAGE%%:8.4.3`) to avoid the default behavior of bootstrapping a new GHC in the container.
diff --git a/haskell/license.md b/haskell/license.md
@@ -1 +1 @@
-This image is licensed under the MIT License (see [LICENSE](https://github.com/darinmorrison/docker-haskell/blob/master/LICENSE)), and includes software licensed under the [Glasgow Haskell Compiler License](https://www.haskell.org/ghc/license) (BSD-style).
+This image is licensed under the MIT License ([LICENSE](https://github.com/freebroccolo/docker-haskell/blob/master/LICENSE)) and includes software licensed under BSD licenses: [Glasgow Haskell Compiler License](https://www.haskell.org/ghc/license), [Stack License](https://github.com/commercialhaskell/stack/blob/master/LICENSE).
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		This image is licensed under the MIT License (see [LICENSE](https://github.com/darinmorrison/docker-haskell/blob/master/LICENSE)), and includes software licensed under the [Glasgow Haskell Compiler License](https://www.haskell.org/ghc/license) (BSD-style).
		This image is licensed under the MIT License ([LICENSE](https://github.com/freebroccolo/docker-haskell/blob/master/LICENSE)) and includes software licensed under BSD licenses: [Glasgow Haskell Compiler License](https://www.haskell.org/ghc/license), [Stack License](https://github.com/commercialhaskell/stack/blob/master/LICENSE).