Eliminate use of ambiguous term 'build tool'

Author: mpilgrem

CONTRIBUTING.md

@@ -735,7 +735,7 @@ Stack can be built with Stack (which is recommended) or with Cabal (the tool).
     ~~~
 
 A cradle is not committed to Stack's repository because it imposes a choice of
-build tool.
+tool used for building.
 
 ## Dev Containers
 

ChangeLog.md

@@ -1235,9 +1235,9 @@ Behavior changes:
   [help file](https://github.com/commercialhaskell/stack-templates/blob/master/STACK_HELP.md)
   with more information on how to discover templates. See:
   [#4039](https://github.com/commercialhaskell/stack/issues/4039)
-* Build tools are now handled in a similar way to `cabal-install`. In
-  particular, for legacy `build-tools` fields, we use a hard-coded
-  list of build tools in place of looking up build tool packages in a
+* Tools used during building ('build tools') are now handled in a similar way to
+  `cabal-install`. In particular, for legacy `build-tools` fields, we use a
+  hard-coded list of build tools in place of looking up build tool packages in a
   tool map. This both brings Stack's behavior closer into line with
   `cabal-install`, avoids some bugs, and opens up some possible
   optimizations/laziness. See:

doc/GUIDE.md

@@ -2,12 +2,13 @@
 
 # User guide (introductory)
 
-Stack is a modern, cross-platform build tool for Haskell code.
+Stack is a modern, cross-platform tool for building Haskell code.
 
 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).
+experience with the Haskell packaging system or other tools used for, or during,
+building Haskell code. 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.
@@ -16,9 +17,10 @@ Some of Stack's features will not be needed regularly or by all users. See the
 
 Stack handles the management of your toolchain (including GHC — the Glasgow
 Haskell Compiler — and, for Windows users, MSYS2), building and registering
-libraries, building build tool dependencies, and more. While it can use existing
-tools on your system, Stack has the capacity to be your one-stop shop for all
-Haskell tooling you need. This guide will follow that Stack-centric approach.
+libraries, building dependencies on tools used during building, and more. While
+it can use existing tools on your system, Stack has the capacity to be your
+one-stop shop for all Haskell tooling you need. This guide will follow that
+Stack-centric approach.
 
 ### What makes Stack special?
 
@@ -45,8 +47,8 @@ Stack directories. Stack-built files generally go in either the Stack root
 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).
+version of GHC or interfere with packages installed by other tools used for
+building Haskell code, such as Cabal (the tool).
 
 ## Downloading and Installation
 

doc/README.md

@@ -277,11 +277,11 @@ explained in the [glossary](glossary.md).
 
 ## Why Stack?
 
-Stack is a build tool for Haskell designed to answer the needs of Haskell users,
-both new and experienced. It has a strong focus on reproducible build plans,
-multi-package projects, and a consistent, easy-to-learn set of Stack commands.
-It also aims to provide the customizability and power that experienced
-developers need.
+Stack is a tool for building Haskell code designed to answer the needs of
+Haskell users, both new and experienced. It has a strong focus on reproducible
+build plans, multi-package projects, and a consistent, easy-to-learn set of
+Stack commands. It also aims to provide the customizability and power that
+experienced developers need.
 
 Stack does not stand alone. It is built on the great work provided by:
 
@@ -294,9 +294,9 @@ Stack does not stand alone. It is built on the great work provided by:
 
     !!! info
 
