Merge branch 'stable' into rc/v2.15

Author: mpilgrem

doc/maintainers/self-hosted_runners.md

@@ -6,19 +6,22 @@
 The `linux-arm64` job of the `integration-tests.yml` workflow runs on a
 self-hosted runner for Linux and ARM64.
 
-The basic setup is:
+The current basic setup is:
 
 * FP Complete has an Oracle Cloud account that provides a free tier that
   includes a really powerful ARM64 machine;
 * within Oracle Cloud, FP Complete are running an Ubuntu/ARM64 instance; and
 * on that instance, FP Complete are running the GitHub Runner software.
 
+The runner name is `stack-github-action3` and the machine name is
+`stack-github-action3`.
+
 Occasionally Oracle will turn off the machine because:
 
 * Oracle thinks it is not being used (because of the free tier); and/or
 * other things, like disk space filling up.
 
-## Managing the runner
+## Managing the `stack-github-action3` runner
 
 With the appropriate authority installed on the server, the runner can be
 managed remotely using SSH, with command `ssh [email protected]`.
@@ -28,3 +31,24 @@ is for filesystem `/dev/sda1`.
 
 If the available space is low, that may be due to unncessary GHC versions
 installed in Stack's `programs` directory.
+
+## The `ghc-arm-5` runner
+
+From 9 February 2024, the Haskell Foundation sought to provide an alternative
+runner named `ghc-arm-5` but that was based on NixOS and proved to be
+incompatible.
+
+## Alternatives to the self-hosted runners
+
+One alternative to the self-hosted runners is to build statically-linked Stack
+executables for Linux/AArch64 on macOS/AArch64. This can be done thanks to
+the multi-architecture Docker images built and published by Olivier Benz, at
+https://gitlab.com/benz0li/ghc-musl.
+
+GitHub provides a GitHub-hosted macOS/AArch64 runner (`macOS-14`).
+Unfortunately, that is macOS/M1 and the M1 machine architecture does not support
+nested virtualisation. This rules out using Docker, as the runner is itself a
+virtual machine.
+
+However, this solution can be applied locally and the build outputs for the
+Linux/AArch64 platform added manually to the result of the GitHub workflow.

doc/stack_root.md

@@ -166,9 +166,18 @@ it, Stack will recreate the contents of the directory.
 
 ### `pantry\hackage` directory
 
-This contains the package index. If the contents of the directory are deleted,
-and Stack needs to consult the package index, Stack will seek to download the
-latest package index.
+This contains a local cache of the package index. If the contents of the
+directory are deleted, and Stack needs to consult the package index, Stack will
+seek to download the latest package index.
+
+!!! info
+
+    Stack depends on package `pantry` which, in turn, depends on package
+    `hackage-security`. The latter handles the local cache of the package index.
+    The type `CacheLayout` represents the location of the files that are cached.
+    `pantry` uses `cabalCacheLayout :: CacheLayout`, the layout that Cabal (the
+    tool) uses. That is what specifies the names of the files used to cache the
+    package index, including `00-index.tar` and `00-index.tar.gz`.
 
 ### `pantry` directory