adding py-pyspy package

.devcontainer/devcontainer.json

@@ -1,4 +0,0 @@
-{
-  "image": "ghcr.io/spack/ubuntu20.04-runner-amd64-gcc-11.4:2023.08.01",
-  "postCreateCommand": "./.devcontainer/postCreateCommand.sh"
-}

.devcontainer/postCreateCommand.sh

@@ -1,20 +0,0 @@
-#!/bin/bash
-
-# Load spack environment at terminal startup
-cat <<EOF >> /root/.bashrc
-. /workspaces/spack/share/spack/setup-env.sh
-EOF
-
-# Load spack environment in this script
-. /workspaces/spack/share/spack/setup-env.sh
-
-# Ensure generic targets for maximum matching with buildcaches
-spack config --scope site add "packages:all:require:[target=x86_64_v3]"
-spack config --scope site add "concretizer:targets:granularity:generic"
-
-# Find compiler and install gcc-runtime
-spack compiler find --scope site
-
-# Setup buildcaches
-spack mirror add --scope site develop https://binaries.spack.io/develop
-spack buildcache keys --install --trust

.github/pull_request_template.md

@@ -1,6 +0,0 @@
-<!--  
-Remember that `spackbot` can help with your PR in multiple ways:
-- `@spackbot help` shows all the commands that are currently available
-- `@spackbot fix style` tries to push a commit to fix style issues in this PR
-- `@spackbot re-run pipeline` runs the pipelines again, if you have write access to the repository 
--->

.github/workflows/audit.yaml

@@ -22,8 +22,8 @@ jobs:
       matrix:
         operating_system: ["ubuntu-latest", "macos-latest"]
     steps:
-    - uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+    - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # @v2
-    - uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d
+    - uses: actions/setup-python@65d7f2d534ac1bc67fcd62888c5f4f3d2cb2b236 # @v2
       with:
         python-version: ${{inputs.python_version}}
     - name: Install Python packages
@@ -43,9 +43,7 @@ jobs:
           . share/spack/setup-env.sh
           $(which spack) audit packages
           $(which spack) audit externals
-    - uses: codecov/codecov-action@c16abc29c95fcf9174b58eb7e1abf4c866893bc8
+    - uses: codecov/codecov-action@eaaf4bedf32dbdc6b720b63067d99c4d77d6047d # @v2.1.0
       if: ${{ inputs.with_coverage == 'true' }}
       with:
         flags: unittests,audits
-        token: ${{ secrets.CODECOV_TOKEN }}
-        verbose: true

.github/workflows/bootstrap.yml

@@ -24,7 +24,7 @@ jobs:
               make patch unzip which xz python3 python3-devel tree \
               cmake bison bison-devel libstdc++-static
       - name: Checkout
-        uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
         with:
           fetch-depth: 0
       - name: Setup non-root user
@@ -62,7 +62,7 @@ jobs:
               make patch unzip xz-utils python3 python3-dev tree \
               cmake bison
       - name: Checkout
-        uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
         with:
           fetch-depth: 0
       - name: Setup non-root user
@@ -99,7 +99,7 @@ jobs:
               bzip2 curl file g++ gcc gfortran git gnupg2 gzip \
               make patch unzip xz-utils python3 python3-dev tree
       - name: Checkout
-        uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
         with:
           fetch-depth: 0
       - name: Setup non-root user
@@ -133,7 +133,7 @@ jobs:
               make patch unzip which xz python3 python3-devel tree \
               cmake bison
       - name: Checkout
-        uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
         with:
           fetch-depth: 0
       - name: Setup repo
@@ -158,8 +158,8 @@ jobs:
         run: |
           brew install cmake bison@2.7 tree
       - name: Checkout
-        uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
-      - uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d
+      - uses: actions/setup-python@65d7f2d534ac1bc67fcd62888c5f4f3d2cb2b236 # @v2
         with:
           python-version: "3.12"
       - name: Bootstrap clingo
@@ -182,7 +182,7 @@ jobs:
         run: |
           brew install tree
       - name: Checkout
-        uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
       - name: Bootstrap clingo
         run: |
           set -ex
@@ -207,7 +207,7 @@ jobs:
     runs-on: ubuntu-20.04
     steps:
       - name: Checkout
-        uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
         with:
           fetch-depth: 0
       - name: Setup repo
@@ -250,7 +250,7 @@ jobs:
               bzip2 curl file g++ gcc patchelf gfortran git gzip \
               make patch unzip xz-utils python3 python3-dev tree
       - name: Checkout
-        uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
         with:
           fetch-depth: 0
       - name: Setup non-root user
@@ -287,7 +287,7 @@ jobs:
               make patch unzip xz-utils python3 python3-dev tree \
               gawk
       - name: Checkout
-        uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
         with:
           fetch-depth: 0
       - name: Setup non-root user
@@ -320,7 +320,7 @@ jobs:
           # Remove GnuPG since we want to bootstrap it
           sudo rm -rf /usr/local/bin/gpg
       - name: Checkout
-        uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
       - name: Bootstrap GnuPG
         run: |
           source share/spack/setup-env.sh
@@ -338,7 +338,7 @@ jobs:
           # Remove GnuPG since we want to bootstrap it
           sudo rm -rf /usr/local/bin/gpg
       - name: Checkout
-        uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
       - name: Bootstrap GnuPG
         run: |
           source share/spack/setup-env.sh

.github/workflows/build-containers.yml

@@ -55,9 +55,9 @@ jobs:
     if: github.repository == 'spack/spack'
     steps:
       - name: Checkout
-        uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # @v2
 
-      - uses: docker/metadata-action@8e5442c4ef9f78752691e2d8f8d19755c6f78e81
+      - uses: docker/metadata-action@96383f45573cb7f253c731d3b3ab81c87ef81934
         id: docker_meta
         with:
           images: |
@@ -96,10 +96,10 @@ jobs:
         uses: docker/setup-qemu-action@68827325e0b33c7199eb31dd4e31fbe9023e06e3
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@2b51285047da1547ffb1b2203d8be4c0af6b1f20
+        uses: docker/setup-buildx-action@f95db51fddba0c2d1ec667646a06c2ce06100226
 
       - name: Log in to GitHub Container Registry
-        uses: docker/login-action@e92390c5fb421da1463c202d546fed0ec5c39f20
+        uses: docker/login-action@343f7c4344506bcbf9b4de18042ae17996df046d
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -107,16 +107,18 @@ jobs:
 
       - name: Log in to DockerHub
         if: github.event_name != 'pull_request'