-        Cabal is also the name of another build tool, provided by the
-        `cabal-install` package. This guide distinguishes between them by Cabal
-        (the library) and Cabal (the tool).
+        Cabal is also the name of another tool used for building Haskell code,
+        provided by the `cabal-install` package. This guide distinguishes
+        between them by Cabal (the library) and Cabal (the tool).
 
 * The __Hackage Haskell Package Repository__, a
   [repository](https://hackage.haskell.org/) of Haskell packages providing

doc/Stack_and_VS_Code.md

@@ -22,13 +22,13 @@ extension's settings (under 'Haskell: Manage HLS') allow a user to specify
 that the extension should use a separate application,
 [GHCup](https://www.haskell.org/ghcup/), to download and install the versions of
 HLS that it needs. GHCup can download and install things other than HLS,
-including GHC, MSYS2 (on Windows), Cabal (a build tool), and Stack itself. GHCup
-can also update itself. On Windows, GHCup has the capability of using the
-Stack-supplied MSYS2 rather than installing a duplicate copy. Cabal (the build
-tool), like Stack, depends on the Cabal (the library). Cabal (the tool), unlike
-Stack, does not have the capability to automatically install necessary versions
-of GHC, and (as well as supporting the extension) GHCup fills a important gap
-for users of the Cabal tool.
+including GHC, MSYS2 (on Windows), Cabal (a tool for building Haskell code), and
+Stack itself. GHCup can also update itself. On Windows, GHCup has the capability
+of using the Stack-supplied MSYS2 rather than installing a duplicate copy. Cabal
+(the tool), like Stack, depends on the Cabal (the library). Cabal (the tool),
+unlike Stack, does not have the capability to automatically install necessary
+versions of GHC, and (as well as supporting the extension) GHCup fills a
+important gap for users of the Cabal tool.
 
 If the VS Code extension is set not to use GHCup, its user needs to ensure that
 each version of HLS that the extension needs is on the PATH.
@@ -78,8 +78,8 @@ different version of GHC, then GHCup must be used to install it (if GHCup has
 not already installed that version). For example, to use `snapshot: lts-22.21`
 (GHC 9.6.5), the command `ghcup install ghc 9.6.5` must have been used to
 install GHC 9.6.5. That may be a minor inconvenience for some people, as one the
-primary benefits of Stack over other Haskell build tools has been that Stack
-automatically ensures that the necessary version of GHC is available.
+primary benefits of Stack over other tools for building Haskell code has been
+that Stack automatically ensures that the necessary version of GHC is available.
 
 ### Workaround #2
 

doc/build_overview.md

@@ -230,8 +230,9 @@ installed in this database will never need to be rebuilt.
 * Apply flags, platform, and actual GHC version to resolve
   dependencies in any package analyzed
 * Include all library dependencies for all enabled components
-* Include all build tool dependencies for all enabled components
-  (using the fun backwards compat logic for `build-tools`)
+* Include all dependencies for tools used during building ('build tools') for
+  all enabled components (using the fun backwards compat logic for
+  `build-tools`)
 * Apply the logic recursively to come up with a full build plan
 * If a task depends exclusively on immutable packages, mark it as
   immutable. Otherwise, it's mutable. The former go into the snapshot

doc/dev_containers.md

@@ -124,8 +124,8 @@ The
 and the
 [Haskell extension](https://marketplace.visualstudio.com/items?itemName=haskell.haskell)
 are only available in the default Dev Container. In order to use the Haskell
-extension, you must first configure the project for the build tool of your
-choice.
+extension, you must first configure the project for the tool used for building
+of your choice.
 
 <!--
 **Stack**

doc/faq.md

@@ -239,17 +239,18 @@ with the various requirements (version, architecture) that your project needs.
 See issue [#420](https://github.com/commercialhaskell/stack/issues/420) for a
 detailed discussion of Stack's behavior when `system-ghc` is enabled.
 
-## How do I get extra build tools?
+## How do I get extra tools used during building?
 
-Stack will automatically install build tools required by your packages or their
-dependencies, in particular [Alex](https://hackage.haskell.org/package/alex) and
+Stack will automatically install tools used during building required by your
+packages or their dependencies, in particular
+[Alex](https://hackage.haskell.org/package/alex) and
 [Happy](https://hackage.haskell.org/package/happy).
 
 !!! note
 
     This works when using LTS or nightly snapshots, not with GHC or custom
-    snapshots. You can manually install build tools by running, e.g.,
-    `stack build alex happy`.
+    snapshots. You can manually install tools used during building by running,
+    e.g., `stack build alex happy`.
 
 ## How does Stack choose which snapshot to use when creating a new configuration file?
 

doc/glossary.md

@@ -8,7 +8,7 @@ The following terms are used in Stack's documentation.
 |-------------------|----------------------------------------------------------|
 |Cabal              |The Haskell Common Architecture for Building Applications and Libraries, provided by the [`Cabal` package](https://hackage.haskell.org/package/Cabal). Also referred to as Cabal (the library) to distinguish it from Cabal (the tool).|
 |Cabal file|A file containing a [package description](https://cabal.readthedocs.io/en/stable/cabal-package.html) used by Cabal, named `<package_name>.cabal`.|
-|Cabal (the tool)|The Haskell build tool provided by the [`cabal-install` package](https://hackage.haskell.org/package/cabal-install).|
+|Cabal (the tool)|The Haskell tool used for building provided by the [`cabal-install` package](https://hackage.haskell.org/package/cabal-install).|
 |CI                 |Continuous integration.                                   |
 |CMake              |A [system](https://cmake.org/) for managing build processes.|
 |`config.yaml`      |A global and non-project-specific configuration file used by Stack.|

doc/install_and_upgrade.md

@@ -20,11 +20,11 @@ GitHub repository.
     using the separate [GHCup](https://www.haskell.org/ghcup/) installer for
     Haskell-related tools. GHCup provides Stack for some combinations of machine
     architecture and operating system not provided elsewhere. Unlike Stack,
-    other build tools do not automatically install GHC. GHCup can be used to
-    install GHC for those other tools. By default, the script to install GHCup
-    (which can be run more than once) also configures Stack so that if Stack
-    needs a version of GHC, GHCup takes over obtaining and installing that
-    version.
+    other tools used for building Haskell code do not automatically install GHC.
+    GHCup can be used to install GHC for those other tools. By default, the
+    script to install GHCup (which can be run more than once) also configures
+    Stack so that if Stack needs a version of GHC, GHCup takes over obtaining
+    and installing that version.
 
 !!! info "Releases on GitHub"
 

doc/maintainers/archive/releases.md

@@ -233,7 +233,7 @@ Now continue to the **General Windows setup** subsection below.
    git config --global user.name "Emanuel Borsboom"
    ~~~
 
-10. Install build tools and dependencies packages
+10. Install tools used during building and dependencies packages
 
     ~~~text
     sudo apt-get install -y g++ gcc libc6-dev libffi-dev libgmp-dev make xz-utils zlib1g-dev git gnupg

doc/stack_yaml_vs_cabal_package_file.md

@@ -29,8 +29,8 @@ file and a package description file.
 
 ## Package versus project
 
-Stack is a build tool and it uses Cabal, a build system. Cabal defines the
-concept of a _package_. A package has:
+Stack is a tool for building Haskell code and it uses Cabal, a build system.
+Cabal defines the concept of a _package_. A package has:
 
 * A name and version
 * optionally, one library