diff --git a/doc/README.md b/doc/README.md index 1ad3870191..e53a473029 100644 --- a/doc/README.md +++ b/doc/README.md @@ -150,6 +150,19 @@ Stack can be installed directly or by using the GHCup tool. Systems with antivirus software may need to add Stack to the list of 'trusted' applications. + ??? warning "I have a Windows username with a space in it" + + GHC 9.4.1 and later have a bug which means they do not work if + the path to the `ghc` executable has a space character in it. + The default location for Stack's 'programs' directory will have + a space in the path if the value of the `USERNAME` environment + variable includes a space. + + A solution is to configure Stack to use a different location for + its 'programs' directory. For further information, see the + [`local-programs-path`](configure/yaml/non-project.md#local-programs-path) + non-project specific configuration option documentation. + === "Windows on Arm" The GHC project does not yet provide a version of GHC that runs on diff --git a/doc/configure/yaml/non-project.md b/doc/configure/yaml/non-project.md index 548f1a151f..4f86f77eb3 100644 --- a/doc/configure/yaml/non-project.md +++ b/doc/configure/yaml/non-project.md @@ -932,18 +932,45 @@ Stack's defaults differ between Unix-like operating systems and Windows. The MSYS2 tool is also installed in the Stack 'programs' directory. - !!! warning + !!! warning "Space character in the path to Stack's 'programs' directory" If there is a space character in the path to Stack's 'programs' - directory 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 directory 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 specify an alternative path that does not contain - space characters. Examples of packages on Hackage that make use of - `configure` are `network` and `process`. + directory 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 directory 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). Examples of packages on Hackage that make use + of `configure` are `network` and `process`; and + + * building with GHC 9.4.1 and later. These versions of GHC have a bug + which means they do not work if the path to the `ghc` executable has + a space in it. + + The default location for Stack's 'programs' directory will have a space + in the path if the value of the `USERNAME` environment variable includes + a space. + + If there are problems building, it will be necessary to specify an + alternative path that does not contain spaces. For example, the + `programs` directory in the [Stack root](../../topics/stack_root.md) + (assuming that path is space-free). For example, if the relevant + directory is `C:\sr\programs`, add: + ~~~yaml + local-program-paths: C:\sr\programs + ~~~ + + to Stack's [global configuration](https://docs.haskellstack.org/en/stable/configure/yaml/#location-of-global-configuration) + file (`config.yaml`). + + If that global configuration file does not yet exist, command: + ~~~text + stack --no-install-ghc setup + ~~~ + + to cause Stack to create it (without also installing GHC). === "Windows (Command Prompt)" @@ -953,18 +980,45 @@ Stack's defaults differ between Unix-like operating systems and Windows. The MSYS2 tool is also installed in the Stack 'programs' directory. - !!! warning + !!! warning "Space character in the path to Stack's 'programs' directory" If there is a space character in the path to Stack's 'programs' - directory 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 directory 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 specify an alternative path that does not contain - space characters. Examples of packages on Hackage that make use of - `configure` are `network` and `process`. + directory 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 directory 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). Examples of packages on Hackage that make use + of `configure` are `network` and `process`; and + + * building with GHC 9.4.1 and later. These versions of GHC have a bug + which means they do not work if the path to the `ghc` executable has + a space in it. + + The default location for Stack's 'programs' directory will have a space + in the path if the value of the `USERNAME` environment variable includes + a space. + + If there are problems building, it will be necessary to specify an + alternative path that does not contain spaces. For example, the + `programs` directory in the [Stack root](../../topics/stack_root.md) + (assuming that path is space-free). For example, if the relevant + directory is `C:\sr\programs`, add: + ~~~yaml + local-program-paths: C:\sr\programs + ~~~ + + to Stack's [global configuration](https://docs.haskellstack.org/en/stable/configure/yaml/#location-of-global-configuration) + file (`config.yaml`). + + If that global configuration file does not yet exist, command: + ~~~text + stack --no-install-ghc setup + ~~~ + + to cause Stack to create it (without also installing GHC). ## modify-code-page diff --git a/doc/faq.md b/doc/faq.md index 53a4464745..f6ee317b27 100644 --- a/doc/faq.md +++ b/doc/faq.md @@ -593,6 +593,11 @@ Stack. See issue [#399](https://github.com/commercialhaskell/stack/issues/399) for the ongoing effort and information on workarounds. +??? question "I have a Windows username with a space in it and problems building" + + See the [`local-programs-path`](configure/yaml/non-project.md#local-programs-path) + non-project specific configuration option documentation for advice. + ??? question "How to get a working executable on Windows?" When executing a binary after building with `stack build` (e.g. for target @@ -616,14 +621,3 @@ https://msdn.microsoft.com/de-de/library/7d83bc18.aspx). See 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 the - [local-programs-path](configure/yaml/non-project.md#local-programs-path) option - for more information. - - See issue [#4726](https://github.com/commercialhaskell/stack/issues/4726). diff --git a/doc/install_and_upgrade.md b/doc/install_and_upgrade.md index c8a5c4ef64..de45df72c0 100644 --- a/doc/install_and_upgrade.md +++ b/doc/install_and_upgrade.md @@ -646,7 +646,20 @@ Stack can be installed directly or by using the GHCup tool. installer. If so, click on **More info**, and then click on the **Run anyway** button that appears. - !!! warning "Long user PATH environment variable" + ??? warning "I have a Windows username with a space in it" + + GHC 9.4.1 and later have a bug which means they do not work if + the path to the `ghc` executable has a space character in it. + The default location for Stack's 'programs' directory will have + a space in the path if the value of the `USERNAME` environment + variable includes a space. + + A solution is to configure Stack to use a different location for + its 'programs' directory. For further information, see the + [`local-programs-path`](configure/yaml/non-project.md#local-programs-path) + non-project specific configuration option documentation. + + ??? warning "Stack 2.9.1, 2.9.3 and 2.11.1: Long user PATH environment variable" The Windows installer for Stack 2.9.1, 2.9.3 and 2.11.1 (only) will replace the user `PATH` environment variable (rather than