Elevate the Stack root to a specific topic

Author: mpilgrem

doc/GUIDE.md

@@ -42,10 +42,11 @@ 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 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 other build tools, such as Cabal (the tool).
+directory or `./.stack-work` directories local to each project. The
+[Stack root](stack_root.md) 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 other build tools, such
+as Cabal (the tool).
 
 ## Downloading and Installation
 
@@ -807,7 +808,7 @@ The reason we have this structure is that:
   non-standard content into the shared snapshot database.
 
 As you probably guessed, there can be multiple snapshot databases available. See
-the contents of the `snapshots` directory in the Stack root.
+the contents of the `snapshots` directory in the [Stack root](stack_root.md).
 
 * 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
@@ -1429,87 +1430,6 @@ configuration. It has no effect on projects at all. Every package you install
 with it is put into isolated databases just like everywhere else. The only magic
 is that it's the catch-all project whenever you're running Stack somewhere else.
 
-## Setting the Stack root location
-
-The Stack root is a directory where Stack stores important files. The location
-and contents of the directory depend on the operating system and/or whether
-Stack is configured to use the XDG Base Directory Specification.
-
-The location of the Stack root can be configured by setting the `STACK_ROOT`
-environment variable or using Stack's `--stack-root` option on the command line.
-
-=== "Unix-like"
-
-    The Stack root contains snapshot packages; tools such as GHC, in a
-    `programs` directory; and Stack's global YAML configuration file
-    (`config.yaml`).
-
-    The default Stack root is `~/.stack`.
-
-=== "Windows"
-
-    The Stack root contains snapshot packages; and Stack's global YAML
-    configuration file (`config.yaml`). The default location of tools such as
-    GHC and MSYS2 is outside of the Stack root.
-
-    The default Stack root is `%APPDIR%\stack`.
-
-    The default location of tools is `%LOCALAPPDATA%\Programs\stack`.
-
-    On Windows, the length of filepaths may be limited (to
-    [MAX_PATH](https://docs.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=cmd)),
-    and things can break when this limit is exceeded. Setting a Stack root with
-    a short path to its location (for example, `C:\sr`) can help.
-
-=== "XDG Base Directory Specification"
-
-    On Unix-like operating systems and Windows, Stack can be configured to
-    follow the XDG Base Directory Specification if the environment variable
-    `STACK_XDG` is set to any non-empty value. However, Stack will ignore that
-    configuration if the Stack root location has been set on the command line or
-    the `STACK_ROOT` environment variable exists.
-
-    If Stack is following the XDG Base Directory Specification, the Stack root
-    contains what it would otherwise contain for the operating system, but
-    Stack's global YAML configuration file (`config.yaml`) may be located
-    elsewhere.
-
-    The Stack root is `<XDG_DATA_HOME>/stack`. If the `XDG_DATA_HOME`
-    environment variable does not exist, the default is `~/.local/share/stack`
-    on Unix-like operating systems and `%APPDIR%\stack` on Windows.
-
-    The location of `config.yaml` is `<XDG_CONFIG_HOME>/stack`. If the
-    `XDG_CONFIG_HOME` environment variable does not exist, the default is
-    `~/.config/stack` on Unix-like operating systems and `%APPDIR%\stack` on
-    Windows.
-
-    This approach treats:
-
-    *   the project-level YAML configuration file that is common to all projects
-        without another such file in their project directory or its ancestor
-        directories as _data_ rather than as part of Stack's own
-        _configuration_;
-
-    *   the snapshots database as essential data rather than as non-essential
-        data that would be part of a _cache_, notwithstanding that Stack will
-        rebuild that database as its contents are needed; and
-
-    *   the Pantry store as essential data rather than as non-essential data
-        that would be part of a _cache_, notwithstanding that Stack will
-        download the package index and rebuild the store if it is absent.
-
-The location of the Stack root is reported by command:
-
-~~~text
-stack path --stack-root
-~~~
-
-The full path of Stack's global YAML configuration file is reported by command:
-
-~~~text
-stack path --global-config
-~~~
-
 ## `stack.yaml` versus Cabal files
 
 Now that we've covered a lot of Stack use cases, this quick summary of

doc/build_command.md

@@ -554,9 +554,9 @@ All the following examples assume that:
 *   if `stack build` is commanded outside of a project directory, there is no
     `stack.yaml` file in the current directory or ancestor directory and,
     consequently, the project-level configuration will be determined by a
-    `stack.yaml` file in the `global-project` directory in the Stack root (for
-    further information, see the [YAML configuration](yaml_configuration.md)
-    documentation); and
+    `stack.yaml` file in the `global-project` directory in the
+    [Stack root](stack_root.md) (for further information, see the
+    [YAML configuration](yaml_configuration.md) documentation); and
 
 *   if `stack build` is commanded in a project directory, there is a
     `stack.yaml` file in that directory.

doc/environment_variables.md

@@ -76,8 +76,8 @@ file (`config.yaml`).
 Overridden by: Stack's global
 [`--stack-root`](global_flags.md#-stack-root-option) option.
 
-The environment variable `STACK_ROOT` can be used to specify the Stack root
-directory.
+The environment variable `STACK_ROOT` can be used to specify the
+[Stack root](stack_root.md) directory.
 
 ## `STACK_WORK`
 

doc/global_flags.md

@@ -13,10 +13,10 @@ Restrictions: POSIX systems only
 
 Default: True, if inside Docker; false otherwise
 
-Enable/disable permitting users other than the owner of the Stack root directory
-to use a Stack installation. For further information, see the documentation for
-the corresponding non-project specific configuration
-[option](yaml_configuration.md#allow-different-user).
+Enable/disable permitting users other than the owner of the
+[Stack root](stack_root.md) directory to use a Stack installation. For further
+information, see the documentation for the corresponding non-project specific
+configuration [option](yaml_configuration.md#allow-different-user).
 
 ## `--arch` option
 
@@ -212,7 +212,8 @@ specific configuration [option](yaml_configuration.md#stack-colors).
 Overrides: `STACK_ROOT` environment variable
 
 Pass the option `--stack-root <absolute_path_to_the_Stack_root>` to specify the
-path to the Stack root directory. The path must be an absolute one.
+path to the [Stack root](stack_root.md) directory. The path must be an absolute
+one.
 
 ## `--stack-yaml` option
 

doc/stack_root.md

@@ -0,0 +1,119 @@
+<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>
+
+# Stack root location
+
+The Stack root is a directory where Stack stores important files. The location
+and contents of the directory depend on the operating system, whether
+Stack is configured to use the XDG Base Directory Specification, and/or
+whether an alternative location to Stack's default 'programs' directory has
+been specified.
+
+The location of the Stack root can be configured by setting the
+[`STACK_ROOT`](environment_variables.md#stack_root) environment variable or
+using Stack's [`--stack-root`](global_flags.md#stack-root-option) option on the
+command line.
+
+=== "Unix-like"
+
+    The Stack root contains snapshot packages; (by default) tools such as GHC,
+    in a `programs` directory; Stack's global
+    [YAML configuration](yaml_configuration.md#yaml-configuration) file
+    (`config.yaml`); and Stack's
+    [`global-projects`](yaml_configuration.md#yaml-configuration) directory.
+
+    The default Stack root is `~/.stack`.
+
+=== "Windows"
+
+    The Stack root contains snapshot packages; Stack's global
+    [YAML configuration](yaml_configuration.md#yaml-configuration) file
+    (`config.yaml`); and Stack's
+    [`global-projects`](yaml_configuration.md#yaml-configuration) directory. The
+    default location of tools such as GHC and MSYS2 is outside of the Stack
+    root.
+
+    The default Stack root is `%APPDIR%\stack`.
+
+    If the `LOCALAPPDATA` environment variable exists, the default location of
+    tools is `%LOCALAPPDATA%\Programs\stack`. Otherwise, it is the `programs`
+    directory in the Stack root.
+
+    !!! warning
+
+        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
+        profile 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 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 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`.
+
+    On Windows, the length of filepaths may be limited (to
+    [MAX_PATH](https://docs.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=cmd)),
+    and things can break when this limit is exceeded. Setting a Stack root with
+    a short path to its location (for example, `C:\sr`) can help.
+
+=== "XDG Base Directory Specification"
+
+    On Unix-like operating systems and Windows, Stack can be configured to
+    follow the XDG Base Directory Specification if the environment variable
+    `STACK_XDG` is set to any non-empty value. However, Stack will ignore that
+    configuration if the Stack root location has been set on the command line or
+    the `STACK_ROOT` environment variable exists.
+
+    If Stack is following the XDG Base Directory Specification, the Stack root
+    contains what it would otherwise contain for the operating system, but
+    Stack's global YAML configuration file (`config.yaml`) may be located
+    elsewhere.
+
+    The Stack root is `<XDG_DATA_HOME>/stack`. If the `XDG_DATA_HOME`
+    environment variable does not exist, the default is `~/.local/share/stack`
+    on Unix-like operating systems and `%APPDIR%\stack` on Windows.
+
+    The location of `config.yaml` is `<XDG_CONFIG_HOME>/stack`. If the
+    `XDG_CONFIG_HOME` environment variable does not exist, the default is
+    `~/.config/stack` on Unix-like operating systems and `%APPDIR%\stack` on
+    Windows.
+
+    This approach treats:
+
+    *   the project-level YAML configuration file that is common to all projects
+        without another such file in their project directory or its ancestor
+        directories as _data_ rather than as part of Stack's own
+        _configuration_;
+
+    *   the snapshots database as essential data rather than as non-essential
+        data that would be part of a _cache_, notwithstanding that Stack will
+        rebuild that database as its contents are needed; and
+
+    *   the Pantry store as essential data rather than as non-essential data
+        that would be part of a _cache_, notwithstanding that Stack will
+        download the package index and rebuild the store if it is absent.
+
+An alternative to the default location of tools such as GHC can be specified
+with the [`local-programs-path`](yaml_configuration.md#local-programs-path)
+configuration option.
+
+The location of the Stack root is reported by command:
+
+~~~text
+stack path --stack-root
+~~~
+
+The full path of Stack's global YAML configuration file is reported by command:
+
+~~~text
+stack path --global-config
+~~~
+
+The location of tools such as GHC for the current platform is reported by
+command:
+
+~~~text
+stack path --programs
+~~~