Prefer 'project package' to 'local package', consistently

Author: mpilgrem

ChangeLog.md

@@ -68,7 +68,7 @@ Other enhancements:
   `1.24.0.0`.
 * Experimental: Add flag `--haddock-for-hackage` to Stack's `build` command
   (including the `haddock` synonym for `build --haddock`) to enable building
-  local packages with flags to generate Haddock documentation, and an archive
+  project packages with flags to generate Haddock documentation, and an archive
   file, suitable for upload to Hackage. The form of the Haddock documentation
   generated for other packages is unaffected.
 * Experimental: Add flag `--documentation` (`-d` for short) to Stack's `upload`
@@ -89,7 +89,7 @@ Other enhancements:
   key is introduced, to allow the notification to be muted if unwanted.
 * Add option `--filter <item>` to Stack's `ls dependencies text` command to
   filter out an item from the results, if present. The item can be `$locals` for
-  all local packages.
+  all project packages.
 * Add option `--snapshot` as synonym for `--resolver`.
 * Add the `config set snapshot` command, corresponding to the
   `config set resolver` command.
@@ -222,8 +222,9 @@ Other enhancements:
   `c2hs`, `cpphs`, `gcc`, `greencard`, `happy`, `hsc2hs`, `hscolour`, `ld`,
   `pkg-config`, `strip` and `tar`. If Cabal uses the program during the
   configuration step, the argument is passed to it.
-* By default all `--PROG-option` options are applied to all local packages. This
-  behaviour can be changed with new configuration option `apply-prog-options`.
+* By default all `--PROG-option` options are applied to all project packages.
+  This behaviour can be changed with new configuration option
+  `apply-prog-options`.
 * Add flag `--[no-]use-root` to `stack script` (default disabled). Used with
   `--compile` or `--optimize`, when enabled all compilation outputs (including
   the executable) are written to a script-specific location in the `scripts`
@@ -243,8 +244,8 @@ Bug fixes:
 * `stack build` with `--file-watch` or `--file-watch-poll` outputs 'pretty'
   error messages, as intended. See
   [#5978](https://github.com/commercialhaskell/stack/issues/5978).
-* `stack build` unregisters any local packages for the sub libraries of a local
-  package that is to be unregistered. See
+* `stack build` unregisters any project packages for the sub libraries of a
+  project package that is to be unregistered. See
   [#6046](https://github.com/commercialhaskell/stack/issues/6046).
 * The warning that sublibrary dependency is not supported is no longer triggered
   by internal libraries.
@@ -731,7 +732,7 @@ Other enhancements:
   affect the Stackage Curator use case, but there is now an additional message
   letting the user know when a previously-failed test case is being rerun.
 
-* Move configure information for local packages back to .stack-work to improve
+* Move configure information for project packages back to .stack-work to improve
   caching. See
   [#4893](https://github.com/commercialhaskell/stack/issues/4893).
 
@@ -917,7 +918,7 @@ Other enhancements:
 
 * Support MX Linux in get-stack.sh. Fixes
   [#4769](https://github.com/commercialhaskell/stack/issues/4769).
-* Defer loading up of files for local packages. This allows us to get
+* Defer loading up of files for project packages. This allows us to get
   plan construction errors much faster, and avoid some unnecessary
   work when only building a subset of packages. This is especially
   useful for the curator use case.

doc/GUIDE.md

@@ -261,10 +261,11 @@ dependencies, and so on. Our value here says to use
 available to Stack). There are a number of values you can use for `resolver`,
 which we'll cover later.
 
-The value of the `packages` key tells Stack which local packages to build. In
-our simple example, we have only a single package in our project, located in the
-same directory, so '`.`' suffices. However, Stack has powerful support for
-multi-package projects, which we'll elaborate on as this guide progresses.
+The value of the `packages` key tells Stack which project packages, located
+locally, to build. In our simple example, we have only a single project package,
+located in the same directory, so '`.`' suffices. However, Stack has powerful
+support for multi-package projects, which we'll elaborate on as this guide
+progresses.
 
 Another file important to the build is `package.yaml`.
 
@@ -404,9 +405,9 @@ stack build
 ~~~
 
 This output means that the `text` package was downloaded, configured, built, and
-locally installed. Once that was done, we moved on to building our local package
-(`helloworld`). At no point did we need to ask Stack to build dependencies — it
-does so automatically.
+locally installed. Once that was done, we moved on to building our project
+package (`helloworld`). At no point did we need to ask Stack to build
+dependencies — it does so automatically.
 
 ### Listing Dependencies
 
@@ -943,18 +944,18 @@ different types of arguments:
   version, e.g. `stack build yesod-bin-1.4.14`.
     * This is almost identical to specifying a package name, except it will (1)
       choose the given version instead of latest, and (2) error out if the given
-      version conflicts with the version of a local package.
+      version conflicts with the version of a project package.
 * The most flexibility comes from specifying individual *components*, e.g.
   `stack build helloworld:test:helloworld-test` says "build the test suite
   component named helloworld-test from the helloworld package."
     * In addition to this long form, you can also shorten it by skipping what
       type of component it is, e.g. `stack build helloworld:helloworld-test`, or
       even skip the package name entirely, e.g. `stack build :helloworld-test`.
 * Finally, you can specify individual *directories* to build to trigger building
-  of any local packages included in those directories or subdirectories.
+  of any project packages included in those directories or subdirectories.
 
 When you give no specific arguments on the command line (e.g., `stack build`),
-it's the same as specifying the names of all of your local packages. If you
+it's the same as specifying the names of all of your project packages. If you
 just want to build the package for the directory you're currently in, you can
 use `stack build .`.
 
@@ -1083,9 +1084,10 @@ modified version of a dependency that hasn't yet been released upstream.
 !!! note
 
     When adding upstream packages directly to your project it is important to
-    distinguish _local packages_ from the upstream _dependency packages_.
-    Otherwise you may have trouble running `stack ghci`. See
-    [stack.yaml documentation](yaml_configuration.md#packages) for more details.
+    distinguish _project packages_ located locally from the upstream
+    _dependency packages_. Otherwise you may have trouble running `stack ghci`.
+    See [stack.yaml documentation](yaml_configuration.md#packages) for more
+    details.
 
 ## Flags and GHC options
 

doc/build_command.md

@@ -63,7 +63,7 @@ run. The running behaviour can be disabled with the `--no-run-tests` flag.
 Similarly, if a benchmark component is targeted, it is built and run unless the
 running behaviour is disabled with the `--no-run-benchmarks` flag.
 
-This ability to specify a component applies only to a local package. With
+This ability to specify a component applies only to a project package. With
 dependencies, Stack will *always* build the library (if present) and all
 executables (if any), and ignore test suites and benchmarks. If you want more
 control over a package, you must add it to your `packages` setting in your
@@ -75,15 +75,15 @@ project-level configuration file (`stack.yaml`).
 supported syntaxes for targets are:
 
 *   *package*, e.g. `stack build foobar`, is the most commonly used target. It
-    will try to find the package in the following locations: local packages,
+    will try to find the package in the following locations: project packages,
     extra deps, snapshots, and package index (e.g. Hackage). If it's found in
     the package index, then the latest version of that package from the index is
     implicitly added to your extra dependencies.
 
-    If the package is a local package, the library and executable components are
-    selected to be built. If the `--test` and `--bench` flags are set, then all
-    of the test suite and benchmark components, respectively, are selected to be
-    built.
+    If the package is a project package, the library and executable components
+    are selected to be built. If the `--test` and `--bench` flags are set, then
+    all of the test suite and benchmark components, respectively, are selected
+    to be built.
 
     If *package* is a GHC boot package (packages that come with GHC and are
     included in GHC's global package database), the behaviour can be complex.
@@ -97,7 +97,7 @@ supported syntaxes for targets are:
     include directly most boot packages but some snapshots may include directly
     some boot packages. In particular, some snapshots include directly `Win32`
     (which is a boot package on Windows) while others do not. For example, if
-    `Cabal` (a boot package) is not a local package or an extra dep, then
+    `Cabal` (a boot package) is not a project package or an extra-dep, then
     `stack build Cabal` with Stackage snapshot LTS Haskell 20.25 will:
 
     * on Windows, try to build the latest version of `Cabal` in the package
@@ -109,7 +109,7 @@ supported syntaxes for targets are:
 *   *package identifier*, e.g. `stack build foobar-1.2.3`, is usually used to
     include specific package versions from the package index.
 
-    If the package name conflicts with that of a local package, then Stack
+    If the package name conflicts with that of a project package, then Stack
     fails with an error.
 
     Otherwise, this is the same as using `stack build foobar` (that is, ignoring
@@ -140,11 +140,11 @@ supported syntaxes for targets are:
          example, `stack build mypackage:mytestsuite`.
 
     *   `:<comp-name>` is a useful shortcut, saying "find the component
-        `<comp-name>` in all of the local packages". This will result in an
+        `<comp-name>` in all of the project packages". This will result in an
         error if more than one package has a component with the specified name.
         To continue the above example, `stack build :mytestsuite`.
 
-*   *directory*, e.g. `stack build foo/bar`, will find all local packages that
+*   *directory*, e.g. `stack build foo/bar`, will find all project packages that
     exist in the given directory hierarchy and then follow the same procedure as
     passing in package names as mentioned above. There's an important caveat
     here: if your directory name is parsed as one of the above target types, it
@@ -153,10 +153,10 @@ supported syntaxes for targets are:
 
     !!! note
 
-        `stack build .` will target local packages in the current working
+        `stack build .` will target project packages in the current working
         directory or its subdirectories.
 
-`stack build` with no targets specified will build all local packages.
+`stack build` with no targets specified will build all project packages.
 
 For further information about available targets, see the
 [`stack ide targets` command](ide_command.md).
@@ -267,11 +267,11 @@ Unset the flag to disable building Haddock documentation for dependencies.
 
 Default: Disabled
 
-Set the flag to build local packages with flags to generate Haddock
+Set the flag to build project packages with flags to generate Haddock
 documentation suitable for upload to Hackage. The form of the Haddock
 documentation generated for other packages is unaffected.
 
-For each local package:
+For each project package:
 
 * the generated Haddock documentation files are in directory
   `doc\html\<package_version>-docs\`, relative to Stack's dist work directory
@@ -383,7 +383,7 @@ particular when they depend on external data files.
 ### `--skip` option
 
 `stack build --skip <component>` skips building the specified components of a
-local package. It allows you to skip test suites and benchmark without
+project package. It allows you to skip test suites and benchmark without
 specifying other components (e.g. `stack test --skip long-test-suite` will run
 the tests without the `long-test-suite` test suite). Be aware that skipping
 executables won't work the first time the package is built due to an issue in
@@ -414,7 +414,8 @@ using events to determine if a file has changed.
 [:octicons-tag-24: 2.5.1](https://github.com/commercialhaskell/stack/releases/tag/v2.5.1)
 
 Pass the flag to rebuild your project every time any local file changes (from
-project packages or from local dependencies). See also the `--file-watch` flag.
+project packages or from dependencies located locally). See also the
+`--file-watch` flag.
 
 ## Controlling what happens after building
 
@@ -574,7 +575,7 @@ used by Cabal during the configuration step, you could command
 to `happy` its `--ghc` flag.
 
 By default, all and any `--PROG-option` options on Stack's command line are
-applied to all local packages (targets or otherwise). This behaviour can be
+applied to all project packages (targets or otherwise). This behaviour can be
 changed. See the
 [`apply-prog-options`](yaml_configuration.md#apply-prog-options) configuration
 option.

doc/config_command.md

@@ -23,7 +23,8 @@ stack config env [--[no-]locals] [--[no-]ghc-package-path] [--[no-]stack-exe]
 `stack config env` outputs a script that sets or unsets environment variables
 for a Stack environment. Flags modify the script that is output:
 
-* `--[no-]locals` (enabled by default) include/exclude local package information
+* `--[no-]locals` (enabled by default) include/exclude project package
+  information
 * `--[no-]ghc-package-path` (enabled by default) set `GHC_PACKAGE_PATH`
   environment variable or not
 * `--[no-]stack-exe` (enabled by default) set `STACK_EXE` environment variable

doc/faq.md

@@ -427,10 +427,9 @@ doesn't lead to a rebuild, add the `-fforce-recomp` flag to your
 
 ## Why doesn't Stack apply my `--ghc-options` to my dependencies?
 
-By default, Stack applies command line GHC options only to local packages (these
-are all the packages that are specified in the `packages` section of your
-`stack.yaml` file). For an explanation of this choice see this discussion on
-issue
+By default, Stack applies command line GHC options only to
+[project packages](yaml_configuration.md#packages). For an explanation of this
+choice see this discussion on issue
 [#827](https://github.com/commercialhaskell/stack/issues/827#issuecomment-133263678).
 
 If you still want to set specific GHC options for a dependency, use the

doc/global_flags.md

@@ -54,9 +54,10 @@ further information see `stack --docker-help` or the
 
 Default: Dump warning logs
 
-Enables/disables the dumping of the build output logs for local packages to the
-console. For further information, see the documentation for the corresponding
-non-project specific configuration [option](yaml_configuration.md#dump-logs).
+Enables/disables the dumping of the build output logs for project packages to
+the console. For further information, see the documentation for the
+corresponding non-project specific configuration
+[option](yaml_configuration.md#dump-logs).
 
 ## `--extra-include-dirs` option
 

doc/glossary.md

@@ -12,6 +12,7 @@ The following terms are used in Stack's documentation.
 |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.|
+|dependency         |A Haskell package other than a project package and on which a project package depends (directly or indirectly), located locally or elsewhere.|
 |Docker             |A [platform](https://www.docker.com/) for developing,  shipping, and running applications. It can package and run an application in a loosely isolated environment called a _container_.|
 |Emacs              |[GNU Emacs](https://www.gnu.org/software/emacs/), an extensible, customisable text editor.|
 |extra-deps         |Packages (one version of each) that add to, or amend, those specified in a snapshot. Named after a key used in `stack.yaml` files.|
@@ -40,7 +41,8 @@ The following terms are used in Stack's documentation.
 |`package.yaml`     |A file that describes a package in the Hpack format.      |
 |Pantry             |A library for content-addressable Haskell package management, provided by the [`pantry` package](https://hackage.haskell.org/package/pantry). A dependency of Stack.|
 |PATH               |The `PATH` environment variable, specifying a list of directories searched for executable files.|
-|project            |A Stack project is a local directory that contains a project-level configuration file (`stack.yaml`). A project may relate to more than one local package.|
+|project            |A Stack project is a local directory that contains a project-level configuration file (`stack.yaml`). A project may relate to more than one project package.|
+|project package    |A Haskell package that is part of a project and located locally. Distinct from a dependency located locally.|
 |PVP                |The Haskell [Package Versioning Policy](https://pvp.haskell.org/), which tells developers of libraries how to set their version numbers.|
 |REPL               |An interactive (run-eval-print loop) programming environment.|
 |resolver           |A synonym for snapshot.                                   |

doc/hpc_command.md

@@ -90,7 +90,7 @@ This report will consider all test results as well as the newly generated
 
 `stack test --coverage` is quite streamlined for the following use-case:
 
-1.  You have test suites which exercise your local packages.
+1.  You have test suites which exercise your project packages.
 
 2.  These test suites link against your library, rather than building the
     library directly. Coverage information is only given for libraries, ignoring
@@ -119,12 +119,12 @@ When your project has these properties, you will get the following:
 Most users can get away with just understanding the above documentation.
 However, advanced users may want to understand exactly how `--coverage` works:
 
-1. The GHC option `-fhpc` gets passed to all local packages.  This tells GHC to
+1. The GHC option `-fhpc` gets passed to all project packages. This tells GHC to
    output executables that track coverage information and output them to `.tix`
    files. `the-exe-name.tix` files will get written to the working directory of
    the executable.
 
-   When switching on this flag, it will usually cause all local packages to be
+   When switching on this flag, it will usually cause all project packages to be
    rebuilt (see issue
    [#1940](https://github.com/commercialhaskell/stack/issues/1940)).
 
@@ -145,7 +145,7 @@ However, advanced users may want to understand exactly how `--coverage` works:
    the modules compiled in the `executable` or `test-suite` stanza of your Cabal
    file. This makes it possible to directly union multiple `*.tix` files from
    different executables (assuming they are using the exact same versions of the
-   local packages).
+   project packages).
 
    If there is enough popular demand, it may be possible in the future to give
    coverage information for modules that are compiled directly into the

doc/ide_command.md

@@ -20,7 +20,7 @@ commands.
 stack ide packages [--stdout] [--cabal-files]
 ~~~
 
-`stack ide packages` lists all available local packages that are loadable.
+`stack ide packages` lists all available project packages that are loadable.
 
 By default:
 

doc/lock_files.md

@@ -21,7 +21,7 @@ project, snapshot packages and snapshots themselves so that:
 
 * These files can be stored in source control
 * Users on other machines can reuse these lock files and get identical build
-  plans given that the used local packages and local snapshots are the same on
+  plans given that the used project packages and local snapshots are the same on
   those machines
 * Rerunning `stack build` in the future is deterministic in the build plan, not
   depending on mutable state in the world like Hackage revisions