Merge branch 'stable'

Also updates stack.cabal for the new *.md file.

Author: mpilgrem

doc/GUIDE.md

@@ -1,13 +1,16 @@
 <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>
 
-# User guide
+# User guide (introductory)
 
 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. Terms used in the guide are
-defined in the [glossary](glossary.md).
+This introductory 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. Terms used in
+the guide are defined in the [glossary](glossary.md).
+
+Some of Stack's features will not be needed regularly or by all users. See the
+[advanced user's guide](GUIDE_advanced.md) for information about those features.
 
 ## Stack's functions
 
@@ -79,7 +82,9 @@ package name first:
 
 We'll call our project `helloworld`, and we'll use the `new-template` project
 template. This template is used by default, but in our example we will refer to
-it expressly. From the root directory for all our Haskell projects, we command:
+it expressly. Other templates are available, see the `stack templates` command.
+
+From the root directory for all our Haskell projects, we command:
 
     $ stack new helloworld new-template
 
@@ -730,6 +735,16 @@ The reason we have this structure is that:
 As you probably guessed, there can be multiple snapshot databases available. See
 the contents of the `snapshots` directory in the Stack root.
 
+* On Unix-like operating systems, each snapshot is in the last of a sequence of
+  three subdirectories named after the platform, a 256-bit hash of the source
+  map (how the package should be built -- including the compiler, options, and
+  immutable dependencies), and the GHC version.
+
+* On Windows, each snapshot is in a subdirectory that is a shorter hash (eight
+  characters) of the sequence of three directories used on Unix-like operating
+  systems. This is done to avoid problems created by default limits on file
+  path lengths on Windows systems.
+
 These snapshot databases don't get layered on top of each other; they are each
 used separately.
 
@@ -1598,250 +1613,6 @@ __Other tools for comparison (including active and historical)__
   constraints and snapshots, it did not work as well as hoped. It is deprecated
   in favor of Stack.
 
-## Fun features
-
-This is just a quick collection of fun and useful feature Stack supports.
-
-### Templates
-
-We started off using the `new` command to create a project. Stack provides
-multiple templates to start a new project from. For more information, command:
-
-    $ stack templates
-
-You can specify one of these templates following your project name
-in the `stack new` command:
-
-    $ stack new my-rio-project rio
-    Downloading template "rio" to create project "my-rio-project" in my-rio-project/ ...
-    Looking for .cabal or package.yaml files to use to init the project.
-    Using cabal packages:
-    - my-rio-project/
-
-    Selecting the best among 18 snapshots...
-
-    * Matches ...
-
-    Selected resolver: ...
-    Initialising configuration using resolver: ...
-    Total number of user packages considered: 1
-    Writing configuration to file: my-rio-project/stack.yaml
-    All done.
-    <Stack root>\templates\rio.hsfiles:   10.10 KiB downloaded...
-
-The default templates repository is
-https://github.com/commercialhaskell/stack-templates. You can download templates
-from a different Github user by prefixing the username and a slash:
-
-    $ stack new my-yesod-project yesodweb/simple
-
-Then template file `simple.hsfiles` would be downloaded from GitHub repository
-`yesodweb/stack-templates`.
-
-You can even download templates from a service other that GitHub, such as
-[GitLab](https://gitlab.com) or [Bitbucket](https://bitbucket.com). For example:
-
-    $ stack new my-project gitlab:user29/foo
-
-Template file `foo.hsfiles` would be downloaded from GitLab, user account
-`user29`, repository `stack-templates`.
-
-If you need more flexibility, you can specify the full URL of the template:
-
-    $ stack new my-project https://my-site.com/content/template9.hsfiles
-
-(The `.hsfiles` extension is optional; it will be added if it's not specified.)
-
-Alternatively you can use a local template by specifying the path:
-
-    $ stack new project <path_to_template>/template.hsfiles
-
-As a starting point for creating your own templates, you can use the
-["simple" template](https://github.com/commercialhaskell/stack-templates/blob/master/simple.hsfiles).
-The
-[stack-templates repository](https://github.com/commercialhaskell/stack-templates#readme)
-provides an introduction into creating templates.
-
-### Editor integration
-
-For editor integration, Stack has a related project called
-[intero](https://github.com/commercialhaskell/intero). It is particularly well
-supported by Emacs, but some other editors have integration for it as well.
-
-### Visualizing dependencies
-
-If you'd like to get some insight into the dependency tree of your packages, you
-can use the `stack dot` command and Graphviz. More information is available in
-the [Dependency visualization documentation](dependency_visualization.md).
-
-### Travis with caching
-
-This content has been moved to a dedicated
-[Travis CI document](https://docs.haskellstack.org/en/stable/travis_ci/).
-
-### Shell auto-completion
-
-Love tab-completion of commands? You're not alone. If you're on bash, just run
-the following (or add it to `.bashrc`):
-
-    eval "$(stack --bash-completion-script stack)"
-
-For more information and other shells, see the
-[Shell auto-completion wiki page](https://docs.haskellstack.org/en/stable/shell_autocompletion)
-
-### Docker
-
-Stack is able to build your code inside a Docker image, which means even more
-reproducibility to your builds, since you and the rest of your team will always
-have the same system libraries.
-
-### Nix
-
-Stack provides an integration with [Nix](http://nixos.org/nix), providing you
-with the same two benefits as the first Docker integration discussed above:
-
-* more reproducible builds, since fixed versions of any system libraries and
-  commands required to build the project are automatically built using Nix and
-  managed locally per-project. These system packages never conflict with any
-  existing versions of these libraries on your system. That they are managed
-  locally to the project means that you don't need to alter your system in any
-  way to build any odd project pulled from the Internet.
-* implicit sharing of system packages between projects, so you don't have more
-  copies on-disk than you need to.
-
-When using the Nix integration, Stack downloads and builds Haskell dependencies
-as usual, but resorts on Nix to provide non-Haskell dependencies that exist in
-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 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
-common case or even to learn how to use the Nix tools (they're called under the
-hood).
-
-For more information, see
-[the Nix-integration documentation](nix_integration.md).
-
-## Power user commands
-
-The following commands are a little more powerful, and won't be needed by all
-users. Here's a quick rundown:
-
-* `stack update` will download the most recent set of packages from your package
-  indices (e.g. Hackage). Generally, Stack runs this for you automatically
-  when necessary, but it can be useful to do this manually sometimes.
-* `stack unpack` is a command we've already used quite a bit for examples, but
-  most users won't use it regularly. It does what you'd expect: downloads a
-  tarball and unpacks it. It accept optional `--to` argument to specify
-  the destination directory.
-* `stack sdist` generates an uploading tarball containing your package code
-* `stack upload` uploads an sdist to Hackage. As of version
-  [1.1.0](https://docs.haskellstack.org/en/v1.1.0/ChangeLog/) Stack will also
-  attempt to GPG sign your packages as per
-  [our blog post](https://www.fpcomplete.com/blog/2016/05/stack-security-gnupg-keys).
-    * `--no-signature` disables signing of packages
-    * `--candidate` upload a
-      [package candidate](http://hackage.haskell.org/upload#candidates)
-    * Hackage API key can be used instead of username and password. Usage
-      example:
-
-    ```bash
-    HACKAGE_KEY=<api_key> stack upload .
-    ```
-
-    * `username` and `password` can be read by environment
-
-    ```bash
-    export $HACKAGE_USERNAME="<username>"
-    export $HACKAGE_PASSWORD="<password>"
-    ```
-
-* `stack upgrade` will build a new version of Stack from source.
-    * `--git` is a convenient way to get the most recent version from the
-      `master` branch, for those testing and living on the bleeding edge.
-* `stack ls snapshots` will list all the local snapshots by default. You can
-  also view the remote snapshots using `stack ls snapshots remote`. It also
-  supports option for viewing only lts (`-l`) and nightly (`-n`) snapshots.
-* `stack ls dependencies` lists all of the packages and versions used for a
-  project
-* `stack list [PACKAGE]...` list the version of the specified package(s) in a
-  snapshot, or without an argument list all the snapshot's package versions.
-  If no resolver is specified the latest package version from Hackage is given.
-* `stack sig` subcommand can help you with GPG signing & verification
-    * `sign` will sign an sdist tarball and submit the signature to
-      sig.commercialhaskell.org for storage in the sig-archive git repo.
-      (Signatures will be used later to verify package integrity.)
-
-## Debugging
-
-To profile a component of the current project, simply pass the `--profile`
-flag to `stack`. The `--profile` flag turns on the `--enable-library-profiling`
-and `--enable-executable-profiling` Cabal options _and_ passes the `+RTS -p`
-runtime options to any testsuites and benchmarks.
-
-For example the following command will build the `my-tests` testsuite with
-profiling options and create a `my-tests.prof` file in the current directory
-as a result of the test run.
-
-    $ stack test --profile my-tests
-
-The `my-tests.prof` file now contains time and allocation info for the test run.
-
-To create a profiling report for an executable, e.g. `my-exe`, you can run
-
-     $ stack exec --profile -- my-exe +RTS -p
-
-For more fine-grained control of compilation options there are the
-`--library-profiling` and `--executable-profiling` flags which will turn on the
-`--enable-library-profiling` and `--enable-executable-profiling` Cabal
-options respectively. Custom GHC options can be passed in with
-`--ghc-options "more options here"`.
-
-To enable compilation with profiling options by default you can add the
-following snippet to your `stack.yaml` or `~/.stack/config.yaml`:
-
-```yaml
-build:
-  library-profiling: true
-  executable-profiling: true
-```
-
-### Further reading
-
-For more commands and uses, see the
-[official GHC chapter on profiling](https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/profiling.html),
-the [Haskell wiki](https://wiki.haskell.org/How_to_profile_a_Haskell_program),
-and the
-[chapter on profiling in Real World Haskell](http://book.realworldhaskell.org/read/profiling-and-optimization.html).
-
-### Tracing
-
-To generate a backtrace in case of exceptions during a test or benchmarks run,
-use the `--trace` flag. Like `--profile` this compiles with profiling options,
-but adds the `+RTS -xc` runtime option.
-
-### Debugging symbols
-
-Building with debugging symbols in the
-[DWARF information](https://ghc.haskell.org/trac/ghc/wiki/DWARF) is supported by
-Stack. This can be done by passing the flag `--ghc-options="-g"` and also to
-override the default behaviour of stripping executables of debugging symbols by
-passing either one of the following flags: `--no-strip`,
-`--no-library-stripping` or `--no-executable-stripping`.
-
-In Windows, GDB can be installed to debug an executable with
-`stack exec -- pacman -S gdb`. Windows' Visual Studio compiler's debugging
-format PDB is not supported at the moment. This might be possible by
-[separating](https://stackoverflow.com/questions/866721/how-to-generate-gcc-debug-symbol-outside-the-build-target)
-debugging symbols and
-[converting](https://github.com/rainers/cv2pdb) their format. Or as an option
-when
-[using the LLVM backend](http://blog.llvm.org/2017/08/llvm-on-windows-now-supports-pdb-debug.html).
-
 ## More resources
 
 There are lots of resources available for learning more about Stack: