Re #6920 Document the compiler tools directory in the Stack root

Author: mpilgrem

doc/commands/build_command.md

@@ -1026,8 +1026,10 @@ to Stack's local binary directory (see `stack path --local-bin`). The
 Default: Disabled
 
 Set the flag to enable copying of built executable files (binaries) of targets
-to Stack's compiler tools binary directory (see
-`stack path --compiler-tools-bin`).
+to Stack's
+[compiler tools directory](../topics/stack_root.md#compiler-tools-directory-optional)
+for the specified compiler version (see Stack's
+[`path --compiler-tools-bin` command](path_command.md)).
 
 ### `--coverage` flag
 

doc/commands/path_command.md

@@ -21,7 +21,7 @@ Pass the following flags for information about specific files or locations:
 |--bin-path             |The PATH in the [Stack environment](../topics/stack_environment.md).|
 |--compiler-bin         |The directory containing the GHC executable.          |
 |--compiler-exe         |The GHC executable.                                   |
-|--compiler-tools-bin   |The directory containing binaries specific to a particular compiler.|
+|--compiler-tools-bin   |The [compiler tools directory](../topics/stack_root.md#compiler-tools-directory-optional) for the specified compiler version.|
 |--config-location      |Stack's project-level configuration file (`stack.yaml`, by default).|
 |--dist-dir             |The dist work directory, relative to the package directory.|
 |--extra-include-dirs   |Extra include directories.                            |
@@ -36,11 +36,11 @@ Pass the following flags for information about specific files or locations:
 |--local-install-root   |The root directory for local project installation.    |
 |--local-pkg-db         |The local package database.                           |
 |--programs             |The root directory for GHC and other Stack-supplied tools.|
-|--project-root         |The project root directory.|
+|--project-root         |The project root directory.                           |
 |--snapshot-doc-root    |The root directory for snapshot documentation.        |
 |--snapshot-install-root|The root directory for snapshot installation.         |
 |--snapshot-pkg-db      |The snapshot package database.                        |
-|--stack-root           |The Stack root.                                       |
+|--stack-root           |The [Stack root](../topics/stack_root.md).            |
 
 The command also accepts flags and options of the
 [`stack build`](build_command.md#flags-affecting-ghcs-behaviour) command that

doc/topics/stack_environment.md

@@ -45,29 +45,35 @@ root directory.
 
 ## The compiler tools directory
 
-Stack creates, in the [Stack root](stack_root.md), a compiler tools directory
-for the specified version of GHC (when the directory is required). Command
-[`stack path --compiler-tools-bin`](../commands/path_command.md) to see
-that directory.
+When the directory is required, Stack creates, in the
+[Stack root](stack_root.md#compiler-tools-directory-optional), a compiler tools
+directory for the specified compiler version. Command
+[`stack path --compiler-tools-bin`](../commands/path_command.md) to see that
+directory.
 
 !!! info
 
     Stack's
     [`build` command](../commands/build_command.md#-no-copy-compiler-tool-flag)
     can be configured to install built executable files of project packages into
-    the compiler tools directory.
+    the
+    [compiler tools directory](stack_root.md#compiler-tools-directory-optional)
+    for the specified compiler version.
 
 !!! info
 
-    If you wish to override a tool that is included in the specified compiler's
-    binary directory, put a copy of the alternative tool (or a link to it) in
-    the compiler tools directory.
+    If you wish to override a tool that is co-located with the specified
+    compiler's executable file, put a copy of the alternative tool (or a link to
+    it) in the
+    [compiler tools directory](stack_root.md#compiler-tools-directory-optional)
+    for the specified compiler version.
 
 ## The compiler binary's directory
 
-The directory in which the GHC binary that will be used by Stack is located.
-Command [`stack path --compiler-bin`](../commands/path_command.md) to see
-that directory.
+The directory in which the GHC executable file (binary) that will be used by
+Stack is located. Command
+[`stack path --compiler-bin`](../commands/path_command.md) to see that
+directory.
 
 ## GHC's MinGW `bin` directory (Windows only)
 

doc/topics/stack_root.md

@@ -191,6 +191,27 @@ default, in the Stack root.
 If the work directory is deleted, and Stack needs that work directory, then
 Stack will recreate it.
 
+### `compiler-tools` directory (optional)
+
+When it exists, this contains a directory for the platform. That directory
+contains (if it has been created) a directory for a compiler version
+that, in turn, contains a `bin` directory (the compiler tools directory for that
+compiler version).
+
+If the compiler tools directory for a specified compiler version does not exist,
+and Stack needs that directory, then Stack will create it.
+
+In the [Stack environment](stack_environment.md#the-compiler-tools-directory),
+the compiler tools directory for the specified compiler version is on the PATH.
+
+For further information see:
+
+* The [Stack environment](stack_environment.md#the-compiler-tools-directory);
+* Stack's [`path --compiler-tools-bin` command](../commands/path_command.md);
+  and
+* Stack's
+  [`build --copy-compiler-tool` command](../commands/build_command.md#-no-copy-compiler-tool-flag).
+
 ### `global-project` directory
 
 This contains: