Merge branch 'master' into fix5866

Author: mpilgrem

.github/workflows/integration-tests.yml

@@ -11,6 +11,11 @@ on:
     - '**'
   workflow_dispatch:
 
+# Stack will use the value of the GH_TOKEN environment variable to authenticate
+# its requests of the GitHub REST API, providing a higher request rate limit.
+env:
+  GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
 # As of 26 December 2022, ubuntu-latest, windows-latest and macos-latest come
 # with Stack 2.9.1. ubuntu-latest and macos-latest come with GHC 9.4.3.
 # windows-latest comes with GHC 9.4.2. windows-latest comes with NSIS 3.08, for

ChangeLog.md

@@ -27,6 +27,9 @@ Other enhancements:
 
 * Better error message if the value of the `STACK_WORK` environment variable or
   `--work-dir` option is not a valid relative path.
+* Stack will use the value of the `GH_TOKEN`, or `GITHUB_TOKEN`, environment
+  variable as credentials to authenticate its GitHub REST API requests.
+
 
 Bug fixes:
 

doc/environment_variables.md

@@ -5,6 +5,22 @@
 The environment variables listed in alphabetal order below can affect how Stack
 behaves.
 
+## `GH_TOKEN` or `GITHUB_TOKEN`
+
+:octicons-tag-24: UNRELEASED
+
+Stack will use the value of the `GH_TOKEN` or, in the alternative,
+`GITHUB_TOKEN` environment variable (if not an empty string) as credentials to
+authenticate its requests of the GitHub REST API, using HTTP 'Basic'
+authentication.
+
+GitHub limits the rate of unauthenticated requests to its API, although most
+users of Stack will not experience that limit from the use of Stack alone. The
+limit for authenticated requests is significantly higher.
+
+For more information about authentication of requests of the GitHub REST API,
+see GitHub's REST API documentation.
+
 ## `HACKAGE_KEY`
 
 [:octicons-tag-24: 2.7.5](https://github.com/commercialhaskell/stack/releases/tag/v2.7.5)

doc/global_flags.md

@@ -118,7 +118,12 @@ Default: `read-write`, if snapshot specified in YAML configuration file;
 `read-only`, if a different snapshot is specified on the command line.
 
 Pass the option `--lock-file <mode>` to specify how Stack interacts with lock
-files. Valid modes are `error-on-write`, `ignore`, `read-only` and `read-write`.
+files. Valid modes are:
+
+* `error-on-write`: Stack reports an error, rather than write a lock file;
+* `ignore`: Stack ignores lock files;
+* `read-only`: Stack only reads lock files; and
+* `read-write`: Stack reads and writes lock files.
 
 ## `--[no-]modify-code-page` flag
 

doc/lock_files.md

@@ -145,30 +145,40 @@ packages:
       sha256: 614bc0cca76937507ea0a5ccc17a504c997ce458d7f2f9e43b15a10c8eaeb033
 ~~~
 
-## Creation
+## Creation procedure
 
 Whenever a project-level configuration file (`stack.yaml`) is loaded, Stack
 checks for a lock file in the same file path, with a `.lock` extension added.
 For example, if you command:
 
 ~~~text
-stack build --stack-yaml my-stack.yaml
+stack --stack-yaml my-stack.yaml build
 ~~~
 
-Stack will use a lock file in the location `my-stack.yaml.lock`. For the rest of
-this document, we'll assume that the files are simply `stack.yaml` and
+or
+
+~~~text
+stack --stack-yaml my-stack.yaml build --dry-run
+~~~
+
+then Stack will use a lock file in the location `my-stack.yaml.lock`. For the
+rest of this document, we'll assume that the files are simply `stack.yaml` and
 `stack.yaml.lock`.
 
-If the lock file does not exist, it will be created by:
+If the lock file does not exist, subject to Stack's
+[`--lock-file`](global_flags.md#-lock-file-option) option, it will be
+created by:
 
 * Loading the `stack.yaml`
 * Loading all snapshot files
 * Completing all missing information
-* Writing out the new `stack.yaml.lock` file
+* Writing out the new `stack.yaml.lock` file to the disk
 
 ## Update procedure
 
-When loading a Stack project all completed package or snapshot locations (even
-when they were completed using information from a lock file) get collected to
-form a new lock file in memory and compare against the one on disk, writing if
-there are any differences.
+Whenever a project-level configuration file (`stack.yaml`) is loaded, all
+completed package or snapshot locations (even those completed using information
+from a lock file) get collected to form a new lock file in memory. Subject to
+Stack's [`--lock-file`](global_flags.md#-lock-file-option) option, that new lock
+file is compared against the one on disk and, if there are any differences,
+written out to the disk.

doc/pantry.md

@@ -90,57 +90,55 @@ There are three types of package locations:
 
 1.  Hackage packages
 2.  Git and Mecurial repositories
-3.  Local or remote archives
+3.  Local or remote archives (such as GitHub archives)
 
 All three types support optional tree metadata to be added, which can be used
 for reproducibility and faster downloads. This information can automatically be
 generated in a [lock file](lock_files.md).
 
 ### Hackage packages
 
-Packages can be stated by a name-version combination. The basic syntax for this
-is:
+A package can be identified by its name, version and Cabal file revision
+number, with revision `0` being the original Cabal file. For example:
 
 ~~~yaml
 extra-deps:
-- acme-missiles-0.3
+- acme-missiles-0.3@rev:0
 ~~~
 
-Using this syntax, the most recent Cabal file revision available will
-be used.
-
-You can specify a specific revision number, with `0` being the original file,
-like this:
+A package name and version only can be stated. Using this syntax, the most
+recent Cabal file revision available in the package index will be used. For
+example:
 
 ~~~yaml
 extra-deps:
-- acme-missiles-0.3@rev:0
+- acme-missiles-0.3
 ~~~
 
-For safer, more reproducible builds, you can optionally specify the SHA256 hash
-of the Cabal file's contents, like this:
+This syntax is often used in practice, but may result in one build differing
+from another, if a new or further Cabal file revision is added to the package
+index between the builds.
+
+As an alternative to specifying the Cabal file revision number, you can specify
+the package name and version with the SHA256 hash of the contents of its Cabal
+file. Doing so is slightly more resilient than using the Cabal file revision
+number, as it does not rely on the correct ordering in the package index.
+For example:
 
 ~~~yaml
 extra-deps:
 - acme-missiles-0.3@sha256:2ba66a092a32593880a87fb00f3213762d7bca65a687d45965778deb8694c5d1
 ~~~
 
-You can optionally also specify the size of the Cabal file in bytes, like this:
+Optionally, you can specify also the size of the Cabal file in bytes. For
+example (where the file size is `631` bytes):
 
 ~~~yaml
 extra-deps:
 - acme-missiles-0.3@sha256:2ba66a092a32593880a87fb00f3213762d7bca65a687d45965778deb8694c5d1,631
 ~~~
 
-!!! note
-
-    Specifying package using SHA256 is slightly more resilient in that it does
-    not rely on correct ordering in the package index, while revision number is
-    likely simpler to use. In practice, both should guarantee equally
-    reproducible build plans.
-
-You can also include the Pantry tree information. The following would be
-generated and stored in the lock file:
+Optionally, you can specify also the Pantry tree information. For example:
 
 ~~~yaml
 - hackage: acme-missiles-0.3@sha256:2ba66a092a32593880a87fb00f3213762d7bca65a687d45965778deb8694c5d1,613
@@ -149,10 +147,17 @@ generated and stored in the lock file:
     sha256: 614bc0cca76937507ea0a5ccc17a504c997ce458d7f2f9e43b15a10c8eaeb033
 ~~~
 
+The SHA256 hash of the contents of the Cabal file and its size in bytes is
+provided in Stack's lock file. For further information, see the
+[lock files](lock_files.md) documentation. The SHA256 hash and file size
+alternative is also what Stack uses when it makes suggestions about missing
+packages.
+
 ### Git and Mercurial repositories
 
-You can give a Git or Mercurial repository at a specific commit, and Stack will
-clone that repository. For example:
+You can specify a Git or Mercurial repository at a specific commit, and Stack
+will clone that repository and, if it has submodules (Git), update the
+repository's submodules. For example:
 
 ~~~yaml
 extra-deps:
@@ -193,19 +198,6 @@ the root of the repository. If you specify a value of `subdirs`, then `'.'` is
 _not_ included by default and needs to be explicitly specified if a required
 package is found in the top-level directory of the repository.
 
-#### GitHub
-
-[:octicons-tag-24: 1.7.1](https://github.com/commercialhaskell/stack/releases/tag/v1.7.1)
-
-You can specify packages from GitHub repository name using `github`. For
-example:
-
-~~~yaml
-extra-deps:
-- github: snoyberg/http-client
-  commit: a5f4f30f01366738f913968163d856366d7e0342
-~~~
-
 #### git-annex
 
 [git-annex](https://git-annex.branchable.com) is not supported. This is because
@@ -225,7 +217,9 @@ following line:
 fonts export-ignore
 ~~~
 
-### Local or remote archives
+### Local or remote archives (such as GitHub archives)
+
+#### Filepaths or URLs to archive files
 
 You can use filepaths referring to local archive files or HTTP or HTTPS URLs
 referring to remote archive files, either tarballs or ZIP files.
@@ -250,3 +244,27 @@ extra-deps:
 - archive: ../acme-missiles-0.3.tar.gz
   sha256: e563d8b524017a06b32768c4db8eff1f822f3fb22a90320b7e414402647b735b
 ~~~
+
+#### GitHub archive files
+
+[:octicons-tag-24: 1.7.1](https://github.com/commercialhaskell/stack/releases/tag/v1.7.1)
+
+You can specify a GitHub respository at a specific commit and Stack will obtain
+from GitHub an archive file of the files in the repository at that point in its
+history. For example:
+
+~~~yaml
+extra-deps:
+- github: snoyberg/http-client
+  commit: a5f4f30f01366738f913968163d856366d7e0342
+~~~
+
+!!! note
+
+    An archive file of the files in a GitHub repository at a point in its
+    history is not the same as a clone of the repository (including its history)
+    and the updating of any submodules. If you need the latter, use the syntax
+    for a [Git repository](pantry.md#git-and-mercurial-repositories).
+
+    If the package fails to build due to missing files, it may be that updated
+    submodules are required.

package.yaml

@@ -1,3 +1,6 @@
+# Hpack >= 0.35.0 is provided by Stack >= 2.9.1.
+spec-version: 0.35.0
+
 name: stack
 version: '2.10.0'
 synopsis: The Haskell Tool Stack
@@ -8,7 +11,7 @@ description: |
   If building a 'stack' executable for distribution, please download the
   source code from <https://github.com/commercialhaskell/stack/releases>
   and build it using Stack itself in order to ensure identical behaviour
-  to official binaries.  This package on Hackage is provided for convenience
+  to official binaries. This package on Hackage is provided for convenience
   and bootstrapping purposes.
   .
   Note that the API for the library is not currently stable, and may
@@ -39,6 +42,8 @@ extra-source-files:
 - test/package-dump/ghc-head.txt
 - src/test/Stack/Untar/test1.tar.gz
 - src/test/Stack/Untar/test2.tar.gz
+# GHC's GHC2021 language extension is supported by GHC >= 9.2.1
+language: GHC2021
 ghc-options:
 - -fwrite-ide-info
 - -hiedir=.hie

src/Control/Concurrent/Execute.hs

@@ -1,5 +1,4 @@
 {-# LANGUAGE NoImplicitPrelude  #-}
-{-# LANGUAGE DeriveDataTypeable #-}
 {-# LANGUAGE RecordWildCards    #-}
 
 -- Concurrent execution with dependencies. Types currently hard-coded for needs

src/Data/Attoparsec/Args.hs

@@ -37,8 +37,8 @@ argsParser mode = many (P.skipSpace *> (quoted <|> unquoted)) <*
   unquoted = P.many1 naked
   quoted = P.char '"' *> str <* P.char '"'
   str = many ( case mode of
-                   Escaping -> escaped <|> nonquote
-                   NoEscaping -> nonquote
+                 Escaping -> escaped <|> nonquote
+                 NoEscaping -> nonquote
              )
   escaped = P.char '\\' *> P.anyChar
   nonquote = P.satisfy (/= '"')

src/Data/Attoparsec/Combinators.hs

@@ -11,8 +11,11 @@ module Data.Attoparsec.Combinators
 import           Stack.Prelude
 
 -- | Concatenate two parsers.
-appending :: (Applicative f, Semigroup a)
-                 => f a -> f a -> f a
+appending ::
+     (Applicative f, Semigroup a)
+  => f a
+  -> f a
+  -> f a
 appending a b = (<>) <$> a <*> b
 
 -- | Alternative parsers.