Merge pull request #4798 from mpilgrem/4726-local-programs-path

Fix #4726: Improve docs on stack's programs path, on Windows

Author: snoyberg

doc/GUIDE.md

@@ -37,10 +37,11 @@ __resolver__, to the snapshot which your package will be built against.
 
 Finally, stack is __isolated__: it will not make changes outside of specific
 stack directories. stack-built files generally go in either the stack root
-directory (default `~/.stack`) or `./.stack-work` directories local to each
-project. The stack root directory holds packages belonging to snapshots and any
-stack-installed versions of GHC. Stack will not tamper with any system version
-of GHC or interfere with packages installed by `cabal` or any other build tools.
+directory (default `~/.stack` or, on Windows, `%LOCALAPPDATA%\Programs\stack`)
+or `./.stack-work` directories local to each project. The stack root directory
+holds packages belonging to snapshots and any stack-installed versions of GHC.
+Stack will not tamper with any system version of GHC or interfere with packages
+installed by `cabal` or any other build tools.
 
 _NOTE_ In this guide, we'll use commands as run on a GNU/Linux system
 (specifically Ubuntu 14.04, 64-bit) and share output from that. Output on other
@@ -558,8 +559,8 @@ Haskell packages, this will often be enough to build most packages. However,
 at times, you may find that not all dependencies required may be available in
 the Stackage snapshots.
 
-Let's simulate an unsatisfied dependency by adding acme-missiles to the list of dependencies 
-the build requires. This is done by including it in the `Build-depends` section in the .cabal file 
+Let's simulate an unsatisfied dependency by adding acme-missiles to the list of dependencies
+the build requires. This is done by including it in the `Build-depends` section in the .cabal file
 and then re-initing:
 
 ```
@@ -1198,7 +1199,8 @@ While we're talking about paths, to wipe our stack install completely, here's
 what needs to be removed:
 
 1. The stack executable itself
-2. The stack root, e.g. `$HOME/.stack` on non-Windows systems.
+2. The stack root, e.g. `$HOME/.stack` on non-Windows systems or, on Windows,
+   `%LOCALAPPDATA%\Programs\stack`.
     * See `stack path --stack-root`
     * On Windows, you will also need to delete `stack path --programs`
 3. Any local `.stack-work` directories inside a project

doc/README.md

@@ -148,9 +148,9 @@ stack ghci
 λ: :main --stack-root /path/to/root/ --stack-yaml /path/to/stack.yaml COMMAND
 ```
 
-This allows you to set a special stack root (instead of `~/.stack/`) and to
-target your commands at a particular `stack.yaml` instead of the one found in
-the current directory.
+This allows you to set a special stack root (instead of `~/.stack/` or, on
+Windows, `%LOCALAPPDATA%\Programs\stack`) and to target your commands at a
+particular `stack.yaml` instead of the one found in the current directory.
 
 #### Complete guide to stack
 
@@ -203,4 +203,3 @@ label on the Github issue tracker.
 
 #### How to uninstall
 Removing ``~/.stack`` and ``/usr/local/bin/stack`` should be sufficient. You may want to delete ``.stack-work`` folders in any Haskell projects that you have built.
-

doc/faq.md

@@ -360,6 +360,17 @@ copying the files somewhere Windows finds them (cf. https://msdn.microsoft.com/d
 
 Cf. issue [#425](https://github.com/commercialhaskell/stack/issues/425).
 
+Another issue that may arise with building on Windows is as follows. The default
+location of stack's programs folder is `%LOCALAPPDATA\Programs\stack`. If there
+is a space character in the `%LOCALAPPDATA%` path this may, in some
+circumstances, cause problems with building packages that make use of the GNU
+project's `autoconf` package and `configure` shell script files. It may be
+necessary to override the default location of stack's programs folder. See
+[Non-project-specific config option, local-programs-path](yaml_configuration.md)
+for more informaton.
+
+Cf. issue [#4726](https://github.com/commercialhaskell/stack/issues/4726)
+
 ## Can I change stack's default temporary directory?
 
 Stack downloads and extracts files to `$STACK_ROOT/programs` on most platforms,

doc/yaml_configuration.md

@@ -475,10 +475,10 @@ extra-lib-dirs:
 ```
 
 Since these are system-dependent absolute paths, it is recommended that you
-specify these in your `config.yaml` within the stack root (usually, `~/.stack`).
-If you control the build environment in your project's ``stack.yaml``, perhaps
-through docker or other means, then it may well make sense to include these
-there as well.
+specify these in your `config.yaml` within the stack root (usually, `~/.stack`
+or, on Windows, `%LOCALAPPDATA%\Programs\stack`). If you control the build
+environment in your project's ``stack.yaml``, perhaps through docker or other
+means, then it may well make sense to include these there as well.
 
 
 ### with-gcc
@@ -1004,9 +1004,21 @@ This overrides the location of the programs directory, where tools like ghc and
 msys get installed.
 
 On most systems, this defaults to a folder called `programs`
-within the stack root directory. On windows, if the `LOCALAPPDATA` environment
-variable exists, then it defaults to `$LOCALAPPDATA/Programs/stack/`, which
-follows windows conventions.
+within the stack root directory. On Windows, if the `LOCALAPPDATA` environment
+variable exists, then it defaults to `%LOCALAPPDATA%\Programs\stack`, which
+follows Windows' conventions.
+
+__NOTE__: On Windows, if there is a space character in the `%LOCALAPPDATA%` path
+(which may be the case if the relevant user account name and its corresponding
+user profie path have a space) this may cause problems with building packages
+that make use of the GNU project's `autoconf` package and `configure` shell
+script files. That may be the case particularly if there is no corresponding
+short name ('8 dot 3' name) for the folder in the path with the space (which may
+be the case if '8 dot 3' names have been stripped or their creation not enabled
+by default). If there are problems building, it will be necessary to override
+the default location of stack's programs directory to specify an alternative
+path that does not contain space characters. Examples of packages on Hackage
+that make use of `configure` are `network` and `process`.
 
 Since 1.3.0