-        uses: docker/login-action@e92390c5fb421da1463c202d546fed0ec5c39f20
+        uses: docker/login-action@343f7c4344506bcbf9b4de18042ae17996df046d
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Build & Deploy ${{ matrix.dockerfile[0] }}
-        uses: docker/build-push-action@2cdde995de11925a030ce8070c3d77a52ffcf1c0
+        uses: docker/build-push-action@0565240e2d4ab88bba5387d719585280857ece09
         with:
           context: dockerfiles/${{ matrix.dockerfile[0] }}
           platforms: ${{ matrix.dockerfile[1] }}
           push: ${{ github.event_name != 'pull_request' }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
           tags: ${{ steps.docker_meta.outputs.tags }}
           labels: ${{ steps.docker_meta.outputs.labels }}

.github/workflows/ci.yaml

@@ -18,7 +18,6 @@ jobs:
   prechecks:
     needs: [ changes ]
     uses: ./.github/workflows/valid-style.yml
-    secrets: inherit
     with:
       with_coverage: ${{ needs.changes.outputs.core }}
   all-prechecks:
@@ -36,12 +35,12 @@ jobs:
       core: ${{ steps.filter.outputs.core }}
       packages: ${{ steps.filter.outputs.packages }}
     steps:
-      - uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # @v2
         if: ${{ github.event_name == 'push' }}
         with:
           fetch-depth: 0
             # For pull requests it's not necessary to checkout the code
-      - uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36
+      - uses: dorny/paths-filter@4512585405083f25c027a35db413c2b3b9006d50
         id: filter
         with:
           # See https://github.com/dorny/paths-filter/issues/56 for the syntax used below
@@ -71,17 +70,14 @@ jobs:
     if: ${{ github.repository == 'spack/spack' && needs.changes.outputs.bootstrap == 'true' }}
     needs: [ prechecks, changes ]
     uses: ./.github/workflows/bootstrap.yml
-    secrets: inherit
   unit-tests:
     if: ${{ github.repository == 'spack/spack' && needs.changes.outputs.core == 'true' }}
     needs: [ prechecks, changes ]
     uses: ./.github/workflows/unit_tests.yaml
-    secrets: inherit
   windows:
     if: ${{ github.repository == 'spack/spack' && needs.changes.outputs.core == 'true' }}
     needs: [ prechecks ]
     uses: ./.github/workflows/windows_python.yml
-    secrets: inherit
   all:
     needs: [ windows, unit-tests, bootstrap ]
     runs-on: ubuntu-latest

.github/workflows/nightly-win-builds.yml

@@ -14,10 +14,10 @@ jobs:
   build-paraview-deps:
     runs-on: windows-latest
     steps:
-    - uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+    - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
       with:
         fetch-depth: 0
-    - uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d
+    - uses: actions/setup-python@65d7f2d534ac1bc67fcd62888c5f4f3d2cb2b236
       with:
         python-version: 3.9
     - name: Install Python packages

.github/workflows/style/requirements.txt

@@ -1,7 +1,7 @@
-black==24.3.0
+black==23.11.0
-clingo==5.7.1
+clingo==5.6.2
-flake8==7.0.0
+flake8==6.1.0
-isort==5.13.2
+isort==5.12.0
-mypy==1.8.0
+mypy==1.6.1
 types-six==1.16.21.9
-vermin==1.6.0
+vermin==1.5.2

.github/workflows/unit_tests.yaml

@@ -51,10 +51,10 @@ jobs:
           on_develop: false
 
     steps:
-    - uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+    - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # @v2
       with:
         fetch-depth: 0
-    - uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d
+    - uses: actions/setup-python@65d7f2d534ac1bc67fcd62888c5f4f3d2cb2b236 # @v2
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install System packages
@@ -91,19 +91,17 @@ jobs:
           UNIT_TEST_COVERAGE: ${{ matrix.python-version == '3.11' }}
       run: |
           share/spack/qa/run-unit-tests
-    - uses: codecov/codecov-action@c16abc29c95fcf9174b58eb7e1abf4c866893bc8
+    - uses: codecov/codecov-action@eaaf4bedf32dbdc6b720b63067d99c4d77d6047d
       with:
         flags: unittests,linux,${{ matrix.concretizer }}
-        token: ${{ secrets.CODECOV_TOKEN }}
-        verbose: true
   # Test shell integration
   shell:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+    - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # @v2
       with:
         fetch-depth: 0
-    - uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d
+    - uses: actions/setup-python@65d7f2d534ac1bc67fcd62888c5f4f3d2cb2b236 # @v2
       with:
         python-version: '3.11'
     - name: Install System packages
@@ -124,11 +122,9 @@ jobs:
           COVERAGE: true
       run: |
           share/spack/qa/run-shell-tests
-    - uses: codecov/codecov-action@c16abc29c95fcf9174b58eb7e1abf4c866893bc8
+    - uses: codecov/codecov-action@eaaf4bedf32dbdc6b720b63067d99c4d77d6047d
       with:
         flags: shelltests,linux
-        token: ${{ secrets.CODECOV_TOKEN }}
-        verbose: true
 
   # Test RHEL8 UBI with platform Python. This job is run
   # only on PRs modifying core Spack
@@ -141,7 +137,7 @@ jobs:
           dnf install -y \
               bzip2 curl file gcc-c++ gcc gcc-gfortran git gnupg2 gzip \
               make patch tcl unzip which xz
-    - uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+    - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # @v2
     - name: Setup repo and non-root user
       run: |
           git --version
@@ -160,10 +156,10 @@ jobs:
   clingo-cffi:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+    - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # @v2
       with:
         fetch-depth: 0
-    - uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d
+    - uses: actions/setup-python@65d7f2d534ac1bc67fcd62888c5f4f3d2cb2b236 # @v2
       with:
         python-version: '3.11'
     - name: Install System packages
@@ -185,23 +181,20 @@ jobs:
           SPACK_TEST_SOLVER: clingo
       run: |
           share/spack/qa/run-unit-tests
-    - uses: codecov/codecov-action@c16abc29c95fcf9174b58eb7e1abf4c866893bc8
+    - uses: codecov/codecov-action@eaaf4bedf32dbdc6b720b63067d99c4d77d6047d # @v2.1.0
       with:
         flags: unittests,linux,clingo
-        token: ${{ secrets.CODECOV_TOKEN }}
-        verbose: true
   # Run unit tests on MacOS
   macos:
-    runs-on: ${{ matrix.os }}
+    runs-on: macos-latest
     strategy:
       matrix:
-        os: [macos-latest, macos-14]
         python-version: ["3.11"]
     steps:
-    - uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+    - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # @v2
       with:
         fetch-depth: 0
-    - uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d
+    - uses: actions/setup-python@65d7f2d534ac1bc67fcd62888c5f4f3d2cb2b236 # @v2
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install Python packages
@@ -222,9 +215,7 @@ jobs:
         $(which spack) bootstrap disable spack-install
         $(which spack) solve zlib
         common_args=(--dist loadfile --tx '4*popen//python=./bin/spack-tmpconfig python -u ./bin/spack python' -x)
-        $(which spack) unit-test --verbose --cov --cov-config=pyproject.toml --cov-report=xml:coverage.xml "${common_args[@]}"
+        $(which spack) unit-test --cov --cov-config=pyproject.toml --cov-report=xml:coverage.xml "${common_args[@]}"
-    - uses: codecov/codecov-action@c16abc29c95fcf9174b58eb7e1abf4c866893bc8
+    - uses: codecov/codecov-action@eaaf4bedf32dbdc6b720b63067d99c4d77d6047d
       with:
         flags: unittests,macos
-        token: ${{ secrets.CODECOV_TOKEN }}
-        verbose: true

.github/workflows/valid-style.yml

@@ -18,8 +18,8 @@ jobs:
   validate:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+    - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
-    - uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d
+    - uses: actions/setup-python@65d7f2d534ac1bc67fcd62888c5f4f3d2cb2b236
       with:
         python-version: '3.11'
         cache: 'pip'
@@ -35,10 +35,10 @@ jobs:
   style:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+    - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
       with:
         fetch-depth: 0
-    - uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d
+    - uses: actions/setup-python@65d7f2d534ac1bc67fcd62888c5f4f3d2cb2b236
       with:
         python-version: '3.11'
         cache: 'pip'
@@ -56,7 +56,6 @@ jobs:
           share/spack/qa/run-style-tests
   audit:
     uses: ./.github/workflows/audit.yaml
-    secrets: inherit
     with:
       with_coverage: ${{ inputs.with_coverage }}
       python_version: '3.11'
@@ -70,7 +69,7 @@ jobs:
           dnf install -y \
               bzip2 curl file gcc-c++ gcc gcc-gfortran git gnupg2 gzip \
               make patch tcl unzip which xz
-      - uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # @v2
       - name: Setup repo and non-root user
         run: |
           git --version

.github/workflows/windows_python.yml

@@ -15,10 +15,10 @@ jobs:
   unit-tests:
     runs-on: windows-latest
     steps:
-    - uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+    - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
       with:
         fetch-depth: 0
-    - uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d
+    - uses: actions/setup-python@65d7f2d534ac1bc67fcd62888c5f4f3d2cb2b236
       with:
         python-version: 3.9
     - name: Install Python packages
@@ -33,18 +33,16 @@ jobs:
         ./share/spack/qa/validate_last_exit.ps1
         coverage combine -a
         coverage xml
-    - uses: codecov/codecov-action@c16abc29c95fcf9174b58eb7e1abf4c866893bc8
+    - uses: codecov/codecov-action@eaaf4bedf32dbdc6b720b63067d99c4d77d6047d
       with:
         flags: unittests,windows
-        token: ${{ secrets.CODECOV_TOKEN }}
-        verbose: true
   unit-tests-cmd:
     runs-on: windows-latest
     steps:
-    - uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+    - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
       with:
         fetch-depth: 0
-    - uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d
+    - uses: actions/setup-python@65d7f2d534ac1bc67fcd62888c5f4f3d2cb2b236
       with:
         python-version: 3.9
     - name: Install Python packages
@@ -59,18 +57,16 @@ jobs:
         ./share/spack/qa/validate_last_exit.ps1
         coverage combine -a
         coverage xml
-    - uses: codecov/codecov-action@c16abc29c95fcf9174b58eb7e1abf4c866893bc8
+    - uses: codecov/codecov-action@eaaf4bedf32dbdc6b720b63067d99c4d77d6047d
       with:
         flags: unittests,windows
-        token: ${{ secrets.CODECOV_TOKEN }}
-        verbose: true
   build-abseil:
     runs-on: windows-latest
     steps:
-    - uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633
+    - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
       with:
         fetch-depth: 0
-    - uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d
+    - uses: actions/setup-python@65d7f2d534ac1bc67fcd62888c5f4f3d2cb2b236
       with:
         python-version: 3.9
     - name: Install Python packages

CHANGELOG.md

@@ -1,290 +1,3 @@
-# v0.21.0 (2023-11-11)
-
-`v0.21.0` is a major feature release.
-
-## Features in this release
-
-1. **Better error messages with condition chaining**
-
-   In v0.18, we added better error messages that could tell you what problem happened,
-   but they couldn't tell you *why* it happened. `0.21` adds *condition chaining* to the
-   solver, and Spack can now trace back through the conditions that led to an error and
-   build a tree of causes potential causes and where they came from. For example:
-
-   ```console
-   $ spack solve hdf5 ^cmake@3.0.1
-   ==> Error: concretization failed for the following reasons:
-
-      1. Cannot satisfy 'cmake@3.0.1'
-      2. Cannot satisfy 'cmake@3.0.1'
-           required because hdf5 ^cmake@3.0.1 requested from CLI
-      3. Cannot satisfy 'cmake@3.18:' and 'cmake@3.0.1
-           required because hdf5 ^cmake@3.0.1 requested from CLI
-           required because hdf5 depends on cmake@3.18: when @1.13:
-             required because hdf5 ^cmake@3.0.1 requested from CLI
-      4. Cannot satisfy 'cmake@3.12:' and 'cmake@3.0.1
-           required because hdf5 depends on cmake@3.12:
-             required because hdf5 ^cmake@3.0.1 requested from CLI
-           required because hdf5 ^cmake@3.0.1 requested from CLI
-   ```
-
-   More details in #40173.
-
-2. **OCI build caches**
-
-   You can now use an arbitrary [OCI](https://opencontainers.org) registry as a build
-   cache:
-
-   ```console
-   $ spack mirror add my_registry oci://user/image # Dockerhub
-   $ spack mirror add my_registry oci://ghcr.io/haampie/spack-test # GHCR
-   $ spack mirror set --push --oci-username ... --oci-password ... my_registry  # set login creds
-   $ spack buildcache push my_registry [specs...]
-   ```
-
-   And you can optionally add a base image to get *runnable* images:
-
-   ```console
-   $ spack buildcache push --base-image ubuntu:23.04 my_registry python
-   Pushed ... as [image]:python-3.11.2-65txfcpqbmpawclvtasuog4yzmxwaoia.spack
-
-   $ docker run --rm -it [image]:python-3.11.2-65txfcpqbmpawclvtasuog4yzmxwaoia.spack
-   ```
-
-   This creates a container image from the Spack installations on the host system,
-   without the need to run `spack install` from a `Dockerfile` or `sif` file. It also
-   addresses the inconvenience of losing binaries of dependencies when `RUN spack
-   install` fails inside `docker build`.
-
-   Further, the container image layers and build cache tarballs are the same files. This
-   means that `spack install` and `docker pull` use the exact same underlying binaries.
-   If you previously used `spack install` inside of `docker build`, this feature helps
-   you save storage by a factor two.
-
-   More details in #38358.
-
-3. **Multiple versions of build dependencies**
-
-   Increasingly, complex package builds require multiple versions of some build
-   dependencies. For example, Python packages frequently require very specific versions
-   of `setuptools`, `cython`, and sometimes different physics packages require different
-   versions of Python to build. The concretizer enforced that every solve was *unified*,
-   i.e., that there only be one version of every package. The concretizer now supports
-   "duplicate" nodes for *build dependencies*, but enforces unification through
-   transitive link and run dependencies. This will allow it to better resolve complex
-   dependency graphs in ecosystems like Python, and it also gets us very close to
-   modeling compilers as proper dependencies.
-
-   This change required a major overhaul of the concretizer, as well as a number of
-   performance optimizations. See #38447, #39621.
-
-4. **Cherry-picking virtual dependencies**
-
-   You can now select only a subset of virtual dependencies from a spec that may provide
-   more. For example, if you want `mpich` to be your `mpi` provider, you can be explicit
-   by writing:
-
-   ```
-   hdf5 ^[virtuals=mpi] mpich
-   ```
-
-   Or, if you want to use, e.g., `intel-parallel-studio` for `blas` along with an external
-   `lapack` like `openblas`, you could write:
-
-   ```
-   strumpack ^[virtuals=mpi] intel-parallel-studio+mkl ^[virtuals=lapack] openblas
-   ```
-
-   The `virtuals=mpi` is an edge attribute, and dependency edges in Spack graphs now
-   track which virtuals they satisfied. More details in #17229 and #35322.
-
-   Note for packaging: in Spack 0.21 `spec.satisfies("^virtual")` is true if and only if
-   the package specifies `depends_on("virtual")`. This is different from Spack 0.20,
-   where depending on a provider implied depending on the virtual provided. See #41002
-   for an example where `^mkl` was being used to test for several `mkl` providers in a
-   package that did not depend on `mkl`.
-
-5. **License directive**
-
-   Spack packages can now have license metadata, with the new `license()` directive:
-
-   ```python
-       license("Apache-2.0")
-   ```
-
-   Licenses use [SPDX identifiers](https://spdx.org/licenses), and you can use SPDX
-   expressions to combine them:
-
-   ```python
-       license("Apache-2.0 OR MIT")
-   ```
-
-   Like other directives in Spack, it's conditional, so you can handle complex cases like
-   Spack itself:
-
-   ```python
-      license("LGPL-2.1", when="@:0.11")
-      license("Apache-2.0 OR MIT", when="@0.12:")
-   ```
-
-   More details in #39346, #40598.
-
-6. **`spack deconcretize` command**
-
-   We are getting close to having a `spack update` command for environments, but we're
-   not quite there yet. This is the next best thing. `spack deconcretize` gives you
-   control over what you want to update in an already concrete environment. If you have
-   an environment built with, say, `meson`, and you want to update your `meson` version,
-   you can run:
-
-   ```console
-   spack deconcretize meson
-   ```
-
-   and have everything that depends on `meson` rebuilt the next time you run `spack
-   concretize`. In a future Spack version, we'll handle all of this in a single command,
-   but for now you can use this to drop bits of your lockfile and resolve your
-   dependencies again. More in #38803.
-
-7. **UI Improvements**
-
-   The venerable `spack info` command was looking shabby compared to the rest of Spack's
-   UI, so we reworked it to have a bit more flair. `spack info` now makes much better
-   use of terminal space and shows variants, their values, and their descriptions much
-   more clearly. Conditional variants are grouped separately so you can more easily
-   understand how packages are structured. More in #40998.
-
-   `spack checksum` now allows you to filter versions from your editor, or by version
-   range. It also notifies you about potential download URL changes. See #40403.
-
-8. **Environments can include definitions**
-
-   Spack did not previously support using `include:` with The
-   [definitions](https://spack.readthedocs.io/en/latest/environments.html#spec-list-references)
-   section of an environment, but now it does. You can use this to curate lists of specs
-   and more easily reuse them across environments. See #33960.
-
-9. **Aliases**
-
-   You can now add aliases to Spack commands in `config.yaml`, e.g. this might enshrine
-   your favorite args to `spack find` as `spack f`:
-
-   ```yaml
-   config:
-     aliases:
-       f: find -lv
-   ```
-
-   See #17229.
-
-10. **Improved autoloading of modules**
-
-    Spack 0.20 was the first release to enable autoloading of direct dependencies in
-    module files.
-
-    The downside of this was that `module avail` and `module load` tab completion would
-    show users too many modules to choose from, and many users disabled generating
-    modules for dependencies through `exclude_implicits: true`. Further, it was
-    necessary to keep hashes in module names to avoid file name clashes.
-
-    In this release, you can start using `hide_implicits: true` instead, which exposes
-    only explicitly installed packages to the user, while still autoloading
-    dependencies. On top of that, you can safely use `hash_length: 0`, as this config
-    now only applies to the modules exposed to the user -- you don't have to worry about
-    file name clashes for hidden dependencies.
-
-   Note: for `tcl` this feature requires Modules 4.7 or higher
-
-11. **Updated container labeling**
-
-    Nightly Docker images from the `develop` branch will now be tagged as `:develop` and
-    `:nightly`. The `:latest` tag is no longer associated with `:develop`, but with the
-    latest stable release. Releases will be tagged with `:{major}`, `:{major}.{minor}`
-    and `:{major}.{minor}.{patch}`. `ubuntu:18.04` has also been removed from the list of
-    generated Docker images, as it is no longer supported. See #40593.
-
-## Other new commands and directives
-
-* `spack env activate` without arguments now loads a `default` environment that you do
-  not have to create (#40756).
-* `spack find -H` / `--hashes`: a new shortcut for piping `spack find` output to
-  other commands (#38663)
-* Add `spack checksum --verify`, fix `--add` (#38458)
-* New `default_args` context manager factors out common args for directives (#39964)
-* `spack compiler find --[no]-mixed-toolchain` lets you easily mix `clang` and
-  `gfortran` on Linux (#40902)
-
-## Performance improvements
-
-* `spack external find` execution is now much faster (#39843)
-* `spack location -i` now much faster on success (#40898)
-* Drop redundant rpaths post install (#38976)
-* ASP-based solver: avoid cycles in clingo using hidden directive (#40720)
-* Fix multiple quadratic complexity issues in environments (#38771)
-
-## Other new features of note
-
-* archspec: update to v0.2.2, support for Sapphire Rapids, Power10, Neoverse V2 (#40917)
-* Propagate variants across nodes that don't have that variant (#38512)
-* Implement fish completion (#29549)
-* Can now distinguish between source/binary mirror; don't ping mirror.spack.io as much (#34523)
-* Improve status reporting on install (add [n/total] display) (#37903)
-
-## Windows
-
-This release has the best Windows support of any Spack release yet, with numerous
-improvements and much larger swaths of tests passing:
-
-* MSVC and SDK improvements (#37711, #37930, #38500, #39823, #39180)
-* Windows external finding: update default paths; treat .bat as executable on Windows (#39850)
-* Windows decompression: fix removal of intermediate file (#38958)
-* Windows: executable/path handling (#37762)
-* Windows build systems: use ninja and enable tests (#33589)
-* Windows testing (#36970, #36972, #36973, #36840, #36977, #36792, #36834, #34696, #36971)
-* Windows PowerShell support (#39118, #37951)
-* Windows symlinking and libraries (#39933, #38599, #34701, #38578, #34701)
-
-## Notable refactors
-* User-specified flags take precedence over others in Spack compiler wrappers (#37376)
-* Improve setup of build, run, and test environments (#35737, #40916)
-* `make` is no longer a required system dependency of Spack (#40380)
-* Support Python 3.12 (#40404, #40155, #40153)
-* docs: Replace package list with packages.spack.io (#40251)
-* Drop Python 2 constructs in Spack (#38720, #38718, #38703)
-
-## Binary cache and stack updates
-* e4s arm stack: duplicate and target neoverse v1 (#40369)
-* Add macOS ML CI stacks (#36586)
-* E4S Cray CI Stack (#37837)
-* e4s cray: expand spec list (#38947)
-* e4s cray sles ci: expand spec list (#39081)
-
-## Removals, deprecations, and syntax changes
-* ASP: targets, compilers and providers soft-preferences are only global (#31261)
-* Parser: fix ambiguity with whitespace in version ranges (#40344)
-* Module file generation is disabled by default; you'll need to enable it to use it (#37258)
-* Remove deprecated "extra_instructions" option for containers (#40365)
-* Stand-alone test feature deprecation postponed to v0.22 (#40600)
-* buildcache push: make `--allow-root` the default and deprecate the option (#38878)
-
-## Notable Bugfixes
-* Bugfix: propagation of multivalued variants (#39833)
-* Allow `/` in git versions (#39398)
-* Fetch & patch: actually acquire stage lock, and many more issues (#38903)
-* Environment/depfile: better escaping of targets with Git versions (#37560)
-* Prevent "spack external find" to error out on wrong permissions (#38755)
-* lmod: allow core compiler to be specified with a version range (#37789)
-
-## Spack community stats
-
-* 7,469 total packages, 303 new since `v0.20.0`
-    * 150 new Python packages
-    * 34 new R packages
-* 353 people contributed to this release
-    * 336 committers to packages
-    * 65 committers to core
-
-
 # v0.20.3 (2023-10-31)
 
 ## Bugfixes

CITATION.cff

@@ -31,17 +31,13 @@ type: software
 message: "If you are referencing Spack in a publication, please cite the paper below."
 title: "The Spack Package Manager: Bringing Order to HPC Software Chaos"
 abstract: >-
-  Large HPC centers spend considerable time supporting software for thousands of users, but the
+  Large HPC centers spend considerable time supporting software for thousands of users, but the complexity of HPC software is quickly outpacing the capabilities of existing software management tools.
-  complexity of HPC software is quickly outpacing the capabilities of existing software management
+  Scientific applications require specific versions of compilers, MPI, and other dependency libraries, so using a single, standard software stack is infeasible.
-  tools. Scientific applications require specific versions of compilers, MPI, and other dependency
+  However, managing many configurations is difficult because the configuration space is combinatorial in size.
-  libraries, so using a single, standard software stack is infeasible. However, managing many
+  We introduce Spack, a tool used at Lawrence Livermore National Laboratory to manage this complexity.
-  configurations is difficult because the configuration space is combinatorial in size. We
+  Spack provides a novel, re- cursive specification syntax to invoke parametric builds of packages and dependencies.
-  introduce Spack, a tool used at Lawrence Livermore National Laboratory to manage this complexity.
+  It allows any number of builds to coexist on the same system, and it ensures that installed packages can find their dependencies, regardless of the environment.
-  Spack provides a novel, re- cursive specification syntax to invoke parametric builds of packages
+  We show through real-world use cases that Spack supports diverse and demanding applications, bringing order to HPC software chaos.
-  and dependencies. It allows any number of builds to coexist on the same system, and it ensures
-  that installed packages can find their dependencies, regardless of the environment. We show
-  through real-world use cases that Spack supports diverse and demanding applications, bringing
-  order to HPC software chaos.
 preferred-citation:
   title: "The Spack Package Manager: Bringing Order to HPC Software Chaos"
   type: conference-paper

LICENSE-MIT

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2013-2024 LLNS, LLC and other Spack Project Developers.
+Copyright (c) 2013-2023 LLNS, LLC and other Spack Project Developers.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,34 +1,13 @@
-<div align="left">
+# <img src="https://cdn.rawgit.com/spack/spack/develop/share/spack/logo/spack-logo.svg" width="64" valign="middle" alt="Spack"/> Spack
 
-<h2>
+[![Unit Tests](https://github.com/spack/spack/workflows/linux%20tests/badge.svg)](https://github.com/spack/spack/actions)
-<picture>
+[![Bootstrapping](https://github.com/spack/spack/actions/workflows/bootstrap.yml/badge.svg)](https://github.com/spack/spack/actions/workflows/bootstrap.yml)
-  <source media="(prefers-color-scheme: dark)" srcset="https://cdn.rawgit.com/spack/spack/develop/share/spack/logo/spack-logo-white-text.svg" width="250">
+[![codecov](https://codecov.io/gh/spack/spack/branch/develop/graph/badge.svg)](https://codecov.io/gh/spack/spack)
-  <source media="(prefers-color-scheme: light)" srcset="https://cdn.rawgit.com/spack/spack/develop/share/spack/logo/spack-logo-text.svg" width="250">
+[![Containers](https://github.com/spack/spack/actions/workflows/build-containers.yml/badge.svg)](https://github.com/spack/spack/actions/workflows/build-containers.yml)
-  <img alt="Spack" src="https://cdn.rawgit.com/spack/spack/develop/share/spack/logo/spack-logo-text.svg" width="250">
+[![Read the Docs](https://readthedocs.org/projects/spack/badge/?version=latest)](https://spack.readthedocs.io)
-</picture>
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-
+[![Slack](https://slack.spack.io/badge.svg)](https://slack.spack.io)
-<br>
+[![Matrix](https://img.shields.io/matrix/spack-space%3Amatrix.org?label=Matrix)](https://matrix.to/#/#spack-space:matrix.org)
-<br clear="all">
-
-<a href="https://github.com/spack/spack/actions/workflows/ci.yml"><img src="https://github.com/spack/spack/workflows/ci/badge.svg" alt="CI Status"></a>
-<a href="https://github.com/spack/spack/actions/workflows/bootstrapping.yml"><img src="https://github.com/spack/spack/actions/workflows/bootstrap.yml/badge.svg" alt="Bootstrap Status"></a>
-<a href="https://github.com/spack/spack/actions/workflows/build-containers.yml"><img src="https://github.com/spack/spack/actions/workflows/build-containers.yml/badge.svg" alt="Containers Status"></a>
-<a href="https://spack.readthedocs.io"><img src="https://readthedocs.org/projects/spack/badge/?version=latest" alt="Documentation Status"></a>
-<a href="https://codecov.io/gh/spack/spack"><img src="https://codecov.io/gh/spack/spack/branch/develop/graph/badge.svg" alt="Code coverage"/></a>
-<a href="https://slack.spack.io"><img src="https://slack.spack.io/badge.svg" alt="Slack"/></a>
-<a href="https://matrix.to/#/#spack-space:matrix.org"><img src="https://img.shields.io/matrix/spack-space%3Amatrix.org?label=matrix" alt="Matrix"/></a>
-
-</h2>
-
-**[Getting Started] &nbsp; • &nbsp; [Config] &nbsp; • &nbsp; [Community] &nbsp; • &nbsp; [Contributing] &nbsp; • &nbsp; [Packaging Guide]**
-
-[Getting Started]: https://spack.readthedocs.io/en/latest/getting_started.html
-[Config]: https://spack.readthedocs.io/en/latest/configuration.html
-[Community]: #community
-[Contributing]: https://spack.readthedocs.io/en/latest/contribution_guide.html
-[Packaging Guide]: https://spack.readthedocs.io/en/latest/packaging_guide.html
-
-</div>
 
 Spack is a multi-platform package manager that builds and installs
 multiple versions and configurations of software. It works on Linux,
@@ -87,11 +66,10 @@ Resources:
 * **Matrix space**: [#spack-space:matrix.org](https://matrix.to/#/#spack-space:matrix.org):
   [bridged](https://github.com/matrix-org/matrix-appservice-slack#matrix-appservice-slack) to Slack.
 * [**Github Discussions**](https://github.com/spack/spack/discussions):
-  for Q&A and discussions. Note the pinned discussions for announcements.
+  not just for discussions, but also Q&A.
+* **Mailing list**: [groups.google.com/d/forum/spack](https://groups.google.com/d/forum/spack)
 * **Twitter**: [@spackpm](https://twitter.com/spackpm). Be sure to
   `@mention` us!
-* **Mailing list**: [groups.google.com/d/forum/spack](https://groups.google.com/d/forum/spack):
-  only for announcements. Please use other venues for discussions.
 
 Contributing
 ------------------------

bin/haspywin.py

@@ -1,4 +1,4 @@
-# Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
 # Spack Project Developers. See the top-level COPYRIGHT file for details.
 #
 # SPDX-License-Identifier: (Apache-2.0 OR MIT)

bin/sbang

@@ -1,6 +1,6 @@
 #!/bin/sh
 #
-# Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
 # sbang project developers. See the top-level COPYRIGHT file for details.
 #
 # SPDX-License-Identifier: (Apache-2.0 OR MIT)

bin/spack

@@ -1,7 +1,7 @@
 #!/bin/sh
 # -*- python -*-
 #
-# Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
 # Spack Project Developers. See the top-level COPYRIGHT file for details.
 #
 # SPDX-License-Identifier: (Apache-2.0 OR MIT)

bin/spack-python

@@ -1,6 +1,6 @@
 #!/bin/sh
 #
-# Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
 # Spack Project Developers. See the top-level COPYRIGHT file for details.
 #
 # SPDX-License-Identifier: (Apache-2.0 OR MIT)

bin/spack.bat

@@ -1,4 +1,4 @@
-:: Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+:: Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
 :: Spack Project Developers. See the top-level COPYRIGHT file for details.
 ::
 :: SPDX-License-Identifier: (Apache-2.0 OR MIT)

bin/spack.ps1

@@ -1,4 +1,4 @@
-#  Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+#  Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
 #  Spack Project Developers. See the top-level COPYRIGHT file for details.
 
 #  SPDX-License-Identifier: (Apache-2.0 OR MIT)

bin/spack_pwsh.ps1

@@ -1,4 +1,4 @@
-# Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
 # Spack Project Developers. See the top-level COPYRIGHT file for details.
 #
 # SPDX-License-Identifier: (Apache-2.0 OR MIT)

etc/spack/defaults/concretizer.yaml

@@ -42,8 +42,3 @@ concretizer:
     # "minimal": allows the duplication of 'build-tools' nodes only (e.g. py-setuptools, cmake etc.)
     # "full" (experimental): allows separation of the entire build-tool stack (e.g. the entire "cmake" subDAG)
     strategy: minimal
-  # Option to specify compatiblity between operating systems for reuse of compilers and packages
-  # Specified as a key: [list] where the key is the os that is being targeted, and the list contains the OS's 
-  # it can reuse. Note this is a directional compatibility so mutual compatibility between two OS's 
-  # requires two entries i.e. os_compatible: {sonoma: [monterey], monterey: [sonoma]}
-  os_compatible: {}

etc/spack/defaults/config.yaml

@@ -101,12 +101,6 @@ config:
   verify_ssl: true
 
 
-  # This is where custom certs for proxy/firewall are stored.
-  # It can be a path or environment variable. To match ssl env configuration
-  # the default is the environment variable SSL_CERT_FILE
-  ssl_certs: $SSL_CERT_FILE
-
-
   # Suppress gpg warnings from binary package verification
   # Only suppresses warnings, gpg failure will still fail the install
   # Potential rationale to set True: users have already explicitly trusted the

etc/spack/defaults/darwin/packages.yaml

@@ -50,4 +50,4 @@ packages:
     # Apple bundles libuuid in libsystem_c version 1353.100.2,
     # although the version number used here isn't critical
     - spec: apple-libuuid@1353.100.2
-      prefix: /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk
+      prefix: /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk

etc/spack/defaults/packages.yaml

@@ -24,7 +24,6 @@ packages:
       elf: [elfutils]
       fftw-api: [fftw, amdfftw]
       flame: [libflame, amdlibflame]
-      fortran-rt: [gcc-runtime, intel-oneapi-runtime]
       fuse: [libfuse]
       gl: [glx, osmesa]
       glu: [mesa-glu, openglu]
@@ -35,9 +34,7 @@ packages:
       java: [openjdk, jdk, ibm-java]
       jpeg: [libjpeg-turbo, libjpeg]
       lapack: [openblas, amdlibflame]
-      libgfortran: [ gcc-runtime ]
       libglx: [mesa+glx, mesa18+glx]
-      libifcore: [ intel-oneapi-runtime ]
       libllvm: [llvm]
       libosmesa: [mesa+osmesa, mesa18+osmesa]
       lua-lang: [lua, lua-luajit-openresty, lua-luajit]

lib/spack/docs/_pygments/style.py

@@ -1,4 +1,4 @@
-# Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
 # Spack Project Developers. See the top-level COPYRIGHT file for details.
 #
 # SPDX-License-Identifier: (Apache-2.0 OR MIT)

lib/spack/docs/basic_usage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -1119,9 +1119,6 @@ and ``3.4.2``.  Similarly, ``@4.2:`` means any version above and including
 ``4.2``.  As a short-hand, ``@3`` is equivalent to the range ``@3:3`` and
 includes any version with major version ``3``.
 
-Versions are ordered lexicograpically by its components. For more details
-on the order, see :ref:`the packaging guide <version-comparison>`.
-
 Notice that you can distinguish between the specific version ``@=3.2`` and
 the range ``@3.2``. This is useful for packages that follow a versioning
 scheme that omits the zero patch version number: ``3.2``, ``3.2.1``,
@@ -1133,10 +1130,6 @@ A version specifier can also be a list of ranges and specific versions,
 separated by commas.  For example, ``@1.0:1.5,=1.7.1`` matches any version
 in the range ``1.0:1.5`` and the specific version ``1.7.1``.
 
-^^^^^^^^^^^^
-Git versions
-^^^^^^^^^^^^
-
 For packages with a ``git`` attribute, ``git`` references
 may be specified instead of a numerical version i.e. branches, tags
 and commits. Spack will stage and build based off the ``git``

lib/spack/docs/binary_caches.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -153,43 +153,7 @@ keyring, and trusting all downloaded keys.
 List of popular build caches
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-* `Extreme-scale Scientific Software Stack (E4S) <https://e4s-project.github.io/>`_: `build cache <https://oaciss.uoregon.edu/e4s/inventory.html>`_'
+* `Extreme-scale Scientific Software Stack (E4S) <https://e4s-project.github.io/>`_: `build cache <https://oaciss.uoregon.edu/e4s/inventory.html>`_
-
--------------------
-Build cache signing
--------------------
-
-By default, Spack will add a cryptographic signature to each package pushed to
-a build cache, and verifies the signature when installing from a build cache.
-
-Keys for signing can be managed with the :ref:`spack gpg <cmd-spack-gpg>` command,
-as well as ``spack buildcache keys`` as mentioned above.
-
-You can disable signing when pushing with ``spack buildcache push --unsigned``,
-and disable verification when installing from any build cache with
-``spack install --no-check-signature``.
-
-Alternatively, signing and verification can be enabled or disabled on a per build cache
-basis:
-
-.. code-block:: console
-
-    $ spack mirror add --signed <name> <url>  # enable signing and verification
-    $ spack mirror add --unsigned <name> <url>  # disable signing and verification
-
-    $ spack mirror set --signed <name>  # enable signing and verification for an existing mirror
-    $ spack mirror set --unsigned <name>  # disable signing and verification for an existing mirror
-
-Or you can directly edit the ``mirrors.yaml`` configuration file:
-
-.. code-block:: yaml
-
-    mirrors:
-      <name>:
-        url: <url>
-        signed: false # disable signing and verification
-
-See also :ref:`mirrors`.
 
 ----------
 Relocation
@@ -218,41 +182,6 @@ section of the configuration:
        padded_length: 128
 
 
-.. _binary_caches_oci:
-
----------------------------------
-Automatic push to a build cache
----------------------------------
-
-Sometimes it is convenient to push packages to a build cache as soon as they are installed. Spack can do this by setting autopush flag when adding a mirror:
-
-.. code-block:: console
-
-    $ spack mirror add --autopush <name> <url or path>
-
-Or the autopush flag can be set for an existing mirror:
-
-.. code-block:: console
-
-    $ spack mirror set --autopush <name>  # enable automatic push for an existing mirror
-    $ spack mirror set --no-autopush <name>  # disable automatic push for an existing mirror
-
-Then after installing a package it is automatically pushed to all mirrors with ``autopush: true``. The command
-
-.. code-block:: console
-
-    $ spack install <package>
-
-will have the same effect as
-
-.. code-block:: console
-
-    $ spack install <package>
-    $ spack buildcache push <cache> <package>  # for all caches with autopush: true
-
-.. note::
-
-    Packages are automatically pushed to a build cache only if they are built from source.
 
 -----------------------------------------
 OCI / Docker V2 registries as build cache
@@ -321,13 +250,87 @@ To significantly speed up Spack in GitHub Actions, binaries can be cached in
 GitHub Packages. This service is an OCI registry that can be linked to a GitHub
 repository.
 
+A typical workflow is to include a ``spack.yaml`` environment in your repository
+that specifies the packages to install, the target architecture, and the build
+cache to use under ``mirrors``:
+
+.. code-block:: yaml
+
+    spack:
+      specs:
+      - python@3.11
+      config:
+        install_tree:
+          root: /opt/spack
+          padded_length: 128
+      packages:
+        all:
+          require: target=x86_64_v2
+      mirrors:
+        local-buildcache: oci://ghcr.io/<organization>/<repository>
+
+A GitHub action can then be used to install the packages and push them to the
+build cache:
+
+.. code-block:: yaml
+
+    name: Install Spack packages
+
+    on: push
+
+    env:
+      SPACK_COLOR: always
+
+    jobs:
+      example:
+        runs-on: ubuntu-22.04
+        permissions:
+          packages: write
+        steps:
+        - name: Checkout
+          uses: actions/checkout@v3
+
+        - name: Checkout Spack
+          uses: actions/checkout@v3
+          with:
+            repository: spack/spack
+            path: spack
+
+        - name: Setup Spack
+          run: echo "$PWD/spack/bin" >> "$GITHUB_PATH"
+
+        - name: Concretize
+          run: spack -e . concretize
+
+        - name: Install
+          run: spack -e . install --no-check-signature
+
+        - name: Run tests
+            run: ./my_view/bin/python3 -c 'print("hello world")'
+
+        - name: Push to buildcache
+          run: |
+            spack -e . mirror set --oci-username ${{ github.actor }} --oci-password "${{ secrets.GITHUB_TOKEN }}" local-buildcache
+            spack -e . buildcache push --base-image ubuntu:22.04 --unsigned --update-index local-buildcache
+          if: ${{ !cancelled() }}
+
+The first time this action runs, it will build the packages from source and
+push them to the build cache. Subsequent runs will pull the binaries from the
+build cache. The concretizer will ensure that prebuilt binaries are favored
+over source builds.
+
+The build cache entries appear in the GitHub Packages section of your repository,
+and contain instructions for pulling and running them with ``docker`` or ``podman``.
+
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Using Spack's public build cache for GitHub Actions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 Spack offers a public build cache for GitHub Actions with a set of common packages,
 which lets you get started quickly. See the following resources for more information:
 
-* `spack/setup-spack <https://github.com/spack/setup-spack>`_ for setting up Spack in GitHub
+* `spack/github-actions-buildcache <https://github.com/spack/github-actions-buildcache>`_
-  Actions
-* `spack/github-actions-buildcache <https://github.com/spack/github-actions-buildcache>`_ for
-  more details on the public build cache
 
 .. _cmd-spack-buildcache:
 

lib/spack/docs/bootstrapping.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -87,7 +87,7 @@ You can check what is installed in the bootstrapping store at any time using:
 
 .. code-block:: console
 
-   % spack -b find
+   % spack find -b
    ==> Showing internal bootstrap store at "/Users/spack/.spack/bootstrap/store"
    ==> 11 installed packages
    -- darwin-catalina-x86_64 / apple-clang@12.0.0 ------------------
@@ -101,7 +101,7 @@ In case it is needed you can remove all the software in the current bootstrappin
    % spack clean -b
    ==> Removing bootstrapped software and configuration in "/Users/spack/.spack/bootstrap"
 
-   % spack -b find
+   % spack find -b
    ==> Showing internal bootstrap store at "/Users/spack/.spack/bootstrap/store"
    ==> 0 installed packages
 

lib/spack/docs/build_settings.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -37,11 +37,7 @@ to enable reuse for a single installation, and you can use:
    spack install --fresh <spec>
 
 to do a fresh install if ``reuse`` is enabled by default.
-``reuse: dependencies`` is the default.
+``reuse: true`` is the default.
-
-.. seealso::
-
-   FAQ: :ref:`Why does Spack pick particular versions and variants? <faq-concretizer-precedence>`
 
 ------------------------------------------
 Selection of the target microarchitectures
@@ -103,3 +99,547 @@ while `py-numpy` still needs an older version:
 
 Up to Spack v0.20 ``duplicates:strategy:none`` was the default (and only) behavior. From Spack v0.21 the
 default behavior is ``duplicates:strategy:minimal``.
+
+.. _build-settings:
+
+================================
+Package Settings (packages.yaml)
+================================
+
+Spack allows you to customize how your software is built through the
+``packages.yaml`` file.  Using it, you can make Spack prefer particular
+implementations of virtual dependencies (e.g., MPI or BLAS/LAPACK),
+or you can make it prefer to build with particular compilers.  You can
+also tell Spack to use *external* software installations already
+present on your system.
+
+At a high level, the ``packages.yaml`` file is structured like this:
+
+.. code-block:: yaml
+
+   packages:
+     package1:
+       # settings for package1
+     package2:
+       # settings for package2
+     # ...
+     all:
+       # settings that apply to all packages.
+
+So you can either set build preferences specifically for *one* package,
+or you can specify that certain settings should apply to *all* packages.
+The types of settings you can customize are described in detail below.
+
+Spack's build defaults are in the default
+``etc/spack/defaults/packages.yaml`` file.  You can override them in
+``~/.spack/packages.yaml`` or ``etc/spack/packages.yaml``. For more
+details on how this works, see :ref:`configuration-scopes`.
+
+.. _sec-external-packages:
+
+-----------------
+External Packages
+-----------------
+
+Spack can be configured to use externally-installed
+packages rather than building its own packages. This may be desirable
+if machines ship with system packages, such as a customized MPI
+that should be used instead of Spack building its own MPI.
+
+External packages are configured through the ``packages.yaml`` file.
+Here's an example of an external configuration:
+
+.. code-block:: yaml
+
+   packages:
+     openmpi:
+       externals:
+       - spec: "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64"
+         prefix: /opt/openmpi-1.4.3
+       - spec: "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64+debug"
+         prefix: /opt/openmpi-1.4.3-debug
+       - spec: "openmpi@1.6.5%intel@10.1 arch=linux-debian7-x86_64"
+         prefix: /opt/openmpi-1.6.5-intel
+
+This example lists three installations of OpenMPI, one built with GCC,
+one built with GCC and debug information, and another built with Intel.
+If Spack is asked to build a package that uses one of these MPIs as a
+dependency, it will use the pre-installed OpenMPI in
+the given directory. Note that the specified path is the top-level
+install prefix, not the ``bin`` subdirectory.
+
+``packages.yaml`` can also be used to specify modules to load instead
+of the installation prefixes.  The following example says that module
+``CMake/3.7.2`` provides cmake version 3.7.2.
+
+.. code-block:: yaml
+
+   cmake:
+     externals:
+     - spec: cmake@3.7.2
+       modules:
+       - CMake/3.7.2
+
+Each ``packages.yaml`` begins with a ``packages:`` attribute, followed
+by a list of package names.  To specify externals, add an ``externals:``
+attribute under the package name, which lists externals.
+Each external should specify a ``spec:`` string that should be as
+well-defined as reasonably possible.  If a
+package lacks a spec component, such as missing a compiler or
+package version, then Spack will guess the missing component based
+on its most-favored packages, and it may guess incorrectly.
+
+Each package version and compiler listed in an external should
+have entries in Spack's packages and compiler configuration, even
+though the package and compiler may not ever be built.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Prevent packages from being built from sources
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Adding an external spec in ``packages.yaml`` allows Spack to use an external location,
+but it does not prevent Spack from building packages from sources. In the above example,
+Spack might choose for many valid reasons to start building and linking with the
+latest version of OpenMPI rather than continue using the pre-installed OpenMPI versions.
+
+To prevent this, the ``packages.yaml`` configuration also allows packages
+to be flagged as non-buildable.  The previous example could be modified to
+be:
+
+.. code-block:: yaml
+
+   packages:
+     openmpi:
+       externals:
+       - spec: "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64"
+         prefix: /opt/openmpi-1.4.3
+       - spec: "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64+debug"
+         prefix: /opt/openmpi-1.4.3-debug
+       - spec: "openmpi@1.6.5%intel@10.1 arch=linux-debian7-x86_64"
+         prefix: /opt/openmpi-1.6.5-intel
+       buildable: False
+
+The addition of the ``buildable`` flag tells Spack that it should never build
+its own version of OpenMPI from sources, and it will instead always rely on a pre-built
+OpenMPI.
+
+.. note::
+
+   If ``concretizer:reuse`` is on (see :ref:`concretizer-options` for more information on that flag)
+   pre-built specs include specs already available from a local store, an upstream store, a registered
+   buildcache or specs marked as externals in ``packages.yaml``. If ``concretizer:reuse`` is off, only
+   external specs in ``packages.yaml`` are included in the list of pre-built specs.
+
+If an external module is specified as not buildable, then Spack will load the
+external module into the build environment which can be used for linking.
+
+The ``buildable`` does not need to be paired with external packages.
+It could also be used alone to forbid packages that may be
+buggy or otherwise undesirable.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Non-buildable virtual packages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Virtual packages in Spack can also be specified as not buildable, and
+external implementations can be provided. In the example above,
+OpenMPI is configured as not buildable, but Spack will often prefer
+other MPI implementations over the externally available OpenMPI. Spack
+can be configured with every MPI provider not buildable individually,
+but more conveniently:
+
+.. code-block:: yaml
+
+   packages:
+     mpi:
+       buildable: False
+     openmpi:
+       externals:
+       - spec: "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64"
+         prefix: /opt/openmpi-1.4.3
+       - spec: "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64+debug"
+         prefix: /opt/openmpi-1.4.3-debug
+       - spec: "openmpi@1.6.5%intel@10.1 arch=linux-debian7-x86_64"
+         prefix: /opt/openmpi-1.6.5-intel
+
+Spack can then use any of the listed external implementations of MPI
+to satisfy a dependency, and will choose depending on the compiler and
+architecture.
+
+In cases where the concretizer is configured to reuse specs, and other ``mpi`` providers
+(available via stores or buildcaches) are not wanted, Spack can be configured to require
+specs matching only the available externals:
+
+.. code-block:: yaml
+
+   packages:
+     mpi:
+       buildable: False
+       require:
+       - one_of: [
+           "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64",
+           "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64+debug",
+           "openmpi@1.6.5%intel@10.1 arch=linux-debian7-x86_64"
+         ]
+     openmpi:
+       externals:
+       - spec: "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64"
+         prefix: /opt/openmpi-1.4.3
+       - spec: "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64+debug"
+         prefix: /opt/openmpi-1.4.3-debug
+       - spec: "openmpi@1.6.5%intel@10.1 arch=linux-debian7-x86_64"
+         prefix: /opt/openmpi-1.6.5-intel
+
+This configuration prevents any spec using MPI and originating from stores or buildcaches to be reused,
+unless it matches the requirements under ``packages:mpi:require``. For more information on requirements see
+:ref:`package-requirements`.
+
+.. _cmd-spack-external-find:
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Automatically Find External Packages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can run the :ref:`spack external find <spack-external-find>` command
+to search for system-provided packages and add them to ``packages.yaml``.
+After running this command your ``packages.yaml`` may include new entries:
+
+.. code-block:: yaml
+
+   packages:
+     cmake:
+       externals:
+       - spec: cmake@3.17.2
+         prefix: /usr
+
+Generally this is useful for detecting a small set of commonly-used packages;
+for now this is generally limited to finding build-only dependencies.
+Specific limitations include:
+
+* Packages are not discoverable by default: For a package to be
+  discoverable with ``spack external find``, it needs to add special
+  logic. See :ref:`here <make-package-findable>` for more details.
+* The logic does not search through module files, it can only detect
+  packages with executables defined in ``PATH``; you can help Spack locate
+  externals which use module files by loading any associated modules for
+  packages that you want Spack to know about before running
+  ``spack external find``.
+* Spack does not overwrite existing entries in the package configuration:
+  If there is an external defined for a spec at any configuration scope,
+  then Spack will not add a new external entry (``spack config blame packages``
+  can help locate all external entries).
+
+.. _package-requirements:
+
+--------------------
+Package Requirements
+--------------------
+
+Spack can be configured to always use certain compilers, package
+versions, and variants during concretization through package
+requirements.
+
+Package requirements are useful when you find yourself repeatedly
+specifying the same constraints on the command line, and wish that
+Spack respects these constraints whether you mention them explicitly
+or not. Another use case is specifying constraints that should apply
+to all root specs in an environment, without having to repeat the
+constraint everywhere.
+
+Apart from that, requirements config is more flexible than constraints
+on the command line, because it can specify constraints on packages
+*when they occur* as a dependency. In contrast, on the command line it
+is not possible to specify constraints on dependencies while also keeping
+those dependencies optional.
+
+^^^^^^^^^^^^^^^^^^^
+Requirements syntax
+^^^^^^^^^^^^^^^^^^^
+
+The package requirements configuration is specified in ``packages.yaml``,
+keyed by package name and expressed using the Spec syntax. In the simplest
+case you can specify attributes that you always want the package to have
+by providing a single spec string to ``require``:
+
+.. code-block:: yaml
+
+   packages:
+     libfabric:
+       require: "@1.13.2"
+
+In the above example, ``libfabric`` will always build with version 1.13.2. If you
+need to compose multiple configuration scopes ``require`` accepts a list of
+strings:
+
+.. code-block:: yaml
+
+   packages:
+     libfabric:
+       require:
+       - "@1.13.2"
+       - "%gcc"
+
+In this case ``libfabric`` will always build with version 1.13.2 **and** using GCC
+as a compiler.
+
+For more complex use cases, require accepts also a list of objects. These objects
+must have either a ``any_of`` or a ``one_of`` field, containing a list of spec strings,
+and they can optionally have a ``when`` and a ``message`` attribute:
+
+.. code-block:: yaml
+
+   packages:
+     openmpi:
+       require:
+       - any_of: ["@4.1.5", "%gcc"]
+         message: "in this example only 4.1.5 can build with other compilers"
+
+``any_of`` is a list of specs. One of those specs must be satisfied
+and it is also allowed for the concretized spec to match more than one.
+In the above example, that means you could build ``openmpi@4.1.5%gcc``,
+``openmpi@4.1.5%clang`` or ``openmpi@3.9%gcc``, but
+not ``openmpi@3.9%clang``.
+
+If a custom message is provided, and the requirement is not satisfiable,
+Spack will print the custom error message:
+
+.. code-block:: console
+
+   $ spack spec openmpi@3.9%clang
+   ==> Error: in this example only 4.1.5 can build with other compilers
+
+We could express a similar requirement using the ``when`` attribute:
+
+.. code-block:: yaml
+
+   packages:
+     openmpi:
+       require:
+       - any_of: ["%gcc"]
+         when: "@:4.1.4"
+         message: "in this example only 4.1.5 can build with other compilers"
+
+In the example above, if the version turns out to be 4.1.4 or less, we require the compiler to be GCC.
+For readability, Spack also allows a ``spec`` key accepting a string when there is only a single
+constraint:
+
+.. code-block:: yaml
+
+   packages:
+     openmpi:
+       require:
+       - spec: "%gcc"
+         when: "@:4.1.4"
+         message: "in this example only 4.1.5 can build with other compilers"
+
+This code snippet and the one before it are semantically equivalent.
+
+Finally, instead of ``any_of`` you can use ``one_of`` which also takes a list of specs. The final
+concretized spec must match one and only one of them:
+
+.. code-block:: yaml
+
+   packages:
+     mpich:
+       require:
+       - one_of: ["+cuda", "+rocm"]
+
+In the example above, that means you could build ``mpich+cuda`` or ``mpich+rocm`` but not ``mpich+cuda+rocm``.
+
+.. note::
+
+   For ``any_of`` and ``one_of``, the order of specs indicates a
+   preference: items that appear earlier in the list are preferred
+   (note that these preferences can be ignored in favor of others).
+
+.. note::
+
+   When using a conditional requirement, Spack is allowed to actively avoid the triggering
+   condition (the ``when=...`` spec) if that leads to a concrete spec with better scores in
+   the optimization criteria. To check the current optimization criteria and their
+   priorities you can run ``spack solve zlib``.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Setting default requirements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can also set default requirements for all packages under ``all``
+like this:
+
+.. code-block:: yaml
+
+   packages:
+     all:
+       require: '%clang'
+
+which means every spec will be required to use ``clang`` as a compiler.
+
+Note that in this case ``all`` represents a *default set of requirements* -
+if there are specific package requirements, then the default requirements
+under ``all`` are disregarded. For example, with a configuration like this:
+
+.. code-block:: yaml
+
+   packages:
+     all:
+       require: '%clang'
+     cmake:
+       require: '%gcc'
+
+Spack requires ``cmake`` to use ``gcc`` and all other nodes (including ``cmake``
+dependencies) to use ``clang``.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Setting requirements on virtual specs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A requirement on a virtual spec applies whenever that virtual is present in the DAG.
+This can be useful for fixing which virtual provider you want to use:
+
+.. code-block:: yaml
+
+   packages:
+     mpi:
+       require: 'mvapich2 %gcc'
+
+With the configuration above the only allowed ``mpi`` provider is ``mvapich2 %gcc``.
+
+Requirements on the virtual spec and on the specific provider are both applied, if
+present. For instance with a configuration like:
+
+.. code-block:: yaml
+
+   packages:
+     mpi:
+       require: 'mvapich2 %gcc'
+     mvapich2:
+       require: '~cuda'
+
+you will use ``mvapich2~cuda %gcc`` as an ``mpi`` provider.
+
+.. _package-preferences:
+
+-------------------
+Package Preferences
+-------------------
+
+In some cases package requirements can be too strong, and package
+preferences are the better option. Package preferences do not impose
+constraints on packages for particular versions or variants values,
+they rather only set defaults. The concretizer is free to change
+them if it must, due to other constraints, and also prefers reusing
+installed packages over building new ones that are a better match for
+preferences.
+
+Most package preferences (``compilers``, ``target`` and ``providers``)
+can only be set globally under the ``all`` section of ``packages.yaml``:
+
+.. code-block:: yaml
+
+   packages:
+     all:
+       compiler: [gcc@12.2.0, clang@12:, oneapi@2023:]
+       target: [x86_64_v3]
+       providers:
+         mpi: [mvapich2, mpich, openmpi]
+
+These preferences override Spack's default and effectively reorder priorities
+when looking for the best compiler, target or virtual package provider. Each
+preference takes an ordered list of spec constraints, with earlier entries in
+the list being preferred over later entries.
+
+In the example above all packages prefer to be compiled with ``gcc@12.2.0``,
+to target the ``x86_64_v3`` microarchitecture and to use ``mvapich2`` if they
+depend on ``mpi``.
+
+The ``variants`` and ``version`` preferences can be set under
+package specific sections of the ``packages.yaml`` file:
+
+.. code-block:: yaml
+
+   packages:
+     opencv:
+       variants: +debug
+     gperftools:
+       version: [2.2, 2.4, 2.3]
+
+In this case, the preference for ``opencv`` is to build with debug options, while
+``gperftools`` prefers version 2.2 over 2.4.
+
+Any preference can be overwritten on the command line if explicitly requested.
+
+Preferences cannot overcome explicit constraints, as they only set a preferred
+ordering among homogeneous attribute values. Going back to the example, if
+``gperftools@2.3:`` was requested, then Spack will install version 2.4
+since the most preferred version 2.2 is prohibited by the version constraint.
+
+.. _package_permissions:
+
+-------------------
+Package Permissions
+-------------------
+
+Spack can be configured to assign permissions to the files installed
+by a package.
+
+In the ``packages.yaml`` file under ``permissions``, the attributes
+``read``, ``write``, and ``group`` control the package
+permissions. These attributes can be set per-package, or for all
+packages under ``all``. If permissions are set under ``all`` and for a
+specific package, the package-specific settings take precedence.
+
+The ``read`` and ``write`` attributes take one of ``user``, ``group``,
+and ``world``.
+
+.. code-block:: yaml
+
+  packages:
+    all:
+      permissions:
+        write: group
+        group: spack
+    my_app:
+      permissions:
+        read: group
+        group: my_team
+
+The permissions settings describe the broadest level of access to
+installations of the specified packages. The execute permissions of
+the file are set to the same level as read permissions for those files
+that are executable. The default setting for ``read`` is ``world``,
+and for ``write`` is ``user``. In the example above, installations of
+``my_app`` will be installed with user and group permissions but no
+world permissions, and owned by the group ``my_team``. All other
+packages will be installed with user and group write privileges, and
+world read privileges. Those packages will be owned by the group
+``spack``.
+
+The ``group`` attribute assigns a Unix-style group to a package. All
+files installed by the package will be owned by the assigned group,
+and the sticky group bit will be set on the install prefix and all
+directories inside the install prefix. This will ensure that even
+manually placed files within the install prefix are owned by the
+assigned group. If no group is assigned, Spack will allow the OS
+default behavior to go as expected.
+
+----------------------------
+Assigning Package Attributes
+----------------------------
+
+You can assign class-level attributes in the configuration:
+
+.. code-block:: yaml
+
+  packages:
+    mpileaks:
+      # Override existing attributes
+      url: http://www.somewhereelse.com/mpileaks-1.0.tar.gz
+      # ... or add new ones
+      x: 1
+
+Attributes set this way will be accessible to any method executed
+in the package.py file (e.g. the ``install()`` method). Values for these
+attributes may be any value parseable by yaml.
+
+These can only be applied to specific packages, not "all" or
+virtual packages.

lib/spack/docs/build_systems.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)

lib/spack/docs/build_systems/autotoolspackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)

lib/spack/docs/build_systems/bundlepackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)

lib/spack/docs/build_systems/cachedcmakepackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)

lib/spack/docs/build_systems/cmakepackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -82,7 +82,7 @@ class already contains:
 
 .. code-block:: python
 
-   depends_on("cmake", type="build")
+   depends_on('cmake', type='build')
 
 
 If you need to specify a particular version requirement, you can
@@ -90,7 +90,7 @@ override this in your package:
 
 .. code-block:: python
 
-   depends_on("cmake@2.8.12:", type="build")
+   depends_on('cmake@2.8.12:', type='build')
 
 
 ^^^^^^^^^^^^^^^^^^^
@@ -137,10 +137,10 @@ and without the :meth:`~spack.build_systems.cmake.CMakeBuilder.define` and
 
    def cmake_args(self):
        args = [
-           "-DWHATEVER:STRING=somevalue",
+           '-DWHATEVER:STRING=somevalue',
-           self.define("ENABLE_BROKEN_FEATURE", False),
+           self.define('ENABLE_BROKEN_FEATURE', False),
-           self.define_from_variant("DETECT_HDF5", "hdf5"),
+           self.define_from_variant('DETECT_HDF5', 'hdf5'),
-           self.define_from_variant("THREADS"), # True if +threads
+           self.define_from_variant('THREADS'), # True if +threads
        ]
 
        return args
@@ -151,10 +151,10 @@ and CMake simply ignores the empty command line argument. For example the follow
 
 .. code-block:: python
 
-   variant("example", default=True, when="@2.0:")
+   variant('example', default=True, when='@2.0:')
 
    def cmake_args(self):
-      return [self.define_from_variant("EXAMPLE", "example")]
+      return [self.define_from_variant('EXAMPLE', 'example')]
 
 will generate ``'cmake' '-DEXAMPLE=ON' ...`` when `@2.0: +example` is met, but will
 result in ``'cmake' '' ...`` when the spec version is below ``2.0``.
@@ -193,9 +193,9 @@ a variant to control this:
 
 .. code-block:: python
 
-   variant("build_type", default="RelWithDebInfo",
+   variant('build_type', default='RelWithDebInfo',
-           description="CMake build type",
+           description='CMake build type',
-           values=("Debug", "Release", "RelWithDebInfo", "MinSizeRel"))
+           values=('Debug', 'Release', 'RelWithDebInfo', 'MinSizeRel'))
 
 However, not every CMake package accepts all four of these options.
 Grep the ``CMakeLists.txt`` file to see if the default values are
@@ -205,9 +205,9 @@ package overrides the default variant with:
 
 .. code-block:: python
 
-   variant("build_type", default="DebugRelease",
+   variant('build_type', default='DebugRelease',
-           description="The build type to build",
+           description='The build type to build',
-           values=("Debug", "Release", "DebugRelease"))
+           values=('Debug', 'Release', 'DebugRelease'))
 
 For more information on ``CMAKE_BUILD_TYPE``, see:
 https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html
@@ -250,7 +250,7 @@ generator is Ninja. To switch to the Ninja generator, simply add:
 
 .. code-block:: python
 
-   generator("ninja")
+   generator = 'Ninja'
 
 
 ``CMakePackage`` defaults to "Unix Makefiles". If you switch to the
@@ -258,7 +258,7 @@ Ninja generator, make sure to add:
 
 .. code-block:: python
 
-   depends_on("ninja", type="build")
+   depends_on('ninja', type='build')
 
 to the package as well. Aside from that, you shouldn't need to do
 anything else. Spack will automatically detect that you are using
@@ -288,7 +288,7 @@ like so:
 
 .. code-block:: python
 
-   root_cmakelists_dir = "src"
+   root_cmakelists_dir = 'src'
 
 
 Note that this path is relative to the root of the extracted tarball,
@@ -304,7 +304,7 @@ different sub-directory, simply override ``build_directory`` like so:
 
 .. code-block:: python
 
-   build_directory = "my-build"
+   build_directory = 'my-build'
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 Build and install targets
@@ -324,8 +324,8 @@ library or build the documentation, you can add these like so:
 
 .. code-block:: python
 
-   build_targets = ["all", "docs"]
+   build_targets = ['all', 'docs']
-   install_targets = ["install", "docs"]
+   install_targets = ['install', 'docs']
 
 ^^^^^^^
 Testing

lib/spack/docs/build_systems/cudapackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)

lib/spack/docs/build_systems/custompackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)

lib/spack/docs/build_systems/inteloneapipackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -53,24 +53,18 @@ Install the oneAPI compilers::
 
 Add the compilers to your ``compilers.yaml`` so spack can use them::
 
-  spack compiler add `spack location -i intel-oneapi-compilers`/compiler/latest/bin
+  spack compiler add `spack location -i intel-oneapi-compilers`/compiler/latest/linux/bin/intel64
+  spack compiler add `spack location -i intel-oneapi-compilers`/compiler/latest/linux/bin
 
 Verify that the compilers are available::
 
   spack compiler list
 
-Note that 2024 and later releases do not include ``icc``. Before 2024,
-the package layout was different::
-  
-  spack compiler add `spack location -i intel-oneapi-compilers`/compiler/latest/linux/bin/intel64
-  spack compiler add `spack location -i intel-oneapi-compilers`/compiler/latest/linux/bin
-
 The ``intel-oneapi-compilers`` package includes 2 families of
 compilers:
 
 * ``intel``: ``icc``, ``icpc``, ``ifort``. Intel's *classic*
-  compilers. 2024 and later releases contain ``ifort``, but not
+  compilers.
-  ``icc`` and ``icpc``.
 * ``oneapi``: ``icx``, ``icpx``, ``ifx``. Intel's new generation of
   compilers based on LLVM.
 
@@ -95,8 +89,8 @@ Install the oneAPI compilers::
 
 Add the compilers to your ``compilers.yaml`` so Spack can use them::
 
-  spack compiler add `spack location -i intel-oneapi-compilers`/compiler/latest/bin
+  spack compiler add `spack location -i intel-oneapi-compilers`/compiler/latest/linux/bin/intel64
-  spack compiler add `spack location -i intel-oneapi-compilers`/compiler/latest/bin
+  spack compiler add `spack location -i intel-oneapi-compilers`/compiler/latest/linux/bin
 
 Verify that the compilers are available::
 
@@ -152,7 +146,8 @@ Compilers
 To use the compilers, add some information about the installation to
 ``compilers.yaml``. For most users, it is sufficient to do::
 
-  spack compiler add /opt/intel/oneapi/compiler/latest/bin
+  spack compiler add /opt/intel/oneapi/compiler/latest/linux/bin/intel64
+  spack compiler add /opt/intel/oneapi/compiler/latest/linux/bin
 
 Adapt the paths above if you did not install the tools in the default
 location. After adding the compilers, using them is the same
@@ -161,12 +156,6 @@ Another option is to manually add the configuration to
 ``compilers.yaml`` as described in :ref:`Compiler configuration
 <compiler-config>`.
 
-Before 2024, the directory structure was different::
-  
-  spack compiler add /opt/intel/oneapi/compiler/latest/linux/bin/intel64
-  spack compiler add /opt/intel/oneapi/compiler/latest/linux/bin
-
-
 Libraries
 ---------
 

lib/spack/docs/build_systems/intelpackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -90,7 +90,7 @@ and optimizers do require a paid license.  In Spack, they are packaged as:
     TODO: Confirm and possible change(!) the scope of MPI components (runtime
     vs. devel) in current (and previous?) *cluster/professional/composer*
     editions, i.e., presence in downloads, possibly subject to license
-    coverage(!); see `discussion in PR #4300
+    coverage(!); see `disussion in PR #4300
     <https://github.com/spack/spack/pull/4300#issuecomment-305582898>`_.  [NB:
     An "mpi" subdirectory is not indicative of the full MPI SDK being present
     (i.e., ``mpicc``, ..., and header files).  The directory may just as well
@@ -392,7 +392,7 @@ See section
 :ref:`Configuration Scopes <configuration-scopes>`
 for an explanation about the different files
 and section
-:ref:`Build customization <packages-config>`
+:ref:`Build customization <build-settings>`
 for specifics and examples for ``packages.yaml`` files.
 
 .. If your system administrator did not provide modules for pre-installed Intel
@@ -934,9 +934,9 @@ a *virtual* ``mkl`` package is declared in Spack.
   .. code-block:: python
 
      # Examples for absolute and conditional dependencies:
-     depends_on("mkl")
+     depends_on('mkl')
-     depends_on("mkl", when="+mkl")
+     depends_on('mkl', when='+mkl')
-     depends_on("mkl", when="fftw=mkl")
+     depends_on('mkl', when='fftw=mkl')
 
   The ``MKLROOT`` environment variable (part of the documented API) will be set
   during all stages of client package installation, and is available to both
@@ -972,8 +972,8 @@ a *virtual* ``mkl`` package is declared in Spack.
       def configure_args(self):
           args = []
           ...
-          args.append("--with-blas=%s" % self.spec["blas"].libs.ld_flags)
+          args.append('--with-blas=%s' % self.spec['blas'].libs.ld_flags)
-          args.append("--with-lapack=%s" % self.spec["lapack"].libs.ld_flags)
+          args.append('--with-lapack=%s' % self.spec['lapack'].libs.ld_flags)
           ...
 
   .. tip::
@@ -989,13 +989,13 @@ a *virtual* ``mkl`` package is declared in Spack.
 
   .. code-block:: python
 
-    self.spec["blas"].headers.include_flags
+    self.spec['blas'].headers.include_flags
 
   and to generate linker options (``-L<dir> -llibname ...``), use the same as above,
 
   .. code-block:: python
 
-    self.spec["blas"].libs.ld_flags
+    self.spec['blas'].libs.ld_flags
 
   See
   :ref:`MakefilePackage <makefilepackage>`

lib/spack/docs/build_systems/luapackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -88,7 +88,7 @@ override the ``luarocks_args`` method like so:
 .. code-block:: python
 
     def luarocks_args(self):
-        return ["flag1", "flag2"]
+        return ['flag1', 'flag2']
 
 One common use of this is to override warnings or flags for newer compilers, as in:
 

lib/spack/docs/build_systems/makefilepackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -88,13 +88,13 @@ command-line. However, Makefiles that use ``?=`` for assignment honor
 environment variables. Since Spack already sets ``CC``, ``CXX``, ``F77``,
 and ``FC``, you won't need to worry about setting these variables. If
 there are any other variables you need to set, you can do this in the
-``setup_build_environment`` method:
+``edit`` method:
 
 .. code-block:: python
 
-   def setup_build_environment(self, env):
+   def edit(self, spec, prefix):
-       env.set("PREFIX", prefix)
+       env["PREFIX"] = prefix
-       env.set("BLASLIB", spec["blas"].libs.ld_flags)
+       env["BLASLIB"] = spec["blas"].libs.ld_flags
 
 
 `cbench <https://github.com/spack/spack/blob/develop/var/spack/repos/builtin/packages/cbench/package.py>`_
@@ -140,7 +140,7 @@ Edit Makefile
 Some Makefiles are just plain stubborn and will ignore command-line
 variables. The only way to ensure that these packages build correctly
 is to directly edit the Makefile. Spack provides a ``FileFilter`` class
-and a ``filter`` method to help with this. For example:
+and a ``filter_file`` method to help with this. For example:
 
 .. code-block:: python
 

lib/spack/docs/build_systems/mavenpackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -48,8 +48,8 @@ class automatically adds the following dependencies:
 
 .. code-block:: python
 
-   depends_on("java", type=("build", "run"))
+   depends_on('java', type=('build', 'run'))
-   depends_on("maven", type="build")
+   depends_on('maven', type='build')
 
 
 In the ``pom.xml`` file, you may see sections like:
@@ -72,8 +72,8 @@ should add:
 
 .. code-block:: python
 
-   depends_on("java@7:", type="build")
+   depends_on('java@7:', type='build')
-   depends_on("maven@3.5.4:", type="build")
+   depends_on('maven@3.5.4:', type='build')
 
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -88,9 +88,9 @@ the build phase. For example:
 
    def build_args(self):
        return [
-           "-Pdist,native",
+           '-Pdist,native',
-           "-Dtar",
+           '-Dtar',
-           "-Dmaven.javadoc.skip=true"
+           '-Dmaven.javadoc.skip=true'
        ]
 
 

lib/spack/docs/build_systems/mesonpackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -86,8 +86,8 @@ the ``MesonPackage`` base class already contains:
 
 .. code-block:: python
 
-   depends_on("meson", type="build")
+   depends_on('meson', type='build')
-   depends_on("ninja", type="build")
+   depends_on('ninja', type='build')
 
 
 If you need to specify a particular version requirement, you can
@@ -95,8 +95,8 @@ override this in your package:
 
 .. code-block:: python
 
-   depends_on("meson@0.43.0:", type="build")
+   depends_on('meson@0.43.0:', type='build')
-   depends_on("ninja", type="build")
+   depends_on('ninja', type='build')
 
 
 ^^^^^^^^^^^^^^^^^^^
@@ -121,7 +121,7 @@ override the ``meson_args`` method like so:
 .. code-block:: python
 
    def meson_args(self):
-       return ["--warnlevel=3"]
+       return ['--warnlevel=3']
 
 
 This method can be used to pass flags as well as variables.

lib/spack/docs/build_systems/octavepackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)

lib/spack/docs/build_systems/perlpackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -118,7 +118,7 @@ so ``PerlPackage`` contains:
 
 .. code-block:: python
 
-   extends("perl")
+   extends('perl')
 
 
 If your package requires a specific version of Perl, you should
@@ -132,14 +132,14 @@ properly. If your package uses ``Makefile.PL`` to build, add:
 
 .. code-block:: python
 
-   depends_on("perl-extutils-makemaker", type="build")
+   depends_on('perl-extutils-makemaker', type='build')
 
 
 If your package uses ``Build.PL`` to build, add:
 
 .. code-block:: python
 
-   depends_on("perl-module-build", type="build")
+   depends_on('perl-module-build', type='build')
 
 
 ^^^^^^^^^^^^^^^^^
@@ -165,80 +165,14 @@ arguments to ``Makefile.PL`` or ``Build.PL`` by overriding
 .. code-block:: python
 
    def configure_args(self):
-       expat = self.spec["expat"].prefix
+       expat = self.spec['expat'].prefix
 
        return [
-           "EXPATLIBPATH={0}".format(expat.lib),
+           'EXPATLIBPATH={0}'.format(expat.lib),
-           "EXPATINCPATH={0}".format(expat.include),
+           'EXPATINCPATH={0}'.format(expat.include),
        ]
 
 
-^^^^^^^
-Testing
-^^^^^^^
-
-``PerlPackage`` provides a simple stand-alone test of the successfully
-installed package to confirm that installed perl module(s) can be used.
-These tests can be performed any time after the installation using
-``spack -v test run``. (For more information on the command, see 
-:ref:`cmd-spack-test-run`.)
-
-The base class automatically detects perl modules based on the presence
-of ``*.pm`` files under the package's library directory. For example,
-the files under ``perl-bignum``'s perl library are:
-
-.. code-block:: console
-
-   $ find . -name "*.pm"
-   ./bigfloat.pm
-   ./bigrat.pm
-   ./Math/BigFloat/Trace.pm
-   ./Math/BigInt/Trace.pm
-   ./Math/BigRat/Trace.pm
-   ./bigint.pm
-   ./bignum.pm
-
-
-which results in the package having the ``use_modules`` property containing:
-
-.. code-block:: python
-
-   use_modules = [
-       "bigfloat",
-       "bigrat",
-       "Math::BigFloat::Trace",
-       "Math::BigInt::Trace",
-       "Math::BigRat::Trace",
-       "bigint",
-       "bignum",
-   ]
-
-.. note::
-
-   This list can often be used to catch missing dependencies.
-
-If the list is somehow wrong, you can provide the names of the modules
-yourself by overriding ``use_modules`` like so:
-
- .. code-block:: python
-
-    use_modules = ["bigfloat", "bigrat", "bigint", "bignum"]
-
-If you only want a subset of the automatically detected modules to be
-tested, you could instead define the ``skip_modules`` property on the
-package. So, instead of overriding ``use_modules`` as shown above, you
-could define the following:
-
- .. code-block:: python
-
-    skip_modules = [
-        "Math::BigFloat::Trace",
-        "Math::BigInt::Trace",
-        "Math::BigRat::Trace",
-    ]
-
-for the same use tests.
-
 ^^^^^^^^^^^^^^^^^^^^^
 Alternatives to Spack
 ^^^^^^^^^^^^^^^^^^^^^

lib/spack/docs/build_systems/pythonpackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)

lib/spack/docs/build_systems/qmakepackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -83,7 +83,7 @@ base class already contains:
 
 .. code-block:: python
 
-   depends_on("qt", type="build")
+   depends_on('qt', type='build')
 
 
 If you want to specify a particular version requirement, or need to
@@ -91,7 +91,7 @@ link to the ``qt`` libraries, you can override this in your package:
 
 .. code-block:: python
 
-   depends_on("qt@5.6.0:")
+   depends_on('qt@5.6.0:')
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 Passing arguments to qmake
@@ -103,7 +103,7 @@ override the ``qmake_args`` method like so:
 .. code-block:: python
 
    def qmake_args(self):
-       return ["-recursive"]
+       return ['-recursive']
 
 
 This method can be used to pass flags as well as variables.
@@ -118,7 +118,7 @@ sub-directory by adding the following to the package:
 
 .. code-block:: python
 
-   build_directory = "src"
+   build_directory = 'src'
 
 
 ^^^^^^^^^^^^^^^^^^^^^^

lib/spack/docs/build_systems/racketpackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)

lib/spack/docs/build_systems/rocmpackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)

lib/spack/docs/build_systems/rpackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -163,28 +163,28 @@ attributes that can be used to set ``homepage``, ``url``, ``list_url``, and
 
 .. code-block:: python
 
-   cran = "caret"
+   cran = 'caret'
 
 is equivalent to:
 
 .. code-block:: python
 
-   homepage = "https://cloud.r-project.org/package=caret"
+   homepage = 'https://cloud.r-project.org/package=caret'
-   url      = "https://cloud.r-project.org/src/contrib/caret_6.0-86.tar.gz"
+   url      = 'https://cloud.r-project.org/src/contrib/caret_6.0-86.tar.gz'
-   list_url = "https://cloud.r-project.org/src/contrib/Archive/caret"
+   list_url = 'https://cloud.r-project.org/src/contrib/Archive/caret'
 
 Likewise, the following ``bioc`` attribute:
 
 .. code-block:: python
 
-   bioc = "BiocVersion"
+   bioc = 'BiocVersion'
 
 is equivalent to:
 
 .. code-block:: python
 
-   homepage = "https://bioconductor.org/packages/BiocVersion/"
+   homepage = 'https://bioconductor.org/packages/BiocVersion/'
-   git      = "https://git.bioconductor.org/packages/BiocVersion"
+   git      = 'https://git.bioconductor.org/packages/BiocVersion'
 
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -200,7 +200,7 @@ base class contains:
 
 .. code-block:: python
 
-   extends("r")
+   extends('r')
 
 
 Take a close look at the homepage for ``caret``. If you look at the
@@ -209,7 +209,7 @@ You should add this to your package like so:
 
 .. code-block:: python
 
-   depends_on("r@3.2.0:", type=("build", "run"))
+   depends_on('r@3.2.0:', type=('build', 'run'))
 
 
 ^^^^^^^^^^^^^^
@@ -227,7 +227,7 @@ and list all of their dependencies in the following sections:
 * LinkingTo
 
 As far as Spack is concerned, all 3 of these dependency types
-correspond to ``type=("build", "run")``, so you don't have to worry
+correspond to ``type=('build', 'run')``, so you don't have to worry
 about the details. If you are curious what they mean,
 https://github.com/spack/spack/issues/2951 has a pretty good summary:
 
@@ -330,7 +330,7 @@ the dependency:
 
 .. code-block:: python
 
-   depends_on("r-lattice@0.20:", type=("build", "run"))
+   depends_on('r-lattice@0.20:', type=('build', 'run'))
 
 
 ^^^^^^^^^^^^^^^^^^
@@ -361,20 +361,20 @@ like so:
 .. code-block:: python
 
    def configure_args(self):
-       mpi_name = self.spec["mpi"].name
+       mpi_name = self.spec['mpi'].name
 
        # The type of MPI. Supported values are:
        # OPENMPI, LAM, MPICH, MPICH2, or CRAY
-       if mpi_name == "openmpi":
+       if mpi_name == 'openmpi':
-           Rmpi_type = "OPENMPI"
+           Rmpi_type = 'OPENMPI'
-       elif mpi_name == "mpich":
+       elif mpi_name == 'mpich':
-           Rmpi_type = "MPICH2"
+           Rmpi_type = 'MPICH2'
        else:
-           raise InstallError("Unsupported MPI type")
+           raise InstallError('Unsupported MPI type')
 
        return [
-           "--with-Rmpi-type={0}".format(Rmpi_type),
+           '--with-Rmpi-type={0}'.format(Rmpi_type),
-           "--with-mpi={0}".format(spec["mpi"].prefix),
+           '--with-mpi={0}'.format(spec['mpi'].prefix),
        ]
 
 

lib/spack/docs/build_systems/rubypackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -84,8 +84,8 @@ The ``*.gemspec`` file may contain something like:
 
 .. code-block:: ruby
 
-   summary = "An implementation of the AsciiDoc text processor and publishing toolchain"
+   summary = 'An implementation of the AsciiDoc text processor and publishing toolchain'
-   description = "A fast, open source text processor and publishing toolchain for converting AsciiDoc content to HTML 5, DocBook 5, and other formats."
+   description = 'A fast, open source text processor and publishing toolchain for converting AsciiDoc content to HTML 5, DocBook 5, and other formats.'
 
 
 Either of these can be used for the description of the Spack package.
@@ -98,7 +98,7 @@ The ``*.gemspec`` file may contain something like:
 
 .. code-block:: ruby
 
-   homepage = "https://asciidoctor.org"
+   homepage = 'https://asciidoctor.org'
 
 
 This should be used as the official homepage of the Spack package.
@@ -112,21 +112,21 @@ the base class contains:
 
 .. code-block:: python
 
-   extends("ruby")
+   extends('ruby')
 
 
 The ``*.gemspec`` file may contain something like:
 
 .. code-block:: ruby
 
-   required_ruby_version = ">= 2.3.0"
+   required_ruby_version = '>= 2.3.0'
 
 
 This can be added to the Spack package using:
 
 .. code-block:: python
 
-   depends_on("ruby@2.3.0:", type=("build", "run"))
+   depends_on('ruby@2.3.0:', type=('build', 'run'))
 
 
 ^^^^^^^^^^^^^^^^^

lib/spack/docs/build_systems/sconspackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)

lib/spack/docs/build_systems/sippackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -124,7 +124,7 @@ are wrong, you can provide the names yourself by overriding
 
 .. code-block:: python
 
-   import_modules = ["PyQt5"]
+   import_modules = ['PyQt5']
 
 
 These tests often catch missing dependencies and non-RPATHed

lib/spack/docs/build_systems/sourceforgepackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)

lib/spack/docs/build_systems/wafpackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -63,8 +63,8 @@ run package-specific unit tests.
 .. code-block:: python
 
    def installtest(self):
-       with working_dir("test"):
+       with working_dir('test'):
-           pytest = which("py.test")
+           pytest = which('py.test')
            pytest()
 
 
@@ -93,7 +93,7 @@ the following dependency automatically:
 
 .. code-block:: python
 
-   depends_on("python@2.5:", type="build")
+   depends_on('python@2.5:', type='build')
 
 
 Waf only supports Python 2.5 and up.
@@ -113,7 +113,7 @@ phase, you can use:
        args = []
 
        if self.run_tests:
-           args.append("--test")
+           args.append('--test')
 
        return args
 

lib/spack/docs/chain.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)

lib/spack/docs/conf.py

@@ -1,4 +1,4 @@
-# Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
 # Spack Project Developers. See the top-level COPYRIGHT file for details.
 #
 # SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -199,7 +199,6 @@ def setup(sphinx):
     ("py:class", "contextlib.contextmanager"),
     ("py:class", "module"),
     ("py:class", "_io.BufferedReader"),
-    ("py:class", "_io.BytesIO"),
     ("py:class", "unittest.case.TestCase"),
     ("py:class", "_frozen_importlib_external.SourceFileLoader"),
     ("py:class", "clingo.Control"),
@@ -216,7 +215,6 @@ def setup(sphinx):
     ("py:class", "spack.spec.InstallStatus"),
     ("py:class", "spack.spec.SpecfileReaderBase"),
     ("py:class", "spack.install_test.Pb"),
-    ("py:class", "spack.filesystem_view.SimpleFilesystemView"),
 ]
 
 # The reST default role (used for this markup: `text`) to use for all documents.

lib/spack/docs/config_yaml.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -145,22 +145,6 @@ hosts when making ``ssl`` connections.  Set to ``false`` to disable, and
 tools like ``curl`` will use their ``--insecure`` options.  Disabling
 this can expose you to attacks.  Use at your own risk.
 
---------------------
-``ssl_certs``
---------------------
-
-Path to custom certificats for SSL verification. The value can be a 
-filesytem path, or an environment variable that expands to a file path.
-The default value is set to the environment variable ``SSL_CERT_FILE``
-to use the same syntax used by many other applications that automatically
-detect custom certificates.
-When ``url_fetch_method:curl`` the ``config:ssl_certs`` should resolve to
-a single file.  Spack will then set the environment variable ``CURL_CA_BUNDLE``
-in the subprocess calling ``curl``.
-If ``url_fetch_method:urllib`` then files and directories are supported i.e. 
-``config:ssl_certs:$SSL_CERT_FILE`` or ``config:ssl_certs:$SSL_CERT_DIR``
-will work.
-
 --------------------
 ``checksum``
 --------------------

lib/spack/docs/configuration.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -17,7 +17,7 @@ case you want to skip directly to specific docs:
 * :ref:`config.yaml <config-yaml>`
 * :ref:`mirrors.yaml <mirrors>`
 * :ref:`modules.yaml <modules>`
-* :ref:`packages.yaml <packages-config>`
+* :ref:`packages.yaml <build-settings>`
 * :ref:`repos.yaml <repositories>`
 
 You can also add any of these as inline configuration in the YAML
@@ -73,12 +73,9 @@ are six configuration scopes. From lowest to highest:
    Spack instance per project) or for site-wide settings on a multi-user
    machine (e.g., for a common Spack instance).
 
-#. **plugin**: Read from a Python project's entry points. Settings here affect
-   all instances of Spack running with the same Python installation.  This scope takes higher precedence than site, system, and default scopes.
-
 #. **user**: Stored in the home directory: ``~/.spack/``. These settings
    affect all instances of Spack and take higher precedence than site,
-   system, plugin, or defaults scopes.
+   system, or defaults scopes.
 
 #. **custom**: Stored in a custom directory specified by ``--config-scope``.
    If multiple scopes are listed on the command line, they are ordered
@@ -199,45 +196,6 @@ with MPICH. You can create different configuration scopes for use with
                mpi: [mpich]
 
 
-.. _plugin-scopes:
-
-^^^^^^^^^^^^^
-Plugin scopes
-^^^^^^^^^^^^^
-
-.. note::
-   Python version >= 3.8 is required to enable plugin configuration.
-
-Spack can be made aware of configuration scopes that are installed as part of a python package.  To do so, register a function that returns the scope's path to the ``"spack.config"`` entry point.  Consider the Python package ``my_package`` that includes Spack configurations:
-
-.. code-block:: console
-
-  my-package/
-  ├── src
-  │   ├── my_package
-  │   │   ├── __init__.py
-  │   │   └── spack/
-  │   │   │   └── config.yaml
-  └── pyproject.toml
-
-adding the following to ``my_package``'s ``pyproject.toml`` will make ``my_package``'s ``spack/`` configurations visible to Spack when ``my_package`` is installed:
-
-.. code-block:: toml
-
-   [project.entry_points."spack.config"]
-   my_package = "my_package:get_config_path"
-
-The function ``my_package.get_extension_path`` in ``my_package/__init__.py`` might look like
-
-.. code-block:: python
-
-   import importlib.resources
-
-   def get_config_path():
-       dirname = importlib.resources.files("my_package").joinpath("spack")
-       if dirname.exists():
-           return str(dirname)
-
 .. _platform-scopes:
 
 ------------------------

lib/spack/docs/containers.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -9,96 +9,24 @@
 Container Images
 ================
 
-Spack :ref:`environments` can easily be turned into container images. This page
+Spack :ref:`environments` are a great tool to create container images, but
-outlines two ways in which this can be done:
+preparing one that is suitable for production requires some more boilerplate
-
+than just:
-1. By installing the environment on the host system, and copying the installations
-   into the container image. This approach does not require any tools like Docker
-   or Singularity to be installed.
-2. By generating a Docker or Singularity recipe that can be used to build the
-   container image. In this approach, Spack builds the software inside the
-   container runtime, not on the host system.
-
-The first approach is easiest if you already have an installed environment,
-the second approach gives more control over the container image.
-
----------------------------
-From existing installations
----------------------------
-
-If you already have a Spack environment installed on your system, you can
-share the binaries as an OCI compatible container image. To get started you
-just have to configure and OCI registry and run ``spack buildcache push``.
-
-.. code-block:: console
-  
-   # Create and install an environment in the current directory
-   spack env create -d .
-   spack -e . add pkg-a pkg-b
-   spack -e . install
-
-   # Configure the registry
-   spack -e . mirror add --oci-username ... --oci-password ... container-registry oci://example.com/name/image
-
-   # Push the image
-   spack -e . buildcache push --update-index --base-image ubuntu:22.04 --tag my_env container-registry
-
-The resulting container image can then be run as follows:
-
-.. code-block:: console
-
-   $ docker run -it example.com/name/image:my_env
-
-The image generated by Spack consists of the specified base image with each package from the
-environment as a separate layer on top. The image is minimal by construction, it only contains the
-environment roots and its runtime dependencies.
-
-.. note::
-
-  When using registries like GHCR and Docker Hub, the ``--oci-password`` flag is not
-  the password for your account, but a personal access token you need to generate separately.
-
-The specified ``--base-image`` should have a libc that is compatible with the host system.
-For example if your host system is Ubuntu 20.04, you can use ``ubuntu:20.04``, ``ubuntu:22.04``
-or newer: the libc in the container image must be at least the version of the host system,
-assuming ABI compatibility. It is also perfectly fine to use a completely different
-Linux distribution as long as the libc is compatible.
-
-For convenience, Spack also turns the OCI registry into a :ref:`build cache <binary_caches_oci>`,
-so that future ``spack install`` of the environment will simply pull the binaries from the
-registry instead of doing source builds. The flag ``--update-index`` is needed to make Spack
-take the build cache into account when concretizing.
-
-.. note::
-
-  When generating container images in CI, the approach above is recommended when CI jobs
-  already run in a sandboxed environment. You can simply use ``spack`` directly
-  in the CI job and push the resulting image to a registry. Subsequent CI jobs should
-  run faster because Spack can install from the same registry instead of rebuilding from
-  sources.
-
----------------------------------------------
-Generating recipes for Docker and Singularity
----------------------------------------------
-
-Apart from copying existing installations into container images, Spack can also
-generate recipes for container images. This is useful if you want to run Spack
-itself in a sandboxed environment instead of on the host system.
-
-Since recipes need a little bit more boilerplate than
 
 .. code-block:: docker
 
    COPY spack.yaml /environment
    RUN spack -e /environment install
 
-Spack provides a command to generate customizable recipes for container images. Customizations
+Additional actions may be needed to minimize the size of the
-include minimizing the size of the image, installing packages in the base image using the system
+container, or to update the system software that is installed in the base
-package manager, and setting up a proper entrypoint to run the image.
+image, or to set up a proper entrypoint to run the image. These tasks are
+usually both necessary and repetitive, so Spack comes with a command
+to generate recipes for container images starting from a ``spack.yaml``.
 
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 A Quick Introduction
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 Consider having a Spack environment like the following:
 
@@ -109,8 +37,8 @@ Consider having a Spack environment like the following:
      - gromacs+mpi
      - mpich
 
-Producing a ``Dockerfile`` from it is as simple as changing directories to
+Producing a ``Dockerfile`` from it is as simple as moving to the directory
-where the ``spack.yaml`` file is stored and running the following command:
+where the ``spack.yaml`` file is stored and giving the following command:
 
 .. code-block:: console
 
@@ -176,9 +104,9 @@ configuration are discussed in details in the sections below.
 
 .. _container_spack_images:
 
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
 Spack Images on Docker Hub
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
 
 Docker images with Spack preinstalled and ready to be used are
 built when a release is tagged, or nightly on ``develop``. The images
@@ -248,9 +176,9 @@ by Spack use them as default base images for their ``build`` stage,
 even though handles to use custom base images provided by users are
 available to accommodate complex use cases.
 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------
-Configuring the Container Recipe
+Creating Images From Environments
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------
 
 Any Spack Environment can be used for the automatic generation of container
 recipes. Sensible defaults are provided for things like the base image or the
@@ -291,18 +219,18 @@ under the ``container`` attribute of environments:
 
 A detailed description of the options available can be found in the :ref:`container_config_options` section.
 
-~~~~~~~~~~~~~~~~~~~
+-------------------
 Setting Base Images
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 The ``images`` subsection is used to select both the image where
 Spack builds the software and the image where the built software
 is installed. This attribute can be set in different ways and
 which one to use depends on the use case at hand.
 
-""""""""""""""""""""""""""""""""""""""""
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Use Official Spack Images From Dockerhub
-""""""""""""""""""""""""""""""""""""""""
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 To generate a recipe that uses an official Docker image from the
 Spack organization to build the software and the corresponding official OS image
@@ -507,9 +435,9 @@ responsibility to ensure that:
 Therefore we don't recommend its use in cases that can be otherwise
 covered by the simplified mode shown first.
 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------
 Singularity Definition Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------
 
 In addition to producing recipes in ``Dockerfile`` format Spack can produce
 Singularity Definition Files by just changing the value of the ``format``
@@ -530,9 +458,9 @@ attribute:
 The minimum version of Singularity required to build a SIF (Singularity Image Format)
 image from the recipes generated by Spack is ``3.5.3``.
 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------
 Extending the Jinja2 Templates
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------
 
 The Dockerfile and the Singularity definition file that Spack can generate are based on
 a few Jinja2 templates that are rendered according to the environment being containerized.
@@ -653,9 +581,9 @@ The recipe that gets generated contains the two extra instruction that we added
 
 .. _container_config_options:
 
-~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------
 Configuration Reference
-~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------
 
 The tables below describe all the configuration options that are currently supported
 to customize the generation of container recipes:
@@ -752,13 +680,13 @@ to customize the generation of container recipes:
      - Description string
      - No
 
-~~~~~~~~~~~~~~
+--------------
 Best Practices
-~~~~~~~~~~~~~~
+--------------
 
-"""
+^^^
 MPI
-"""
+^^^
 Due to the dependency on Fortran for OpenMPI, which is the spack default
 implementation, consider adding ``gfortran`` to the ``apt-get install`` list.
 
@@ -769,9 +697,9 @@ For execution on HPC clusters, it can be helpful to import the docker
 image into Singularity in order to start a program with an *external*
 MPI. Otherwise, also add ``openssh-server`` to the ``apt-get install`` list.
 
-""""
+^^^^
 CUDA
-""""
+^^^^
 Starting from CUDA 9.0, Nvidia provides minimal CUDA images based on
 Ubuntu. Please see `their instructions <https://hub.docker.com/r/nvidia/cuda/>`_.
 Avoid double-installing CUDA by adding, e.g.
@@ -790,9 +718,9 @@ to your ``spack.yaml``.
 Users will either need ``nvidia-docker`` or e.g. Singularity to *execute*
 device kernels.
 
-"""""""""""""""""""""""""
+^^^^^^^^^^^^^^^^^^^^^^^^^
 Docker on Windows and OSX
-"""""""""""""""""""""""""
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 On Mac OS and Windows, docker runs on a hypervisor that is not allocated much
 memory by default, and some spack packages may fail to build due to lack of

lib/spack/docs/contribution_guide.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)

lib/spack/docs/developer_guide.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -357,23 +357,91 @@ If there is a hook that you would like and is missing, you can propose to add a
 ``pre_install(spec)``
 """""""""""""""""""""
 
-A ``pre_install`` hook is run within the install subprocess, directly before the install starts.
+A ``pre_install`` hook is run within an install subprocess, directly before
-It expects a single argument of a spec.
+the install starts. It expects a single argument of a spec, and is run in
+a multiprocessing subprocess. Note that if you see ``pre_install`` functions associated with packages these are not hooks
+as we have defined them here, but rather callback functions associated with
+a package install.
 
 
-"""""""""""""""""""""""""""""""""""""
+""""""""""""""""""""""
-``post_install(spec, explicit=None)``
+``post_install(spec)``
-"""""""""""""""""""""""""""""""""""""
+""""""""""""""""""""""
 
-A ``post_install`` hook is run within the install subprocess, directly after the install finishes,
+A ``post_install`` hook is run within an install subprocess, directly after
-but before the build stage is removed and the spec is registered in the database. It expects two
+the install finishes, but before the build stage is removed. If you
-arguments: spec and an optional boolean indicating whether this spec is being installed explicitly.
+write one of these hooks, you should expect it to accept a spec as the only
+argument. This is run in a multiprocessing subprocess. This ``post_install`` is
+also seen in packages, but in this context not related to the hooks described
+here.
 
-""""""""""""""""""""""""""""""""""""""""""""""""""""
-``pre_uninstall(spec)`` and ``post_uninstall(spec)``
-""""""""""""""""""""""""""""""""""""""""""""""""""""
 
-These hooks are currently used for cleaning up module files after uninstall.
+""""""""""""""""""""""""""
+``on_install_start(spec)``
+""""""""""""""""""""""""""
+
+This hook is run at the beginning of ``lib/spack/spack/installer.py``,
+in the install function of a ``PackageInstaller``,
+and importantly is not part of a build process, but before it. This is when
+we have just newly grabbed the task, and are preparing to install. If you
+write a hook of this type, you should provide the spec to it.
+
+.. code-block:: python
+
+    def on_install_start(spec):
+        """On start of an install, we want to...
+        """
+        print('on_install_start')
+
+
+""""""""""""""""""""""""""""
+``on_install_success(spec)``
+""""""""""""""""""""""""""""
+
+This hook is run on a successful install, and is also run inside the build
+process, akin to ``post_install``. The main difference is that this hook
+is run outside of the context of the stage directory, meaning after the
+build stage has been removed and the user is alerted that the install was
+successful. If you need to write a hook that is run on success of a particular
+phase, you should use ``on_phase_success``.
+
+""""""""""""""""""""""""""""
+``on_install_failure(spec)``
+""""""""""""""""""""""""""""
+
+This hook is run given an install failure that happens outside of the build
+subprocess, but somewhere in ``installer.py`` when something else goes wrong.
+If you need to write a hook that is relevant to a failure within a build
+process, you would want to instead use ``on_phase_failure``.
+
+
+"""""""""""""""""""""""""""
+``on_install_cancel(spec)``
+"""""""""""""""""""""""""""
+
+The same, but triggered if a spec install is cancelled for any reason.
+
+
+"""""""""""""""""""""""""""""""""""""""""""""""
+``on_phase_success(pkg, phase_name, log_file)``
+"""""""""""""""""""""""""""""""""""""""""""""""
+
+This hook is run within the install subprocess, and specifically when a phase
+successfully finishes. Since we are interested in the package, the name of
+the phase, and any output from it, we require:
+
+ - **pkg**: the package variable, which also has the attached spec at ``pkg.spec``
+ - **phase_name**: the name of the phase that was successful (e.g., configure)
+ - **log_file**: the path to the file with output, in case you need to inspect or otherwise interact with it.
+
+"""""""""""""""""""""""""""""""""""""""""""""
+``on_phase_error(pkg, phase_name, log_file)``
+"""""""""""""""""""""""""""""""""""""""""""""
+
+In the case of an error during a phase, we might want to trigger some event
+with a hook, and this is the purpose of this particular hook. Akin to
+``on_phase_success`` we require the same variables - the package that failed,
+the name of the phase, and the log file where we might find errors.
 
 
 ^^^^^^^^^^^^^^^^^^^^^^

lib/spack/docs/environments.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -142,21 +142,6 @@ user's prompt to begin with the environment name in brackets.
    $ spack env activate -p myenv
    [myenv] $ ...
 
-The ``activate`` command can also be used to create a new environment, if it is
-not already defined, by adding the ``--create`` flag. Managed and anonymous
-environments, anonymous environments are explained in the next section,
-can both be created using the same flags that `spack env create` accepts.
-If an environment already exists then spack will simply activate it and ignore the
-create specific flags.
-
-.. code-block:: console
-   
-   $ spack env activate --create -p myenv
-   # ...
-   # [creates if myenv does not exist yet]
-   # ...
-   [myenv] $ ...
-
 To deactivate an environment, use the command:
 
 .. code-block:: console
@@ -416,23 +401,6 @@ that git clone if ``foo`` is in the environment.
 Further development on ``foo`` can be tested by reinstalling the environment,
 and eventually committed and pushed to the upstream git repo.
 
-If the package being developed supports out-of-source builds then users can use the
-``--build_directory`` flag to control the location and name of the build directory. 
-This is a shortcut to set the ``package_attributes:build_directory`` in the
-``packages`` configuration (see :ref:`assigning-package-attributes`).
-The supplied location will become the build-directory for that package in all future builds.
-
-.. warning::
-   Potential pitfalls of setting the build directory
-    Spack does not check for out-of-source build compatibility with the packages and
-    so the onerous of making sure the package supports out-of-source builds is on
-    the user.
-    For example, most ``autotool`` and ``makefile`` packages do not support out-of-source builds
-    while all ``CMake`` packages do.
-    Understanding these nuances are on the software developers and we strongly encourage
-    developers to only redirect the build directory if they understand their package's
-    build-system.
-
 ^^^^^^^
 Loading
 ^^^^^^^
@@ -489,11 +457,11 @@ a ``packages.yaml`` file) could contain:
 .. code-block:: yaml
 
    spack:
-     # ...
+     ...
      packages:
        all:
          compiler: [intel]
-     # ...
+     ...
 
 This configuration sets the default compiler for all packages to
 ``intel``.
@@ -839,7 +807,7 @@ directories.
 .. code-block:: yaml
 
    spack:
-     # ...
+     ...
      view:
        mpis:
          root: /path/to/view
@@ -883,7 +851,7 @@ automatically named ``default``, so that
 .. code-block:: yaml
 
    spack:
-     # ...
+     ...
      view: True
 
 is equivalent to
@@ -891,7 +859,7 @@ is equivalent to
 .. code-block:: yaml
 
    spack:
-     # ...
+     ...
      view:
        default:
          root: .spack-env/view
@@ -901,7 +869,7 @@ and
 .. code-block:: yaml
 
    spack:
-     # ...
+     ...
      view: /path/to/view
 
 is equivalent to
@@ -909,7 +877,7 @@ is equivalent to
 .. code-block:: yaml
 
    spack:
-     # ...
+     ...
      view:
        default:
          root: /path/to/view
@@ -952,17 +920,6 @@ function, as shown in the example below:
      ^mpi: "{name}-{version}/{^mpi.name}-{^mpi.version}-{compiler.name}-{compiler.version}"
      all: "{name}-{version}/{compiler.name}-{compiler.version}"
 
-Projections also permit environment and spack configuration variable
-expansions as shown below:
-
-.. code-block:: yaml
-
-   projections:
-     all: "{name}-{version}/{compiler.name}-{compiler.version}/$date/$SYSTEM_ENV_VARIBLE"
-
-where ``$date`` is the spack configuration variable that will expand with the ``YYYY-MM-DD``
-format and ``$SYSTEM_ENV_VARIABLE`` is an environment variable defined in the shell.
-
 The entries in the projections configuration file must all be either
 specs or the keyword ``all``. For each spec, the projection used will
 be the first non-``all`` entry that the spec satisfies, or ``all`` if

lib/spack/docs/extensions.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -9,42 +9,46 @@
 Custom Extensions
 =================
 
-*Spack extensions* allow you to extend Spack capabilities by deploying your
+*Spack extensions* permit you to extend Spack capabilities by deploying your
 own custom commands or logic in an arbitrary location on your filesystem.
 This might be extremely useful e.g. to develop and maintain a command whose purpose is
 too specific to be considered for reintegration into the mainline or to
 evolve a command through its early stages before starting a discussion to merge
 it upstream.
-
 From Spack's point of view an extension is any path in your filesystem which
-respects the following naming and layout for files:
+respects a prescribed naming and layout for files:
 
 .. code-block:: console
 
   spack-scripting/ # The top level directory must match the format 'spack-{extension_name}'
   ├── pytest.ini # Optional file if the extension ships its own tests
   ├── scripting # Folder that may contain modules that are needed for the extension commands
-  │   ├── cmd # Folder containing extension commands
+  │   └── cmd # Folder containing extension commands
-  │   │   └── filter.py # A new command that will be available
+  │       └── filter.py # A new command that will be available
-  │   └── functions.py # Module with internal details
+  ├── tests # Tests for this extension
-  └── tests # Tests for this extension
   │   ├── conftest.py
   │   └── test_filter.py
   └── templates # Templates that may be needed by the extension
 
-In the example above, the extension is named *scripting*. It adds an additional command
+In the example above the extension named *scripting* adds an additional command (``filter``)
-(``spack filter``) and unit tests to verify its behavior.
+and unit tests to verify its behavior. The code for this example can be
+obtained by cloning the corresponding git repository:
 
-The extension can import any core Spack module in its implementation. When loaded by
+.. TODO: write an ad-hoc "hello world" extension and make it part of the spack organization
-the ``spack`` command, the extension itself is imported as a Python package in the
-``spack.extensions`` namespace. In the example above, since the extension is named
-"scripting", the corresponding Python module is ``spack.extensions.scripting``.
-
-The code for this example extension can be obtained by cloning the corresponding git repository:
 
 .. code-block:: console
 
-   $ git -C /tmp clone https://github.com/spack/spack-scripting.git
+   $ cd ~/
+   $ mkdir tmp && cd tmp
+   $ git clone https://github.com/alalazo/spack-scripting.git
+   Cloning into 'spack-scripting'...
+   remote: Counting objects: 11, done.
+   remote: Compressing objects: 100% (7/7), done.
+   remote: Total 11 (delta 0), reused 11 (delta 0), pack-reused 0
+   Receiving objects: 100% (11/11), done.
+
+As you can see by inspecting the sources, Python modules that are part of the extension
+can import any core Spack module.
 
 ---------------------------------
 Configure Spack to Use Extensions
@@ -57,7 +61,7 @@ paths to ``config.yaml``. In the case of our example this means ensuring that:
 
    config:
      extensions:
-     - /tmp/spack-scripting
+     - ~/tmp/spack-scripting
 
 is part of your configuration file. Once this is setup any command that the extension provides
 will be available from the command line:
@@ -82,68 +86,37 @@ will be available from the command line:
      --implicit       select specs that are not installed or were installed implicitly
      --output OUTPUT  where to dump the result
 
-The corresponding unit tests can be run giving the appropriate options to ``spack unit-test``:
+The corresponding unit tests can be run giving the appropriate options
+to ``spack unit-test``:
 
 .. code-block:: console
 
    $ spack unit-test --extension=scripting
-   ========================================== test session starts ===========================================
+
-   platform linux -- Python 3.11.5, pytest-7.4.3, pluggy-1.3.0
+   ============================================================== test session starts ===============================================================
-   rootdir: /home/culpo/github/spack-scripting
+   platform linux2 -- Python 2.7.15rc1, pytest-3.2.5, py-1.4.34, pluggy-0.4.0
-   configfile: pytest.ini
+   rootdir: /home/mculpo/tmp/spack-scripting, inifile: pytest.ini
-   testpaths: tests
-   plugins: xdist-3.5.0
    collected 5 items
 
-   tests/test_filter.py .....                                                                         [100%]
+   tests/test_filter.py ...XX
+   ============================================================ short test summary info =============================================================
+   XPASS tests/test_filter.py::test_filtering_specs[flags3-specs3-expected3]
+   XPASS tests/test_filter.py::test_filtering_specs[flags4-specs4-expected4]
 
-   ========================================== slowest 30 durations ==========================================
+   =========================================================== slowest 20 test durations ============================================================
-   2.31s setup    tests/test_filter.py::test_filtering_specs[kwargs0-specs0-expected0]
+   3.74s setup    tests/test_filter.py::test_filtering_specs[flags0-specs0-expected0]
-   0.57s call     tests/test_filter.py::test_filtering_specs[kwargs2-specs2-expected2]
+   0.17s call     tests/test_filter.py::test_filtering_specs[flags3-specs3-expected3]
-   0.56s call     tests/test_filter.py::test_filtering_specs[kwargs4-specs4-expected4]
+   0.16s call     tests/test_filter.py::test_filtering_specs[flags2-specs2-expected2]
-   0.54s call     tests/test_filter.py::test_filtering_specs[kwargs3-specs3-expected3]
+   0.15s call     tests/test_filter.py::test_filtering_specs[flags1-specs1-expected1]
-   0.54s call     tests/test_filter.py::test_filtering_specs[kwargs1-specs1-expected1]
+   0.13s call     tests/test_filter.py::test_filtering_specs[flags4-specs4-expected4]
-   0.48s call     tests/test_filter.py::test_filtering_specs[kwargs0-specs0-expected0]
+   0.08s call     tests/test_filter.py::test_filtering_specs[flags0-specs0-expected0]
-   0.01s setup    tests/test_filter.py::test_filtering_specs[kwargs4-specs4-expected4]
+   0.04s teardown tests/test_filter.py::test_filtering_specs[flags4-specs4-expected4]
-   0.01s setup    tests/test_filter.py::test_filtering_specs[kwargs2-specs2-expected2]
+   0.00s setup    tests/test_filter.py::test_filtering_specs[flags4-specs4-expected4]
-   0.01s setup    tests/test_filter.py::test_filtering_specs[kwargs1-specs1-expected1]
+   0.00s setup    tests/test_filter.py::test_filtering_specs[flags3-specs3-expected3]
-   0.01s setup    tests/test_filter.py::test_filtering_specs[kwargs3-specs3-expected3]
+   0.00s setup    tests/test_filter.py::test_filtering_specs[flags1-specs1-expected1]
-
+   0.00s setup    tests/test_filter.py::test_filtering_specs[flags2-specs2-expected2]
-   (5 durations < 0.005s hidden.  Use -vv to show these durations.)
+   0.00s teardown tests/test_filter.py::test_filtering_specs[flags2-specs2-expected2]
-   =========================================== 5 passed in 5.06s ============================================
+   0.00s teardown tests/test_filter.py::test_filtering_specs[flags1-specs1-expected1]
-
+   0.00s teardown tests/test_filter.py::test_filtering_specs[flags0-specs0-expected0]
----------------------------------------
+   0.00s teardown tests/test_filter.py::test_filtering_specs[flags3-specs3-expected3]
-Registering Extensions via Entry Points
+   ====================================================== 3 passed, 2 xpassed in 4.51 seconds =======================================================
----------------------------------------
-
-.. note::
-   Python version >= 3.8 is required to register extensions via entry points.
-
-Spack can be made aware of extensions that are installed as part of a python package.  To do so, register a function that returns the extension path, or paths, to the ``"spack.extensions"`` entry point.  Consider the Python package ``my_package`` that includes a Spack extension:
-
-.. code-block:: console
-
-  my-package/
-  ├── src
-  │   ├── my_package
-  │   │   └── __init__.py
-  │   └── spack-scripting/  # the spack extensions
-  └── pyproject.toml
-
-adding the following to ``my_package``'s ``pyproject.toml`` will make the ``spack-scripting`` extension visible to Spack when ``my_package`` is installed:
-
-.. code-block:: toml
-
-   [project.entry_points."spack.extenions"]
-   my_package = "my_package:get_extension_path"
-
-The function ``my_package.get_extension_path`` in ``my_package/__init__.py`` might look like
-
-.. code-block:: python
-
-   import importlib.resources
-
-   def get_extension_path():
-       dirname = importlib.resources.files("my_package").joinpath("spack-scripting")
-       if dirname.exists():
-           return str(dirname)

lib/spack/docs/features.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)

lib/spack/docs/frequently_asked_questions.rst

@@ -1,77 +0,0 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
-   Spack Project Developers. See the top-level COPYRIGHT file for details.
-
-   SPDX-License-Identifier: (Apache-2.0 OR MIT)
-
-==========================
-Frequently Asked Questions
-==========================
-
-This page contains answers to frequently asked questions about Spack.
-If you have questions that are not answered here, feel free to ask on
-`Slack <https://slack.spack.io>`_ or `GitHub Discussions
-<https://github.com/spack/spack/discussions>`_. If you've learned the
-answer to a question that you think should be here, please consider
-contributing to this page.
-
-.. _faq-concretizer-precedence:
-
------------------------------------------------------
-Why does Spack pick particular versions and variants?
------------------------------------------------------
-
-This question comes up in a variety of forms:
-
- 1. Why does Spack seem to ignore my package preferences from ``packages.yaml`` config?
- 2. Why does Spack toggle a variant instead of using the default from the ``package.py`` file?
-
-The short answer is that Spack always picks an optimal configuration
-based on a complex set of criteria\ [#f1]_. These criteria are more nuanced
-than always choosing the latest versions or default variants.
-
-.. note::
-
-    As a rule of thumb: requirements + constraints > reuse > preferences > defaults.
-
-The following set of criteria (from lowest to highest precedence) explain
-common cases where concretization output may seem surprising at first.
-
-1. :ref:`Package preferences <package-preferences>` configured in ``packages.yaml``
-   override variant defaults from ``package.py`` files, and influence the optimal
-   ordering of versions. Preferences are specified as follows:
-
-   .. code-block:: yaml
-
-      packages:
-        foo:
-          version: [1.0, 1.1]
-          variants: ~mpi
-
-2. :ref:`Reuse concretization <concretizer-options>` configured in ``concretizer.yaml``
-   overrides preferences, since it's typically faster to reuse an existing spec than to
-   build a preferred one from sources. When build caches are enabled, specs may be reused
-   from a remote location too. Reuse concretization is configured as follows:
-
-   .. code-block:: yaml
-
-      concretizer:
-        reuse: dependencies  # other options are 'true' and 'false'
-
-3. :ref:`Package requirements <package-requirements>` configured in ``packages.yaml``,
-   and constraints from the command line as well as ``package.py`` files override all
-   of the above. Requirements are specified as follows:
-
-   .. code-block:: yaml
-
-      packages:
-        foo:
-          require:
-          - "@1.2: +mpi"
-
-Requirements and constraints restrict the set of possible solutions, while reuse
-behavior and preferences influence what an optimal solution looks like.
-
-
-.. rubric:: Footnotes
-
-.. [#f1] The exact list of criteria can be retrieved with the ``spack solve`` command

lib/spack/docs/getting_started.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -250,10 +250,9 @@ Compiler configuration
 
 Spack has the ability to build packages with multiple compilers and
 compiler versions. Compilers can be made available to Spack by
-specifying them manually in ``compilers.yaml`` or ``packages.yaml``,
+specifying them manually in ``compilers.yaml``, or automatically by
-or automatically by running ``spack compiler find``, but for
+running ``spack compiler find``, but for convenience Spack will
-convenience Spack will automatically detect compilers the first time
+automatically detect compilers the first time it needs them.
-it needs them.
 
 .. _cmd-spack-compilers:
 
@@ -458,48 +457,6 @@ specification. The operations available to modify the environment are ``set``, `
          prepend_path: # Similar for append|remove_path
            LD_LIBRARY_PATH: /ld/paths/added/by/setvars/sh
 
-.. note::
-
-   Spack is in the process of moving compilers from a separate
-   attribute to be handled like all other packages. As part of this
-   process, the ``compilers.yaml`` section will eventually be replaced
-   by configuration in the ``packages.yaml`` section. This new
-   configuration is now available, although it is not yet the default
-   behavior.
-
-Compilers can also be configured as external packages in the
-``packages.yaml`` config file. Any external package for a compiler
-(e.g. ``gcc`` or ``llvm``) will be treated as a configured compiler
-assuming the paths to the compiler executables are determinable from
-the prefix.
-
-If the paths to the compiler executable are not determinable from the
-prefix, you can add them to the ``extra_attributes`` field. Similarly,
-all other fields from the compilers config can be added to the
-``extra_attributes`` field for an external representing a compiler.
-
-.. code-block:: yaml
-
-   packages:
-     gcc:
-       external:
-       - spec: gcc@12.2.0 arch=linux-rhel8-skylake
-         prefix: /usr
-         extra_attributes:
-           environment:
-             set:
-               GCC_ROOT: /usr
-       external:
-       - spec: llvm+clang@15.0.0 arch=linux-rhel8-skylake
-         prefix: /usr
-         extra_attributes:
-           paths:
-             cc: /usr/bin/clang-with-suffix
-             cxx: /usr/bin/clang++-with-extra-info
-             fc: /usr/bin/gfortran
-             f77: /usr/bin/gfortran
-           extra_rpaths:
-           - /usr/lib/llvm/
 
 ^^^^^^^^^^^^^^^^^^^^^^^
 Build Your Own Compiler
@@ -666,7 +623,7 @@ Fortran.
 
       compilers:
       - compiler:
-        # ...
+        ...
         paths:
           cc: /usr/bin/clang
           cxx: /usr/bin/clang++

lib/spack/docs/gpu_configuration.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -111,28 +111,3 @@ CUDA is split into fewer components and is simpler to specify:
          prefix: /opt/cuda/cuda-11.0.2/
 
 where ``/opt/cuda/cuda-11.0.2/lib/`` contains ``libcudart.so``.
-
-
-
------------------------------------
-Using an External OpenGL API
------------------------------------
-Depending on whether we have a graphics card or not, we may choose to use OSMesa or GLX to implement the OpenGL API.
-
-If a graphics card is unavailable, OSMesa is recommended and can typically be built with Spack.
-However, if we prefer to utilize the system GLX tailored to our graphics card, we need to declare it as an external. Here's how to do it:
-
-
-.. code-block:: yaml
-
-  packages:
-    libglx:
-      require: [opengl]
-    opengl:
-      buildable: false
-      externals:
-      - prefix: /usr/
-        spec: opengl@4.6
-
-Note that prefix has to be the root of both the libraries and the headers, using is /usr not the path the the lib.
-To know which spec for opengl is available use ``cd /usr/include/GL && grep -Ri gl_version``.

lib/spack/docs/index.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -55,7 +55,6 @@ or refer to the full manual below.
    getting_started
    basic_usage
    replace_conda_homebrew
-   frequently_asked_questions
 
 .. toctree::
    :maxdepth: 2
@@ -71,7 +70,7 @@ or refer to the full manual below.
 
    configuration
    config_yaml
-   packages_yaml
+   bootstrapping
    build_settings
    environments
    containers
@@ -79,7 +78,6 @@ or refer to the full manual below.
    module_file_support
    repositories
    binary_caches
-   bootstrapping
    command_index
    chain
    extensions

lib/spack/docs/mirrors.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)

lib/spack/docs/module_file_support.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -10,7 +10,7 @@ Modules (modules.yaml)
 ======================
 
 The use of module systems to manage user environment in a controlled way
-is a common practice at HPC centers that is sometimes embraced also by
+is a common practice at HPC centers that is often embraced also by
 individual programmers on their development machines. To support this
 common practice Spack integrates with `Environment Modules
 <http://modules.sourceforge.net/>`_ and `Lmod
@@ -21,38 +21,14 @@ Modules are one of several ways you can use Spack packages. For other
 options that may fit your use case better, you should also look at
 :ref:`spack load <spack-load>` and :ref:`environments <environments>`.
 
------------
+----------------------------
-Quick start
+Using module files via Spack
------------
+----------------------------
 
-In the current version of Spack, module files are not generated by default. To get started, you
+If you have installed a supported module system you should be able to
-can generate module files for all currently installed packages by running either
+run ``module avail`` to see what module
-
+files have been installed. Here is sample output of those programs,
-.. code-block:: console
+showing lots of installed packages:
-
-   $ spack module tcl refresh
-
-or
-
-.. code-block:: console
-
-   $ spack module lmod refresh
-
-Spack can also generate module files for all future installations automatically through the
-following configuration:
-
-.. code-block:: console
-
-   $ spack config add modules:default:enable:[tcl]
-
-or
-
-.. code-block:: console
-
-   $ spack config add modules:default:enable:[lmod]
-
-Assuming you have a module system installed, you should now be able to use the ``module`` command
-to interact with them:
 
 .. code-block:: console
 
@@ -89,17 +65,33 @@ scheme used at your site.
 Module file customization
 -------------------------
 
+Module files are generated by post-install hooks after the successful
+installation of a package.
+
+.. note::
+
+   Spack only generates modulefiles when a package is installed. If
+   you attempt to install a package and it is already installed, Spack
+   will not regenerate modulefiles for the package. This may lead to
+   inconsistent modulefiles if the Spack module configuration has
+   changed since the package was installed, either by editing a file
+   or changing scopes or environments.
+
+   Later in this section there is a subsection on :ref:`regenerating
+   modules <cmd-spack-module-refresh>` that will allow you to bring
+   your modules to a consistent state.
+
 The table below summarizes the essential information associated with
 the different file formats that can be generated by Spack:
 
 
-  +-----------+--------------+------------------------------+----------------------------------------------+----------------------+
+  +-----------------------------+--------------------+-------------------------------+----------------------------------------------+----------------------+
-  |           | Hierarchical |  **Default root directory**  | **Default template file**                    | **Compatible tools** |
+  |                             | **Hook name**      |  **Default root directory**   | **Default template file**                    | **Compatible tools** |
-  +===========+==============+==============================+==============================================+======================+
+  +=============================+====================+===============================+==============================================+======================+
-  |  ``tcl``  | No           | share/spack/modules          | share/spack/templates/modules/modulefile.tcl | Env. Modules/Lmod    |
+  |  **Tcl - Non-Hierarchical** | ``tcl``            |  share/spack/modules          | share/spack/templates/modules/modulefile.tcl | Env. Modules/Lmod    |
-  +-----------+--------------+------------------------------+----------------------------------------------+----------------------+
+  +-----------------------------+--------------------+-------------------------------+----------------------------------------------+----------------------+
-  |  ``lmod`` | Yes          | share/spack/lmod             | share/spack/templates/modules/modulefile.lua | Lmod                 |
+  |  **Lua - Hierarchical**     | ``lmod``           |  share/spack/lmod             | share/spack/templates/modules/modulefile.lua | Lmod                 |
-  +-----------+--------------+------------------------------+----------------------------------------------+----------------------+
+  +-----------------------------+--------------------+-------------------------------+----------------------------------------------+----------------------+
 
 
 Spack ships with sensible defaults for the generation of module files, but
@@ -110,7 +102,7 @@ In general you can override or extend the default behavior by:
  2. writing specific rules in the ``modules.yaml`` configuration file
  3. writing your own templates to override or extend the defaults
 
-The former method lets you express changes in the run-time environment
+The former method let you express changes in the run-time environment
 that are needed to use the installed software properly, e.g. injecting variables
 from language interpreters into their extensions. The latter two instead permit to
 fine tune the filesystem layout, content and creation of module files to meet
@@ -118,62 +110,79 @@ site specific conventions.
 
 .. _overide-api-calls-in-package-py:
 
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Setting environment variables dynamically in ``package.py``
+Override API calls in ``package.py``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-There are two methods that you can implement in any ``package.py`` to dynamically affect the
+There are two methods that you can override in any ``package.py`` to affect the
-content of the module files generated by Spack. The most important one is
+content of the module files generated by Spack. The first one:
-``setup_run_environment``, which can be used to set environment variables in the module file that
-depend on the spec:
 
 .. code-block:: python
 
    def setup_run_environment(self, env):
-       if self.spec.satisfies("+foo"):
+       pass
-           env.set("FOO", "bar")
 
-The second, less commonly used, is ``setup_dependent_run_environment(self, env, dependent_spec)``,
+can alter the content of the module file associated with the same package where it is overridden.
-which allows a dependency to set variables in the module file of its dependents. This is typically
+The second method:
-used in packages like ``python``, ``r``, or ``perl`` to prepend the dependent's prefix to the
-search path of the interpreter (``PYTHONPATH``, ``R_LIBS``, ``PERL5LIB`` resp.), so it can locate
-the packages at runtime.
-
-For example, a simplified version of the ``python`` package could look like this:
 
 .. code-block:: python
 
    def setup_dependent_run_environment(self, env, dependent_spec):
-       if dependent_spec.package.extends(self.spec):
+       pass
-           env.prepend_path("PYTHONPATH", dependent_spec.prefix.lib.python)
 
-and would make any package that ``extends("python")`` have its library directory added to the
+can instead inject run-time environment modifications in the module files of packages
-``PYTHONPATH`` environment variable in the module file. It's much more convenient to set this
+that depend on it. In both cases you need to fill ``env`` with the desired
-variable here, than to repeat it in every Python extension's ``setup_run_environment`` method.
+list of environment modifications.
+
+.. admonition:: The ``r`` package and callback APIs
+
+  An example in which it is crucial to override both methods
+  is given by the ``r`` package. This package installs libraries and headers
+  in non-standard locations and it is possible to prepend the appropriate directory
+  to the corresponding environment variables:
+
+  ================== =================================
+   LD_LIBRARY_PATH    ``self.prefix/rlib/R/lib``
+   PKG_CONFIG_PATH    ``self.prefix/rlib/pkgconfig``
+  ================== =================================
+
+  with the following snippet:
+
+  .. literalinclude:: _spack_root/var/spack/repos/builtin/packages/r/package.py
+     :pyobject: R.setup_run_environment
+
+  The ``r`` package also knows which environment variable should be modified
+  to make language extensions provided by other packages available, and modifies
+  it appropriately in the override of the second method:
+
+  .. literalinclude:: _spack_root/var/spack/repos/builtin/packages/r/package.py
+     :pyobject: R.setup_dependent_run_environment
 
 .. _modules-yaml:
 
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^
-The ``modules.yaml`` config file and module sets
+Write a configuration file
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The configuration files that control module generation behavior are named ``modules.yaml``. The
+The configuration files that control module generation behavior
-default configuration looks like this:
+are named ``modules.yaml``. The default configuration:
 
 .. literalinclude:: _spack_root/etc/spack/defaults/modules.yaml
    :language: yaml
 
-You can define one or more **module sets**, each of which can be configured separately with regard
+activates the hooks to generate ``tcl`` module files and inspects
-to install location, naming scheme, inclusion and exclusion, autoloading, et cetera.
+the installation folder of each package for the presence of a set of subdirectories
+(``bin``, ``man``, ``share/man``, etc.). If any is found its full path is prepended
+to the environment variables listed below the folder name.
 
-The default module set is aptly named ``default``. All
+Spack modules can be configured for multiple module sets. The default
-:ref:`Spack commands that operate on modules <maintaining-module-files>` apply to the ``default``
+module set is named ``default``. All Spack commands which operate on
-module set, unless another module set is specified explicitly (with the ``--name`` flag).
+modules default to apply the ``default`` module set, but can be
+applied to any module set in the configuration.
 
-
+"""""""""""""""""""""""""
-^^^^^^^^^^^^^^^^^^^^^^^^^
 Changing the modules root
-^^^^^^^^^^^^^^^^^^^^^^^^^
+"""""""""""""""""""""""""
 
 As shown in the table above, the default module root for ``lmod`` is
 ``$spack/share/spack/lmod`` and the default root for ``tcl`` is
@@ -189,7 +198,7 @@ set by changing the ``roots`` key of the configuration.
      my_custom_lmod_modules:
        roots:
          lmod: /path/to/install/custom/lmod/modules
-         # ...
+         ...
 
 This configuration will create two module sets. The default module set
 will install its ``tcl`` modules to ``/path/to/install/tcl/modules``
@@ -215,32 +224,25 @@ location could be confusing to users of your modules. In the next
 section, we will discuss enabling and disabling module types (module
 file generators) for each module set.
 
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+""""""""""""""""""""
-Automatically generating module files
+Activate other hooks
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+""""""""""""""""""""
 
-Spack can be configured to automatically generate module files as part of package installation.
+Any other module file generator shipped with Spack can be activated adding it to the
-This is done by adding the desired module systems to the ``enable`` list.
+list under the ``enable`` key in the module file. Currently the only generator that
+is not active by default is ``lmod``, which produces hierarchical lua module files.
+
+Each module system can then be configured separately. In fact, you should list configuration
+options that affect a particular type of module files under a top level key corresponding
+to the generator being customized:
 
 .. code-block:: yaml
 
    modules:
      default:
        enable:
-       - tcl
+         - tcl
-       - lmod
+         - lmod
-
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Configuring ``tcl`` and ``lmod`` modules
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-You can configure the behavior of either module system separately, under a key corresponding to
-the generator being customized:
-
-.. code-block:: yaml
-
-   modules:
-     default:
        tcl:
          # contains environment modules specific customizations
        lmod:
@@ -251,82 +253,16 @@ either change the layout of the module files on the filesystem, or they will aff
 their content. For the latter point it is possible to use anonymous specs
 to fine tune the set of packages on which the modifications should be applied.
 
-.. _autoloading-dependencies:
-
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Autoloading and hiding dependencies
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A module file should set the variables that are needed for an application to work. But since an
-application often has many dependencies, where should all the environment variables for those be
-set? In Spack the rule is that each package sets the runtime variables that are needed by the
-package itself, and no more. This way, dependencies can be loaded standalone too, and duplication
-of environment variables is avoided.
-
-That means however that if you want to use an application, you need to load the modules for all its
-dependencies. Of course this is not something you would want users to do manually.
-
-Since Spack knows the dependency graph of every package, it can easily generate module files that
-automatically load the modules for its dependencies recursively. It is enabled by default for both
-Lmod and Environment Modules under the ``autoload: direct`` config option. The former system has
-builtin support through the ``depends_on`` function, the latter simply uses a ``module load``
-statement. Both module systems (at least in newer versions) do reference counting, so that if a
-module is loaded by two different modules, it will only be unloaded after the others are.
-
-The ``autoload`` key accepts the values:
-
-  * ``none``: no autoloading
-  * ``run``: autoload direct *run* type dependencies
-  * ``direct``: autoload direct *link and run* type dependencies
-  * ``all``: autoload all dependencies
-
-In case of ``run`` and ``direct``, a ``module load`` triggers a recursive load.
-
-The ``direct`` option is most correct: there are cases where pure link dependencies need to set
-variables for themselves, or need to have variables of their own dependencies set.
-
-In practice however, ``run`` is often sufficient, and may make ``module load`` snappier.
-
-The ``all`` option is discouraged and seldomly used.
-
-A common complaint about autoloading is the large number of modules that are visible to the user.
-Spack has a solution for this as well: ``hide_implicits: true``. This ensures that only those
-packages you've explicitly installed are exposed by ``module avail``, but still allows for
-autoloading of hidden dependencies. Lmod should support hiding implicits in general, while
-Environment Modules requires version 4.7 or higher.
-
-.. note::
-   If supported by your module system, we highly encourage the following configuration that enables
-   autoloading and hiding of implicits. It ensures all runtime variables are set correctly,
-   including those for dependencies, without overwhelming the user with a large number of available
-   modules. Further, it makes it easier to get readable module names without collisions, see the
-   section below on :ref:`modules-projections`.
-
-    .. code-block:: yaml
-  
-        modules:
-          default:
-            tcl:
-              hide_implicits: true
-              all:
-                autoload: direct # or `run`
-            lmod:
-              hide_implicits: true
-              all:
-                autoload: direct # or `run`
-
 .. _anonymous_specs:
 
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+""""""""""""""""""""""""""""
-Setting environment variables for selected packages in config
+Selection by anonymous specs
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+""""""""""""""""""""""""""""
 
-In the configuration file you can filter particular specs, and make further changes to the
+In the configuration file you can use *anonymous specs* (i.e. specs
-environment variables that go into their module files. This is very powerful when you want to avoid
+that **are not required to have a root package** and are thus used just
-:ref:`modifying the package itself <overide-api-calls-in-package-py>`, or when you want to set
+to express constraints) to apply certain modifications on a selected set
-certain variables on multiple selected packages at once.
+of the installed software. For instance, in the snippet below:
-
-For instance, in the snippet below:
 
 .. code-block:: yaml
 
@@ -369,28 +305,12 @@ the variable ``FOOBAR`` will be unset.
 .. note::
    Order does matter
      The modifications associated with the ``all`` keyword are always evaluated
-     first, no matter where they appear in the configuration file. All the other changes to
+     first, no matter where they appear in the configuration file. All the other
-     environment variables for matching specs are evaluated from top to bottom.
+     spec constraints are instead evaluated top to bottom.
 
-.. warning::
+""""""""""""""""""""""""""""""""""""""""""""
-
-     As general advice, it's often better to set as few unnecessary variables as possible. For
-     example, the following seemingly innocent and potentially useful configuration
-
-     .. code-block:: yaml
-
-        all:
-          environment:
-            set:
-              "{name}_ROOT": "{prefix}"
-
-     sets ``BINUTILS_ROOT`` to its prefix in modules for ``binutils``, which happens to break
-     the ``gcc`` compiler: it uses this variable as its default search path for certain object
-     files and libraries, and by merely setting it, everything fails to link.
-
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Exclude or include specific module files
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+""""""""""""""""""""""""""""""""""""""""""""
 
 You can use anonymous specs also to prevent module files from being written or
 to force them to be written. Consider the case where you want to hide from users
@@ -410,19 +330,14 @@ you will prevent the generation of module files for any package that
 is compiled with ``gcc@4.4.7``, with the only exception of any ``gcc``
 or any ``llvm`` installation.
 
-It is safe to combine ``exclude`` and ``autoload``
-:ref:`mentioned above <autoloading-dependencies>`. When ``exclude`` prevents a module file to be
-generated for a dependency, the ``autoload`` feature will simply not generate a statement to load
-it.
-
 
 .. _modules-projections:
 
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+"""""""""""""""""""""""""""""""
 Customize the naming of modules
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+"""""""""""""""""""""""""""""""
 
-The names of environment modules generated by Spack are not always easy to
+The names of environment modules generated by spack are not always easy to
 fully comprehend due to the long hash in the name. There are three module
 configuration options to help with that. The first is a global setting to
 adjust the hash length. It can be set anywhere from 0 to 32 and has a default
@@ -438,13 +353,6 @@ shows how to set hash length in the module file names:
        tcl:
          hash_length: 7
 
-.. tip::
-
-   Using ``hide_implicits: true`` (see :ref:`autoloading-dependencies`) vastly reduces the number
-   modules exposed to the user. The hidden modules always contain the hash in their name, and are
-   not influenced by the ``hash_length`` setting. Hidden implicits thus make it easier to use a
-   short hash length or no hash at all, without risking name conflicts.
-
 To help make module names more readable, and to help alleviate name conflicts
 with a short hash, one can use the ``suffixes`` option in the modules
 configuration file. This option will add strings to modules that match a spec.
@@ -457,12 +365,12 @@ For instance, the following config options,
        tcl:
          all:
            suffixes:
-             ^python@3.12: 'python-3.12'
+             ^python@2.7.12: 'python-2.7.12'
              ^openblas: 'openblas'
 
-will add a ``python-3.12`` version string to any packages compiled with
+will add a ``python-2.7.12`` version string to any packages compiled with
-Python matching the spec, ``python@3.12``. This is useful to know which
+python matching the spec, ``python@2.7.12``. This is useful to know which
-version of Python a set of Python extensions is associated with. Likewise, the
+version of python a set of python extensions is associated with. Likewise, the
 ``openblas`` string is attached to any program that has openblas in the spec,
 most likely via the ``+blas`` variant specification.
 
@@ -560,11 +468,41 @@ that are already in the Lmod hierarchy.
    For hierarchies that are deeper than three layers ``lmod spider`` may have some issues.
    See `this discussion on the Lmod project <https://github.com/TACC/Lmod/issues/114>`_.
 
+""""""""""""""""""""""
+Select default modules
+""""""""""""""""""""""
+
+By default, when multiple modules of the same name share a directory,
+the highest version number will be the default module. This behavior
+of the ``module`` command can be overridden with a symlink named
+``default`` to the desired default module. If you wish to configure
+default modules with Spack, add a ``defaults`` key to your modules
+configuration:
+
+.. code-block:: yaml
+
+  modules:
+    my-module-set:
+      tcl:
+        defaults:
+        - gcc@10.2.1
+        - hdf5@1.2.10+mpi+hl%gcc
+
+These defaults may be arbitrarily specific. For any package that
+satisfies a default, Spack will generate the module file in the
+appropriate path, and will generate a default symlink to the module
+file as well.
+
+.. warning::
+  If Spack is configured to generate multiple default packages in the
+  same directory, the last modulefile to be generated will be the
+  default module.
+
 .. _customize-env-modifications:
 
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+"""""""""""""""""""""""""""""""""""
 Customize environment modifications
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+"""""""""""""""""""""""""""""""""""
 
 You can control which prefixes in a Spack package are added to
 environment variables with the ``prefix_inspections`` section; this
@@ -662,9 +600,9 @@ stack to users who are likely to inspect the modules to find full
 paths to software, when it is desirable to present the users with a
 simpler set of paths than those generated by the Spack install tree.
 
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+""""""""""""""""""""""""""""""""""""
 Filter out environment modifications
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+""""""""""""""""""""""""""""""""""""
 
 Modifications to certain environment variables in module files are there by
 default, for instance because they are generated by prefix inspections.
@@ -684,37 +622,49 @@ do so by using the ``exclude_env_vars``:
 The configuration above will generate module files that will not contain
 modifications to either ``CPATH`` or ``LIBRARY_PATH``.
 
-^^^^^^^^^^^^^^^^^^^^^^
-Select default modules
-^^^^^^^^^^^^^^^^^^^^^^
 
-By default, when multiple modules of the same name share a directory,
+.. _autoloading-dependencies:
-the highest version number will be the default module. This behavior
+
-of the ``module`` command can be overridden with a symlink named
+"""""""""""""""""""""
-``default`` to the desired default module. If you wish to configure
+Autoload dependencies
-default modules with Spack, add a ``defaults`` key to your modules
+"""""""""""""""""""""
-configuration:
+
+Often it is required for a module to have its (transient) dependencies loaded as well.
+One example where this is useful is when one package needs to use executables provided
+by its dependency; when the dependency is autoloaded, the executable will be in the
+PATH. Similarly for scripting languages such as Python, packages and their dependencies
+have to be loaded together.
+
+Autoloading is enabled by default for Lmod and Environment Modules. The former
+has builtin support for through the ``depends_on`` function. The latter uses
+``module load`` statement to load and track dependencies.
+
+Autoloading can also be enabled conditionally:
 
 .. code-block:: yaml
 
-  modules:
+    modules:
-    my-module-set:
+      default:
-      tcl:
+        tcl:
-        defaults:
+          all:
-        - gcc@10.2.1
+            autoload: none
-        - hdf5@1.2.10+mpi+hl%gcc
+          ^python:
+            autoload: direct
 
-These defaults may be arbitrarily specific. For any package that
+The configuration file above will produce module files that will
-satisfies a default, Spack will generate the module file in the
+load their direct dependencies if the package installed depends on ``python``.
-appropriate path, and will generate a default symlink to the module
+The allowed values for the ``autoload`` statement are either ``none``,
-file as well.
+``direct`` or ``all``.
 
-.. warning::
+.. note::
-  If Spack is configured to generate multiple default packages in the
+  Tcl prerequisites
-  same directory, the last modulefile to be generated will be the
+     In the ``tcl`` section of the configuration file it is possible to use
-  default module.
+     the ``prerequisites`` directive that accepts the same values as
-
+     ``autoload``. It will produce module files that have a ``prereq``
-.. _maintaining-module-files:
+     statement, which autoloads dependencies on Environment Modules when its
+     ``auto_handling`` configuration option is enabled. If Environment Modules
+     is installed with Spack, ``auto_handling`` is enabled by default starting
+     version 4.2. Otherwise it is enabled by default since version 5.0.
 
 ------------------------
 Maintaining Module Files

lib/spack/docs/packages_yaml.rst

@@ -1,673 +0,0 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
-   Spack Project Developers. See the top-level COPYRIGHT file for details.
-
-   SPDX-License-Identifier: (Apache-2.0 OR MIT)
-
-
-.. _packages-config:
-
-================================
-Package Settings (packages.yaml)
-================================
-
-Spack allows you to customize how your software is built through the
-``packages.yaml`` file.  Using it, you can make Spack prefer particular
-implementations of virtual dependencies (e.g., MPI or BLAS/LAPACK),
-or you can make it prefer to build with particular compilers.  You can
-also tell Spack to use *external* software installations already
-present on your system.
-
-At a high level, the ``packages.yaml`` file is structured like this:
-
-.. code-block:: yaml
-
-   packages:
-     package1:
-       # settings for package1
-     package2:
-       # settings for package2
-     # ...
-     all:
-       # settings that apply to all packages.
-
-So you can either set build preferences specifically for *one* package,
-or you can specify that certain settings should apply to *all* packages.
-The types of settings you can customize are described in detail below.
-
-Spack's build defaults are in the default
-``etc/spack/defaults/packages.yaml`` file.  You can override them in
-``~/.spack/packages.yaml`` or ``etc/spack/packages.yaml``. For more
-details on how this works, see :ref:`configuration-scopes`.
-
-.. _sec-external-packages:
-
------------------
-External Packages
------------------
-
-Spack can be configured to use externally-installed
-packages rather than building its own packages. This may be desirable
-if machines ship with system packages, such as a customized MPI
-that should be used instead of Spack building its own MPI.
-
-External packages are configured through the ``packages.yaml`` file.
-Here's an example of an external configuration:
-
-.. code-block:: yaml
-
-   packages:
-     openmpi:
-       externals:
-       - spec: "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64"
-         prefix: /opt/openmpi-1.4.3
-       - spec: "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64+debug"
-         prefix: /opt/openmpi-1.4.3-debug
-       - spec: "openmpi@1.6.5%intel@10.1 arch=linux-debian7-x86_64"
-         prefix: /opt/openmpi-1.6.5-intel
-
-This example lists three installations of OpenMPI, one built with GCC,
-one built with GCC and debug information, and another built with Intel.
-If Spack is asked to build a package that uses one of these MPIs as a
-dependency, it will use the pre-installed OpenMPI in
-the given directory. Note that the specified path is the top-level
-install prefix, not the ``bin`` subdirectory.
-
-``packages.yaml`` can also be used to specify modules to load instead
-of the installation prefixes.  The following example says that module
-``CMake/3.7.2`` provides cmake version 3.7.2.
-
-.. code-block:: yaml
-
-   cmake:
-     externals:
-     - spec: cmake@3.7.2
-       modules:
-       - CMake/3.7.2
-
-Each ``packages.yaml`` begins with a ``packages:`` attribute, followed
-by a list of package names.  To specify externals, add an ``externals:``
-attribute under the package name, which lists externals.
-Each external should specify a ``spec:`` string that should be as
-well-defined as reasonably possible.  If a
-package lacks a spec component, such as missing a compiler or
-package version, then Spack will guess the missing component based
-on its most-favored packages, and it may guess incorrectly.
-
-Each package version and compiler listed in an external should
-have entries in Spack's packages and compiler configuration, even
-though the package and compiler may not ever be built.
-
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Extra attributes for external packages
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Sometimes external packages require additional attributes to be used
-effectively. This information can be defined on a per-package basis
-and stored in the ``extra_attributes`` section of the external package
-configuration. In addition to per-package information, this section
-can be used to define environment modifications to be performed
-whenever the package is used. For example, if an external package is
-built without ``rpath`` support, it may require ``LD_LIBRARY_PATH``
-settings to find its dependencies. This could be configured as
-follows:
-
-.. code-block:: yaml
-
-   packages:
-     mpich:
-       externals:
-       - spec: mpich@3.3 %clang@12.0.0 +hwloc
-         prefix: /path/to/mpich
-         extra_attributes:
-           environment:
-             prepend_path:
-               LD_LIBRARY_PATH: /path/to/hwloc/lib64
-
-See :ref:`configuration_environment_variables` for more information on
-how to configure environment modifications in Spack config files.
-
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Prevent packages from being built from sources
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Adding an external spec in ``packages.yaml`` allows Spack to use an external location,
-but it does not prevent Spack from building packages from sources. In the above example,
-Spack might choose for many valid reasons to start building and linking with the
-latest version of OpenMPI rather than continue using the pre-installed OpenMPI versions.
-
-To prevent this, the ``packages.yaml`` configuration also allows packages
-to be flagged as non-buildable.  The previous example could be modified to
-be:
-
-.. code-block:: yaml
-
-   packages:
-     openmpi:
-       externals:
-       - spec: "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64"
-         prefix: /opt/openmpi-1.4.3
-       - spec: "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64+debug"
-         prefix: /opt/openmpi-1.4.3-debug
-       - spec: "openmpi@1.6.5%intel@10.1 arch=linux-debian7-x86_64"
-         prefix: /opt/openmpi-1.6.5-intel
-       buildable: False
-
-The addition of the ``buildable`` flag tells Spack that it should never build
-its own version of OpenMPI from sources, and it will instead always rely on a pre-built
-OpenMPI.
-
-.. note::
-
-   If ``concretizer:reuse`` is on (see :ref:`concretizer-options` for more information on that flag)
-   pre-built specs include specs already available from a local store, an upstream store, a registered
-   buildcache or specs marked as externals in ``packages.yaml``. If ``concretizer:reuse`` is off, only
-   external specs in ``packages.yaml`` are included in the list of pre-built specs.
-
-If an external module is specified as not buildable, then Spack will load the
-external module into the build environment which can be used for linking.
-
-The ``buildable`` does not need to be paired with external packages.
-It could also be used alone to forbid packages that may be
-buggy or otherwise undesirable.
-
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Non-buildable virtual packages
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Virtual packages in Spack can also be specified as not buildable, and
-external implementations can be provided. In the example above,
-OpenMPI is configured as not buildable, but Spack will often prefer
-other MPI implementations over the externally available OpenMPI. Spack
-can be configured with every MPI provider not buildable individually,
-but more conveniently:
-
-.. code-block:: yaml
-
-   packages:
-     mpi:
-       buildable: False
-     openmpi:
-       externals:
-       - spec: "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64"
-         prefix: /opt/openmpi-1.4.3
-       - spec: "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64+debug"
-         prefix: /opt/openmpi-1.4.3-debug
-       - spec: "openmpi@1.6.5%intel@10.1 arch=linux-debian7-x86_64"
-         prefix: /opt/openmpi-1.6.5-intel
-
-Spack can then use any of the listed external implementations of MPI
-to satisfy a dependency, and will choose depending on the compiler and
-architecture.
-
-In cases where the concretizer is configured to reuse specs, and other ``mpi`` providers
-(available via stores or buildcaches) are not wanted, Spack can be configured to require
-specs matching only the available externals:
-
-.. code-block:: yaml
-
-   packages:
-     mpi:
-       buildable: False
-       require:
-       - one_of: [
-           "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64",
-           "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64+debug",
-           "openmpi@1.6.5%intel@10.1 arch=linux-debian7-x86_64"
-         ]
-     openmpi:
-       externals:
-       - spec: "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64"
-         prefix: /opt/openmpi-1.4.3
-       - spec: "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64+debug"
-         prefix: /opt/openmpi-1.4.3-debug
-       - spec: "openmpi@1.6.5%intel@10.1 arch=linux-debian7-x86_64"
-         prefix: /opt/openmpi-1.6.5-intel
-
-This configuration prevents any spec using MPI and originating from stores or buildcaches to be reused,
-unless it matches the requirements under ``packages:mpi:require``. For more information on requirements see
-:ref:`package-requirements`.
-
-.. _cmd-spack-external-find:
-
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Automatically Find External Packages
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-You can run the :ref:`spack external find <spack-external-find>` command
-to search for system-provided packages and add them to ``packages.yaml``.
-After running this command your ``packages.yaml`` may include new entries:
-
-.. code-block:: yaml
-
-   packages:
-     cmake:
-       externals:
-       - spec: cmake@3.17.2
-         prefix: /usr
-
-Generally this is useful for detecting a small set of commonly-used packages;
-for now this is generally limited to finding build-only dependencies.
-Specific limitations include:
-
-* Packages are not discoverable by default: For a package to be
-  discoverable with ``spack external find``, it needs to add special
-  logic. See :ref:`here <make-package-findable>` for more details.
-* The logic does not search through module files, it can only detect
-  packages with executables defined in ``PATH``; you can help Spack locate
-  externals which use module files by loading any associated modules for
-  packages that you want Spack to know about before running
-  ``spack external find``.
-* Spack does not overwrite existing entries in the package configuration:
-  If there is an external defined for a spec at any configuration scope,
-  then Spack will not add a new external entry (``spack config blame packages``
-  can help locate all external entries).
-
-.. _package-requirements:
-
---------------------
-Package Requirements
---------------------
-
-Spack can be configured to always use certain compilers, package
-versions, and variants during concretization through package
-requirements.
-
-Package requirements are useful when you find yourself repeatedly
-specifying the same constraints on the command line, and wish that
-Spack respects these constraints whether you mention them explicitly
-or not. Another use case is specifying constraints that should apply
-to all root specs in an environment, without having to repeat the
-constraint everywhere.
-
-Apart from that, requirements config is more flexible than constraints
-on the command line, because it can specify constraints on packages
-*when they occur* as a dependency. In contrast, on the command line it
-is not possible to specify constraints on dependencies while also keeping
-those dependencies optional.
-
-.. seealso::
-
-   FAQ: :ref:`Why does Spack pick particular versions and variants? <faq-concretizer-precedence>`
-
-
-^^^^^^^^^^^^^^^^^^^
-Requirements syntax
-^^^^^^^^^^^^^^^^^^^
-
-The package requirements configuration is specified in ``packages.yaml``,
-keyed by package name and expressed using the Spec syntax. In the simplest
-case you can specify attributes that you always want the package to have
-by providing a single spec string to ``require``:
-
-.. code-block:: yaml
-
-   packages:
-     libfabric:
-       require: "@1.13.2"
-
-In the above example, ``libfabric`` will always build with version 1.13.2. If you
-need to compose multiple configuration scopes ``require`` accepts a list of
-strings:
-
-.. code-block:: yaml
-
-   packages:
-     libfabric:
-       require:
-       - "@1.13.2"
-       - "%gcc"
-
-In this case ``libfabric`` will always build with version 1.13.2 **and** using GCC
-as a compiler.
-
-For more complex use cases, require accepts also a list of objects. These objects
-must have either a ``any_of`` or a ``one_of`` field, containing a list of spec strings,
-and they can optionally have a ``when`` and a ``message`` attribute:
-
-.. code-block:: yaml
-
-   packages:
-     openmpi:
-       require:
-       - any_of: ["@4.1.5", "%gcc"]
-         message: "in this example only 4.1.5 can build with other compilers"
-
-``any_of`` is a list of specs. One of those specs must be satisfied
-and it is also allowed for the concretized spec to match more than one.
-In the above example, that means you could build ``openmpi@4.1.5%gcc``,
-``openmpi@4.1.5%clang`` or ``openmpi@3.9%gcc``, but
-not ``openmpi@3.9%clang``.
-
-If a custom message is provided, and the requirement is not satisfiable,
-Spack will print the custom error message:
-
-.. code-block:: console
-
-   $ spack spec openmpi@3.9%clang
-   ==> Error: in this example only 4.1.5 can build with other compilers
-
-We could express a similar requirement using the ``when`` attribute:
-
-.. code-block:: yaml
-
-   packages:
-     openmpi:
-       require:
-       - any_of: ["%gcc"]
-         when: "@:4.1.4"
-         message: "in this example only 4.1.5 can build with other compilers"
-
-In the example above, if the version turns out to be 4.1.4 or less, we require the compiler to be GCC.
-For readability, Spack also allows a ``spec`` key accepting a string when there is only a single
-constraint:
-
-.. code-block:: yaml
-
-   packages:
-     openmpi:
-       require:
-       - spec: "%gcc"
-         when: "@:4.1.4"
-         message: "in this example only 4.1.5 can build with other compilers"
-
-This code snippet and the one before it are semantically equivalent.
-
-Finally, instead of ``any_of`` you can use ``one_of`` which also takes a list of specs. The final
-concretized spec must match one and only one of them:
-
-.. code-block:: yaml
-
-   packages:
-     mpich:
-       require:
-       - one_of: ["+cuda", "+rocm"]
-
-In the example above, that means you could build ``mpich+cuda`` or ``mpich+rocm`` but not ``mpich+cuda+rocm``.
-
-.. note::
-
-   For ``any_of`` and ``one_of``, the order of specs indicates a
-   preference: items that appear earlier in the list are preferred
-   (note that these preferences can be ignored in favor of others).
-
-.. note::
-
-   When using a conditional requirement, Spack is allowed to actively avoid the triggering
-   condition (the ``when=...`` spec) if that leads to a concrete spec with better scores in
-   the optimization criteria. To check the current optimization criteria and their
-   priorities you can run ``spack solve zlib``.
-
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Setting default requirements
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-You can also set default requirements for all packages under ``all``
-like this:
-
-.. code-block:: yaml
-
-   packages:
-     all:
-       require: '%clang'
-
-which means every spec will be required to use ``clang`` as a compiler.
-
-Requirements on variants for all packages are possible too, but note that they
-are only enforced for those packages that define these variants, otherwise they
-are disregarded. For example:
-
-.. code-block:: yaml
-
-   packages:
-     all:
-       require:
-       - "+shared"
-       - "+cuda"
-
-will just enforce ``+shared`` on ``zlib``, which has a boolean ``shared`` variant but
-no ``cuda`` variant.
-
-Constraints in a single spec literal are always considered as a whole, so in a case like:
-
-.. code-block:: yaml
-
-   packages:
-     all:
-       require: "+shared +cuda"
-
-the default requirement will be enforced only if a package has both a ``cuda`` and
-a ``shared`` variant, and will never be partially enforced.
-
-Finally, ``all`` represents a *default set of requirements* -
-if there are specific package requirements, then the default requirements
-under ``all`` are disregarded. For example, with a configuration like this:
-
-.. code-block:: yaml
-
-   packages:
-     all:
-       require:
-       - 'build_type=Debug'
-       - '%clang'
-     cmake:
-       require:
-       - 'build_type=Debug'
-       - '%gcc'
-
-Spack requires ``cmake`` to use ``gcc`` and all other nodes (including ``cmake``
-dependencies) to use ``clang``. If enforcing ``build_type=Debug`` is needed also
-on ``cmake``, it must be repeated in the specific ``cmake`` requirements.
-
-
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Setting requirements on virtual specs
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A requirement on a virtual spec applies whenever that virtual is present in the DAG.
-This can be useful for fixing which virtual provider you want to use:
-
-.. code-block:: yaml
-
-   packages:
-     mpi:
-       require: 'mvapich2 %gcc'
-
-With the configuration above the only allowed ``mpi`` provider is ``mvapich2 %gcc``.
-
-Requirements on the virtual spec and on the specific provider are both applied, if
-present. For instance with a configuration like:
-
-.. code-block:: yaml
-
-   packages:
-     mpi:
-       require: 'mvapich2 %gcc'
-     mvapich2:
-       require: '~cuda'
-
-you will use ``mvapich2~cuda %gcc`` as an ``mpi`` provider.
-
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Conflicts and strong preferences
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If the semantic of requirements is too strong, you can also express "strong preferences" and "conflicts"
-from configuration files:
-
-.. code-block:: yaml
-
-   packages:
-     all:
-       prefer:
-       - '%clang'
-       conflict:
-       - '+shared'
-
-The ``prefer`` and ``conflict`` sections can be used whenever a ``require`` section is allowed.
-The argument is always a list of constraints, and each constraint can be either a simple string,
-or a more complex object:
-
-.. code-block:: yaml
-
-   packages:
-     all:
-       conflict:
-       - spec: '%clang'
-         when: 'target=x86_64_v3'
-         message: 'reason why clang cannot be used'
-
-The ``spec`` attribute is mandatory, while both ``when`` and ``message`` are optional.
-
-.. note::
-
-   Requirements allow for expressing both "strong preferences" and "conflicts".
-   The syntax for doing so, though, may not be immediately clear. For
-   instance, if we want to prevent any package from using ``%clang``, we can set:
-
-   .. code-block:: yaml
-
-      packages:
-        all:
-          require:
-          - one_of: ['%clang', '@:']
-
-   Since only one of the requirements must hold, and ``@:`` is always true, the rule above is
-   equivalent to a conflict. For "strong preferences" we need to substitute the ``one_of`` policy
-   with ``any_of``.
-
-
-
-.. _package-preferences:
-
--------------------
-Package Preferences
--------------------
-
-In some cases package requirements can be too strong, and package
-preferences are the better option. Package preferences do not impose
-constraints on packages for particular versions or variants values,
-they rather only set defaults. The concretizer is free to change
-them if it must, due to other constraints, and also prefers reusing
-installed packages over building new ones that are a better match for
-preferences.
-
-.. seealso::
-
-   FAQ: :ref:`Why does Spack pick particular versions and variants? <faq-concretizer-precedence>`
-
-
-Most package preferences (``compilers``, ``target`` and ``providers``)
-can only be set globally under the ``all`` section of ``packages.yaml``:
-
-.. code-block:: yaml
-
-   packages:
-     all:
-       compiler: [gcc@12.2.0, clang@12:, oneapi@2023:]
-       target: [x86_64_v3]
-       providers:
-         mpi: [mvapich2, mpich, openmpi]
-
-These preferences override Spack's default and effectively reorder priorities
-when looking for the best compiler, target or virtual package provider. Each
-preference takes an ordered list of spec constraints, with earlier entries in
-the list being preferred over later entries.
-
-In the example above all packages prefer to be compiled with ``gcc@12.2.0``,
-to target the ``x86_64_v3`` microarchitecture and to use ``mvapich2`` if they
-depend on ``mpi``.
-
-The ``variants`` and ``version`` preferences can be set under
-package specific sections of the ``packages.yaml`` file:
-
-.. code-block:: yaml
-
-   packages:
-     opencv:
-       variants: +debug
-     gperftools:
-       version: [2.2, 2.4, 2.3]
-
-In this case, the preference for ``opencv`` is to build with debug options, while
-``gperftools`` prefers version 2.2 over 2.4.
-
-Any preference can be overwritten on the command line if explicitly requested.
-
-Preferences cannot overcome explicit constraints, as they only set a preferred
-ordering among homogeneous attribute values. Going back to the example, if
-``gperftools@2.3:`` was requested, then Spack will install version 2.4
-since the most preferred version 2.2 is prohibited by the version constraint.
-
-.. _package_permissions:
-
--------------------
-Package Permissions
--------------------
-
-Spack can be configured to assign permissions to the files installed
-by a package.
-
-In the ``packages.yaml`` file under ``permissions``, the attributes
-``read``, ``write``, and ``group`` control the package
-permissions. These attributes can be set per-package, or for all
-packages under ``all``. If permissions are set under ``all`` and for a
-specific package, the package-specific settings take precedence.
-
-The ``read`` and ``write`` attributes take one of ``user``, ``group``,
-and ``world``.
-
-.. code-block:: yaml
-
-  packages:
-    all:
-      permissions:
-        write: group
-        group: spack
-    my_app:
-      permissions:
-        read: group
-        group: my_team
-
-The permissions settings describe the broadest level of access to
-installations of the specified packages. The execute permissions of
-the file are set to the same level as read permissions for those files
-that are executable. The default setting for ``read`` is ``world``,
-and for ``write`` is ``user``. In the example above, installations of
-``my_app`` will be installed with user and group permissions but no
-world permissions, and owned by the group ``my_team``. All other
-packages will be installed with user and group write privileges, and
-world read privileges. Those packages will be owned by the group
-``spack``.
-
-The ``group`` attribute assigns a Unix-style group to a package. All
-files installed by the package will be owned by the assigned group,
-and the sticky group bit will be set on the install prefix and all
-directories inside the install prefix. This will ensure that even
-manually placed files within the install prefix are owned by the
-assigned group. If no group is assigned, Spack will allow the OS
-default behavior to go as expected.
-
-.. _assigning-package-attributes:
-
-----------------------------
-Assigning Package Attributes
-----------------------------
-
-You can assign class-level attributes in the configuration:
-
-.. code-block:: yaml
-
-  packages:
-    mpileaks:
-      package_attributes:
-        # Override existing attributes
-        url: http://www.somewhereelse.com/mpileaks-1.0.tar.gz
-        # ... or add new ones
-        x: 1
-
-Attributes set this way will be accessible to any method executed
-in the package.py file (e.g. the ``install()`` method). Values for these
-attributes may be any value parseable by yaml.
-
-These can only be applied to specific packages, not "all" or
-virtual packages.

lib/spack/docs/packaging_guide.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -237,7 +237,7 @@ for details):
 .. code-block:: python
    :linenos:
 
-   # Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+   # Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    # Spack Project Developers. See the top-level COPYRIGHT file for details.
    #
    # SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -893,50 +893,26 @@ as an option to the ``version()`` directive. Example situations would be a
 "snapshot"-like Version Control System (VCS) tag, a VCS branch such as
 ``v6-16-00-patches``, or a URL specifying a regularly updated snapshot tarball.
 
-
-.. _version-comparison:
-
 ^^^^^^^^^^^^^^^^^^
 Version comparison
 ^^^^^^^^^^^^^^^^^^
 
-Spack imposes a generic total ordering on the set of versions,
-independently from the package they are associated with.
-
 Most Spack versions are numeric, a tuple of integers; for example,
-``0.1``, ``6.96`` or ``1.2.3.1``. In this very basic case, version
+``0.1``, ``6.96`` or ``1.2.3.1``.  Spack knows how to compare and sort
-comparison is lexicographical on the numeric components:
+numeric versions.
-``1.2 < 1.2.1 < 1.2.2 < 1.10``.
 
-Spack can also supports string components such as ``1.1.1a`` and
+Some Spack versions involve slight extensions of numeric syntax; for
-``1.y.0``. String components are considered less than numeric
+example, ``py-sphinx-rtd-theme@=0.1.10a0``.  In this case, numbers are
-components, so ``1.y.0 < 1.0``. This is for consistency with
+always considered to be "newer" than letters.  This is for consistency
-`RPM <https://bugzilla.redhat.com/show_bug.cgi?id=50977>`_. String
+with `RPM <https://bugzilla.redhat.com/show_bug.cgi?id=50977>`_.
-components do not have to be separated by dots or any other delimiter.
-So, the contrived version ``1y0`` is identical to ``1.y.0``.
 
-Pre-release suffixes also contain string parts, but they are handled
+Spack versions may also be arbitrary non-numeric strings, for example
-in a special way. For example ``1.2.3alpha1`` is parsed as a pre-release
+``develop``, ``master``, ``local``.
-of the version ``1.2.3``. This allows Spack to order it before the
-actual release: ``1.2.3alpha1 < 1.2.3``. Spack supports alpha, beta and
-release candidate suffixes: ``1.2alpha1 < 1.2beta1 < 1.2rc1 < 1.2``. Any
-suffix not recognized as a pre-release is treated as an ordinary
-string component, so ``1.2 < 1.2-mysuffix``.
 
-Finally, there are a few special string components that are considered
+The order on versions is defined as follows. A version string is split
-"infinity versions". They include ``develop``, ``main``, ``master``,
+into a list of components based on delimiters such as ``.``, ``-`` etc.
-``head``, ``trunk``, and ``stable``. For example: ``1.2 < develop``.
+Lists are then ordered lexicographically, where components are ordered
-These are useful for specifying the most recent development version of
+as follows:
-a package (often a moving target like a git branch), without assigning
-a specific version number. Infinity versions are not automatically used when determining the latest version of a package unless explicitly required by another package or user.
-
-More formally, the order on versions is defined as follows. A version
-string is split into a list of components based on delimiters such as
-``.`` and ``-`` and string boundaries. The components are split into
-the **release** and a possible **pre-release** (if the last component
-is numeric and the second to last is a string ``alpha``, ``beta`` or ``rc``).
-The release components are ordered lexicographically, with comparsion
-between different types of components as follows:
 
 #. The following special strings are considered larger than any other
    numeric or non-numeric version component, and satisfy the following
@@ -949,9 +925,6 @@ between different types of components as follows:
 #. All other non-numeric components are less than numeric components,
    and are ordered alphabetically.
 
-Finally, if the release components are equal, the pre-release components
-are used to break the tie, in the obvious way.
-
 The logic behind this sort order is two-fold:
 
 #. Non-numeric versions are usually used for special cases while
@@ -2364,7 +2337,7 @@ window while a batch job is running ``spack install`` on the same or
 overlapping dependencies without any process trying to re-do the work of
 another.
 
-For example, if you are using Slurm, you could launch an installation
+For example, if you are using SLURM, you could launch an installation
 of ``mpich`` using the following command:
 
 .. code-block:: console
@@ -4406,16 +4379,10 @@ implementation was selected for this build:
    elif "mvapich" in spec:
        configure_args.append("--with-mvapich")
 
-It's also a bit more concise than satisfies.
+It's also a bit more concise than satisfies.  The difference between
-
+the two functions is that ``satisfies()`` tests whether spec
-.. note::
+constraints overlap at all, while ``in`` tests whether a spec or any
-
+of its dependencies satisfy the provided spec.
-   The ``satisfies()`` method tests whether this spec has, at least, all the constraints of the argument spec,
-   while ``in`` tests whether a spec or any of its dependencies satisfy the provided spec.
-
-   If the provided spec is anonymous (e.g., ":1.2:", "+shared") or has the
-   same name as the spec being checked, then ``in`` works the same as
-   ``satisfies()``; however, use of ``satisfies()`` is more intuitive.
 
 ^^^^^^^^^^^^^^^^^^^^^^^
 Architecture specifiers
@@ -5317,7 +5284,7 @@ installed example.
            example = which(self.prefix.bin.example)
            example()
 
-Output showing the identification of each test part after running the tests
+Output showing the identification of each test part after runnig the tests
 is illustrated below.
 
 .. code-block:: console
@@ -5814,7 +5781,7 @@ with those implemented in the package itself.
    * - `Cxx
        <https://github.com/spack/spack/blob/develop/var/spack/repos/builtin/packages/cxx>`_
      - Compiles and runs several ``hello`` programs
-   * - `Fortran
+   * - `Fortan
        <https://github.com/spack/spack/blob/develop/var/spack/repos/builtin/packages/fortran>`_
      - Compiles and runs ``hello`` programs (``F`` and ``f90``)
    * - `Mpi
@@ -7006,18 +6973,3 @@ you probably care most about are:
 You may also care about `license exceptions
 <https://spdx.org/licenses/exceptions-index.html>`_ that use the ``WITH`` operator,
 e.g. ``Apache-2.0 WITH LLVM-exception``.
-
-Many of the licenses that are currently in the spack repositories have been
-automatically determined. While this is great for bulk adding license
-information and is most likely correct, there are sometimes edge cases that
-require manual intervention. To determine which licenses are validated and
-which are not, there is the `checked_by` parameter in the license directive:
-
-.. code-block:: python
-
-   license("<license>", when="<when>", checked_by="<github username>")
-
-When you have validated a github license, either when doing so explicitly or
-as part of packaging a new package, please set the `checked_by` parameter
-to your Github username to signal that the license has been manually
-verified.

lib/spack/docs/pipelines.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -810,7 +810,7 @@ generated by ``spack ci generate``.  You also want your generated rebuild jobs
 .. code-block:: yaml
 
    spack:
-     # ...
+     ...
      ci:
        pipeline-gen:
        - build-job:

lib/spack/docs/replace_conda_homebrew.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)

lib/spack/docs/repositories.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -17,7 +17,7 @@ experimental software separately from the built-in repository. Spack
 allows you to configure local repositories using either the
 ``repos.yaml`` or the ``spack repo`` command.
 
-A package repository is a directory structured like this::
+A package repository a directory structured like this::
 
   repo/
       repo.yaml

lib/spack/docs/requirements.txt

@@ -1,13 +1,13 @@
 sphinx==7.2.6
 sphinxcontrib-programoutput==0.17
 sphinx_design==0.5.0
-sphinx-rtd-theme==2.0.0
+sphinx-rtd-theme==1.3.0
-python-levenshtein==0.25.0
+python-levenshtein==0.23.0
-docutils==0.20.1
+docutils==0.18.1
-pygments==2.17.2
+pygments==2.16.1
-urllib3==2.2.1
+urllib3==2.0.7
-pytest==8.1.1
+pytest==7.4.3
-isort==5.13.2
+isort==5.12.0
-black==24.3.0
+black==23.11.0
-flake8==7.0.0
+flake8==6.1.0
-mypy==1.9.0
+mypy==1.7.0

lib/spack/docs/signing.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2022 Lawrence Livermore National Security, LLC and other
    Spack Project Developers. See the top-level COPYRIGHT file for details.
 
    SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -142,7 +142,7 @@ Reputational Key
 ----------------
 
 The Reputational Key is the public facing key used to sign complete groups of
-development and release packages. Only one key pair exists in this class of
+development and release packages. Only one key pair exsits in this class of
 keys. In contrast to the Intermediate CI Key the Reputational Key *should* be
 used to verify package integrity. At the end of develop and release pipeline a
 final pipeline job pulls down all signed package metadata built by the pipeline,
@@ -272,7 +272,7 @@ Internal Implementation
 
 The technical implementation of the pipeline signing process includes components
 defined in Amazon Web Services, the Kubernetes cluster, at affilicated
-institutions, and the GitLab/GitLab Runner deployment. We present the technical
+institutions, and the GitLab/GitLab Runner deployment. We present the techincal
 implementation in two interdependent sections. The first addresses how secrets
 are managed through the lifecycle of a develop or release pipeline. The second
 section describes how Gitlab Runner and pipelines are configured and managed to
@@ -295,7 +295,7 @@ infrastructure.
 -----------------------
 
 Multiple intermediate CI signing keys exist, one Intermediate CI Key for jobs
-run in AWS, and one key for each affiliated institution (e.g. University of
+run in AWS, and one key for each affiliated institution (e.g. Univerity of
 Oregon). Here we describe how the Intermediate CI Key is managed in AWS:
 
 The Intermediate CI Key (including the Signing Intermediate CI Private Key is
@@ -305,7 +305,7 @@ contains an ASCII-armored export of just the *public* components of the
 Reputational Key. This secret also contains the *public* components of each of
 the affiliated institutions' Intermediate CI Key. These are potentially needed
 to verify dependent packages which may have been found in the public mirror or
-built by a protected job running on an affiliated institution's infrastructure
+built by a protected job running on an affiliated institution's infrastrcuture
 in an earlier stage of the pipeline.
 
 Procedurally the ``spack-intermediate-ci-signing-key`` secret is used in

lib/spack/docs/spack.yaml

@@ -1,4 +1,4 @@
-# Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
 # Spack Project Developers. See the top-level COPYRIGHT file for details.
 #
 # SPDX-License-Identifier: (Apache-2.0 OR MIT)

lib/spack/env/cc

@@ -1,7 +1,7 @@
 #!/bin/sh -f
 # shellcheck disable=SC2034  # evals in this script fool shellcheck
 #
-# Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
 # Spack Project Developers. See the top-level COPYRIGHT file for details.
 #
 # SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -248,7 +248,7 @@ case "$command" in
         lang_flags=C
         debug_flags="-g"
         ;;
-    c++|CC|g++|clang++|armclang++|icpc|icpx|pgc++|nvc++|xlc++|xlc++_r|FCC|amdclang++|crayCC)
+    c++|CC|g++|clang++|armclang++|icpc|icpx|dpcpp|pgc++|nvc++|xlc++|xlc++_r|FCC|amdclang++|crayCC)
         command="$SPACK_CXX"
         language="C++"
         comp="CXX"
@@ -913,3 +913,4 @@ fi
 # Execute the full command, preserving spaces with IFS set
 # to the alarm bell separator.
 IFS="$lsep"; exec $full_command_list
+

lib/spack/external/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
 # Spack Project Developers. See the top-level COPYRIGHT file for details.
 #
 # SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -18,7 +18,7 @@
 
 * Homepage: https://pypi.python.org/pypi/archspec
 * Usage: Labeling, comparison and detection of microarchitectures
-* Version: 0.2.3 (commit 7b8fe60b69e2861e7dac104bc1c183decfcd3daf)
+* Version: 0.2.2 (commit 1dc58a5776dd77e6fc6e4ba5626af5b1fb24996e)
 
 astunparse
 ----------------

lib/spack/external/archspec/__init__.py

@@ -1,3 +1,2 @@
 """Init file to avoid namespace packages"""
-
+__version__ = "0.2.2"
-__version__ = "0.2.3"

lib/spack/external/archspec/__main__.py

@@ -3,7 +3,6 @@
 """
 
 import sys
-
 from .cli import main
 
 sys.exit(main())

lib/spack/external/archspec/cli.py

@@ -46,11 +46,7 @@ def _make_parser() -> argparse.ArgumentParser:
 
 def cpu() -> int:
     """Run the `archspec cpu` subcommand."""
-    try:
+    print(archspec.cpu.host())
-        print(archspec.cpu.host())
-    except FileNotFoundError as exc:
-        print(exc)
-        return 1
     return 0
 
 

lib/spack/external/archspec/cpu/__init__.py

@@ -5,14 +5,10 @@
 """The "cpu" package permits to query and compare different
 CPU microarchitectures.
 """
+from .microarchitecture import Microarchitecture, UnsupportedMicroarchitecture
+from .microarchitecture import TARGETS, generic_microarchitecture
+from .microarchitecture import version_components
 from .detect import host
-from .microarchitecture import (
-    TARGETS,
-    Microarchitecture,
-    UnsupportedMicroarchitecture,
-    generic_microarchitecture,
-    version_components,
-)
 
 __all__ = [
     "Microarchitecture",

lib/spack/external/archspec/cpu/detect.py

@@ -4,17 +4,15 @@
 # SPDX-License-Identifier: (Apache-2.0 OR MIT)
 """Detection of CPU microarchitectures"""
 import collections
+import functools
 import os
 import platform
 import re
-import struct
 import subprocess
 import warnings
-from typing import Dict, List, Optional, Set, Tuple, Union
 
-from ..vendor.cpuid.cpuid import CPUID
+from .microarchitecture import generic_microarchitecture, TARGETS
-from .microarchitecture import TARGETS, Microarchitecture, generic_microarchitecture
+from .schema import TARGETS_JSON
-from .schema import CPUID_JSON, TARGETS_JSON
 
 #: Mapping from operating systems to chain of commands
 #: to obtain a dictionary of raw info on the current cpu
@@ -24,46 +22,43 @@
 #: functions checking the compatibility of the host with a given target
 COMPATIBILITY_CHECKS = {}
 
-# Constants for commonly used architectures
-X86_64 = "x86_64"
-AARCH64 = "aarch64"
-PPC64LE = "ppc64le"
-PPC64 = "ppc64"
-RISCV64 = "riscv64"
 
-
+def info_dict(operating_system):
-def detection(operating_system: str):
+    """Decorator to mark functions that are meant to return raw info on
-    """Decorator to mark functions that are meant to return partial information on the current cpu.
+    the current cpu.
 
     Args:
-        operating_system: operating system where this function can be used.
+        operating_system (str or tuple): operating system for which the marked
+            function is a viable factory of raw info dictionaries.
     """
 
     def decorator(factory):
         INFO_FACTORY[operating_system].append(factory)
-        return factory
+
+        @functools.wraps(factory)
+        def _impl():
+            info = factory()
+
+            # Check that info contains a few mandatory fields
+            msg = 'field "{0}" is missing from raw info dictionary'
+            assert "vendor_id" in info, msg.format("vendor_id")
+            assert "flags" in info, msg.format("flags")
+            assert "model" in info, msg.format("model")
+            assert "model_name" in info, msg.format("model_name")
+
+            return info
+
+        return _impl
 
     return decorator
 
 
-def partial_uarch(
+@info_dict(operating_system="Linux")
-    name: str = "", vendor: str = "", features: Optional[Set[str]] = None, generation: int = 0
+def proc_cpuinfo():
-) -> Microarchitecture:
+    """Returns a raw info dictionary by parsing the first entry of
-    """Construct a partial microarchitecture, from information gathered during system scan."""
+    ``/proc/cpuinfo``
-    return Microarchitecture(
+    """
-        name=name,
+    info = {}
-        parents=[],
-        vendor=vendor,
-        features=features or set(),
-        compilers={},
-        generation=generation,
-    )
-
-
-@detection(operating_system="Linux")
-def proc_cpuinfo() -> Microarchitecture:
-    """Returns a partial Microarchitecture, obtained from scanning ``/proc/cpuinfo``"""
-    data = {}
     with open("/proc/cpuinfo") as file:  # pylint: disable=unspecified-encoding
         for line in file:
             key, separator, value = line.partition(":")
@@ -75,96 +70,11 @@ def proc_cpuinfo() -> Microarchitecture:
             #
             # we are on a blank line separating two cpus. Exit early as
             # we want to read just the first entry in /proc/cpuinfo
-            if separator != ":" and data:
+            if separator != ":" and info:
                 break
 
-            data[key.strip()] = value.strip()
+            info[key.strip()] = value.strip()
-
+    return info
-    architecture = _machine()
-    if architecture == X86_64:
-        return partial_uarch(
-            vendor=data.get("vendor_id", "generic"), features=_feature_set(data, key="flags")
-        )
-
-    if architecture == AARCH64:
-        return partial_uarch(
-            vendor=_canonicalize_aarch64_vendor(data),
-            features=_feature_set(data, key="Features"),
-        )
-
-    if architecture in (PPC64LE, PPC64):
-        generation_match = re.search(r"POWER(\d+)", data.get("cpu", ""))
-        try:
-            generation = int(generation_match.group(1))
-        except AttributeError:
-            # There might be no match under emulated environments. For instance
-            # emulating a ppc64le with QEMU and Docker still reports the host
-            # /proc/cpuinfo and not a Power
-            generation = 0
-        return partial_uarch(generation=generation)
-
-    if architecture == RISCV64:
-        if data.get("uarch") == "sifive,u74-mc":
-            data["uarch"] = "u74mc"
-        return partial_uarch(name=data.get("uarch", RISCV64))
-
-    return generic_microarchitecture(architecture)
-
-
-class CpuidInfoCollector:
-    """Collects the information we need on the host CPU from cpuid"""
-
-    # pylint: disable=too-few-public-methods
-    def __init__(self):
-        self.cpuid = CPUID()
-
-        registers = self.cpuid.registers_for(**CPUID_JSON["vendor"]["input"])
-        self.highest_basic_support = registers.eax
-        self.vendor = struct.pack("III", registers.ebx, registers.edx, registers.ecx).decode(
-            "utf-8"
-        )
-
-        registers = self.cpuid.registers_for(**CPUID_JSON["highest_extension_support"]["input"])
-        self.highest_extension_support = registers.eax
-
-        self.features = self._features()
-
-    def _features(self):
-        result = set()
-
-        def check_features(data):
-            registers = self.cpuid.registers_for(**data["input"])
-            for feature_check in data["bits"]:
-                current = getattr(registers, feature_check["register"])
-                if self._is_bit_set(current, feature_check["bit"]):
-                    result.add(feature_check["name"])
-
-        for call_data in CPUID_JSON["flags"]:
-            if call_data["input"]["eax"] > self.highest_basic_support:
-                continue
-            check_features(call_data)
-
-        for call_data in CPUID_JSON["extension-flags"]:
-            if call_data["input"]["eax"] > self.highest_extension_support:
-                continue
-            check_features(call_data)
-
-        return result
-
-    def _is_bit_set(self, register: int, bit: int) -> bool:
-        mask = 1 << bit
-        return register & mask > 0
-
-
-@detection(operating_system="Windows")
-def cpuid_info():
-    """Returns a partial Microarchitecture, obtained from running the cpuid instruction"""
-    architecture = _machine()
-    if architecture == X86_64:
-        data = CpuidInfoCollector()
-        return partial_uarch(vendor=data.vendor, features=data.features)
-
-    return generic_microarchitecture(architecture)
 
 
 def _check_output(args, env):
@@ -173,25 +83,14 @@ def _check_output(args, env):
     return str(output.decode("utf-8"))
 
 
-WINDOWS_MAPPING = {
-    "AMD64": "x86_64",
-    "ARM64": "aarch64",
-}
-
-
 def _machine():
-    """Return the machine architecture we are on"""
+    """ "Return the machine architecture we are on"""
     operating_system = platform.system()
 
-    # If we are not on Darwin or Windows, trust what Python tells us
+    # If we are not on Darwin, trust what Python tells us
-    if operating_system not in ("Darwin", "Windows"):
+    if operating_system != "Darwin":
         return platform.machine()
 
-    # Normalize windows specific names
-    if operating_system == "Windows":
-        platform_machine = platform.machine()
-        return WINDOWS_MAPPING.get(platform_machine, platform_machine)
-
     # On Darwin it might happen that we are on M1, but using an interpreter
     # built for x86_64. In that case "platform.machine() == 'x86_64'", so we
     # need to fix that.
@@ -204,47 +103,54 @@ def _machine():
     if "Apple" in output:
         # Note that a native Python interpreter on Apple M1 would return
         # "arm64" instead of "aarch64". Here we normalize to the latter.
-        return AARCH64
+        return "aarch64"
 
-    return X86_64
+    return "x86_64"
 
 
-@detection(operating_system="Darwin")
+@info_dict(operating_system="Darwin")
-def sysctl_info() -> Microarchitecture:
+def sysctl_info_dict():
     """Returns a raw info dictionary parsing the output of sysctl."""
     child_environment = _ensure_bin_usrbin_in_path()
 
-    def sysctl(*args: str) -> str:
+    def sysctl(*args):
         return _check_output(["sysctl"] + list(args), env=child_environment).strip()
 
-    if _machine() == X86_64:
+    if _machine() == "x86_64":
-        features = (
+        flags = (
-            f'{sysctl("-n", "machdep.cpu.features").lower()} '
+            sysctl("-n", "machdep.cpu.features").lower()
-            f'{sysctl("-n", "machdep.cpu.leaf7_features").lower()}'
+            + " "
+            + sysctl("-n", "machdep.cpu.leaf7_features").lower()
         )
-        features = set(features.split())
+        info = {
+            "vendor_id": sysctl("-n", "machdep.cpu.vendor"),
+            "flags": flags,
+            "model": sysctl("-n", "machdep.cpu.model"),
+            "model name": sysctl("-n", "machdep.cpu.brand_string"),
+        }
+    else:
+        model = "unknown"
+        model_str = sysctl("-n", "machdep.cpu.brand_string").lower()
+        if "m2" in model_str:
+            model = "m2"
+        elif "m1" in model_str:
+            model = "m1"
+        elif "apple" in model_str:
+            model = "m1"
 
-        # Flags detected on Darwin turned to their linux counterpart
+        info = {
-        for darwin_flag, linux_flag in TARGETS_JSON["conversions"]["darwin_flags"].items():
+            "vendor_id": "Apple",
-            if darwin_flag in features:
+            "flags": [],
-                features.update(linux_flag.split())
+            "model": model,
-
+            "CPU implementer": "Apple",
-        return partial_uarch(vendor=sysctl("-n", "machdep.cpu.vendor"), features=features)
+            "model name": sysctl("-n", "machdep.cpu.brand_string"),
-
+        }
-    model = "unknown"
+    return info
-    model_str = sysctl("-n", "machdep.cpu.brand_string").lower()
-    if "m2" in model_str:
-        model = "m2"
-    elif "m1" in model_str:
-        model = "m1"
-    elif "apple" in model_str:
-        model = "m1"
-
-    return partial_uarch(name=model, vendor="Apple")
 
 
 def _ensure_bin_usrbin_in_path():
-    # Make sure that /sbin and /usr/sbin are in PATH as sysctl is usually found there
+    # Make sure that /sbin and /usr/sbin are in PATH as sysctl is
+    # usually found there
     child_environment = dict(os.environ.items())
     search_paths = child_environment.get("PATH", "").split(os.pathsep)
     for additional_path in ("/sbin", "/usr/sbin"):
@@ -254,10 +160,22 @@ def _ensure_bin_usrbin_in_path():
     return child_environment
 
 
-def _canonicalize_aarch64_vendor(data: Dict[str, str]) -> str:
+def adjust_raw_flags(info):
-    """Adjust the vendor field to make it human-readable"""
+    """Adjust the flags detected on the system to homogenize
-    if "CPU implementer" not in data:
+    slightly different representations.
-        return "generic"
+    """
+    # Flags detected on Darwin turned to their linux counterpart
+    flags = info.get("flags", [])
+    d2l = TARGETS_JSON["conversions"]["darwin_flags"]
+    for darwin_flag, linux_flag in d2l.items():
+        if darwin_flag in flags:
+            info["flags"] += " " + linux_flag
+
+
+def adjust_raw_vendor(info):
+    """Adjust the vendor field to make it human readable"""
+    if "CPU implementer" not in info:
+        return
 
     # Mapping numeric codes to vendor (ARM). This list is a merge from
     # different sources:
@@ -267,37 +185,43 @@ def _canonicalize_aarch64_vendor(data: Dict[str, str]) -> str:
     # https://github.com/gcc-mirror/gcc/blob/master/gcc/config/aarch64/aarch64-cores.def
     # https://patchwork.kernel.org/patch/10524949/
     arm_vendors = TARGETS_JSON["conversions"]["arm_vendors"]
-    arm_code = data["CPU implementer"]
+    arm_code = info["CPU implementer"]
-    return arm_vendors.get(arm_code, arm_code)
+    if arm_code in arm_vendors:
+        info["CPU implementer"] = arm_vendors[arm_code]
 
 
-def _feature_set(data: Dict[str, str], key: str) -> Set[str]:
+def raw_info_dictionary():
-    return set(data.get(key, "").split())
+    """Returns a dictionary with information on the cpu of the current host.
 
-
+    This function calls all the viable factories one after the other until
-def detected_info() -> Microarchitecture:
+    there's one that is able to produce the requested information.
-    """Returns a partial Microarchitecture with information on the CPU of the current host.
-
-    This function calls all the viable factories one after the other until there's one that is
-    able to produce the requested information. Falls-back to a generic microarchitecture, if none
-    of the calls succeed.
     """
     # pylint: disable=broad-except
+    info = {}
     for factory in INFO_FACTORY[platform.system()]:
         try:
-            return factory()
+            info = factory()
         except Exception as exc:
             warnings.warn(str(exc))
 
-    return generic_microarchitecture(_machine())
+        if info:
+            adjust_raw_flags(info)
+            adjust_raw_vendor(info)
+            break
+
+    return info
 
 
-def compatible_microarchitectures(info: Microarchitecture) -> List[Microarchitecture]:
+def compatible_microarchitectures(info):
-    """Returns an unordered list of known micro-architectures that are compatible with the
+    """Returns an unordered list of known micro-architectures that are
-    partial Microarchitecture passed as input.
+    compatible with the info dictionary passed as argument.
+
+    Args:
+        info (dict): dictionary containing information on the host cpu
     """
     architecture_family = _machine()
-    # If a tester is not registered, assume no known target is compatible with the host
+    # If a tester is not registered, be conservative and assume no known
+    # target is compatible with the host
     tester = COMPATIBILITY_CHECKS.get(architecture_family, lambda x, y: False)
     return [x for x in TARGETS.values() if tester(info, x)] or [
         generic_microarchitecture(architecture_family)
@@ -306,8 +230,8 @@ def compatible_microarchitectures(info: Microarchitecture) -> List[Microarchitec
 
 def host():
     """Detects the host micro-architecture and returns it."""
-    # Retrieve information on the host's cpu
+    # Retrieve a dictionary with raw information on the host's cpu
-    info = detected_info()
+    info = raw_info_dictionary()
 
     # Get a list of possible candidates for this micro-architecture
     candidates = compatible_microarchitectures(info)
@@ -334,15 +258,16 @@ def sorting_fn(item):
     return max(candidates, key=sorting_fn)
 
 
-def compatibility_check(architecture_family: Union[str, Tuple[str, ...]]):
+def compatibility_check(architecture_family):
     """Decorator to register a function as a proper compatibility check.
 
-    A compatibility check function takes a partial Microarchitecture object as a first argument,
+    A compatibility check function takes the raw info dictionary as a first
-    and an arbitrary target Microarchitecture as the second argument. It returns True if the
+    argument and an arbitrary target as the second argument. It returns True
-    target is compatible with first argument, False otherwise.
+    if the target is compatible with the info dictionary, False otherwise.
 
     Args:
-        architecture_family: architecture family for which this test can be used
+        architecture_family (str or tuple): architecture family for which
+            this test can be used, e.g. x86_64 or ppc64le etc.
     """
     # Turn the argument into something iterable
     if isinstance(architecture_family, str):
@@ -355,57 +280,86 @@ def decorator(func):
     return decorator
 
 
-@compatibility_check(architecture_family=(PPC64LE, PPC64))
+@compatibility_check(architecture_family=("ppc64le", "ppc64"))
 def compatibility_check_for_power(info, target):
     """Compatibility check for PPC64 and PPC64LE architectures."""
+    basename = platform.machine()
+    generation_match = re.search(r"POWER(\d+)", info.get("cpu", ""))
+    try:
+        generation = int(generation_match.group(1))
+    except AttributeError:
+        # There might be no match under emulated environments. For instance
+        # emulating a ppc64le with QEMU and Docker still reports the host
+        # /proc/cpuinfo and not a Power
+        generation = 0
+
     # We can use a target if it descends from our machine type and our
     # generation (9 for POWER9, etc) is at least its generation.
-    arch_root = TARGETS[_machine()]
+    arch_root = TARGETS[basename]
     return (
         target == arch_root or arch_root in target.ancestors
-    ) and target.generation <= info.generation
+    ) and target.generation <= generation
 
 
-@compatibility_check(architecture_family=X86_64)
+@compatibility_check(architecture_family="x86_64")
 def compatibility_check_for_x86_64(info, target):
     """Compatibility check for x86_64 architectures."""
+    basename = "x86_64"
+    vendor = info.get("vendor_id", "generic")
+    features = set(info.get("flags", "").split())
+
     # We can use a target if it descends from our machine type, is from our
     # vendor, and we have all of its features
-    arch_root = TARGETS[X86_64]
+    arch_root = TARGETS[basename]
     return (
         (target == arch_root or arch_root in target.ancestors)
-        and target.vendor in (info.vendor, "generic")
+        and target.vendor in (vendor, "generic")
-        and target.features.issubset(info.features)
+        and target.features.issubset(features)
     )
 
 
-@compatibility_check(architecture_family=AARCH64)
+@compatibility_check(architecture_family="aarch64")
 def compatibility_check_for_aarch64(info, target):
     """Compatibility check for AARCH64 architectures."""
-    # At the moment, it's not clear how to detect compatibility with
+    basename = "aarch64"
+    features = set(info.get("Features", "").split())
+    vendor = info.get("CPU implementer", "generic")
+
+    # At the moment it's not clear how to detect compatibility with
     # a specific version of the architecture
-    if target.vendor == "generic" and target.name != AARCH64:
+    if target.vendor == "generic" and target.name != "aarch64":
         return False
 
-    arch_root = TARGETS[AARCH64]
+    arch_root = TARGETS[basename]
     arch_root_and_vendor = arch_root == target.family and target.vendor in (
-        info.vendor,
+        vendor,
         "generic",
     )
 
     # On macOS it seems impossible to get all the CPU features
     # with syctl info, but for ARM we can get the exact model
     if platform.system() == "Darwin":
-        model = TARGETS[info.name]
+        model_key = info.get("model", basename)
+        model = TARGETS[model_key]
         return arch_root_and_vendor and (target == model or target in model.ancestors)
 
-    return arch_root_and_vendor and target.features.issubset(info.features)
+    return arch_root_and_vendor and target.features.issubset(features)
 
 
-@compatibility_check(architecture_family=RISCV64)
+@compatibility_check(architecture_family="riscv64")
 def compatibility_check_for_riscv64(info, target):
     """Compatibility check for riscv64 architectures."""
-    arch_root = TARGETS[RISCV64]
+    basename = "riscv64"
+    uarch = info.get("uarch")
+
+    # sifive unmatched board
+    if uarch == "sifive,u74-mc":
+        uarch = "u74mc"
+    # catch-all for unknown uarchs
+    else:
+        uarch = "riscv64"
+
+    arch_root = TARGETS[basename]
     return (target == arch_root or arch_root in target.ancestors) and (
-        target.name == info.name or target.vendor == "generic"
+        target == uarch or target.vendor == "generic"
     )

lib/spack/external/archspec/cpu/microarchitecture.py

@@ -13,7 +13,6 @@
 import archspec
 import archspec.cpu.alias
 import archspec.cpu.schema
-
 from .alias import FEATURE_ALIASES
 from .schema import LazyDictionary
 
@@ -48,7 +47,7 @@ class Microarchitecture:
             which has "broadwell" as a parent, supports running binaries
             optimized for "broadwell".
         vendor (str): vendor of the micro-architecture
-        features (set of str): supported CPU flags. Note that the semantic
+        features (list of str): supported CPU flags. Note that the semantic
             of the flags in this field might vary among architectures, if
             at all present. For instance x86_64 processors will list all
             the flags supported by a given CPU while Arm processors will
@@ -181,28 +180,24 @@ def generic(self):
         generics = [x for x in [self] + self.ancestors if x.vendor == "generic"]
         return max(generics, key=lambda x: len(x.ancestors))
 
-    def to_dict(self):
+    def to_dict(self, return_list_of_items=False):
-        """Returns a dictionary representation of this object."""
+        """Returns a dictionary representation of this object.
-        return {
-            "name": str(self.name),
-            "vendor": str(self.vendor),
-            "features": sorted(str(x) for x in self.features),
-            "generation": self.generation,
-            "parents": [str(x) for x in self.parents],
-            "compilers": self.compilers,
-        }
 
-    @staticmethod
+        Args:
-    def from_dict(data) -> "Microarchitecture":
+            return_list_of_items (bool): if True returns an ordered list of
-        """Construct a microarchitecture from a dictionary representation."""
+                items instead of the dictionary
-        return Microarchitecture(
+        """
-            name=data["name"],
+        list_of_items = [
-            parents=[TARGETS[x] for x in data["parents"]],
+            ("name", str(self.name)),
-            vendor=data["vendor"],
+            ("vendor", str(self.vendor)),
-            features=set(data["features"]),
+            ("features", sorted(str(x) for x in self.features)),
-            compilers=data.get("compilers", {}),
+            ("generation", self.generation),
-            generation=data.get("generation", 0),
+            ("parents", [str(x) for x in self.parents]),
-        )
+        ]
+        if return_list_of_items:
+            return list_of_items
+
+        return dict(list_of_items)
 
     def optimization_flags(self, compiler, version):
         """Returns a string containing the optimization flags that needs
@@ -276,7 +271,9 @@ def tuplify(ver):
                 flags = flags_fmt.format(**compiler_entry)
                 return flags
 
-        msg = "cannot produce optimized binary for micro-architecture '{0}' with {1}@{2}"
+        msg = (
+            "cannot produce optimized binary for micro-architecture '{0}' with {1}@{2}"
+        )
         if compiler_info:
             versions = [x["versions"] for x in compiler_info]
             msg += f' [supported compiler versions are {", ".join(versions)}]'
@@ -292,7 +289,9 @@ def generic_microarchitecture(name):
     Args:
         name (str): name of the micro-architecture
     """
-    return Microarchitecture(name, parents=[], vendor="generic", features=[], compilers={})
+    return Microarchitecture(
+        name, parents=[], vendor="generic", features=[], compilers={}
+    )
 
 
 def version_components(version):
@@ -346,7 +345,9 @@ def fill_target_from_dict(name, data, targets):
         compilers = values.get("compilers", {})
         generation = values.get("generation", 0)
 
-        targets[name] = Microarchitecture(name, parents, vendor, features, compilers, generation)
+        targets[name] = Microarchitecture(
+            name, parents, vendor, features, compilers, generation
+        )
 
     known_targets = {}
     data = archspec.cpu.schema.TARGETS_JSON["microarchitectures"]

lib/spack/external/archspec/cpu/schema.py

@@ -7,9 +7,7 @@
 """
 import collections.abc
 import json
-import os
+import os.path
-import pathlib
-from typing import Tuple
 
 
 class LazyDictionary(collections.abc.MutableMapping):
@@ -48,65 +46,21 @@ def __len__(self):
         return len(self.data)
 
 
-#: Environment variable that might point to a directory with a user defined JSON file
+def _load_json_file(json_file):
-DIR_FROM_ENVIRONMENT = "ARCHSPEC_CPU_DIR"
+    json_dir = os.path.join(os.path.dirname(__file__), "..", "json", "cpu")
+    json_dir = os.path.abspath(json_dir)
 
-#: Environment variable that might point to a directory with extensions to JSON files
+    def _factory():
-EXTENSION_DIR_FROM_ENVIRONMENT = "ARCHSPEC_EXTENSION_CPU_DIR"
+        filename = os.path.join(json_dir, json_file)
+        with open(filename, "r", encoding="utf-8") as file:
+            return json.load(file)
 
-
+    return _factory
-def _json_file(filename: str, allow_custom: bool = False) -> Tuple[pathlib.Path, pathlib.Path]:
-    """Given a filename, returns the absolute path for the main JSON file, and an
-    optional absolute path for an extension JSON file.
-
-    Args:
-        filename: filename for the JSON file
-        allow_custom: if True, allows overriding the location  where the file resides
-    """
-    json_dir = pathlib.Path(__file__).parent / ".." / "json" / "cpu"
-    if allow_custom and DIR_FROM_ENVIRONMENT in os.environ:
-        json_dir = pathlib.Path(os.environ[DIR_FROM_ENVIRONMENT])
-    json_dir = json_dir.absolute()
-    json_file = json_dir / filename
-
-    extension_file = None
-    if allow_custom and EXTENSION_DIR_FROM_ENVIRONMENT in os.environ:
-        extension_dir = pathlib.Path(os.environ[EXTENSION_DIR_FROM_ENVIRONMENT])
-        extension_dir.absolute()
-        extension_file = extension_dir / filename
-
-    return json_file, extension_file
-
-
-def _load(json_file: pathlib.Path, extension_file: pathlib.Path):
-    with open(json_file, "r", encoding="utf-8") as file:
-        data = json.load(file)
-
-    if not extension_file or not extension_file.exists():
-        return data
-
-    with open(extension_file, "r", encoding="utf-8") as file:
-        extension_data = json.load(file)
-
-    top_level_sections = list(data.keys())
-    for key in top_level_sections:
-        if key not in extension_data:
-            continue
-
-        data[key].update(extension_data[key])
-
-    return data
 
 
 #: In memory representation of the data in microarchitectures.json,
 #: loaded on first access
-TARGETS_JSON = LazyDictionary(_load, *_json_file("microarchitectures.json", allow_custom=True))
+TARGETS_JSON = LazyDictionary(_load_json_file("microarchitectures.json"))
 
 #: JSON schema for microarchitectures.json, loaded on first access
-TARGETS_JSON_SCHEMA = LazyDictionary(_load, *_json_file("microarchitectures_schema.json"))
+SCHEMA = LazyDictionary(_load_json_file("microarchitectures_schema.json"))
-
-#: Information on how to call 'cpuid' to get information on the HOST CPU
-CPUID_JSON = LazyDictionary(_load, *_json_file("cpuid.json", allow_custom=True))
-
-#: JSON schema for cpuid.json, loaded on first access
-CPUID_JSON_SCHEMA = LazyDictionary(_load, *_json_file("cpuid_schema.json"))

lib/spack/external/archspec/json/README.md

@@ -9,11 +9,11 @@ language specific APIs.
 
 Currently the repository contains the following JSON files:
 ```console
-cpu/
+.
-├── cpuid.json                     # Contains information on CPUID calls to retrieve vendor and features on x86_64
+├── COPYRIGHT
-├── cpuid_schema.json              # Schema for the file above
+└── cpu
-├── microarchitectures.json        # Contains information on CPU microarchitectures
+    ├── microarchitectures.json         # Contains information on CPU microarchitectures
-└── microarchitectures_schema.json # Schema for the file above
+    └── microarchitectures_schema.json  # Schema for the file above
  ```
 
 

lib/spack/external/archspec/json/cpu/cpuid_schema.json

@@ -1,134 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "Schema for microarchitecture definitions and feature aliases",
-  "type": "object",
-  "additionalProperties": false,
-  "properties": {
-    "vendor": {
-      "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "description": {
-          "type": "string"
-        },
-        "input": {
-          "type": "object",
-          "additionalProperties": false,
-          "properties": {
-            "eax": {
-              "type": "integer"
-            },
-            "ecx": {
-              "type": "integer"
-            }
-          }
-        }
-      }
-    },
-    "highest_extension_support": {
-      "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "description": {
-          "type": "string"
-        },
-        "input": {
-          "type": "object",
-          "additionalProperties": false,
-          "properties": {
-            "eax": {
-              "type": "integer"
-            },
-            "ecx": {
-              "type": "integer"
-            }
-          }
-        }
-      }
-    },
-    "flags": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "additionalProperties": false,
-        "properties": {
-          "description": {
-            "type": "string"
-          },
-          "input": {
-            "type": "object",
-            "additionalProperties": false,
-            "properties": {
-              "eax": {
-                "type": "integer"
-              },
-              "ecx": {
-                "type": "integer"
-              }
-            }
-          },
-          "bits": {
-            "type": "array",
-            "items": {
-              "type": "object",
-              "additionalProperties": false,
-              "properties": {
-                "name": {
-                  "type": "string"
-                },
-                "register": {
-                  "type": "string"
-                },
-                "bit": {
-                  "type": "integer"
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    "extension-flags": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "additionalProperties": false,
-        "properties": {
-          "description": {
-            "type": "string"
-          },
-          "input": {
-            "type": "object",
-            "additionalProperties": false,
-            "properties": {
-              "eax": {
-                "type": "integer"
-              },
-              "ecx": {
-                "type": "integer"
-              }
-            }
-          },
-          "bits": {
-            "type": "array",
-            "items": {
-              "type": "object",
-              "additionalProperties": false,
-              "properties": {
-                "name": {
-                  "type": "string"
-                },
-                "register": {
-                  "type": "string"
-                },
-                "bit": {
-                  "type": "integer"
-                }
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-}

lib/spack/external/archspec/vendor/cpuid/LICENSE

@@ -1,20 +0,0 @@
-The MIT License (MIT)
-
-Copyright (c) 2014 Anders Høst
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of
-this software and associated documentation files (the "Software"), to deal in
-the Software without restriction, including without limitation the rights to
-use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
-the Software, and to permit persons to whom the Software is furnished to do so,
-subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
-FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
-COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
-IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

lib/spack/external/archspec/vendor/cpuid/README.md

@@ -1,76 +0,0 @@
-cpuid.py
-========
-
-Now, this is silly!
-
-Pure Python library for accessing information about x86 processors
-by querying the [CPUID](http://en.wikipedia.org/wiki/CPUID)
-instruction. Well, not exactly pure Python...
-
-It works by allocating a small piece of virtual memory, copying
-a raw x86 function to that memory, giving the memory execute
-permissions and then calling the memory as a function. The injected
-function executes the CPUID instruction and copies the result back
-to a ctypes.Structure where is can be read by Python.
-
-It should work fine on both 32 and 64 bit versions of Windows and Linux
-running x86 processors. Apple OS X and other BSD systems should also work,
-not tested though...
-
-
-Why?
-----
-For poops and giggles. Plus, having access to a low-level feature
-without having to compile a C wrapper is pretty neat.
-
-
-Examples
---------
-Getting info with eax=0:
-
-    import cpuid
-
-    q = cpuid.CPUID()
-    eax, ebx, ecx, edx = q(0)
-
-Running the files:
-
-    $ python example.py 
-    Vendor ID : GenuineIntel
-    CPU name  : Intel(R) Xeon(R) CPU           W3550  @ 3.07GHz
-    
-    Vector instructions supported:
-    SSE       : Yes
-    SSE2      : Yes
-    SSE3      : Yes
-    SSSE3     : Yes
-    SSE4.1    : Yes
-    SSE4.2    : Yes
-    SSE4a     : --
-    AVX       : --
-    AVX2      : --
-    
-    $ python cpuid.py
-    CPUID    A        B        C        D
-    00000000 0000000b 756e6547 6c65746e 49656e69
-    00000001 000106a5 00100800 009ce3bd bfebfbff
-    00000002 55035a01 00f0b2e4 00000000 09ca212c
-    00000003 00000000 00000000 00000000 00000000
-    00000004 00000000 00000000 00000000 00000000
-    00000005 00000040 00000040 00000003 00001120
-    00000006 00000003 00000002 00000001 00000000
-    00000007 00000000 00000000 00000000 00000000
-    00000008 00000000 00000000 00000000 00000000
-    00000009 00000000 00000000 00000000 00000000
-    0000000a 07300403 00000044 00000000 00000603
-    0000000b 00000000 00000000 00000095 00000000
-    80000000 80000008 00000000 00000000 00000000
-    80000001 00000000 00000000 00000001 28100800
-    80000002 65746e49 2952286c 6f655820 2952286e
-    80000003 55504320 20202020 20202020 57202020
-    80000004 30353533 20402020 37302e33 007a4847
-    80000005 00000000 00000000 00000000 00000000
-    80000006 00000000 00000000 01006040 00000000
-    80000007 00000000 00000000 00000000 00000100
-    80000008 00003024 00000000 00000000 00000000
-

lib/spack/external/archspec/vendor/cpuid/cpuid.py

@@ -1,172 +0,0 @@
-# -*- coding: utf-8 -*-
-#
-#     Copyright (c) 2024 Anders Høst
-#
-
-from __future__ import print_function
-
-import platform
-import os
-import ctypes
-from ctypes import c_uint32, c_long, c_ulong, c_size_t, c_void_p, POINTER, CFUNCTYPE
-
-# Posix x86_64:
-# Three first call registers : RDI, RSI, RDX
-# Volatile registers         : RAX, RCX, RDX, RSI, RDI, R8-11
-
-# Windows x86_64:
-# Three first call registers : RCX, RDX, R8
-# Volatile registers         : RAX, RCX, RDX, R8-11
-
-# cdecl 32 bit:
-# Three first call registers : Stack (%esp)
-# Volatile registers         : EAX, ECX, EDX
-
-_POSIX_64_OPC = [
-        0x53,                    # push   %rbx
-        0x89, 0xf0,              # mov    %esi,%eax
-        0x89, 0xd1,              # mov    %edx,%ecx
-        0x0f, 0xa2,              # cpuid
-        0x89, 0x07,              # mov    %eax,(%rdi)
-        0x89, 0x5f, 0x04,        # mov    %ebx,0x4(%rdi)
-        0x89, 0x4f, 0x08,        # mov    %ecx,0x8(%rdi)
-        0x89, 0x57, 0x0c,        # mov    %edx,0xc(%rdi)
-        0x5b,                    # pop    %rbx
-        0xc3                     # retq
-]
-
-_WINDOWS_64_OPC = [
-        0x53,                    # push   %rbx
-        0x89, 0xd0,              # mov    %edx,%eax
-        0x49, 0x89, 0xc9,        # mov    %rcx,%r9
-        0x44, 0x89, 0xc1,        # mov    %r8d,%ecx
-        0x0f, 0xa2,              # cpuid
-        0x41, 0x89, 0x01,        # mov    %eax,(%r9)
-        0x41, 0x89, 0x59, 0x04,  # mov    %ebx,0x4(%r9)
-        0x41, 0x89, 0x49, 0x08,  # mov    %ecx,0x8(%r9)
-        0x41, 0x89, 0x51, 0x0c,  # mov    %edx,0xc(%r9)
-        0x5b,                    # pop    %rbx
-        0xc3                     # retq
-]
-
-_CDECL_32_OPC = [
-        0x53,                    # push   %ebx
-        0x57,                    # push   %edi
-        0x8b, 0x7c, 0x24, 0x0c,  # mov    0xc(%esp),%edi
-        0x8b, 0x44, 0x24, 0x10,  # mov    0x10(%esp),%eax
-        0x8b, 0x4c, 0x24, 0x14,  # mov    0x14(%esp),%ecx
-        0x0f, 0xa2,              # cpuid
-        0x89, 0x07,              # mov    %eax,(%edi)
-        0x89, 0x5f, 0x04,        # mov    %ebx,0x4(%edi)
-        0x89, 0x4f, 0x08,        # mov    %ecx,0x8(%edi)
-        0x89, 0x57, 0x0c,        # mov    %edx,0xc(%edi)
-        0x5f,                    # pop    %edi
-        0x5b,                    # pop    %ebx
-        0xc3                     # ret
-]
-
-is_windows = os.name == "nt"
-is_64bit = ctypes.sizeof(ctypes.c_voidp) == 8
-
-
-class CPUID_struct(ctypes.Structure):
-    _register_names = ("eax", "ebx", "ecx", "edx")
-    _fields_ = [(r, c_uint32) for r in _register_names]
-
-    def __getitem__(self, item):
-        if item not in self._register_names:
-            raise KeyError(item)
-        return getattr(self, item)
-
-    def __repr__(self):
-        return "eax=0x{:x}, ebx=0x{:x}, ecx=0x{:x}, edx=0x{:x}".format(self.eax, self.ebx, self.ecx, self.edx)
-
-
-class CPUID(object):
-    def __init__(self):
-        if platform.machine() not in ("AMD64", "x86_64", "x86", "i686"):
-            raise SystemError("Only available for x86")
-
-        if is_windows:
-            if is_64bit:
-                # VirtualAlloc seems to fail under some weird
-                # circumstances when ctypes.windll.kernel32 is
-                # used under 64 bit Python. CDLL fixes this.
-                self.win = ctypes.CDLL("kernel32.dll")
-                opc = _WINDOWS_64_OPC
-            else:
-                # Here ctypes.windll.kernel32 is needed to get the
-                # right DLL. Otherwise it will fail when running
-                # 32 bit Python on 64 bit Windows.
-                self.win = ctypes.windll.kernel32
-                opc = _CDECL_32_OPC
-        else:
-            opc = _POSIX_64_OPC if is_64bit else _CDECL_32_OPC
-
-        size = len(opc)
-        code = (ctypes.c_ubyte * size)(*opc)
-
-        if is_windows:
-            self.win.VirtualAlloc.restype = c_void_p
-            self.win.VirtualAlloc.argtypes = [ctypes.c_void_p, ctypes.c_size_t, ctypes.c_ulong, ctypes.c_ulong]
-            self.addr = self.win.VirtualAlloc(None, size, 0x1000, 0x40)
-            if not self.addr:
-                raise MemoryError("Could not allocate RWX memory")
-            ctypes.memmove(self.addr, code, size)
-        else:
-            from mmap import (
-                mmap,
-                MAP_PRIVATE,
-                MAP_ANONYMOUS,
-                PROT_WRITE,
-                PROT_READ,
-                PROT_EXEC,
-            )
-            self.mm = mmap(
-                -1,
-                size,
-                flags=MAP_PRIVATE | MAP_ANONYMOUS,
-                prot=PROT_WRITE | PROT_READ | PROT_EXEC,
-            )
-            self.mm.write(code)
-            self.addr = ctypes.addressof(ctypes.c_int.from_buffer(self.mm))
-
-        func_type = CFUNCTYPE(None, POINTER(CPUID_struct), c_uint32, c_uint32)
-        self.func_ptr = func_type(self.addr)
-
-    def __call__(self, eax, ecx=0):
-        struct = self.registers_for(eax=eax, ecx=ecx)
-        return struct.eax, struct.ebx, struct.ecx, struct.edx
-
-    def registers_for(self, eax, ecx=0):
-        """Calls cpuid with eax and ecx set as the input arguments, and returns a structure
-        containing eax, ebx, ecx, and edx.
-        """
-        struct = CPUID_struct()
-        self.func_ptr(struct, eax, ecx)
-        return struct
-
-    def __del__(self):
-        if is_windows:
-            self.win.VirtualFree.restype = c_long
-            self.win.VirtualFree.argtypes = [c_void_p, c_size_t, c_ulong]
-            self.win.VirtualFree(self.addr, 0, 0x8000)
-        else:
-            self.mm.close()
-
-
-
-if __name__ == "__main__":
-    def valid_inputs():
-        cpuid = CPUID()
-        for eax in (0x0, 0x80000000):
-            highest, _, _, _ = cpuid(eax)
-            while eax <= highest:
-                regs = cpuid(eax)
-                yield (eax, regs)
-                eax += 1
-
-
-    print(" ".join(x.ljust(8) for x in ("CPUID", "A", "B", "C", "D")).strip())
-    for eax, regs in valid_inputs():
-        print("%08x" % eax, " ".join("%08x" % reg for reg in regs))

lib/spack/external/archspec/vendor/cpuid/example.py

@@ -1,62 +0,0 @@
-# -*- coding: utf-8 -*-
-#
-#     Copyright (c) 2024 Anders Høst
-#
-
-from __future__ import print_function
-
-import struct
-import cpuid
-
-
-def cpu_vendor(cpu):
-    _, b, c, d = cpu(0)
-    return struct.pack("III", b, d, c).decode("utf-8")
-
-
-def cpu_name(cpu):
-    name = "".join((struct.pack("IIII", *cpu(0x80000000 + i)).decode("utf-8")
-                    for i in range(2, 5)))
-
-    return name.split('\x00', 1)[0]
-
-
-def is_set(cpu, leaf, subleaf, reg_idx, bit):
-    """
-    @param {leaf} %eax
-    @param {sublead} %ecx, 0 in most cases
-    @param {reg_idx} idx of [%eax, %ebx, %ecx, %edx], 0-based
-    @param {bit} bit of reg selected by {reg_idx}, 0-based
-    """
-
-    regs = cpu(leaf, subleaf)
-
-    if (1 << bit) & regs[reg_idx]:
-        return "Yes"
-    else:
-        return "--"
-
-
-if __name__ == "__main__":
-    cpu = cpuid.CPUID()
-
-    print("Vendor ID : %s" % cpu_vendor(cpu))
-    print("CPU name  : %s" % cpu_name(cpu))
-    print()
-    print("Vector instructions supported:")
-    print("SSE       : %s" % is_set(cpu, 1, 0, 3, 25))
-    print("SSE2      : %s" % is_set(cpu, 1, 0, 3, 26))
-    print("SSE3      : %s" % is_set(cpu, 1, 0, 2, 0))
-    print("SSSE3     : %s" % is_set(cpu, 1, 0, 2, 9))
-    print("SSE4.1    : %s" % is_set(cpu, 1, 0, 2, 19))
-    print("SSE4.2    : %s" % is_set(cpu, 1, 0, 2, 20))
-    print("SSE4a     : %s" % is_set(cpu, 0x80000001, 0, 2, 6))
-    print("AVX       : %s" % is_set(cpu, 1, 0, 2, 28))
-    print("AVX2      : %s" % is_set(cpu, 7, 0, 1, 5))
-    print("BMI1      : %s" % is_set(cpu, 7, 0, 1, 3))
-    print("BMI2      : %s" % is_set(cpu, 7, 0, 1, 8))
-    # Intel RDT CMT/MBM
-    print("L3 Monitoring : %s" % is_set(cpu, 0xf, 0, 3, 1))
-    print("L3 Occupancy  : %s" % is_set(cpu, 0xf, 1, 3, 0))
-    print("L3 Total BW   : %s" % is_set(cpu, 0xf, 1, 3, 1))
-    print("L3 Local BW   : %s" % is_set(cpu, 0xf, 1, 3, 2))

lib/spack/llnl/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
 # Spack Project Developers. See the top-level COPYRIGHT file for details.
 #
 # SPDX-License-Identifier: (Apache-2.0 OR MIT)

lib/spack/llnl/path.py

@@ -1,4 +1,4 @@
-# Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
 # Spack Project Developers. See the top-level COPYRIGHT file for details.
 #
 # SPDX-License-Identifier: (Apache-2.0 OR MIT)
@@ -42,6 +42,11 @@ def convert_to_posix_path(path: str) -> str:
     return format_os_path(path, mode=Path.unix)
 
 
+def convert_to_windows_path(path: str) -> str:
+    """Converts the input path to Windows style."""
+    return format_os_path(path, mode=Path.windows)
+
+
 def convert_to_platform_path(path: str) -> str:
     """Converts the input path to the current platform's native style."""
     return format_os_path(path, mode=Path.platform_path)

lib/spack/llnl/string.py

@@ -1,4 +1,4 @@
-# Copyright 2013-2024 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
 # Spack Project Developers. See the top-level COPYRIGHT file for details.
 #
 # SPDX-License-Identifier: (Apache-2.0 OR MIT)