python: urls return [None] if not pypi

.codecov.yml

@@ -5,7 +5,7 @@ coverage:
   status:
     project:
       default:
-        threshold: 2.0%
+        threshold: 0.2%
 
 ignore:
   - lib/spack/spack/test/.*

.devcontainer/devcontainer.json

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

.devcontainer/ubuntu22.04/devcontainer.json

@@ -1,5 +0,0 @@
-{
-  "name": "Ubuntu 22.04",
-  "image": "ghcr.io/spack/ubuntu-22.04:v2024-05-07",
-  "postCreateCommand": "./.devcontainer/postCreateCommand.sh"
-}

.github/workflows/audit.yaml

@@ -28,8 +28,8 @@ jobs:
       run:
         shell: ${{ matrix.system.shell }}
     steps:
-    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+    - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
-    - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b
+    - uses: actions/setup-python@39cd14951b08e74b54015e9e001cdefcf80e669f
       with:
         python-version: ${{inputs.python_version}}
     - name: Install Python packages
@@ -40,8 +40,6 @@ jobs:
       run: |
         python -m pip install --upgrade pywin32
     - name: Package audits (with coverage)
-      env:
-          COVERAGE_FILE: coverage/.coverage-audits-${{ matrix.system.os }}
       if: ${{ inputs.with_coverage == 'true' && runner.os != 'Windows' }}
       run: |
           . share/spack/setup-env.sh
@@ -49,6 +47,7 @@ jobs:
           coverage run $(which spack) audit configs
           coverage run $(which spack) -d audit externals
           coverage combine
+          coverage xml
     - name: Package audits (without coverage)
       if: ${{ inputs.with_coverage == 'false' && runner.os != 'Windows' }}
       run: |
@@ -59,15 +58,16 @@ jobs:
     - name: Package audits (without coverage)
       if: ${{ runner.os == 'Windows' }}
       run: |
+          . share/spack/setup-env.sh          
           spack -d audit packages
           ./share/spack/qa/validate_last_exit.ps1
           spack -d audit configs
           ./share/spack/qa/validate_last_exit.ps1
           spack -d audit externals
           ./share/spack/qa/validate_last_exit.ps1
-    - uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b
+    - uses: codecov/codecov-action@e28ff129e5465c2c0dcc6f003fc735cb6ae0c673
-      if: ${{ inputs.with_coverage == 'true' && runner.os != 'Windows' }}
+      if: ${{ inputs.with_coverage == 'true' }}
       with:
-        name: coverage-audits-${{ matrix.system.os }}
+        flags: unittests,audits
-        path: coverage
+        token: ${{ secrets.CODECOV_TOKEN }}
-        include-hidden-files: true
+        verbose: true

.github/workflows/bin/bootstrap-test.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 set -e
 source share/spack/setup-env.sh
-$PYTHON bin/spack bootstrap disable github-actions-v0.5
+$PYTHON bin/spack bootstrap disable github-actions-v0.4
 $PYTHON bin/spack bootstrap disable spack-install
 $PYTHON bin/spack $SPACK_FLAGS solve zlib
 tree $BOOTSTRAP/store

.github/workflows/bin/setup_git.ps1

@@ -1,3 +1,5 @@
+# (c) 2022 Lawrence Livermore National Laboratory
+
 git config --global user.email "spack@example.com"
 git config --global user.name "Test User"
 git config --global core.longpaths true

.github/workflows/bootstrap.yml

@@ -37,14 +37,14 @@ jobs:
               make patch unzip which xz python3 python3-devel tree \
               cmake bison
       - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
         with:
           fetch-depth: 0
       - name: Bootstrap clingo
         run: |
           source share/spack/setup-env.sh
-          spack bootstrap disable github-actions-v0.6
           spack bootstrap disable github-actions-v0.5
+          spack bootstrap disable github-actions-v0.4
           spack external find cmake bison
           spack -d solve zlib
           tree ~/.spack/bootstrap/store/
@@ -53,27 +53,33 @@ jobs:
     runs-on: ${{ matrix.runner }}
     strategy:
       matrix:
-        runner: ['macos-13', 'macos-14', "ubuntu-latest"]
+        runner: ['macos-13', 'macos-14', "ubuntu-latest", "windows-latest"]
     steps:
       - name: Setup macOS
-        if: ${{ matrix.runner != 'ubuntu-latest' }}
+        if: ${{ matrix.runner != 'ubuntu-latest' && matrix.runner != 'windows-latest' }}
         run: |
           brew install cmake bison tree
       - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
         with:
           fetch-depth: 0
-      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b
+      - uses: actions/setup-python@39cd14951b08e74b54015e9e001cdefcf80e669f
         with:
           python-version: "3.12"
       - name: Bootstrap clingo
+        env:
+          SETUP_SCRIPT_EXT: ${{ matrix.runner == 'windows-latest' && 'ps1' || 'sh' }}
+          SETUP_SCRIPT_SOURCE: ${{ matrix.runner == 'windows-latest' && './' || 'source ' }}
+          USER_SCOPE_PARENT_DIR: ${{ matrix.runner == 'windows-latest' && '$env:userprofile' || '$HOME' }}
+          VALIDATE_LAST_EXIT: ${{ matrix.runner == 'windows-latest' && './share/spack/qa/validate_last_exit.ps1' || '' }}
         run: |
-          source share/spack/setup-env.sh
+          ${{ env.SETUP_SCRIPT_SOURCE }}share/spack/setup-env.${{ env.SETUP_SCRIPT_EXT }}
-          spack bootstrap disable github-actions-v0.6
           spack bootstrap disable github-actions-v0.5
+          spack bootstrap disable github-actions-v0.4
           spack external find --not-buildable cmake bison
           spack -d solve zlib
-          tree $HOME/.spack/bootstrap/store/
+          ${{ env.VALIDATE_LAST_EXIT }}
+          tree ${{ env.USER_SCOPE_PARENT_DIR }}/.spack/bootstrap/store/
 
   gnupg-sources:
     runs-on: ${{ matrix.runner }}
@@ -83,22 +89,22 @@ jobs:
     steps:
       - name: Setup macOS
         if: ${{ matrix.runner != 'ubuntu-latest' }}
-        run: brew install tree gawk
-      - name: Remove system executables
         run: |
-          while [ -n "$(command -v gpg gpg2 patchelf)" ]; do
+          brew install tree gawk
-            sudo rm $(command -v gpg gpg2 patchelf)
+          sudo rm -rf $(command -v gpg gpg2)
-          done
+      - name: Setup Ubuntu
+        if: ${{ matrix.runner == 'ubuntu-latest' }}
+        run: sudo rm -rf $(command -v gpg gpg2 patchelf)
       - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
         with:
           fetch-depth: 0
       - name: Bootstrap GnuPG
         run: |
           source share/spack/setup-env.sh
           spack solve zlib
-          spack bootstrap disable github-actions-v0.6
           spack bootstrap disable github-actions-v0.5
+          spack bootstrap disable github-actions-v0.4
           spack -d gpg list
           tree ~/.spack/bootstrap/store/
 
@@ -110,17 +116,19 @@ jobs:
     steps:
       - name: Setup macOS
         if: ${{ matrix.runner != 'ubuntu-latest' }}
-        run: brew install tree
-      - name: Remove system executables
         run: |
-          while [ -n "$(command -v gpg gpg2 patchelf)" ]; do
+          brew install tree
-            sudo rm $(command -v gpg gpg2 patchelf)
+          # Remove GnuPG since we want to bootstrap it
-          done
+          sudo rm -rf /usr/local/bin/gpg
+      - name: Setup Ubuntu
+        if: ${{ matrix.runner == 'ubuntu-latest' }}
+        run: |
+          sudo rm -rf $(which gpg) $(which gpg2) $(which patchelf)
       - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
         with:
           fetch-depth: 0
-      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b
+      - uses: actions/setup-python@39cd14951b08e74b54015e9e001cdefcf80e669f
         with:
           python-version: |
             3.8
@@ -128,16 +136,15 @@ jobs:
             3.10
             3.11
             3.12
-            3.13
       - name: Set bootstrap sources
         run: |
           source share/spack/setup-env.sh
-          spack bootstrap disable github-actions-v0.5
+          spack bootstrap disable github-actions-v0.4
           spack bootstrap disable spack-install
       - name: Bootstrap clingo
         run: |
           set -e
-          for ver in '3.8' '3.9' '3.10' '3.11' '3.12' '3.13'; do
+          for ver in '3.8' '3.9' '3.10' '3.11' '3.12' ; do
             not_found=1
             ver_dir="$(find $RUNNER_TOOL_CACHE/Python -wholename "*/${ver}.*/*/bin" | grep . || true)"
             if [[ -d "$ver_dir" ]] ; then
@@ -160,35 +167,4 @@ jobs:
         run: |
           source share/spack/setup-env.sh
           spack -d gpg list
-          tree $HOME/.spack/bootstrap/store/
+          tree ~/.spack/bootstrap/store/
-
-
-  windows:
-    runs-on: "windows-latest"
-    steps:
-      - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
-        with:
-          fetch-depth: 0
-      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b
-        with:
-          python-version: "3.12"
-      - name: Setup Windows
-        run: |
-          Remove-Item -Path (Get-Command gpg).Path
-          Remove-Item -Path (Get-Command file).Path
-      - name: Bootstrap clingo
-        run: |
-          ./share/spack/setup-env.ps1
-          spack bootstrap disable github-actions-v0.6
-          spack bootstrap disable github-actions-v0.5
-          spack external find --not-buildable cmake bison
-          spack -d solve zlib
-          ./share/spack/qa/validate_last_exit.ps1
-          tree $env:userprofile/.spack/bootstrap/store/
-      - name: Bootstrap GnuPG
-        run: |
-          ./share/spack/setup-env.ps1
-          spack -d gpg list
-          ./share/spack/qa/validate_last_exit.ps1
-          tree $env:userprofile/.spack/bootstrap/store/

.github/workflows/build-containers.yml

@@ -40,30 +40,24 @@ jobs:
         # 1: Platforms to build for
         # 2: Base image (e.g. ubuntu:22.04)
         dockerfile: [[amazon-linux, 'linux/amd64,linux/arm64', 'amazonlinux:2'],
-                     [centos-stream9, 'linux/amd64,linux/arm64', 'centos:stream9'],
+                     [centos-stream9, 'linux/amd64,linux/arm64,linux/ppc64le', 'centos:stream9'],
-                     [leap15, 'linux/amd64,linux/arm64', 'opensuse/leap:15'],
+                     [leap15, 'linux/amd64,linux/arm64,linux/ppc64le', 'opensuse/leap:15'],
-                     [ubuntu-focal, 'linux/amd64,linux/arm64', 'ubuntu:20.04'],
+                     [ubuntu-focal, 'linux/amd64,linux/arm64,linux/ppc64le', 'ubuntu:20.04'],
-                     [ubuntu-jammy, 'linux/amd64,linux/arm64', 'ubuntu:22.04'],
+                     [ubuntu-jammy, 'linux/amd64,linux/arm64,linux/ppc64le', 'ubuntu:22.04'],
-                     [ubuntu-noble, 'linux/amd64,linux/arm64', 'ubuntu:24.04'],
+                     [ubuntu-noble, 'linux/amd64,linux/arm64,linux/ppc64le', 'ubuntu:24.04'],
-                     [almalinux8, 'linux/amd64,linux/arm64', 'almalinux:8'],
+                     [almalinux8, 'linux/amd64,linux/arm64,linux/ppc64le', 'almalinux:8'],
-                     [almalinux9, 'linux/amd64,linux/arm64', 'almalinux:9'],
+                     [almalinux9, 'linux/amd64,linux/arm64,linux/ppc64le', 'almalinux:9'],
                      [rockylinux8, 'linux/amd64,linux/arm64', 'rockylinux:8'],
                      [rockylinux9, 'linux/amd64,linux/arm64', 'rockylinux:9'],
-                     [fedora39, 'linux/amd64,linux/arm64', 'fedora:39'],
+                     [fedora39, 'linux/amd64,linux/arm64,linux/ppc64le', 'fedora:39'],
-                     [fedora40, 'linux/amd64,linux/arm64', 'fedora:40']]
+                     [fedora40, 'linux/amd64,linux/arm64,linux/ppc64le', 'fedora:40']]
     name: Build ${{ matrix.dockerfile[0] }}
     if: github.repository == 'spack/spack'
     steps:
       - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
 
-      - name: Determine latest release tag
+      - uses: docker/metadata-action@8e5442c4ef9f78752691e2d8f8d19755c6f78e81
-        id: latest
-        run: |
-          git fetch --quiet --tags
-          echo "tag=$(git tag --list --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -n 1)" | tee -a $GITHUB_OUTPUT
-
-      - uses: docker/metadata-action@369eb591f429131d6889c46b94e711f089e6ca96
         id: docker_meta
         with:
           images: |
@@ -77,7 +71,6 @@ jobs:
               type=semver,pattern={{major}}
               type=ref,event=branch
               type=ref,event=pr
-              type=raw,value=latest,enable=${{ github.ref == format('refs/tags/{0}', steps.latest.outputs.tag) }}
 
       - name: Generate the Dockerfile
         env:
@@ -94,7 +87,7 @@ jobs:
           fi
 
       - name: Upload Dockerfile
-        uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b
+        uses: actions/upload-artifact@834a144ee995460fba8ed112a2fc961b36a5ec5a
         with:
           name: dockerfiles_${{ matrix.dockerfile[0] }}
           path: dockerfiles
@@ -103,7 +96,7 @@ jobs:
         uses: docker/setup-qemu-action@49b3bc8e6bdd4a60e6116a5414239cba5943d3cf
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@6524bf65af31da8d45b59e8c27de4bd072b392f5
+        uses: docker/setup-buildx-action@988b5a0280414f521da01fcc63a27aeeb4b104db
 
       - name: Log in to GitHub Container Registry
         uses: docker/login-action@9780b0c442fbb1117ed29e0efdff1e18412f7567
@@ -120,7 +113,7 @@ jobs:
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Build & Deploy ${{ matrix.dockerfile[0] }}
-        uses: docker/build-push-action@48aba3b46d1b1fec4febb7c5d0c644b249a11355
+        uses: docker/build-push-action@16ebe778df0e7752d2cfcbd924afdbbd89c1a755
         with:
           context: dockerfiles/${{ matrix.dockerfile[0] }}
           platforms: ${{ matrix.dockerfile[1] }}
@@ -133,7 +126,7 @@ jobs:
     needs: deploy-images
     steps:
       - name: Merge Artifacts
-        uses: actions/upload-artifact/merge@6f51ac03b9356f520e9adb1b1b7802705f340c2b
+        uses: actions/upload-artifact/merge@834a144ee995460fba8ed112a2fc961b36a5ec5a
         with:
           name: dockerfiles
           pattern: dockerfiles_*

.github/workflows/ci.yaml

@@ -9,13 +9,24 @@ on:
     branches:
       - develop
       - releases/**
-  merge_group:
 
 concurrency:
   group: ci-${{github.ref}}-${{github.event.pull_request.number || github.run_number}}
   cancel-in-progress: true
 
 jobs:
+  prechecks:
+    needs: [ changes ]
+    uses: ./.github/workflows/valid-style.yml
+    secrets: inherit
+    with:
+      with_coverage: ${{ needs.changes.outputs.core }}
+  all-prechecks:
+    needs: [ prechecks ]
+    runs-on: ubuntu-latest
+    steps:
+    - name: Success
+      run: "true"
   # Check which files have been updated by the PR
   changes:
     runs-on: ubuntu-latest
@@ -25,18 +36,14 @@ jobs:
       core: ${{ steps.filter.outputs.core }}
       packages: ${{ steps.filter.outputs.packages }}
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
-        if: ${{ github.event_name == 'push' || github.event_name == 'merge_group' }}
+        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
         id: filter
         with:
-          # For merge group events, compare against the target branch (main)
-          base: ${{ github.event_name == 'merge_group' && github.event.merge_group.base_ref || '' }}
-          # For merge group events, use the merge group head ref
-          ref: ${{ github.event_name == 'merge_group' && github.event.merge_group.head_sha || github.ref }}
           # See https://github.com/dorny/paths-filter/issues/56 for the syntax used below
           # Don't run if we only modified packages in the
           # built-in repository or documentation
@@ -72,59 +79,14 @@ jobs:
     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
-
+  all:
-  prechecks:
+    needs: [ unit-tests, bootstrap ]
-    needs: [ changes ]
-    uses: ./.github/workflows/prechecks.yml
-    secrets: inherit
-    with:
-      with_coverage: ${{ needs.changes.outputs.core }}
-      with_packages: ${{ needs.changes.outputs.packages }}
-
-  import-check:
-    needs: [ changes ]
-    uses: ./.github/workflows/import-check.yaml
-
-  all-prechecks:
-    needs: [ prechecks ]
-    if: ${{ always() }}
     runs-on: ubuntu-latest
     steps:
     - name: Success
-      run: |
+      run: "true"
-        if [ "${{ needs.prechecks.result }}" == "failure" ] || [ "${{ needs.prechecks.result }}" == "canceled" ]; then
-          echo "Unit tests failed."
-          exit 1
-        else
-          exit 0
-        fi
-
-  coverage:
-    needs: [ unit-tests, prechecks ]
-    if: ${{ needs.changes.outputs.core }}
-    uses: ./.github/workflows/coverage.yml
-    secrets: inherit
-
-  all:
-    needs: [ unit-tests, coverage, bootstrap ]
-    if: ${{ always() }}
-    runs-on: ubuntu-latest
-    # See https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#needs-context
-    steps:
-    - name: Status summary
-      run: |
-        if [ "${{ needs.unit-tests.result }}" == "failure" ] || [ "${{ needs.unit-tests.result }}" == "canceled" ]; then
-          echo "Unit tests failed."
-          exit 1
-        elif [ "${{ needs.bootstrap.result }}" == "failure" ] || [ "${{ needs.bootstrap.result }}" == "canceled" ]; then
-          echo "Bootstrap tests failed."
-          exit 1
-        else
-          exit 0
-        fi

.github/workflows/coverage.yml

@@ -1,36 +0,0 @@
-name: coverage
-
-on:
-  workflow_call:
-
-jobs:
-  # Upload coverage reports to codecov once as a single bundle
-  upload:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
-    - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b
-      with:
-        python-version: '3.11'
-        cache: 'pip'
-
-    - name: Install python dependencies
-      run: pip install -r .github/workflows/requirements/coverage/requirements.txt
-
-    - name: Download coverage artifact files
-      uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16
-      with:
-        pattern: coverage-*
-        path: coverage
-        merge-multiple: true
-
-    - run: ls -la coverage
-    - run: coverage combine -a coverage/.coverage*
-    - run: coverage xml
-
-    - name: "Upload coverage report to CodeCov"
-      uses: codecov/codecov-action@1e68e06f1dbfde0e4cefc87efeba9e4643565303
-      with:
-        verbose: true
-        fail_ci_if_error: false
-        token: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/import-check.yaml

@@ -1,49 +0,0 @@
-name: import-check
-
-on:
-  workflow_call:
-
-jobs:
-  # Check we don't make the situation with circular imports worse
-  import-check:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: julia-actions/setup-julia@v2
-      with:
-        version: '1.10'
-    - uses: julia-actions/cache@v2
-
-    # PR: use the base of the PR as the old commit
-    - name: Checkout PR base commit
-      if: github.event_name == 'pull_request'
-      uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
-      with:
-        ref: ${{ github.event.pull_request.base.sha }}
-        path: old
-    # not a PR: use the previous commit as the old commit
-    - name: Checkout previous commit
-      if: github.event_name != 'pull_request'
-      uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
-      with:
-        fetch-depth: 2
-        path: old
-    - name: Checkout previous commit
-      if: github.event_name != 'pull_request'
-      run: git -C old reset --hard HEAD^
-
-    - name: Checkout new commit
-      uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
-      with:
-        path: new
-    - name: Install circular import checker
-      uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
-      with:
-        repository: haampie/circular-import-fighter
-        ref: 4cdb0bf15f04ab6b49041d5ef1bfd9644cce7f33
-        path: circular-import-fighter
-    - name: Install dependencies
-      working-directory: circular-import-fighter
-      run: make -j dependencies
-    - name: Circular import check
-      working-directory: circular-import-fighter
-      run: make -j compare "SPACK_ROOT=../old ../new"

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

@@ -14,10 +14,10 @@ jobs:
   build-paraview-deps:
     runs-on: windows-latest
     steps:
-    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+    - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
       with:
         fetch-depth: 0
-    - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b
+    - uses: actions/setup-python@39cd14951b08e74b54015e9e001cdefcf80e669f
       with:
         python-version: 3.9
     - name: Install Python packages

.github/workflows/requirements/coverage/requirements.txt

@@ -1 +0,0 @@
-coverage==7.6.1

.github/workflows/requirements/style/requirements.txt

@@ -1,7 +1,7 @@
-black==25.1.0
+black==24.8.0
 clingo==5.7.1
-flake8==7.2.0
+flake8==7.1.1
-isort==6.0.1
+isort==5.13.2
-mypy==1.15.0
+mypy==1.8.0
-types-six==1.17.0.20250304
+types-six==1.16.21.20240513
 vermin==1.6.0

.github/workflows/unit_tests.yaml

@@ -15,32 +15,46 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
+        python-version: ['3.7', '3.8', '3.9', '3.10', '3.11', '3.12']
+        concretizer: ['clingo']
         on_develop:
         - ${{ github.ref == 'refs/heads/develop' }}
         include:
-        - python-version: '3.7'
+        - python-version: '3.11'
-          os: ubuntu-22.04
+          os: ubuntu-latest
+          concretizer: original
+          on_develop: ${{ github.ref == 'refs/heads/develop' }}
+        - python-version: '3.6'
+          os: ubuntu-20.04
+          concretizer: clingo
           on_develop: ${{ github.ref == 'refs/heads/develop' }}
         exclude:
+        - python-version: '3.7'
+          os: ubuntu-latest
+          concretizer: 'clingo'
+          on_develop: false
         - python-version: '3.8'
           os: ubuntu-latest
+          concretizer: 'clingo'
           on_develop: false
         - python-version: '3.9'
           os: ubuntu-latest
+          concretizer: 'clingo'
           on_develop: false
         - python-version: '3.10'
           os: ubuntu-latest
+          concretizer: 'clingo'
           on_develop: false
         - python-version: '3.11'
           os: ubuntu-latest
+          concretizer: 'clingo'
           on_develop: false
 
     steps:
-    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+    - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
       with:
         fetch-depth: 0
-    - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b
+    - uses: actions/setup-python@39cd14951b08e74b54015e9e001cdefcf80e669f
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install System packages
@@ -49,13 +63,7 @@ jobs:
           # Needed for unit tests
           sudo apt-get -y install \
               coreutils cvs gfortran graphviz gnupg2 mercurial ninja-build \
-              cmake bison libbison-dev subversion
+              cmake bison libbison-dev kcov
-    # On ubuntu 24.04, kcov was removed. It may come back in some future Ubuntu
-    - name: Set up Homebrew
-      id: set-up-homebrew
-      uses: Homebrew/actions/setup-homebrew@40e9946c182a64b3db1bf51be0dcb915f7802aa9
-    - name: Install kcov with brew
-      run: "brew install kcov"
     - name: Install Python packages
       run: |
           pip install --upgrade pip setuptools pytest pytest-xdist pytest-cov
@@ -77,38 +85,32 @@ jobs:
     - name: Run unit tests
       env:
           SPACK_PYTHON: python
+          SPACK_TEST_SOLVER: ${{ matrix.concretizer }}
           SPACK_TEST_PARALLEL: 2
           COVERAGE: true
-          COVERAGE_FILE: coverage/.coverage-${{ matrix.os }}-python${{ matrix.python-version }}
           UNIT_TEST_COVERAGE: ${{ matrix.python-version == '3.11' }}
       run: |
           share/spack/qa/run-unit-tests
-    - uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b
+    - uses: codecov/codecov-action@e28ff129e5465c2c0dcc6f003fc735cb6ae0c673
       with:
-        name: coverage-${{ matrix.os }}-python${{ matrix.python-version }}
+        flags: unittests,linux,${{ matrix.concretizer }}
-        path: coverage
+        token: ${{ secrets.CODECOV_TOKEN }}
-        include-hidden-files: true
+        verbose: true
   # Test shell integration
   shell:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+    - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
       with:
         fetch-depth: 0
-    - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b
+    - uses: actions/setup-python@39cd14951b08e74b54015e9e001cdefcf80e669f
       with:
         python-version: '3.11'
     - name: Install System packages
       run: |
           sudo apt-get -y update
           # Needed for shell tests
-          sudo apt-get install -y coreutils csh zsh tcsh fish dash bash subversion
+          sudo apt-get install -y coreutils kcov csh zsh tcsh fish dash bash
-    # On ubuntu 24.04, kcov was removed. It may come back in some future Ubuntu
-    - name: Set up Homebrew
-      id: set-up-homebrew
-      uses: Homebrew/actions/setup-homebrew@40e9946c182a64b3db1bf51be0dcb915f7802aa9
-    - name: Install kcov with brew
-      run: "brew install kcov"
     - name: Install Python packages
       run: |
           pip install --upgrade pip setuptools pytest coverage[toml] pytest-xdist
@@ -122,11 +124,11 @@ jobs:
           COVERAGE: true
       run: |
           share/spack/qa/run-shell-tests
-    - uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b
+    - uses: codecov/codecov-action@e28ff129e5465c2c0dcc6f003fc735cb6ae0c673
       with:
-        name: coverage-shell
+        flags: shelltests,linux
-        path: coverage
+        token: ${{ secrets.CODECOV_TOKEN }}
-        include-hidden-files: true
+        verbose: true
 
   # Test RHEL8 UBI with platform Python. This job is run
   # only on PRs modifying core Spack
@@ -137,13 +139,13 @@ jobs:
     - name: Install dependencies
       run: |
           dnf install -y \
-              bzip2 curl gcc-c++ gcc gcc-gfortran git gnupg2 gzip \
+              bzip2 curl file gcc-c++ gcc gcc-gfortran git gnupg2 gzip \
               make patch tcl unzip which xz
-    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+    - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
     - name: Setup repo and non-root user
       run: |
           git --version
-          git config --global --add safe.directory '*'
+          git config --global --add safe.directory /__w/spack/spack
           git fetch --unshallow
           . .github/workflows/bin/setup_git.sh
           useradd spack-test
@@ -158,37 +160,36 @@ jobs:
   clingo-cffi:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+    - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
       with:
         fetch-depth: 0
-    - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b
+    - uses: actions/setup-python@39cd14951b08e74b54015e9e001cdefcf80e669f
       with:
-        python-version: '3.13'
+        python-version: '3.11'
     - name: Install System packages
       run: |
           sudo apt-get -y update
-          sudo apt-get -y install coreutils gfortran graphviz gnupg2
+          sudo apt-get -y install coreutils cvs gfortran graphviz gnupg2 mercurial ninja-build kcov
     - name: Install Python packages
       run: |
-          pip install --upgrade pip setuptools pytest coverage[toml] pytest-cov clingo
+          pip install --upgrade pip setuptools pytest coverage[toml] pytest-cov clingo pytest-xdist
           pip install --upgrade flake8 "isort>=4.3.5" "mypy>=0.900" "click" "black"
+    - name: Setup git configuration
+      run: |
+          # Need this for the git tests to succeed.
+          git --version
+          . .github/workflows/bin/setup_git.sh
     - name: Run unit tests (full suite with coverage)
       env:
           COVERAGE: true
-          COVERAGE_FILE: coverage/.coverage-clingo-cffi
+          SPACK_TEST_SOLVER: clingo
       run: |
-        . share/spack/setup-env.sh
+          share/spack/qa/run-unit-tests
-        spack bootstrap disable spack-install
+    - uses: codecov/codecov-action@e28ff129e5465c2c0dcc6f003fc735cb6ae0c673
-        spack bootstrap disable github-actions-v0.5
-        spack bootstrap disable github-actions-v0.6
-        spack bootstrap status
-        spack solve zlib
-        spack unit-test --verbose --cov --cov-config=pyproject.toml --cov-report=xml:coverage.xml lib/spack/spack/test/concretization/core.py
-    - uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b
       with:
-        name: coverage-clingo-cffi
+        flags: unittests,linux,clingo
-        path: coverage
+        token: ${{ secrets.CODECOV_TOKEN }}
-        include-hidden-files: true
+        verbose: true
   # Run unit tests on MacOS
   macos:
     runs-on: ${{ matrix.os }}
@@ -197,10 +198,10 @@ jobs:
         os: [macos-13, macos-14]
         python-version: ["3.11"]
     steps:
-    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+    - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
       with:
         fetch-depth: 0
-    - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b
+    - uses: actions/setup-python@39cd14951b08e74b54015e9e001cdefcf80e669f
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install Python packages
@@ -209,11 +210,11 @@ jobs:
           pip install --upgrade pytest coverage[toml] pytest-xdist pytest-cov
     - name: Setup Homebrew packages
       run: |
-        brew install dash fish gcc gnupg kcov
+        brew install dash fish gcc gnupg2 kcov
     - name: Run unit tests
       env:
+        SPACK_TEST_SOLVER: clingo
         SPACK_TEST_PARALLEL: 4
-        COVERAGE_FILE: coverage/.coverage-${{ matrix.os }}-python${{ matrix.python-version }}
       run: |
         git --version
         . .github/workflows/bin/setup_git.sh
@@ -222,11 +223,11 @@ jobs:
         $(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[@]}"
-    - uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b
+    - uses: codecov/codecov-action@e28ff129e5465c2c0dcc6f003fc735cb6ae0c673
       with:
-        name: coverage-${{ matrix.os }}-python${{ matrix.python-version }}
+        flags: unittests,macos
-        path: coverage
+        token: ${{ secrets.CODECOV_TOKEN }}
-        include-hidden-files: true
+        verbose: true
   # Run unit tests on Windows
   windows:
     defaults:
@@ -235,10 +236,10 @@ jobs:
           powershell Invoke-Expression -Command "./share/spack/qa/windows_test_setup.ps1"; {0}
     runs-on: windows-latest
     steps:
-    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+    - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
       with:
         fetch-depth: 0
-    - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b
+    - uses: actions/setup-python@39cd14951b08e74b54015e9e001cdefcf80e669f
       with:
         python-version: 3.9
     - name: Install Python packages
@@ -248,13 +249,13 @@ jobs:
       run: |
         ./.github/workflows/bin/setup_git.ps1
     - name: Unit Test
-      env:
-        COVERAGE_FILE: coverage/.coverage-windows
       run: |
         spack unit-test -x --verbose --cov --cov-config=pyproject.toml
         ./share/spack/qa/validate_last_exit.ps1
-    - uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b
+        coverage combine -a
+        coverage xml
+    - uses: codecov/codecov-action@e28ff129e5465c2c0dcc6f003fc735cb6ae0c673
       with:
-        name: coverage-windows
+        flags: unittests,windows
-        path: coverage
+        token: ${{ secrets.CODECOV_TOKEN }}
-        include-hidden-files: true
+        verbose: true

.github/workflows/valid-style.yml

@@ -1,4 +1,4 @@
-name: prechecks
+name: style
 
 on:
   workflow_call:
@@ -6,9 +6,6 @@ on:
       with_coverage:
         required: true
         type: string
-      with_packages:
-        required: true
-        type: string
 
 concurrency:
   group: style-${{github.ref}}-${{github.event.pull_request.number || github.run_number}}
@@ -16,14 +13,15 @@ concurrency:
 
 
 jobs:
-  # Validate that the code can be run on all the Python versions supported by Spack
+  # Validate that the code can be run on all the Python versions
+  # supported by Spack
   validate:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+    - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
-    - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b
+    - uses: actions/setup-python@39cd14951b08e74b54015e9e001cdefcf80e669f
       with:
-        python-version: '3.13'
+        python-version: '3.11'
         cache: 'pip'
     - name: Install Python Packages
       run: |
@@ -33,17 +31,16 @@ jobs:
       run: vermin --backport importlib --backport argparse --violations --backport typing -t=3.6- -vvv lib/spack/spack/ lib/spack/llnl/ bin/
     - name: vermin (Repositories)
       run: vermin --backport importlib --backport argparse --violations --backport typing -t=3.6- -vvv var/spack/repos
-
   # Run style checks on the files that have been changed
   style:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+    - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
       with:
         fetch-depth: 0
-    - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b
+    - uses: actions/setup-python@39cd14951b08e74b54015e9e001cdefcf80e669f
       with:
-        python-version: '3.13'
+        python-version: '3.11'
         cache: 'pip'
     - name: Install Python packages
       run: |
@@ -57,25 +54,12 @@ jobs:
     - name: Run style tests
       run: |
           share/spack/qa/run-style-tests
-
   audit:
     uses: ./.github/workflows/audit.yaml
     secrets: inherit
     with:
       with_coverage: ${{ inputs.with_coverage }}
-      python_version: '3.13'
+      python_version: '3.11'
-
-  verify-checksums:
-    if: ${{ inputs.with_packages == 'true' }}
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29
-      with:
-        fetch-depth: 2
-    - name: Verify Added Checksums
-      run: |
-        bin/spack ci verify-versions HEAD^1 HEAD
-
   # Check that spack can bootstrap the development environment on Python 3.6 - RHEL8
   bootstrap-dev-rhel8:
     runs-on: ubuntu-latest
@@ -86,11 +70,11 @@ jobs:
           dnf install -y \
               bzip2 curl file gcc-c++ gcc gcc-gfortran git gnupg2 gzip \
               make patch tcl unzip which xz
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332
       - name: Setup repo and non-root user
         run: |
           git --version
-          git config --global --add safe.directory '*'
+          git config --global --add safe.directory /__w/spack/spack
           git fetch --unshallow
           . .github/workflows/bin/setup_git.sh
           useradd spack-test
@@ -101,23 +85,5 @@ jobs:
           source share/spack/setup-env.sh
           spack debug report
           spack -d bootstrap now --dev
-          spack -d style -t black
+          spack style -t black
           spack unit-test -V
-
-  # Further style checks from pylint
-  pylint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
-        with:
-          fetch-depth: 0
-      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b
-        with:
-          python-version: '3.13'
-          cache: 'pip'
-      - name: Install Python packages
-        run: |
-          pip install --upgrade pip setuptools pylint
-      - name: Pylint (Spack Core)
-        run: |
-          pylint -j 4 --disable=all --enable=unspecified-encoding --ignore-paths=lib/spack/external lib

.gitignore

@@ -201,6 +201,7 @@ tramp
 
 # Org-mode
 .org-id-locations
+*_archive
 
 # flymake-mode
 *_flymake.*

.readthedocs.yml

@@ -14,26 +14,3 @@ sphinx:
 python:
   install:
     - requirements: lib/spack/docs/requirements.txt
-
-search:
-  ranking:
-    spack.html: -10
-    spack.*.html: -10
-    llnl.html: -10
-    llnl.*.html: -10
-    _modules/*: -10
-    command_index.html: -9
-    basic_usage.html: 5
-    configuration.html: 5
-    config_yaml.html: 5
-    packages_yaml.html: 5
-    build_settings.html: 5
-    environments.html: 5
-    containers.html: 5
-    mirrors.html: 5
-    module_file_support.html: 5
-    repositories.html: 5
-    binary_caches.html: 5
-    chain.html: 5
-    pipelines.html: 5
-    packaging_guide.html: 5

CHANGELOG.md

@@ -1,64 +1,3 @@
-# v0.22.2 (2024-09-21)
-
-## Bugfixes
-- Forward compatibility with Spack 0.23 packages with language dependencies (#45205, #45191)
-- Forward compatibility with `urllib` from Python 3.12.6+ (#46453, #46483)
-- Bump vendored `archspec` for better aarch64 support (#45721, #46445)
-- Support macOS Sequoia (#45018, #45127)
-- Fix regression in `{variants.X}` and `{variants.X.value}` format strings (#46206)
-- Ensure shell escaping of environment variable values in load and activate commands (#42780)
-- Fix an issue where `spec[pkg]` considers specs outside the current DAG (#45090)
-- Do not halt concretization on unknown variants in externals (#45326)
-- Improve validation of `develop` config section (#46485)
-- Explicitly disable `ccache` if turned off in config, to avoid cache pollution (#45275)
-- Improve backwards compatibility in `include_concrete` (#45766)
-- Fix issue where package tags were sometimes repeated (#45160)
-- Make `setup-env.sh` "sourced only" by dropping execution bits (#45641)
-- Make certain source/binary fetch errors recoverable instead of a hard error (#45683)
-- Remove debug statements in package hash computation (#45235)
-- Remove redundant clingo warnings (#45269)
-- Remove hard-coded layout version (#45645)
-- Do not initialize previous store state in `use_store` (#45268)
-- Docs improvements (#46475)
-
-## Package updates
-- `chapel` major update (#42197, #44931, #45304)
-
-# v0.22.1 (2024-07-04)
-
-## Bugfixes
-- Fix reuse of externals on Linux (#44316)
-- Ensure parent gcc-runtime version >= child (#44834, #44870)
-- Ensure the latest gcc-runtime is rpath'ed when multiple exist among link deps (#44219)
-- Improve version detection of glibc (#44154)
-- Improve heuristics for solver (#44893, #44976, #45023)
-- Make strong preferences override reuse (#44373)
-- Reduce verbosity when C compiler is missing (#44182)
-- Make missing ccache executable an error when required (#44740)
-- Make every environment view containing `python` a `venv` (#44382)
-- Fix external detection for compilers with os but no target (#44156)
-- Fix version optimization for roots (#44272)
-- Handle common implementations of pagination of tags in OCI build caches (#43136)
-- Apply fetched patches to develop specs (#44950)
-- Avoid Windows wrappers for filesystem utilities on non-Windows (#44126)
-- Fix issue with long filenames in build caches on Windows (#43851)
-- Fix formatting issue in `spack audit` (#45045)
-- CI fixes (#44582, #43965, #43967, #44279, #44213)
-
-## Package updates
-- protobuf: fix 3.4:3.21 patch checksum (#44443)
-- protobuf: update hash for patch needed when="@3.4:3.21" (#44210)
-- git: bump v2.39 to 2.45; deprecate unsafe versions (#44248)
-- gcc: use -rpath {rpath_dir} not -rpath={rpath dir} (#44315)
-- Remove mesa18 and libosmesa (#44264)
-- Enforce consistency of `gl` providers (#44307)
-- Require libiconv for iconv (#44335, #45026).
-  Notice that glibc/musl also provide iconv, but are not guaranteed to be
-  complete. Set `packages:iconv:require:[glibc]` to restore the old behavior.
-- py-matplotlib: qualify when to do a post install (#44191)
-- rust: fix v1.78.0 instructions (#44127)
-- suite-sparse: improve setting of the `libs` property (#44214)
-- netlib-lapack: provide blas and lapack together (#44981)
 
 # v0.22.0 (2024-05-12)
 
@@ -380,16 +319,6 @@
     * 344 committers to packages
     * 45 committers to core
 
-# v0.21.3 (2024-10-02)
-
-## Bugfixes
-- Forward compatibility with Spack 0.23 packages with language dependencies (#45205, #45191)
-- Forward compatibility with `urllib` from Python 3.12.6+ (#46453, #46483)
-- Bump `archspec` to 0.2.5-dev for better aarch64 and Windows support (#42854, #44005,
-  #45721, #46445)
-- Support macOS Sequoia (#45018, #45127, #43862)
-- CI and test maintenance (#42909, #42728, #46711, #41943, #43363)
-
 # v0.21.2 (2024-03-01)
 
 ## Bugfixes

COPYRIGHT

@@ -8,9 +8,8 @@ or http://www.apache.org/licenses/LICENSE-2.0) or the MIT license,
 Copyrights and patents in the Spack project are retained by contributors.
 No copyright assignment is required to contribute to Spack.
 
-Spack was originally developed in 2013 by Lawrence Livermore National
+Spack was originally distributed under the LGPL-2.1 license. Consent from
-Security, LLC. It was originally distributed under the LGPL-2.1 license.
+contributors to relicense to Apache-2.0/MIT is documented at
-Consent from contributors to relicense to Apache-2.0/MIT is documented at
 https://github.com/spack/spack/issues/9137.
 
 
@@ -103,6 +102,6 @@ PackageName: sbang
 PackageHomePage: https://github.com/spack/sbang
 PackageLicenseDeclared: Apache-2.0 OR MIT
 
-PackageName: typing_extensions
+PackageName: six
-PackageHomePage: https://pypi.org/project/typing-extensions/
+PackageHomePage: https://pypi.python.org/pypi/six
-PackageLicenseDeclared: Python-2.0
+PackageLicenseDeclared: MIT

LICENSE-MIT

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) Spack Project Developers.
+Copyright (c) 2013-2024 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

@@ -46,18 +46,13 @@ See the
 [Feature Overview](https://spack.readthedocs.io/en/latest/features.html)
 for examples and highlights.
 
-To install spack and your first package, make sure you have Python & Git.
+To install spack and your first package, make sure you have Python.
 Then:
 
-    $ git clone -c feature.manyFiles=true --depth=2 https://github.com/spack/spack.git
+    $ git clone -c feature.manyFiles=true https://github.com/spack/spack.git
     $ cd spack/bin
     $ ./spack install zlib
 
-> [!TIP]
-> `-c feature.manyFiles=true` improves git's performance on repositories with 1,000+ files.
->
-> `--depth=2` prunes the git history to reduce the size of the Spack installation.
-
 Documentation
 ----------------
 
@@ -70,7 +65,7 @@ Tutorial
 ----------------
 
 We maintain a
-[**hands-on tutorial**](https://spack-tutorial.readthedocs.io/).
+[**hands-on tutorial**](https://spack.readthedocs.io/en/latest/tutorial.html).
 It covers basic to advanced usage, packaging, developer features, and large HPC
 deployments.  You can do all of the exercises on your own laptop using a
 Docker container.

bin/haspywin.py

@@ -1,4 +1,5 @@
-# Copyright Spack Project Developers. See COPYRIGHT file for details.
+# 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)
 import subprocess

bin/sbang

@@ -1,6 +1,7 @@
 #!/bin/sh
 #
-# Copyright sbang project developers. See COPYRIGHT file for details.
+# Copyright 2013-2024 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,8 @@
 #!/bin/sh
 # -*- python -*-
 #
-# Copyright Spack Project Developers. See COPYRIGHT file for details.
+# 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)
 
@@ -25,6 +26,7 @@ exit 1
 # The code above runs this file with our preferred python interpreter.
 
 import os
+import os.path
 import sys
 
 min_python3 = (3, 6)

bin/spack-python

@@ -1,6 +1,7 @@
 #!/bin/sh
 #
-# Copyright Spack Project Developers. See COPYRIGHT file for details.
+# 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)
 

bin/spack.bat

@@ -1,4 +1,5 @@
-:: Copyright Spack Project Developers. See COPYRIGHT file for details.
+:: 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)
 ::#######################################################################

bin/spack.ps1

@@ -1,4 +1,5 @@
-#  Copyright Spack Project Developers. See COPYRIGHT file for details.
+#  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)
 # #######################################################################

bin/spack_cmd.bat

@@ -1,11 +1,71 @@
 @ECHO OFF
+setlocal EnableDelayedExpansion
 :: (c) 2021 Lawrence Livermore National Laboratory
 :: To use this file independently of Spack's installer, execute this script in its directory, or add the
 :: associated bin directory to your PATH. Invoke to launch Spack Shell.
 ::
 :: source_dir/spack/bin/spack_cmd.bat
 ::
+pushd %~dp0..
+set SPACK_ROOT=%CD%
+pushd %CD%\..
+set spackinstdir=%CD%
+popd
 
-call "%~dp0..\share\spack\setup-env.bat"
+
-pushd %SPACK_ROOT%
+:: Check if Python is on the PATH
-%comspec% /K
+if not defined python_pf_ver (
+(for /f "delims=" %%F in ('where python.exe') do (
+                                                    set "python_pf_ver=%%F"
+                                                    goto :found_python
+                                                  ) ) 2> NUL
+)
+:found_python
+if not defined python_pf_ver (
+    :: If not, look for Python from the Spack installer
+    :get_builtin
+    (for /f "tokens=*" %%g in ('dir /b /a:d "!spackinstdir!\Python*"') do (
+        set "python_ver=%%g")) 2> NUL
+
+    if not defined python_ver (
+        echo Python was not found on your system.
+        echo Please install Python or add Python to your PATH.
+    ) else (
+        set "py_path=!spackinstdir!\!python_ver!"
+        set "py_exe=!py_path!\python.exe"
+    )
+    goto :exitpoint
+) else (
+    :: Python is already on the path
+    set "py_exe=!python_pf_ver!"
+    (for /F "tokens=* USEBACKQ" %%F in (
+        `"!py_exe!" --version`) do (set "output=%%F")) 2>NUL
+    if not "!output:Microsoft Store=!"=="!output!" goto :get_builtin
+    goto :exitpoint
+)
+:exitpoint
+
+set "PATH=%SPACK_ROOT%\bin\;%PATH%"
+if defined py_path (
+    set "PATH=%py_path%;%PATH%"
+)
+
+if defined py_exe (
+    "%py_exe%" "%SPACK_ROOT%\bin\haspywin.py"
+)
+
+set "EDITOR=notepad"
+
+DOSKEY spacktivate=spack env activate $*
+
+@echo **********************************************************************
+@echo ** Spack Package Manager
+@echo **********************************************************************
+
+IF "%1"=="" GOTO CONTINUE
+set
+GOTO:EOF
+
+:continue
+set PROMPT=[spack] %PROMPT%
+%comspec% /k

bin/spack_pwsh.ps1

@@ -1,4 +1,5 @@
-# Copyright Spack Project Developers. See COPYRIGHT file for details.
+# 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)
 

etc/spack/defaults/bootstrap.yaml

@@ -9,15 +9,15 @@ bootstrap:
   # may not be able to bootstrap all the software that Spack needs,
   # depending on its type.
   sources:
-  - name: github-actions-v0.6
+  - name: 'github-actions-v0.5'
-    metadata: $spack/share/spack/bootstrap/github-actions-v0.6
-  - name: github-actions-v0.5
     metadata: $spack/share/spack/bootstrap/github-actions-v0.5
-  - name: spack-install
+  - name: 'github-actions-v0.4'
+    metadata: $spack/share/spack/bootstrap/github-actions-v0.4
+  - name: 'spack-install'
     metadata: $spack/share/spack/bootstrap/spack-install
   trusted:
     # By default we trust bootstrapping from sources and from binaries
     # produced on Github via the workflow
-    github-actions-v0.6: true
     github-actions-v0.5: true
+    github-actions-v0.4: true
     spack-install: true

etc/spack/defaults/concretizer.yaml

@@ -39,53 +39,11 @@ concretizer:
   # Option to deal with possible duplicate nodes (i.e. different nodes from the same package) in the DAG.
   duplicates:
     # "none": allows a single node for any package in the DAG.
-    # "minimal": allows the duplication of 'build-tools' nodes only
+    # "minimal": allows the duplication of 'build-tools' nodes only (e.g. py-setuptools, cmake etc.)
-    # (e.g. py-setuptools, cmake etc.)
     # "full" (experimental): allows separation of the entire build-tool stack (e.g. the entire "cmake" subDAG)
     strategy: minimal
-    # Maximum number of duplicates in a DAG, when using a strategy that allows duplicates. "default" is the
+  # Option to specify compatiblity between operating systems for reuse of compilers and packages
-    # number used if there isn't a more specific alternative
-    max_dupes:
-      default: 1
-      # Virtuals
-      c: 2
-      cxx: 2
-      fortran: 1
-      # Regular packages
-      cmake: 2
-      gmake: 2
-      python: 2
-      python-venv: 2
-      py-cython: 2
-      py-flit-core: 2
-      py-pip: 2
-      py-setuptools: 2
-      py-wheel: 2
-      xcb-proto: 2
-      # Compilers
-      gcc: 2
-      llvm: 2
-  # Option to specify compatibility 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: {}
-
-  # Option to specify whether to support splicing. Splicing allows for
-  # the relinking of concrete package dependencies in order to better
-  # reuse already built packages with ABI compatible dependencies
-  splice:
-    explicit: []
-    automatic: false
-  # Maximum time, in seconds, allowed for the 'solve' phase. If set to 0, there is no time limit.
-  timeout: 0
-  # If set to true, exceeding the timeout will always result in a concretization error. If false,
-  # the best (suboptimal) model computed before the timeout is used.
-  #
-  # Setting this to false yields unreproducible results, so we advise to use that value only
-  # for debugging purposes (e.g. check which constraints can help Spack concretize faster).
-  error_on_timeout: true
-
-  # Static analysis may reduce the concretization time by generating smaller ASP problems, in
-  # cases where there are requirements that prevent part of the search space to be explored.
-  static_analysis: false

etc/spack/defaults/config.yaml

@@ -19,7 +19,7 @@ config:
   install_tree:
     root: $spack/opt/spack
     projections:
-      all: "{architecture.platform}-{architecture.target}/{name}-{version}-{hash}"
+      all: "{architecture}/{compiler.name}-{compiler.version}/{name}-{version}-{hash}"
     # install_tree can include an optional padded length (int or boolean)
     # default is False (do not pad)
     # if padded_length is True, Spack will pad as close to the system max path
@@ -115,6 +115,12 @@ config:
   suppress_gpg_warnings: false
 
 
+  # If set to true, Spack will attempt to build any compiler on the spec
+  # that is not already available. If set to False, Spack will only use
+  # compilers already configured in compilers.yaml
+  install_missing_compilers: false
+
+
   # If set to true, Spack will always check checksums after downloading
   # archives. If false, Spack skips the checksum step.
   checksum: true
@@ -164,6 +170,23 @@ config:
   # If set to true, Spack will use ccache to cache C compiles.
   ccache: false
 
+
+  # The concretization algorithm to use in Spack. Options are:
+  #
+  #   'clingo': Uses a logic solver under the hood to solve DAGs with full
+  #       backtracking and optimization for user preferences. Spack will
+  #       try to bootstrap the logic solver, if not already available.
+  #
+  #   'original': Spack's original greedy, fixed-point concretizer. This
+  #       algorithm can make decisions too early and will not backtrack
+  #       sufficiently for many specs. This will soon be deprecated in
+  #       favor of clingo.
+  #
+  # See `concretizer.yaml` for more settings you can fine-tune when
+  # using clingo.
+  concretizer: clingo
+
+
   # How long to wait to lock the Spack installation database. This lock is used
   # when Spack needs to manage its own package metadata and all operations are
   # expected to complete within the default time limit. The timeout should
@@ -194,12 +217,6 @@ config:
     # executables with many dependencies, in particular on slow filesystems.
     bind: false
 
-    # Controls the handling of missing dynamic libraries after installation.
-    # Options are ignore (default), warn, or error. If set to error, the
-    # installation fails if installed binaries reference dynamic libraries that
-    # are not found in their specified rpaths.
-    missing_library_policy: ignore
-
 
   # Set to 'false' to allow installation on filesystems that doesn't allow setgid bit
   # manipulation by unprivileged user (e.g. AFS)

etc/spack/defaults/darwin/packages.yaml

@@ -15,11 +15,12 @@
 # -------------------------------------------------------------------------
 packages:
   all:
+    compiler:
+    - apple-clang
+    - clang
+    - gcc
     providers:
-      c: [apple-clang, llvm, gcc]
-      cxx: [apple-clang, llvm, gcc]
       elf: [libelf]
-      fortran: [gcc]
       fuse: [macfuse]
       gl: [apple-gl]
       glu: [apple-glu]
@@ -49,12 +50,3 @@ packages:
     # although the version number used here isn't critical
     - spec: apple-libuuid@1353.100.2
       prefix: /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk
-  c:
-    prefer:
-    - apple-clang
-  cxx:
-    prefer:
-    - apple-clang
-  fortran:
-    prefer:
-    - gcc

etc/spack/defaults/packages.yaml

@@ -15,18 +15,17 @@
 # -------------------------------------------------------------------------
 packages:
   all:
+    compiler: [gcc, clang, oneapi, xl, nag, fj, aocc]
     providers:
       awk: [gawk]
       armci: [armcimpi]
       blas: [openblas, amdblis]
-      c: [gcc, llvm, intel-oneapi-compilers]
+      cxx: [gcc]
-      cxx: [gcc, llvm, intel-oneapi-compilers]
       D: [ldc]
       daal: [intel-oneapi-daal]
       elf: [elfutils]
       fftw-api: [fftw, amdfftw]
       flame: [libflame, amdlibflame]
-      fortran: [gcc, llvm, intel-oneapi-compilers]
       fortran-rt: [gcc-runtime, intel-oneapi-runtime]
       fuse: [libfuse]
       gl: [glx, osmesa]
@@ -35,13 +34,13 @@ packages:
       go-or-gccgo-bootstrap: [go-bootstrap, gcc]
       iconv: [libiconv]
       ipp: [intel-oneapi-ipp]
-      java: [openjdk, jdk]
+      java: [openjdk, jdk, ibm-java]
       jpeg: [libjpeg-turbo, libjpeg]
       lapack: [openblas, amdlibflame]
       libc: [glibc, musl]
-      libgfortran: [gcc-runtime]
+      libgfortran: [ gcc-runtime ]
       libglx: [mesa+glx]
-      libifcore: [intel-oneapi-runtime]
+      libifcore: [ intel-oneapi-runtime ]
       libllvm: [llvm]
       lua-lang: [lua, lua-luajit-openresty, lua-luajit]
       luajit: [lua-luajit-openresty, lua-luajit]
@@ -64,7 +63,6 @@ packages:
       unwind: [libunwind]
       uuid: [util-linux-uuid, libuuid]
       wasi-sdk: [wasi-sdk-prebuilt]
-      xkbdata-api: [xkeyboard-config, xkbdata]
       xxd: [xxd-standalone, vim]
       yacc: [bison, byacc]
       ziglang: [zig]
@@ -72,27 +70,3 @@ packages:
     permissions:
       read: world
       write: user
-  cray-fftw:
-    buildable: false
-  cray-libsci:
-    buildable: false
-  cray-mpich:
-    buildable: false
-  cray-mvapich2:
-    buildable: false
-  cray-pmi:
-    buildable: false
-  egl:
-    buildable: false
-  essl:
-    buildable: false
-  fujitsu-mpi:
-    buildable: false
-  fujitsu-ssl2:
-    buildable: false
-  hpcx-mpi:
-    buildable: false
-  mpt:
-    buildable: false
-  spectrum-mpi:
-    buildable: false

etc/spack/defaults/windows/config.yaml

@@ -1,5 +1,6 @@
 config:
   locks: false
+  concretizer: clingo
   build_stage::
-    - '$user_cache_path/stage'
+    - '$spack/.staging'
   stage_name: '{name}-{version}-{hash:7}'

etc/spack/defaults/windows/packages.yaml

@@ -15,11 +15,8 @@
 # -------------------------------------------------------------------------
 packages:
   all:
+    compiler:
+    - msvc
     providers:
-      c : [msvc]
-      cxx: [msvc]
       mpi: [msmpi]
       gl: [wgl]
-  mpi:
-    require:
-    - one_of: [msmpi]

lib/spack/docs/_pygments/style.py

@@ -1,4 +1,5 @@
-# Copyright Spack Project Developers. See COPYRIGHT file for details.
+# 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)
 

lib/spack/docs/basic_usage.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 
@@ -1174,17 +1175,6 @@ unspecified version, but packages can depend on other packages with
 could depend on ``mpich@1.2:`` if it can only build with version
 ``1.2`` or higher of ``mpich``.
 
-.. note:: Windows Spec Syntax Caveats
-   Windows has a few idiosyncrasies when it comes to the Spack spec syntax and the use of certain shells
-   Spack's spec dependency syntax uses the carat (``^``) character, however this is an escape string in CMD
-   so it must be escaped with an additional carat (i.e. ``^^``).
-   CMD also will attempt to interpret strings with ``=`` characters in them. Any spec including this symbol
-   must double quote the string.
-
-   Note: All of these issues are unique to CMD, they can be avoided by using Powershell.
-
-   For more context on these caveats see the related issues: `carat <https://github.com/spack/spack/issues/42833>`_ and `equals <https://github.com/spack/spack/issues/43348>`_
-
 Below are more details about the specifiers that you can add to specs.
 
 .. _version-specifier:
@@ -1291,61 +1281,55 @@ based on site policies.
 Variants
 ^^^^^^^^
 
-Variants are named options associated with a particular package and are
+Variants are named options associated with a particular package. They are
-typically used to enable or disable certain features at build time. They
+optional, as each package must provide default values for each variant it
-are optional, as each package must provide default values for each variant
+makes available. Variants can be specified using
-it makes available.
+a flexible parameter syntax ``name=<value>``. For example,
-
+``spack install mercury debug=True`` will install mercury built with debug
-The names of variants available for a particular package depend on
+flags. The names of particular variants available for a package depend on
 what was provided by the package author. ``spack info <package>`` will
 provide information on what build variants are available.
 
-There are different types of variants:
+For compatibility with earlier versions, variants which happen to be
+boolean in nature can be specified by a syntax that represents turning
+options on and off. For example, in the previous spec we could have
+supplied ``mercury +debug`` with the same effect of enabling the debug
+compile time option for the libelf package.
 
-1. Boolean variants. Typically used to enable or disable a feature at
+Depending on the package a variant may have any default value.  For
-   compile time. For example, a package might have a ``debug`` variant that
+``mercury`` here, ``debug`` is ``False`` by default, and we turned it on
-   can be explicitly enabled with ``+debug`` and disabled with ``~debug``.
+with ``debug=True`` or ``+debug``.  If a variant is ``True`` by default
-2. Single-valued variants. Often used to set defaults. For example, a package
+you can turn it off by either adding ``-name`` or ``~name`` to the spec.
-   might have a ``compression`` variant that determines the default
-   compression algorithm, which users could set to ``compression=gzip`` or
-   ``compression=zstd``.
-3. Multi-valued variants. A package might have a ``fabrics`` variant that
-   determines which network fabrics to support. Users could set this to
-   ``fabrics=verbs,ofi`` to enable both InfiniBand verbs and OpenFabrics
-   interfaces. The values are separated by commas.
 
-   The meaning of ``fabrics=verbs,ofi`` is to enable *at least* the specified
+There are two syntaxes here because, depending on context, ``~`` and
-   fabrics, but other fabrics may be enabled as well. If the intent is to
+``-`` may mean different things.  In most shells, the following will
-   enable *only* the specified fabrics, then the ``fabrics:=verbs,ofi``
+result in the shell performing home directory substitution:
-   syntax should be used with the ``:=`` operator.
 
-.. note::
+.. code-block:: sh
-
-   In certain shells, the the ``~`` character is expanded to the home
-   directory. To avoid these issues, avoid whitespace between the package
-   name and the variant:
-
-   .. code-block:: sh
 
    mpileaks ~debug   # shell may try to substitute this!
    mpileaks~debug    # use this instead
 
-   Alternatively, you can use the ``-`` character to disable a variant,
+If there is a user called ``debug``, the ``~`` will be incorrectly
-   but be aware that this requires a space between the package name and
+expanded.  In this situation, you would want to write ``libelf
-   the variant:
+-debug``.  However, ``-`` can be ambiguous when included after a
+package name without spaces:
 
-   .. code-block:: sh
+.. code-block:: sh
 
-      mpileaks-debug     # wrong: refers to a package named "mpileaks-debug"
+   mpileaks-debug     # wrong!
-      mpileaks -debug    # right: refers to a package named mpileaks with debug disabled
+   mpileaks -debug    # right
 
-   As a last resort, ``debug=False`` can also be used to disable a boolean variant.
+Spack allows the ``-`` character to be part of package names, so the
+above will be interpreted as a request for the ``mpileaks-debug``
+package, not a request for ``mpileaks`` built without ``debug``
+options.  In this scenario, you should write ``mpileaks~debug`` to
+avoid ambiguity.
 
-
+When spack normalizes specs, it prints them out with no spaces boolean
-
+variants using the backwards compatibility syntax and uses only ``~``
-"""""""""""""""""""""""""""""""""""
+for disabled boolean variants.  The ``-`` and spaces on the command
-Variant propagation to dependencies
+line are provided for convenience and legibility.
-"""""""""""""""""""""""""""""""""""
 
 Spack allows variants to propagate their value to the package's
 dependency by using ``++``, ``--``, and ``~~`` for boolean variants.
@@ -1364,10 +1348,6 @@ For example, for the ``stackstart`` variant:
     mpileaks stackstart==4   # variant will be propagated to dependencies
     mpileaks stackstart=4    # only mpileaks will have this variant value
 
-Spack also allows variants to be propagated from a package that does
-not have that variant.
-
-
 ^^^^^^^^^^^^^^
 Compiler Flags
 ^^^^^^^^^^^^^^
@@ -1415,16 +1395,14 @@ that executables will run without the need to set ``LD_LIBRARY_PATH``.
 
 .. code-block:: yaml
 
-  packages:
-    gcc:
-      externals:
-      - spec: gcc@4.9.3
-        prefix: /opt/gcc
-        extra_attributes:
   compilers:
-            c: /opt/gcc/bin/gcc
+    - compiler:
-            cxx: /opt/gcc/bin/g++
+        spec: gcc@4.9.3
-            fortran: /opt/gcc/bin/gfortran
+        paths:
+          cc: /opt/gcc/bin/gcc
+          c++: /opt/gcc/bin/g++
+          f77: /opt/gcc/bin/gfortran
+          fc: /opt/gcc/bin/gfortran
         environment:
           unset:
             - BAD_VARIABLE
@@ -1769,24 +1747,19 @@ Verifying installations
 The ``spack verify`` command can be used to verify the validity of
 Spack-installed packages any time after installation.
 
-
-^^^^^^^^^^^^^^^^^^^^^^^^^
-``spack verify manifest``
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
 At installation time, Spack creates a manifest of every file in the
 installation prefix. For links, Spack tracks the mode, ownership, and
 destination. For directories, Spack tracks the mode, and
 ownership. For files, Spack tracks the mode, ownership, modification
-time, hash, and size. The ``spack verify manifest`` command will check,
+time, hash, and size. The Spack verify command will check, for every
-for every file in each package, whether any of those attributes have
+file in each package, whether any of those attributes have changed. It
-changed. It will also check for newly added files or deleted files from
+will also check for newly added files or deleted files from the
-the installation prefix. Spack can either check all installed packages
+installation prefix. Spack can either check all installed packages
 using the `-a,--all` or accept specs listed on the command line to
 verify.
 
-The ``spack verify manifest`` command can also verify for individual files
+The ``spack verify`` command can also verify for individual files that
-that they haven't been altered since installation time. If the given file
+they haven't been altered since installation time. If the given file
 is not in a Spack installation prefix, Spack will report that it is
 not owned by any package. To check individual files instead of specs,
 use the ``-f,--files`` option.
@@ -1801,22 +1774,6 @@ check only local packages (as opposed to those used transparently from
 ``upstream`` spack instances) and the ``-j,--json`` option to output
 machine-readable json data for any errors.
 
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-``spack verify libraries``
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The ``spack verify libraries`` command can be used to verify that packages
-do not have accidental system dependencies. This command scans the install
-prefixes of packages for executables and shared libraries, and resolves
-their needed libraries in their RPATHs. When needed libraries cannot be
-located, an error is reported. This typically indicates that a package
-was linked against a system library, instead of a library provided by
-a Spack package.
-
-This verification can also be enabled as a post-install hook by setting
-``config:shared_linking:missing_library_policy`` to ``error`` or ``warn``
-in :ref:`config.yaml <config-yaml>`.
-
 -----------------------
 Filesystem requirements
 -----------------------

lib/spack/docs/binary_caches.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 
@@ -264,30 +265,25 @@ infrastructure, or to cache Spack built binaries in Github Actions and
 GitLab CI.
 
 To get started, configure an OCI mirror using ``oci://`` as the scheme,
-and optionally specify variables that hold the username and password (or
+and optionally specify a username and password (or personal access token):
-personal access token) for the registry:
 
 .. code-block:: console
 
-    $ spack mirror add --oci-username-variable REGISTRY_USER \
+    $ spack mirror add --oci-username username --oci-password password my_registry oci://example.com/my_image
-                       --oci-password-variable REGISTRY_TOKEN \
-                       my_registry oci://example.com/my_image
 
 Spack follows the naming conventions of Docker, with Dockerhub as the default
 registry. To use Dockerhub, you can omit the registry domain:
 
 .. code-block:: console
 
-    $ spack mirror add ... my_registry oci://username/my_image
+    $ spack mirror add --oci-username username --oci-password password my_registry oci://username/my_image
 
 From here, you can use the mirror as any other build cache:
 
 .. code-block:: console
 
-    $ export REGISTRY_USER=...
-    $ export REGISTRY_TOKEN=...
     $ spack buildcache push my_registry <specs...>  # push to the registry
-    $ spack install <specs...>  # or install from the registry
+    $ spack install <specs...> # install from the registry
 
 A unique feature of buildcaches on top of OCI registries is that it's incredibly
 easy to generate get a runnable container image with the binaries installed. This

lib/spack/docs/bootstrapping.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 
@@ -170,7 +171,7 @@ bootstrapping.
    To register the mirror on the platform where it's supposed to be used run the following command(s):
      % spack bootstrap add --trust local-sources /opt/bootstrap/metadata/sources
      % spack bootstrap add --trust local-binaries /opt/bootstrap/metadata/binaries
-     % spack buildcache update-index /opt/bootstrap/bootstrap_cache
+
 
 This command needs to be run on a machine with internet access and the resulting folder
 has to be moved over to the air-gapped system. Once the local sources are added using the

lib/spack/docs/build_settings.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 
@@ -165,106 +166,3 @@ 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``.
-
---------
-Splicing
---------
-
-The ``splice`` key covers config attributes for splicing specs in the solver.
-
-"Splicing" is a method for replacing a dependency with another spec
-that provides the same package or virtual. There are two types of
-splices, referring to different behaviors for shared dependencies
-between the root spec and the new spec replacing a dependency:
-"transitive" and "intransitive". A "transitive" splice is one that
-resolves all conflicts by taking the dependency from the new node. An
-"intransitive" splice is one that resolves all conflicts by taking the
-dependency from the original root. From a theory perspective, hybrid
-splices are possible but are not modeled by Spack.
-
-All spliced specs retain a ``build_spec`` attribute that points to the
-original Spec before any splice occurred. The ``build_spec`` for a
-non-spliced spec is itself.
-
-The figure below shows examples of transitive and intransitive splices:
-
-.. figure:: images/splices.png
-   :align: center
-
-The concretizer can be configured to explicitly splice particular
-replacements for a target spec. Splicing will allow the user to make
-use of generically built public binary caches, while swapping in
-highly optimized local builds for performance critical components
-and/or components that interact closely with the specific hardware
-details of the system. The most prominent candidate for splicing is
-MPI providers. MPI packages have relatively well-understood ABI
-characteristics, and most High Performance Computing facilities deploy
-highly optimized MPI packages tailored to their particular
-hardware. The following config block configures Spack to replace
-whatever MPI provider each spec was concretized to use with the
-particular package of ``mpich`` with the hash that begins ``abcdef``.
-
-.. code-block:: yaml
-
-   concretizer:
-     splice:
-       explicit:
-       - target: mpi
-         replacement: mpich/abcdef
-         transitive: false
-
-.. warning::
-
-   When configuring an explicit splice, you as the user take on the
-   responsibility for ensuring ABI compatibility between the specs
-   matched by the target and the replacement you provide. If they are
-   not compatible, Spack will not warn you and your application will
-   fail to run.
-
-The ``target`` field of an explicit splice can be any abstract
-spec. The ``replacement`` field must be a spec that includes the hash
-of a concrete spec, and the replacement must either be the same
-package as the target, provide the virtual that is the target, or
-provide a virtual that the target provides. The ``transitive`` field
-is optional -- by default, splices will be transitive.
-
-.. note::
-
-   With explicit splices configured, it is possible for Spack to
-   concretize to a spec that does not satisfy the input. For example,
-   with the config above ``hdf5 ^mvapich2`` will concretize to user
-   ``mpich/abcdef`` instead of ``mvapich2`` as the MPI provider. Spack
-   will warn the user in this case, but will not fail the
-   concretization.
-
-.. _automatic_splicing:
-
-^^^^^^^^^^^^^^^^^^
-Automatic Splicing
-^^^^^^^^^^^^^^^^^^
-
-The Spack solver can be configured to do automatic splicing for
-ABI-compatible packages. Automatic splices are enabled in the concretizer
-config section
-
-.. code-block:: yaml
-
-   concretizer:
-     splice:
-       automatic: True
-
-Packages can include ABI-compatibility information using the
-``can_splice`` directive. See :ref:`the packaging
-guide<abi_compatibility>` for instructions on specifying ABI
-compatibility using the ``can_splice`` directive.
-
-.. note::
-
-   The ``can_splice`` directive is experimental and may be changed in
-   future versions.
-
-When automatic splicing is enabled, the concretizer will combine any
-number of ABI-compatible specs if possible to reuse installed packages
-and packages available from binary caches. The end result of these
-specs is equivalent to a series of transitive/intransitive splices,
-but the series may be non-obvious.

lib/spack/docs/build_systems.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 
@@ -63,6 +64,7 @@ on these ideas for each distinct build system that Spack supports:
    build_systems/cudapackage
    build_systems/custompackage
    build_systems/inteloneapipackage
+   build_systems/intelpackage
    build_systems/rocmpackage
    build_systems/sourceforgepackage
 

lib/spack/docs/build_systems/autotoolspackage.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 
@@ -272,9 +273,9 @@ often lists dependencies and the flags needed to locate them. The
 "environment variables" section lists environment variables that the
 build system uses to pass flags to the compiler and linker.
 
-^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^
-Adding flags to configure
+Addings flags to configure
-^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 For most of the flags you encounter, you will want a variant to
 optionally enable/disable them. You can then optionally pass these
@@ -285,7 +286,7 @@ function like so:
 
    def configure_args(self):
        args = []
-       ...
+
        if self.spec.satisfies("+mpi"):
            args.append("--enable-mpi")
        else:
@@ -299,10 +300,7 @@ Alternatively, you can use the :ref:`enable_or_disable  <autotools_enable_or_dis
 .. code-block:: python
 
    def configure_args(self):
-       args = []
+       return [self.enable_or_disable("mpi")]
-       ...
-       args.extend(self.enable_or_disable("mpi"))
-       return args
 
 
 Note that we are explicitly disabling MPI support if it is not
@@ -347,14 +345,7 @@ typically used to enable or disable some feature within the package.
        default=False,
        description="Memchecker support for debugging [degrades performance]"
    )
-   ...
+   config_args.extend(self.enable_or_disable("memchecker"))
-
-   def configure_args(self):
-       args = []
-       ...
-       args.extend(self.enable_or_disable("memchecker"))
-
-       return args
 
 In this example, specifying the variant ``+memchecker`` will generate
 the following configuration options:

lib/spack/docs/build_systems/bundlepackage.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 

lib/spack/docs/build_systems/cachedcmakepackage.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 

lib/spack/docs/build_systems/cmakepackage.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 

lib/spack/docs/build_systems/cudapackage.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 

lib/spack/docs/build_systems/custompackage.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 
@@ -56,13 +57,13 @@ If you look at the ``perl`` package, you'll see:
 
 .. code-block:: python
 
-   phases = ("configure", "build", "install")
+   phases = ["configure", "build", "install"]
 
 Similarly, ``cmake`` defines:
 
 .. code-block:: python
 
-   phases = ("bootstrap", "build", "install")
+   phases = ["bootstrap", "build", "install"]
 
 If we look at the ``cmake`` example, this tells Spack's ``PackageBase``
 class to run the ``bootstrap``, ``build``, and ``install`` functions
@@ -130,18 +131,13 @@ before or after a particular phase. For example, in ``perl``, we see:
    @run_after("install")
    def install_cpanm(self):
        spec = self.spec
-        maker = make
+
-        cpan_dir = join_path("cpanm", "cpanm")
+       if spec.satisfies("+cpanm"):
-        if sys.platform == "win32":
+           with working_dir(join_path("cpanm", "cpanm")):
-            maker = nmake
-            cpan_dir = join_path(self.stage.source_path, cpan_dir)
-            cpan_dir = windows_sfn(cpan_dir)
-        if "+cpanm" in spec:
-            with working_dir(cpan_dir):
                perl = spec["perl"].command
                perl("Makefile.PL")
-                maker()
+               make()
-                maker("install")
+               make("install")
 
 This extra step automatically installs ``cpanm`` in addition to the
 base Perl installation.
@@ -180,13 +176,7 @@ In the ``perl`` package, we can see:
 
    @run_after("build")
    @on_package_attributes(run_tests=True)
-   def build_test(self):
+   def test(self):
-        if sys.platform == "win32":
-            win32_dir = os.path.join(self.stage.source_path, "win32")
-            win32_dir = windows_sfn(win32_dir)
-            with working_dir(win32_dir):
-                nmake("test", ignore_quotes=True)
-        else:
        make("test")
 
 As you can guess, this runs ``make test`` *after* building the package,

lib/spack/docs/build_systems/inteloneapipackage.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 
@@ -33,6 +34,9 @@ For more information on a specific package, do::
 
   spack info --all <package-name>
 
+Intel no longer releases new versions of Parallel Studio, which can be
+used in Spack via the :ref:`intelpackage`. All of its components can
+now be found in oneAPI.
 
 Examples
 ========
@@ -47,8 +51,34 @@ Install the oneAPI compilers::
 
   spack install intel-oneapi-compilers
 
+Add the compilers to your ``compilers.yaml`` so spack can use them::
 
-To build the ``patchelf`` Spack package with ``icx``, do::
+  spack compiler add `spack location -i intel-oneapi-compilers`/compiler/latest/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
+  ``icc`` and ``icpc``.
+* ``oneapi``: ``icx``, ``icpx``, ``ifx``. Intel's new generation of
+  compilers based on LLVM.
+
+To build the ``patchelf`` Spack package with ``icc``, do::
+
+  spack install patchelf%intel
+
+To build with with ``icx``, do ::
 
   spack install patchelf%oneapi
 
@@ -63,6 +93,15 @@ Install the oneAPI compilers::
 
   spack install intel-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/bin
+
+Verify that the compilers are available::
+
+  spack compiler list
+
 Clone `spack-configs <https://github.com/spack/spack-configs>`_ repo and activate Intel oneAPI CPU environment::
 
   git clone https://github.com/spack/spack-configs
@@ -111,7 +150,7 @@ Compilers
 ---------
 
 To use the compilers, add some information about the installation to
-``packages.yaml``. For most users, it is sufficient to do::
+``compilers.yaml``. For most users, it is sufficient to do::
 
   spack compiler add /opt/intel/oneapi/compiler/latest/bin
 
@@ -119,7 +158,7 @@ Adapt the paths above if you did not install the tools in the default
 location. After adding the compilers, using them is the same
 as if you had installed the ``intel-oneapi-compilers`` package.
 Another option is to manually add the configuration to
-``packages.yaml`` as described in :ref:`Compiler configuration
+``compilers.yaml`` as described in :ref:`Compiler configuration
 <compiler-config>`.
 
 Before 2024, the directory structure was different::
@@ -162,5 +201,15 @@ You can also use Spack-installed libraries. For example::
 Will update your environment CPATH, LIBRARY_PATH, and other
 environment variables for building an application with oneMKL.
 
+More information
+================
+
+This section describes basic use of oneAPI, especially if it has
+changed compared to Parallel Studio. See :ref:`intelpackage` for more
+information on :ref:`intel-virtual-packages`,
+:ref:`intel-unrelated-packages`,
+:ref:`intel-integrating-external-libraries`, and
+:ref:`using-mkl-tips`.
+
 
 .. _`Intel installers`: https://software.intel.com/content/www/us/en/develop/documentation/installation-guide-for-intel-oneapi-toolkits-linux/top.html

lib/spack/docs/build_systems/luapackage.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 

lib/spack/docs/build_systems/makefilepackage.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 

lib/spack/docs/build_systems/mavenpackage.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 

lib/spack/docs/build_systems/mesonpackage.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 

lib/spack/docs/build_systems/octavepackage.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 

lib/spack/docs/build_systems/perlpackage.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 

lib/spack/docs/build_systems/pythonpackage.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 

lib/spack/docs/build_systems/qmakepackage.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 
@@ -24,14 +25,6 @@ QMake does not appear to have a standardized way of specifying
 the installation directory, so you may have to set environment
 variables or edit ``*.pro`` files to get things working properly.
 
-QMake packages will depend on the virtual ``qmake`` package which
-is provided by multiple versions of Qt: ``qt`` provides Qt up to
-Qt5, and ``qt-base`` provides Qt from version Qt6 onwards. This
-split was motivated by the desire to split the single Qt package
-into its components to allow for more fine-grained installation.
-To depend on a specific version, refer to the documentation on
-:ref:`virtual-dependencies`.
-
 ^^^^^^
 Phases
 ^^^^^^

lib/spack/docs/build_systems/racketpackage.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 

lib/spack/docs/build_systems/rocmpackage.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 
@@ -12,7 +13,8 @@ The ``ROCmPackage`` is not a build system but a helper package. Like ``CudaPacka
 it provides standard variants, dependencies, and conflicts to facilitate building
 packages using GPUs though for AMD in this case.
 
-You can find the source for this package (and suggestions for setting up your ``packages.yaml`` file) at
+You can find the source for this package (and suggestions for setting up your
+``compilers.yaml`` and ``packages.yaml`` files) at
 `<https://github.com/spack/spack/blob/develop/lib/spack/spack/build_systems/rocm.py>`__.
 
 ^^^^^^^^

lib/spack/docs/build_systems/rpackage.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 

lib/spack/docs/build_systems/rubypackage.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 

lib/spack/docs/build_systems/sconspackage.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 
@@ -48,14 +49,14 @@ following phases:
 #. ``install`` - install the package
 
 Package developers often add unit tests that can be invoked with
-``scons test`` or ``scons check``. Spack provides a ``build_test`` method
+``scons test`` or ``scons check``. Spack provides a ``test`` method
 to handle this. Since we don't know which one the package developer
-chose, the ``build_test`` method does nothing by default, but can be easily
+chose, the ``test`` method does nothing by default, but can be easily
 overridden like so:
 
 .. code-block:: python
 
-   def build_test(self):
+   def test(self):
        scons("check")
 
 

lib/spack/docs/build_systems/sippackage.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 

lib/spack/docs/build_systems/sourceforgepackage.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 

lib/spack/docs/build_systems/wafpackage.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 

lib/spack/docs/chain.rst

@@ -1,12 +1,13 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 
 .. chain:
 
-=============================================
+============================
-Chaining Spack Installations (upstreams.yaml)
+Chaining Spack Installations
-=============================================
+============================
 
 You can point your Spack installation to another installation to use any
 packages that are installed there. To register the other Spack instance,

lib/spack/docs/conf.py

@@ -1,4 +1,5 @@
-# Copyright Spack Project Developers. See COPYRIGHT file for details.
+# 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)
 
@@ -205,28 +206,17 @@ def setup(sphinx):
     ("py:class", "six.moves.urllib.parse.ParseResult"),
     ("py:class", "TextIO"),
     ("py:class", "hashlib._Hash"),
-    ("py:class", "concurrent.futures._base.Executor"),
     # Spack classes that are private and we don't want to expose
     ("py:class", "spack.provider_index._IndexBase"),
     ("py:class", "spack.repo._PrependFileLoader"),
-    ("py:class", "spack.build_systems._checks.BuilderWithDefaults"),
+    ("py:class", "spack.build_systems._checks.BaseBuilder"),
     # Spack classes that intersphinx is unable to resolve
     ("py:class", "spack.version.StandardVersion"),
     ("py:class", "spack.spec.DependencySpec"),
-    ("py:class", "spack.spec.ArchSpec"),
     ("py:class", "spack.spec.InstallStatus"),
     ("py:class", "spack.spec.SpecfileReaderBase"),
     ("py:class", "spack.install_test.Pb"),
     ("py:class", "spack.filesystem_view.SimpleFilesystemView"),
-    ("py:class", "spack.traverse.EdgeAndDepth"),
-    ("py:class", "archspec.cpu.microarchitecture.Microarchitecture"),
-    ("py:class", "spack.compiler.CompilerCache"),
-    # TypeVar that is not handled correctly
-    ("py:class", "llnl.util.lang.T"),
-    ("py:class", "llnl.util.lang.KT"),
-    ("py:class", "llnl.util.lang.VT"),
-    ("py:obj", "llnl.util.lang.KT"),
-    ("py:obj", "llnl.util.lang.VT"),
 ]
 
 # The reST default role (used for this markup: `text`) to use for all documents.

lib/spack/docs/config_yaml.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 
@@ -25,23 +26,14 @@ These settings can be overridden in ``etc/spack/config.yaml`` or
 The location where Spack will install packages and their dependencies.
 Default is ``$spack/opt/spack``.
 
----------------
+---------------------------------------------------
-``projections``
+``install_hash_length`` and ``install_path_scheme``
----------------
+---------------------------------------------------
 
-.. warning::
+The default Spack installation path can be very long and can create problems
-
+for scripts with hardcoded shebangs. Additionally, when using the Intel
-   Modifying projections of the install tree is strongly discouraged.
+compiler, and if there is also a long list of dependencies, the compiler may
-
+segfault. If you see the following:
-By default Spack installs all packages into a unique directory relative to the install
-tree root with the following layout:
-
-.. code-block::
-
-   {architecture}/{compiler.name}-{compiler.version}/{name}-{version}-{hash}
-
-In very rare cases, it may be necessary to reduce the length of this path. For example,
-very old versions of the Intel compiler are known to segfault when input paths are too long:
 
      .. code-block:: console
 
@@ -49,25 +41,36 @@ very old versions of the Intel compiler are known to segfault when input paths a
        ** Segmentation violation signal raised. **
        Access violation or stack overflow. Please contact Intel Support for assistance.
 
-Another case is Python and R packages with many runtime dependencies, which can result
+it may be because variables containing dependency specs may be too long. There
-in very large ``PYTHONPATH`` and ``R_LIBS`` environment variables. This can cause the
+are two parameters to help with long path names. Firstly, the
-``execve`` system call to fail with ``E2BIG``, preventing processes from starting.
+``install_hash_length`` parameter can set the length of the hash in the
+installation path from 1 to 32. The default path uses the full 32 characters.
 
-For this reason, Spack allows users to modify the installation layout through custom
+Secondly, it is also possible to modify the entire installation
-projections. For example
+scheme. By default Spack uses
+``{architecture}/{compiler.name}-{compiler.version}/{name}-{version}-{hash}``
+where the tokens that are available for use in this directive are the
+same as those understood by the :meth:`~spack.spec.Spec.format`
+method. Using this parameter it is possible to use a different package
+layout or reduce the depth of the installation paths. For example
 
      .. code-block:: yaml
 
        config:
-         install_tree:
+         install_path_scheme: '{name}/{version}/{hash:7}'
-           root: $spack/opt/spack
-           projections:
-             all: "{name}/{version}/{hash:16}"
 
-would install packages into sub-directories using only the package name, version and a
+would install packages into sub-directories using only the package
-hash length of 16 characters.
+name, version and a hash length of 7 characters.
 
-Notice that reducing the hash length increases the likelihood of hash collisions.
+When using either parameter to set the hash length it only affects the
+representation of the hash in the installation directory. You
+should be aware that the smaller the hash length the more likely
+naming conflicts will occur. These parameters are independent of those
+used to configure module names.
+
+.. warning:: Modifying the installation hash length or path scheme after
+   packages have been installed will prevent Spack from being
+   able to find the old installation directories.
 
 --------------------
 ``build_stage``
@@ -125,8 +128,6 @@ are stored in ``$spack/var/spack/cache``.  These are stored indefinitely
 by default. Can be purged with :ref:`spack clean --downloads
 <cmd-spack-clean>`.
 
-.. _Misc Cache:
-
 --------------------
 ``misc_cache``
 --------------------
@@ -155,8 +156,7 @@ 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 additional ``curl`` arguments are required,
+in the subprocess calling ``curl``.
-they can be set in the config, e.g. ``url_fetch_method:'curl -k -q'``.
 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.
@@ -337,52 +337,3 @@ create a new alias called ``inst`` that will always call ``install -v``:
 
    aliases:
      inst: install -v
-
--------------------------------
-``concretization_cache:enable``
--------------------------------
-
-When set to ``true``, Spack will utilize a cache of solver outputs from
-successful concretization runs. When enabled, Spack will check the concretization
-cache prior to running the solver. If a previous request to solve a given
-problem is present in the cache, Spack will load the concrete specs and other
-solver data from the cache rather than running the solver. Specs not previously
-concretized will be added to the cache on a successful solve. The cache additionally
-holds solver statistics, so commands like ``spack solve`` will still return information
-about the run that produced a given solver result.
-
-This cache is a subcache of the :ref:`Misc Cache` and as such will be cleaned when the Misc
-Cache is cleaned.
-
-When ``false`` or ommitted, all concretization requests will be performed from scatch
-
-----------------------------
-``concretization_cache:url``
-----------------------------
-
-Path to the location where Spack will root the concretization cache. Currently this only supports
-paths on the local filesystem.
-
-Default location is under the :ref:`Misc Cache` at: ``$misc_cache/concretization``
-
-------------------------------------
-``concretization_cache:entry_limit``
-------------------------------------
-
-Sets a limit on the number of concretization results that Spack will cache. The limit is evaluated
-after each concretization run; if Spack has stored more results than the limit allows, the
-oldest concretization results are pruned until 10% of the limit has been removed.
-
-Setting this value to 0 disables the automatic pruning. It is expected users will be
-responsible for maintaining this cache.
-
------------------------------------
-``concretization_cache:size_limit``
------------------------------------
-
-Sets a limit on the size of the concretization cache in bytes. The limit is evaluated
-after each concretization run; if Spack has stored more results than the limit allows, the
-oldest concretization results are pruned until 10% of the limit has been removed.
-
-Setting this value to 0 disables the automatic pruning. It is expected users will be
-responsible for maintaining this cache.

lib/spack/docs/configuration.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 
@@ -11,10 +12,9 @@ Configuration Files
 Spack has many configuration files.  Here is a quick list of them, in
 case you want to skip directly to specific docs:
 
-* :ref:`packages.yaml <compiler-config>`
+* :ref:`compilers.yaml <compiler-config>`
 * :ref:`concretizer.yaml <concretizer-options>`
 * :ref:`config.yaml <config-yaml>`
-* :ref:`include.yaml <include-yaml>`
 * :ref:`mirrors.yaml <mirrors>`
 * :ref:`modules.yaml <modules>`
 * :ref:`packages.yaml <packages-config>`
@@ -95,7 +95,7 @@ are six configuration scopes. From lowest to highest:
    precedence over all other scopes.
 
 Each configuration directory may contain several configuration files,
-such as ``config.yaml``, ``packages.yaml``, or ``mirrors.yaml``.  When
+such as ``config.yaml``, ``compilers.yaml``, or ``mirrors.yaml``.  When
 configurations conflict, settings from higher-precedence scopes override
 lower-precedence settings.
 
@@ -281,7 +281,7 @@ When spack queries for configuration parameters, it searches in
 higher-precedence scopes first. So, settings in a higher-precedence file
 can override those with the same key in a lower-precedence one. For
 list-valued settings, Spack *prepends* higher-precedence settings to
-lower-precedence settings. Completely ignoring lower-precedence configuration
+lower-precedence settings. Completely ignoring higher-level configuration
 options is supported with the ``::`` notation for keys (see
 :ref:`config-overrides` below).
 
@@ -511,7 +511,6 @@ Spack understands over a dozen special variables. These are:
 * ``$target_family``. The target family for the current host, as
   detected by ArchSpec. E.g. ``x86_64`` or ``aarch64``.
 * ``$date``: the current date in the format YYYY-MM-DD
-* ``$spack_short_version``: the Spack version truncated to the first components.
 
 
 Note that, as with shell variables, you can write these as ``$varname``

lib/spack/docs/containers.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 
@@ -37,11 +38,9 @@ just have to configure and OCI registry and run ``spack buildcache push``.
    spack -e . install
 
    # Configure the registry
-   spack -e . mirror add --oci-username-variable REGISTRY_USER \
+   spack -e . mirror add --oci-username ... --oci-password ... container-registry oci://example.com/name/image
-                         --oci-password-variable REGISTRY_TOKEN \
-                        container-registry oci://example.com/name/image
 
-   # Push the image (do set REGISTRY_USER and REGISTRY_TOKEN)
+   # 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:

lib/spack/docs/contribution_guide.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 
@@ -183,7 +184,7 @@ Style Tests
 
 Spack uses `Flake8 <http://flake8.pycqa.org/en/latest/>`_ to test for
 `PEP 8 <https://www.python.org/dev/peps/pep-0008/>`_ conformance and
-`mypy <https://mypy.readthedocs.io/en/stable/>`_ for type checking. PEP 8 is
+`mypy <https://mypy.readthedocs.io/en/stable/>` for type checking. PEP 8 is
 a series of style guides for Python that provide suggestions for everything
 from variable naming to indentation. In order to limit the number of PRs that
 were mostly style changes, we decided to enforce PEP 8 conformance. Your PR
@@ -315,214 +316,6 @@ documentation tests to make sure there are no errors. Documentation changes can
 in some obfuscated warning messages. If you don't understand what they mean, feel free
 to ask when you submit your PR.
 
-.. _spack-builders-and-pipelines:
-
-^^^^^^^^^
-GitLab CI
-^^^^^^^^^
-
-""""""""""""""""""
-Build Cache Stacks
-""""""""""""""""""
-
-Spack welcomes the contribution of software stacks of interest to the community. These
-stacks are used to test package recipes and generate publicly available build caches.
-Spack uses GitLab CI for managing the orchestration of build jobs.
-
-GitLab Entry Point
-~~~~~~~~~~~~~~~~~~
-
-Add stack entrypoint to the ``share/spack/gitlab/cloud_pipelines/.gitlab-ci.yml``. There
-are two stages required for each new stack, the generation stage and the build stage.
-
-The generate stage is defined using the job template ``.generate`` configured with
-environment variables defining the name of the stack in ``SPACK_CI_STACK_NAME`` and the
-platform (``SPACK_TARGET_PLATFORM``) and architecture (``SPACK_TARGET_ARCH``) configuration,
-and the tags associated with the class of runners to build on.
-
-.. note::
-
-    The ``SPACK_CI_STACK_NAME`` must match the name of the directory containing the
-    stacks ``spack.yaml``.
-
-
-.. note::
-
-    The platform and architecture variables are specified in order to select the
-    correct configurations from the generic configurations used in Spack CI. The
-    configurations currently available are:
-
-    * ``.cray_rhel_zen4``
-    * ``.cray_sles_zen4``
-    * ``.darwin_aarch64``
-    * ``.darwin_x86_64``
-    * ``.linux_aarch64``
-    * ``.linux_icelake``
-    * ``.linux_neoverse_n1``
-    * ``.linux_neoverse_v1``
-    * ``.linux_neoverse_v2``
-    * ``.linux_skylake``
-    * ``.linux_x86_64``
-    * ``.linux_x86_64_v4``
-
-    New configurations can be added to accommodate new platforms and architectures.
-
-
-The build stage is defined as a trigger job that consumes the GitLab CI pipeline generated in
-the generate stage for this stack. Build stage jobs use the ``.build`` job template which
-handles the basic configuration.
-
-An example entry point for a new stack called ``my-super-cool-stack``
-
-.. code-block:: yaml
-
-    .my-super-cool-stack:
-      extends: [ ".linux_x86_64_v3" ]
-      variables:
-        SPACK_CI_STACK_NAME: my-super-cool-stack
-        tags: [ "all", "tags", "your", "job", "needs"]
-
-    my-super-cool-stack-generate:
-      extends: [ ".generate", ".my-super-cool-stack" ]
-      image: my-super-cool-stack-image:0.0.1
-
-    my-super-cool-stack-build:
-      extends: [ ".build", ".my-super-cool-stack" ]
-      trigger:
-        include:
-          - artifact: jobs_scratch_dir/cloud-ci-pipeline.yml
-            job: my-super-cool-stack-generate
-        strategy: depend
-      needs:
-        - artifacts: True
-          job: my-super-cool-stack-generate
-
-
-Stack Configuration
-~~~~~~~~~~~~~~~~~~~
-
-The stack configuration is a spack environment file with two additional sections added.
-Stack configurations should be located in ``share/spack/gitlab/cloud_pipelines/stacks/<stack_name>/spack.yaml``.
-
-The ``ci`` section is generally used to define stack specific mappings such as image or tags.
-For more information on what can go into the ``ci`` section refer to the docs on pipelines.
-
-The ``cdash`` section is used for defining where to upload the results of builds. Spack configures
-most of the details for posting pipeline results to
-`cdash.spack.io <https://cdash.spack.io/index.php?project=Spack+Testing>`_. The only
-requirement in the stack configuration is to define a ``build-group`` that is unique,
-this is usually the long name of the stack.
-
-An example stack that builds ``zlib``.
-
-.. code-block:: yaml
-
-    spack:
-      view: false
-      packages:
-        all:
-          require: ["%gcc", "target=x86_64_v3"]
-      specs:
-      - zlib
-
-      ci:
-        pipeline-gen
-        - build-job:
-            image: my-super-cool-stack-image:0.0.1
-
-      cdash:
-        build-group: My Super Cool Stack
-
-.. note::
-
-    The ``image`` used in the ``*-generate`` job must match exactly the ``image`` used in the ``build-job``.
-    When the images do not match the build job may fail.
-
-
-"""""""""""""""""""
-Registering Runners
-"""""""""""""""""""
-
-Contributing computational resources to Spack's CI build farm is one way to help expand the
-capabilities and offerings of the public Spack build caches. Currently, Spack utilizes linux runners
-from AWS, Google, and the University of Oregon (UO).
-
-Runners require three key peices:
-* Runner Registration Token
-* Accurate tags
-* OIDC Authentication script
-* GPG keys
-
-
-Minimum GitLab Runner Version: ``16.1.0``
-`Intallation instructions <https://docs.gitlab.com/runner/install/>`_
-
-Registration Token
-~~~~~~~~~~~~~~~~~~
-
-The first step to contribute new runners is to open an issue in the `spack infrastructure <https://github.com/spack/spack-infrastructure/issues/new?assignees=&labels=runner-registration&projects=&template=runner_registration.yml>`_
-project. This will be reported to the spack infrastructure team who will guide users through the process
-of registering new runners for Spack CI.
-
-The information needed to register a runner is the motivation for the new resources, a semi-detailed description of
-the runner, and finallly the point of contact for maintaining the software on the runner.
-
-The point of contact will then work with the infrastruture team to obtain runner registration token(s) for interacting with
-with Spack's GitLab instance. Once the runner is active, this point of contact will also be responsible for updating the
-GitLab runner software to keep pace with Spack's Gitlab.
-
-Tagging
-~~~~~~~
-
-In the initial stages of runner registration it is important to **exclude** the special tag ``spack``. This will prevent
-the new runner(s) from being picked up for production CI jobs while it is configured and evaluated. Once it is determined
-that the runner is ready for production use the ``spack`` tag will be added.
-
-Because gitlab has no concept of tag exclustion, runners that provide specialized resource also require specialized tags.
-For example, a basic CPU only x86_64 runner may have a tag ``x86_64`` associated with it. However, a runner containing an
-CUDA capable GPU may have the tag ``x86_64-cuda`` to denote that it should only be used for packages that will benefit from
-a CUDA capable resource.
-
-OIDC
-~~~~
-
-Spack runners use OIDC authentication for connecting to the appropriate AWS bucket
-which is used for coordinating the communication of binaries between build jobs. In
-order to configure OIDC authentication, Spack CI runners use a python script with minimal
-dependencies. This script can be configured for runners as seen here using the ``pre_build_script``.
-
-.. code-block:: toml
-
-    [[runners]]
-      pre_build_script = """
-      echo 'Executing Spack pre-build setup script'
-
-      for cmd in "${PY3:-}" python3 python; do
-        if command -v > /dev/null "$cmd"; then
-          export PY3="$(command -v "$cmd")"
-          break
-        fi
-      done
-
-      if [ -z "${PY3:-}" ]; then
-        echo "Unable to find python3 executable"
-        exit 1
-      fi
-
-      $PY3 -c "import urllib.request;urllib.request.urlretrieve('https://raw.githubusercontent.com/spack/spack-infrastructure/main/scripts/gitlab_runner_pre_build/pre_build.py', 'pre_build.py')"
-      $PY3 pre_build.py > envvars
-
-      . ./envvars
-      rm -f envvars
-      unset GITLAB_OIDC_TOKEN
-      """
-
-GPG Keys
-~~~~~~~~
-
-Runners that may be utilized for ``protected`` CI require the registration of an intermediate signing key that
-can be used to sign packages. For more information on package signing read :ref:`key_architecture`.
-
 --------
 Coverage
 --------

lib/spack/docs/developer_guide.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 
@@ -177,8 +178,12 @@ Spec-related modules
   Contains :class:`~spack.spec.Spec`. Also implements most of the logic for concretization
   of specs.
 
-:mod:`spack.spec_parser`
+:mod:`spack.parser`
-  Contains :class:`~spack.spec_parser.SpecParser` and functions related to parsing specs.
+  Contains :class:`~spack.parser.SpecParser` and functions related to parsing specs.
+
+:mod:`spack.concretize`
+  Contains :class:`~spack.concretize.Concretizer` implementation,
+  which allows site administrators to change Spack's :ref:`concretization-policies`.
 
 :mod:`spack.version`
   Implements a simple :class:`~spack.version.Version` class with simple
@@ -332,9 +337,13 @@ inserting them at different places in the spack code base. Whenever a hook
 type triggers by way of a function call, we find all the hooks of that type,
 and run them.
 
-Spack defines hooks by way of a module in the ``lib/spack/spack/hooks`` directory.
+Spack defines hooks by way of a module at ``lib/spack/spack/hooks`` where we can define
-This module has to be registered in ``__init__.py`` so that Spack is aware of it.
+types of hooks in the ``__init__.py``, and then python files in that folder
-This section will cover the basic kind of hooks, and how to write them.
+can use hook functions. The files are automatically parsed, so if you write
+a new file for some integration (e.g., ``lib/spack/spack/hooks/myintegration.py``
+you can then write hook functions in that file that will be automatically detected,
+and run whenever your hook is called. This section will cover the basic kind
+of hooks, and how to write them.
 
 ^^^^^^^^^^^^^^
 Types of Hooks
@@ -543,10 +552,10 @@ With either interpreter you can run a single command:
 
 .. code-block:: console
 
-   $ spack python -c 'from spack.concretize import concretize_one; concretize_one("python")'
+   $ spack python -c 'from spack.spec import Spec; Spec("python").concretized()'
    ...
 
-   $ spack python -i ipython -c 'from spack.concretize import concretize_one; concretize_one("python")'
+   $ spack python -i ipython -c 'from spack.spec import Spec; Spec("python").concretized()'
    Out[1]: ...
 
 or a file:
@@ -707,27 +716,27 @@ Release branches
 ^^^^^^^^^^^^^^^^
 
 There are currently two types of Spack releases: :ref:`major releases
-<major-releases>` (``0.21.0``, ``0.22.0``, etc.) and :ref:`patch releases
+<major-releases>` (``0.17.0``, ``0.18.0``, etc.) and :ref:`point releases
-<patch-releases>` (``0.22.1``, ``0.22.2``, ``0.22.3``, etc.). Here is a
+<point-releases>` (``0.17.1``, ``0.17.2``, ``0.17.3``, etc.). Here is a
 diagram of how Spack release branches work::
 
-    o    branch: develop  (latest version, v0.23.0.dev0)
+    o    branch: develop  (latest version, v0.19.0.dev0)
     |
     o
-    | o  branch: releases/v0.22, tag: v0.22.1
+    | o  branch: releases/v0.18, tag: v0.18.1
     o |
-    | o  tag: v0.22.0
+    | o  tag: v0.18.0
     o |
     | o
     |/
     o
     |
     o
-    | o  branch: releases/v0.21, tag: v0.21.2
+    | o  branch: releases/v0.17, tag: v0.17.2
     o |
-    | o  tag: v0.21.1
+    | o  tag: v0.17.1
     o |
-    | o  tag: v0.21.0
+    | o  tag: v0.17.0
     o |
     | o
     |/
@@ -738,8 +747,8 @@ requests target ``develop``. The ``develop`` branch will report that its
 version is that of the next **major** release with a ``.dev0`` suffix.
 
 Each Spack release series also has a corresponding branch, e.g.
-``releases/v0.22`` has ``v0.22.x`` versions of Spack, and
+``releases/v0.18`` has ``0.18.x`` versions of Spack, and
-``releases/v0.21`` has ``v0.21.x`` versions. A major release is the first
+``releases/v0.17`` has ``0.17.x`` versions. A major release is the first
 tagged version on a release branch. Minor releases are back-ported from
 develop onto release branches. This is typically done by cherry-picking
 bugfix commits off of ``develop``.
@@ -769,40 +778,27 @@ for more details.
 Scheduling work for releases
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-We schedule work for **major releases** through `milestones
+We schedule work for releases by creating `GitHub projects
-<https://github.com/spack/spack/milestones>`_ and `GitHub Projects
+<https://github.com/spack/spack/projects>`_. At any time, there may be
-<https://github.com/spack/spack/projects>`_, while **patch releases** use `labels
+several open release projects. For example, below are two releases (from
-<https://github.com/spack/spack/labels>`_.
+some past version of the page linked above):
 
-There is only one milestone open at a time. Its name corresponds to the next major version, for
+.. image:: images/projects.png
-example ``v0.23``. Important issues and pull requests should be assigned to this milestone by
-core developers, so that they are not forgotten at the time of release. The milestone is closed
-when the release is made, and a new milestone is created for the next major release.
 
-Bug reports in GitHub issues are automatically labelled ``bug`` and ``triage``. Spack developers
+This image shows one release in progress for ``0.15.1`` and another for
-assign one of the labels ``impact-low``, ``impact-medium`` or ``impact-high``. This will make the
+``0.16.0``. Each of these releases has a project board containing issues
-issue appear in the `Triaged bugs <https://github.com/orgs/spack/projects/6>`_ project board.
+and pull requests. GitHub shows a status bar with completed work in
-Important issues should be assigned to the next milestone as well, so they appear at the top of
+green, work in progress in purple, and work not started yet in gray, so
-the project board.
+it's fairly easy to see progress.
 
-Spack's milestones are not firm commitments so we move work between releases frequently. If we
+Spack's project boards are not firm commitments so we move work between
-need to make a release and some tasks are not yet done, we will simply move them to the next major
+releases frequently. If we need to make a release and some tasks are not
-release milestone, rather than delaying the release to complete them.
+yet done, we will simply move them to the next minor or major release, rather
+than delaying the release to complete them.
 
-^^^^^^^^^^^^^^^^^^^^^
+For more on using GitHub project boards, see `GitHub's documentation
-Backporting bug fixes
+<https://docs.github.com/en/github/managing-your-work-on-github/about-project-boards>`_.
-^^^^^^^^^^^^^^^^^^^^^
 
-When a bug is fixed in the ``develop`` branch, it is often necessary to backport the fix to one
-(or more) of the ``release/vX.Y`` branches. Only the release manager is responsible for doing
-backports, but Spack maintainers are responsible for labelling pull requests (and issues if no bug
-fix is available yet) with ``vX.Y.Z`` labels. The label should correspond to the next patch version
-that the bug fix should be backported to.
-
-Backports are done publicly by the release manager using a pull request named ``Backports vX.Y.Z``.
-This pull request is opened from the ``backports/vX.Y.Z`` branch, targets the ``releases/vX.Y``
-branch and contains a (growing) list of cherry-picked commits from the ``develop`` branch.
-Typically there are one or two backport pull requests open at any given time.
 
 .. _major-releases:
 
@@ -810,21 +806,25 @@ Typically there are one or two backport pull requests open at any given time.
 Making major releases
 ^^^^^^^^^^^^^^^^^^^^^
 
-Assuming all required work from the milestone is completed, the steps to make the major release
+Assuming a project board has already been created and all required work
-are:
+completed, the steps to make the major release are:
 
-#. `Create a new milestone <https://github.com/spack/spack/milestones>`_ for the next major
+#. Create two new project boards:
-   release.
 
-#. `Create a new label <https://github.com/spack/spack/labels>`_ for the next patch release.
+   * One for the next major release
+   * One for the next point release
 
-#. Move any optional tasks that are not done to the next milestone.
+#. Move any optional tasks that are not done to one of the new project boards.
+
+   In general, small bugfixes should go to the next point release. Major
+   features, refactors, and changes that could affect concretization should
+   go in the next major release.
 
 #. Create a branch for the release, based on ``develop``:
 
    .. code-block:: console
 
-      $ git checkout -b releases/v0.23 develop
+      $ git checkout -b releases/v0.15 develop
 
    For a version ``vX.Y.Z``, the branch's name should be
    ``releases/vX.Y``. That is, you should create a ``releases/vX.Y``
@@ -860,8 +860,8 @@ are:
 
    Create a pull request targeting the ``develop`` branch, bumping the major
    version in ``lib/spack/spack/__init__.py`` with a ``dev0`` release segment.
-   For instance when you have just released ``v0.23.0``, set the version
+   For instance when you have just released ``v0.15.0``, set the version
-   to ``(0, 24, 0, 'dev0')`` on ``develop``.
+   to ``(0, 16, 0, 'dev0')`` on ``develop``.
 
 #. Follow the steps in :ref:`publishing-releases`.
 
@@ -870,52 +870,82 @@ are:
 #. Follow the steps in :ref:`announcing-releases`.
 
 
-.. _patch-releases:
+.. _point-releases:
 
 ^^^^^^^^^^^^^^^^^^^^^
-Making patch releases
+Making point releases
 ^^^^^^^^^^^^^^^^^^^^^
 
-To make the patch release process both efficient and transparent, we use a *backports pull request*
+Assuming a project board has already been created and all required work
-which contains cherry-picked commits from the ``develop`` branch. The majority of the work is to
+completed, the steps to make the point release are:
-cherry-pick the bug fixes, which ideally should be done as soon as they land on ``develop``:
-this ensures cherry-picking happens in order, and makes conflicts easier to resolve since the
-changes are fresh in the mind of the developer.
 
-The backports pull request is always titled ``Backports vX.Y.Z`` and is labelled ``backports``. It
+#. Create a new project board for the next point release.
-is opened from a branch named ``backports/vX.Y.Z`` and targets the ``releases/vX.Y`` branch.
 
-Whenever a pull request labelled ``vX.Y.Z`` is merged, cherry-pick the associated squashed commit
+#. Move any optional tasks that are not done to the next project board.
-on ``develop`` to the ``backports/vX.Y.Z`` branch. For pull requests that were rebased (or not
-squashed), cherry-pick each associated commit individually. Never force push to the
-``backports/vX.Y.Z`` branch.
 
-.. warning::
+#. Check out the release branch (it should already exist).
+
+    For the ``X.Y.Z`` release, the release branch is called ``releases/vX.Y``.
+    For ``v0.15.1``, you would check out ``releases/v0.15``:
+
+   .. code-block:: console
+
+      $ git checkout releases/v0.15
+
+#. If a pull request to the release branch named ``Backports vX.Y.Z`` is not already
+   in the project, create it. This pull request ought to be created as early as
+   possible when working on a release project, so that we can build the release
+   commits incrementally, and identify potential conflicts at an early stage.
+
+#. Cherry-pick each pull request in the ``Done`` column of the release
+   project board onto the ``Backports vX.Y.Z`` pull request.
+
+   This is **usually** fairly simple since we squash the commits from the
+   vast majority of pull requests. That means there is only one commit
+   per pull request to cherry-pick. For example, `this pull request
+   <https://github.com/spack/spack/pull/15777>`_ has three commits, but
+   they were squashed into a single commit on merge. You can see the
+   commit that was created here:
+
+   .. image:: images/pr-commit.png
+
+   You can easily cherry pick it like this (assuming you already have the
+   release branch checked out):
+
+   .. code-block:: console
+
+      $ git cherry-pick 7e46da7
+
+   For pull requests that were rebased (or not squashed), you'll need to
+   cherry-pick each associated commit individually.
+
+   .. warning::
+
+      It is important to cherry-pick commits in the order they happened,
+      otherwise you can get conflicts while cherry-picking. When
+      cherry-picking look at the merge date,
+      **not** the number of the pull request or the date it was opened.
 
       Sometimes you may **still** get merge conflicts even if you have
       cherry-picked all the commits in order. This generally means there
       is some other intervening pull request that the one you're trying
       to pick depends on. In these cases, you'll need to make a judgment
       call regarding those pull requests.  Consider the number of affected
-   files and/or the resulting differences.
+      files and or the resulting differences.
 
-   1. If the changes are small, you might just cherry-pick it.
+      1. If the dependency changes are small, you might just cherry-pick it,
+         too. If you do this, add the task to the release board.
 
       2. If the changes are large, then you may decide that this fix is not
-      worth including in a patch release, in which case you should remove
+         worth including in a point release, in which case you should remove
-      the label from the pull request. Remember that large, manual backports
+         the task from the release project.
-      are seldom the right choice for a patch release.
 
-When all commits are cherry-picked in the ``backports/vX.Y.Z`` branch, make the patch
+      3. You can always decide to manually back-port the fix to the release
-release as follows:
+         branch if neither of the above options makes sense, but this can
+         require a lot of work. It's seldom the right choice.
 
-#. `Create a new label <https://github.com/spack/spack/labels>`_ ``vX.Y.{Z+1}`` for the next patch
+#. When all the commits from the project board are cherry-picked into
-   release.
+   the ``Backports vX.Y.Z`` pull request, you can push a commit to:
-
-#. Replace the label ``vX.Y.Z`` with ``vX.Y.{Z+1}`` for all PRs and issues that are not done.
-
-#. Manually push a single commit with commit message ``Set version to vX.Y.Z`` to the
-   ``backports/vX.Y.Z`` branch, that both bumps the Spack version number and updates the changelog:
 
    1. Bump the version in ``lib/spack/spack/__init__.py``.
    2. Update ``CHANGELOG.md`` with a list of the changes.
@@ -924,22 +954,20 @@ release as follows:
    release branch. See `the changelog from 0.14.1
    <https://github.com/spack/spack/commit/ff0abb9838121522321df2a054d18e54b566b44a>`_.
 
-#. Make sure CI passes on the **backports pull request**, including:
+#. Merge the ``Backports vX.Y.Z`` PR with the **Rebase and merge** strategy. This
+   is needed to keep track in the release branch of all the commits that were
+   cherry-picked.
+
+#. Make sure CI passes on the release branch, including:
 
    * Regular unit tests
    * Build tests
    * The E4S pipeline at `gitlab.spack.io <https://gitlab.spack.io>`_
 
-#. Merge the ``Backports vX.Y.Z`` PR with the **Rebase and merge** strategy. This
+   If CI does not pass, you'll need to figure out why, and make changes
-   is needed to keep track in the release branch of all the commits that were
+   to the release branch until it does. You can make more commits, modify
-   cherry-picked.
+   or remove cherry-picked commits, or cherry-pick **more** from
-
+   ``develop`` to make this happen.
-#. Make sure CI passes on the last commit of the **release branch**.
-
-#. In the rare case you need to include additional commits in the patch release after the backports
-   PR is merged, it is best to delete the last commit ``Set version to vX.Y.Z`` from the release
-   branch with a single force push, open a new backports PR named ``Backports vX.Y.Z (2)``, and
-   repeat the process. Avoid repeated force pushes to the release branch.
 
 #. Follow the steps in :ref:`publishing-releases`.
 
@@ -1014,31 +1042,25 @@ Updating `releases/latest`
 
 If the new release is the **highest** Spack release yet, you should
 also tag it as ``releases/latest``. For example, suppose the highest
-release is currently ``0.22.3``:
+release is currently ``0.15.3``:
 
-* If you are releasing ``0.22.4`` or ``0.23.0``, then you should tag
+* If you are releasing ``0.15.4`` or ``0.16.0``, then you should tag
-  it with ``releases/latest``, as these are higher than ``0.22.3``.
+  it with ``releases/latest``, as these are higher than ``0.15.3``.
 
 * If you are making a new release of an **older** major version of
-  Spack, e.g. ``0.21.4``, then you should not tag it as
+  Spack, e.g. ``0.14.4``, then you should not tag it as
   ``releases/latest`` (as there are newer major versions).
 
-To do so, first fetch the latest tag created on GitHub, since you may not have it locally:
+To tag ``releases/latest``, do this:
 
 .. code-block:: console
 
-   $ git fetch --force git@github.com:spack/spack vX.Y.Z
+   $ git checkout releases/vX.Y     # vX.Y is the new release's branch
+   $ git tag --force releases/latest
+   $ git push --force --tags
 
-Then tag ``vX.Y.Z`` as ``releases/latest`` and push the individual tag to GitHub.
+The ``--force`` argument to ``git tag`` makes ``git`` overwrite the existing
-
+``releases/latest`` tag with the new one.
-.. code-block:: console
-
-   $ git tag --force releases/latest vX.Y.Z
-   $ git push --force git@github.com:spack/spack releases/latest
-
-The ``--force`` argument to ``git tag`` makes ``git`` overwrite the existing ``releases/latest``
-tag with the new one. Do **not** use the ``--tags`` flag when pushing, since this will push *all*
-local tags.
 
 
 .. _announcing-releases:

lib/spack/docs/environments.rst

@@ -1,59 +1,53 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 
 .. _environments:
 
-=====================================
+=========================
-Environments (spack.yaml, spack.lock)
+Environments (spack.yaml)
-=====================================
+=========================
 
-An environment is used to group a set of specs intended for some purpose
+An environment is used to group together a set of specs for the
-to be built, rebuilt, and deployed in a coherent fashion. Environments
+purpose of building, rebuilding and deploying in a coherent fashion.
-define aspects of the installation of the software, such as:
+Environments provide a number of advantages over the *à la carte*
+approach of building and loading individual Spack modules:
 
-#. *which* specs to install;
+#. Environments separate the steps of (a) choosing what to
-#. *how* those specs are configured; and
+   install, (b) concretizing, and (c) installing.  This allows
-#. *where* the concretized software will be installed.
+   Environments to remain stable and repeatable, even if Spack packages
-
+   are upgraded: specs are only re-concretized when the user
-Aggregating this information into an environment for processing has advantages
+   explicitly asks for it.  It is even possible to reliably
-over the *à la carte* approach of building and loading individual Spack modules.
+   transport environments between different computers running
-
+   different versions of Spack!
-With environments, you concretize, install, or load (activate) all of the
+#. Environments allow several specs to be built at once; a more robust
-specs with a single command. Concretization fully configures the specs
+   solution than ad-hoc scripts making multiple calls to ``spack
-and dependencies of the environment in preparation for installing the
+   install``.
-software. This is a more robust solution than ad-hoc installation scripts.
+#. An Environment that is built as a whole can be loaded as a whole
-And you can share an environment or even re-use it on a different computer.
+   into the user environment. An Environment can be built to maintain
-
+   a filesystem view of its packages, and the environment can load
-Environment definitions, especially *how* specs are configured, allow the
+   that view into the user environment at activation time. Spack can
-software to remain stable and repeatable even when Spack packages are upgraded. Changes are only picked up when the environment is explicitly re-concretized.
+   also generate a script to load all modules related to an
-
+   environment.
-Defining *where* specs are installed supports a filesystem view of the
-environment. Yet Spack maintains a single installation of the software that
-can be re-used across multiple environments.
-
-Activating an environment determines *when* all of the associated (and
-installed) specs are loaded so limits the software loaded to those specs
-actually needed by the environment. Spack can even generate a script to
-load all modules related to an environment.
 
 Other packaging systems also provide environments that are similar in
 some ways to Spack environments; for example, `Conda environments
 <https://conda.io/docs/user-guide/tasks/manage-environments.html>`_ or
 `Python Virtual Environments
 <https://docs.python.org/3/tutorial/venv.html>`_.  Spack environments
-provide some distinctive features though:
+provide some distinctive features:
 
 #. A spec installed "in" an environment is no different from the same
-   spec installed anywhere else in Spack.
+   spec installed anywhere else in Spack.  Environments are assembled
-#. Spack environments may contain more than one spec of the same
+   simply by collecting together a set of specs.
+#. Spack Environments may contain more than one spec of the same
    package.
 
 Spack uses a "manifest and lock" model similar to `Bundler gemfiles
-<https://bundler.io/man/gemfile.5.html>`_ and other package managers.
+<https://bundler.io/man/gemfile.5.html>`_ and other package
-The environment's user input file (or manifest), is named ``spack.yaml``.
+managers. The user input file is named ``spack.yaml`` and the lock
-The lock file, which contains the fully configured and concretized specs,
+file is named ``spack.lock``
-is named ``spack.lock``.
 
 .. _environments-using:
 
@@ -74,73 +68,55 @@ An environment is created by:
 
    $ spack env create myenv
 
-The directory ``$SPACK_ROOT/var/spack/environments/myenv`` is created
+Spack then creates the directory ``var/spack/environments/myenv``.
-to manage the environment.
 
 .. note::
 
-   All managed environments by default are stored in the
+   All managed environments by default are stored in the ``var/spack/environments`` folder.
-   ``$SPACK_ROOT/var/spack/environments`` folder. This location can be changed
+   This location can be changed by setting the ``environments_root`` variable in ``config.yaml``.
-   by setting the ``environments_root`` variable in ``config.yaml``.
 
-Spack creates the file ``spack.yaml``, hidden directory ``.spack-env``, and
+In the ``var/spack/environments/myenv`` directory, Spack creates the
-``spack.lock`` file under ``$SPACK_ROOT/var/spack/environments/myenv``. User
+file ``spack.yaml`` and the hidden directory ``.spack-env``.
-interaction occurs through the ``spack.yaml`` file and the Spack commands
+
-that affect it. Metadata and, by default, the view are stored in the
+Spack stores metadata in the ``.spack-env`` directory. User
-``.spack-env`` directory. When the environment is concretized, Spack creates
+interaction will occur through the ``spack.yaml`` file and the Spack
-the ``spack.lock`` file with the fully configured specs and dependencies for
+commands that affect it. When the environment is concretized, Spack
+will create a file ``spack.lock`` with the concrete information for
 the environment.
 
-The ``.spack-env`` subdirectory also contains:
+In addition to being the default location for the view associated with
+an Environment, the ``.spack-env`` directory also contains:
 
-  * ``repo/``: A subdirectory acting as the repo consisting of the Spack
+  * ``repo/``: A repo consisting of the Spack packages used in this
-    packages used in the environment. It allows the environment to build
+    environment.  This allows the environment to build the same, in
-    the same, in theory, even on different versions of Spack with different
+    theory, even on different versions of Spack with different
     packages!
-  * ``logs/``: A subdirectory containing the build logs for the packages
+  * ``logs/``: A directory containing the build logs for the packages
-    in this environment.
+    in this Environment.
 
-Spack Environments can also be created from either the user input, or
+Spack Environments can also be created from either a manifest file
-manifest, file or the lockfile. Create an environment from a manifest using:
+(usually but not necessarily named, ``spack.yaml``) or a lockfile.
+To create an Environment from a manifest:
 
 .. code-block:: console
 
    $ spack env create myenv spack.yaml
 
-The resulting environment is guaranteed to have the same root specs as
+To create an Environment from a ``spack.lock`` lockfile:
-the original but may concretize differently in the presence of different
-explicit or default configuration settings (e.g., a different version of
-Spack or for a different user account).
-
-Environments created from a manifest will copy any included configs
-from relative paths inside the environment. Relative paths from
-outside the environment will cause errors, and absolute paths will be
-kept absolute. For example, if ``spack.yaml`` includes:
-
-.. code-block:: yaml
-
-   spack:
-     include: [./config.yaml]
-
-then the created environment will have its own copy of the file
-``config.yaml`` copied from the location in the original environment.
-
-Create an environment from a ``spack.lock`` file using:
 
 .. code-block:: console
 
    $ spack env create myenv spack.lock
 
-The resulting environment, when on the same or a compatible machine, is
+Either of these commands can also take a full path to the
-guaranteed to initially have the same concrete specs as the original.
+initialization file.
 
-.. note::
+A Spack Environment created from a ``spack.yaml`` manifest is
-
+guaranteed to have the same root specs as the original Environment,
-   Environment creation also accepts a full path to the file.
+but may concretize differently. A Spack Environment created from a
-
+``spack.lock`` lockfile is guaranteed to have the same concrete specs
-   If the path is not under the ``$SPACK_ROOT/var/spack/environments``
+as the original Environment. Either may obviously then differ as the
-   directory then the source is referred to as an
+user modifies it.
-   :ref:`independent environment <independent_environments>`.
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 Activating an Environment
@@ -153,7 +129,7 @@ To activate an environment, use the following command:
    $ spack env activate myenv
 
 By default, the ``spack env activate`` will load the view associated
-with the environment into the user environment. The ``-v,
+with the Environment into the user environment. The ``-v,
 --with-view`` argument ensures this behavior, and the ``-V,
 --without-view`` argument activates the environment without changing
 the user environment variables.
@@ -166,11 +142,8 @@ 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
+The ``activate`` command can also be used to create a new environment if it does not already
-not already defined, by adding the ``--create`` flag. Managed and independent
+exist.
-environments 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
    
@@ -195,50 +168,49 @@ or the shortcut alias
 If the environment was activated with its view, deactivating the
 environment will remove the view from the user environment.
 
-.. _independent_environments:
+^^^^^^^^^^^^^^^^^^^^^^
+Anonymous Environments
+^^^^^^^^^^^^^^^^^^^^^^
 
-^^^^^^^^^^^^^^^^^^^^^^^^
+Apart from managed environments, Spack also supports anonymous environments.
-Independent Environments
-^^^^^^^^^^^^^^^^^^^^^^^^
 
-Independent environments can be located in any directory outside of Spack.
+Anonymous environments can be placed in any directory of choice.
 
 .. note::
 
    When uninstalling packages, Spack asks the user to confirm the removal of packages
-   that are still used in a managed environment. This is not the case for independent
+   that are still used in a managed environment. This is not the case for anonymous
    environments.
 
-To create an independent environment, use one of the following commands:
+To create an anonymous environment, use one of the following commands:
 
 .. code-block:: console
 
    $ spack env create --dir my_env
    $ spack env create ./my_env
 
-As a shorthand, you can also create an independent environment upon activation if it does not
+As a shorthand, you can also create an anonymous environment upon activation if it does not
 already exist:
 
 .. code-block:: console
 
    $ spack env activate --create ./my_env
 
-For convenience, Spack can also place an independent environment in a temporary directory for you:
+For convenience, Spack can also place an anonymous environment in a temporary directory for you:
 
 .. code-block:: console
 
    $ spack env activate --temp
 
 
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Environment-Aware Commands
+Environment Sensitive Commands
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Spack commands are environment-aware. For example, the ``find``
+Spack commands are environment sensitive. For example, the ``find``
-command shows only the specs in the active environment if an
+command shows only the specs in the active Environment if an
-environment has been activated. Otherwise it shows all specs in
+Environment has been activated. Similarly, the ``install`` and
-the Spack instance. The same rule applies to the ``install`` and
+``uninstall`` commands act on the active environment.
-``uninstall`` commands.
 
 .. code-block:: console
 
@@ -283,33 +255,32 @@ the Spack instance. The same rule applies to the ``install`` and
 
 
 Note that when we installed the abstract spec ``zlib@1.2.8``, it was
-presented as a root of the environment. All explicitly installed
+presented as a root of the Environment. All explicitly installed
-packages will be listed as roots of the environment.
+packages will be listed as roots of the Environment.
 
 All of the Spack commands that act on the list of installed specs are
-environment-aware in this way, including ``install``,
+Environment-sensitive in this way, including ``install``,
-``uninstall``, ``find``, ``extensions``, etcetera. In the
+``uninstall``, ``find``, ``extensions``, and more. In the
 :ref:`environment-configuration` section we will discuss
-environment-aware commands further.
+Environment-sensitive commands further.
 
 ^^^^^^^^^^^^^^^^^^^^^
 Adding Abstract Specs
 ^^^^^^^^^^^^^^^^^^^^^
 
-An abstract spec is the user-specified spec before Spack applies
+An abstract spec is the user-specified spec before Spack has applied
-defaults or dependency information.
+any defaults or dependency information.
 
-Users can add abstract specs to an environment using the ``spack add``
+Users can add abstract specs to an Environment using the ``spack add``
-command. The most important component of an environment is a list of
+command. The most important component of an Environment is a list of
 abstract specs.
 
-Adding a spec adds it as a root spec of the environment in the user
+Adding a spec adds to the manifest (the ``spack.yaml`` file), which is
-input file (``spack.yaml``). It does not affect the concrete specs
+used to define the roots of the Environment, but does not affect the
-in the lock file (``spack.lock``) and it does not install the spec.
+concrete specs in the lockfile, nor does it install the spec.
 
-The ``spack add`` command is environment-aware. It adds the spec to the
+The ``spack add`` command is environment aware. It adds to the
-currently active environment. An error is generated if there isn't an
+currently active environment. All environment aware commands can also
-active environment. All environment-aware commands can also
 be called using the ``spack -e`` flag to specify the environment.
 
 .. code-block:: console
@@ -329,11 +300,11 @@ or
 Concretizing
 ^^^^^^^^^^^^
 
-Once user specs have been added to an environment, they can be concretized.
+Once some user specs have been added to an environment, they can be concretized.
-There are three different modes of operation to concretize an environment,
+There are at the moment three different modes of operation to concretize an environment,
-explained in detail in :ref:`environments_concretization_config`.
+which are explained in details in :ref:`environments_concretization_config`.
-Regardless of which mode of operation is chosen, the following
+Regardless of which mode of operation has been chosen, the following
-command will ensure all of the root specs are concretized according to the
+command will ensure all the root specs are concretized according to the
 constraints that are prescribed in the configuration:
 
 .. code-block:: console
@@ -342,15 +313,16 @@ constraints that are prescribed in the configuration:
 
 In the case of specs that are not concretized together, the command
 above will concretize only the specs that were added and not yet
-concretized. Forcing a re-concretization of all of the specs can be done
+concretized. Forcing a re-concretization of all the specs can be done
-by adding the ``-f`` option:
+instead with this command:
 
 .. code-block:: console
 
    [myenv]$ spack concretize -f
 
-Without the option, Spack guarantees that already concretized specs are
+When the ``-f`` flag is not used to reconcretize all specs, Spack
-unchanged in the environment.
+guarantees that already concretized specs are unchanged in the
+environment.
 
 The ``concretize`` command does not install any packages. For packages
 that have already been installed outside of the environment, the
@@ -383,16 +355,16 @@ installed specs using the ``-c`` (``--concretized``) flag.
 Installing an Environment
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-In addition to adding individual specs to an environment, one
+In addition to installing individual specs into an Environment, one
-can install the entire environment at once using the command
+can install the entire Environment at once using the command
 
 .. code-block:: console
 
    [myenv]$ spack install
 
-If the environment has been concretized, Spack will install the
+If the Environment has been concretized, Spack will install the
-concretized specs. Otherwise, ``spack install`` will concretize
+concretized specs. Otherwise, ``spack install`` will first concretize
-the environment before installing the concretized specs.
+the Environment and then install the concretized specs.
 
 .. note::
 
@@ -413,17 +385,17 @@ the environment before installing the concretized specs.
 
 
 As it installs, ``spack install`` creates symbolic links in the
-``logs/`` directory in the environment, allowing for easy inspection
+``logs/`` directory in the Environment, allowing for easy inspection
 of build logs related to that environment. The ``spack install``
 command also stores a Spack repo containing the ``package.py`` file
 used at install time for each package in the ``repos/`` directory in
-the environment.
+the Environment.
 
 The ``--no-add`` option can be used in a concrete environment to tell
 spack to install specs already present in the environment but not to
 add any new root specs to the environment.  For root specs provided
 to ``spack install`` on the command line, ``--no-add`` is the default,
-while for dependency specs, it is optional.  In other
+while for dependency specs on the other hand, it is optional.  In other
 words, if there is an unambiguous match in the active concrete environment
 for a root spec provided to ``spack install`` on the command line, spack
 does not require you to specify the ``--no-add`` option to prevent the spec
@@ -437,39 +409,22 @@ Developing Packages in a Spack Environment
 
 The ``spack develop`` command allows one to develop Spack packages in
 an environment. It requires a spec containing a concrete version, and
-will configure Spack to install the package from local source.
+will configure Spack to install the package from local source. By
-If a version is not provided from the command line interface then spack
+default, it will also clone the package to a subdirectory in the
-will automatically pick the highest version the package has defined.
+environment. This package will have a special variant ``dev_path``
-This means any infinity versions (``develop``, ``main``, ``stable``) will be
-preferred in this selection process.
-By default, ``spack develop`` will also clone the package to a subdirectory in the
-environment for the local source. This package will have a special variant ``dev_path``
 set, and Spack will ensure the package and its dependents are rebuilt
 any time the environment is installed if the package's local source
-code has been modified. Spack's native implementation to check for modifications
+code has been modified. Spack ensures that all instances of a
-is to check if ``mtime`` is newer than the installation.
-A custom check can be created by overriding the ``detect_dev_src_change`` method
-in your package class. This is particularly useful for projects using custom spack repo's
-to drive development and want to optimize performance.
-
-Spack ensures that all instances of a
 developed package in the environment are concretized to match the
 version (and other constraints) passed as the spec argument to the
 ``spack develop`` command.
 
-When working deep in the graph it is often desirable to have multiple specs marked
-as ``develop`` so you don't have to restage and/or do full rebuilds each time you
-call ``spack install``.  The ``--recursive`` flag can be used in these scenarios
-to ensure that all the dependents of the initial spec you provide are also marked
-as develop specs.  The ``--recursive`` flag requires a pre-concretized environment
-so the graph can be traversed from the supplied spec all the way to the root specs.
-
 For packages with ``git`` attributes, git branches, tags, and commits can
 also be used as valid concrete versions (see :ref:`version-specifier`).
 This means that for a package ``foo``, ``spack develop foo@git.main`` will clone
 the ``main`` branch of the package, and ``spack install`` will install from
 that git clone if ``foo`` is in the environment.
-Further development on ``foo`` can be tested by re-installing 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
@@ -654,7 +609,7 @@ manipulate configuration inline in the ``spack.yaml`` file.
 Inline configurations
 ^^^^^^^^^^^^^^^^^^^^^
 
-Inline environment-scope configuration is done using the same yaml
+Inline Environment-scope configuration is done using the same yaml
 format as standard Spack configuration scopes, covered in the
 :ref:`configuration` section. Each section is contained under a
 top-level yaml object with it's name. For example, a ``spack.yaml``
@@ -667,56 +622,31 @@ a ``packages.yaml`` file) could contain:
      # ...
      packages:
        all:
-         providers:
+         compiler: [intel]
-           mpi: [openmpi]
      # ...
 
-This configuration sets the default mpi provider to be openmpi.
+This configuration sets the default compiler for all packages to
+``intel``.
 
 ^^^^^^^^^^^^^^^^^^^^^^^
 Included configurations
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-Spack environments allow an ``include`` heading in their yaml schema.
+Spack environments allow an ``include`` heading in their yaml
-This heading pulls in external configuration files and applies them to
+schema. This heading pulls in external configuration files and applies
-the environment.
+them to the Environment.
 
 .. code-block:: yaml
 
    spack:
      include:
-     - environment/relative/path/to/config.yaml
+     - relative/path/to/config.yaml
-     - path: https://github.com/path/to/raw/config/compilers.yaml
+     - https://github.com/path/to/raw/config/compilers.yaml
-       sha256: 26e871804a92cd07bb3d611b31b4156ae93d35b6a6d6e0ef3a67871fcb1d258b
      - /absolute/path/to/packages.yaml
-     - path: /path/to/$os/$target/environment
-       optional: true
-     - path: /path/to/os-specific/config-dir
-       when: os == "ventura"
-
-Included configuration files are required *unless* they are explicitly optional
-or the entry's condition evaluates to ``false``. Optional includes are specified
-with the ``optional`` clause and conditional with the ``when`` clause. (See
-:ref:`include-yaml` for more information on optional and conditional entries.)
-
-Files are listed using paths to individual files or directories containing them.
-Path entries may be absolute or relative to the environment or specified as 
-URLs. URLs to individual files must link to the **raw** form of the file's 
-contents (e.g., `GitHub
-<https://docs.github.com/en/repositories/working-with-files/using-files/viewing-and-understanding-files#viewing-or-copying-the-raw-file-content>`_ 
-or `GitLab
-<https://docs.gitlab.com/ee/api/repository_files.html#get-raw-file-from-repository>`_) **and** include a valid sha256 for the file.
-Only the ``file``, ``ftp``, ``http`` and ``https`` protocols (or schemes) are
-supported. Spack-specific, environment and user path variables can be used.
-(See :ref:`config-file-variables` for more information.)
-
-.. warning::
-
-   Recursive includes are not currently processed in a breadth-first manner
-   so the value of a configuration option that is altered by multiple included
-   files may not be what you expect. This will be addressed in a future
-   update.
 
+Environments can include files or URLs. File paths can be relative or
+absolute. URLs include the path to the text for individual files or
+can be the path to a directory containing configuration files.
 
 ^^^^^^^^^^^^^^^^^^^^^^^^
 Configuration precedence
@@ -731,7 +661,7 @@ have higher precedence, as the included configs are applied in reverse order.
 Manually Editing the Specs List
 -------------------------------
 
-The list of abstract/root specs in the environment is maintained in
+The list of abstract/root specs in the Environment is maintained in
 the ``spack.yaml`` manifest under the heading ``specs``.
 
 .. code-block:: yaml
@@ -839,7 +769,7 @@ evaluates to the cross-product of those specs. Spec matrices also
 contain an ``excludes`` directive, which eliminates certain
 combinations from the evaluated result.
 
-The following two environment manifests are identical:
+The following two Environment manifests are identical:
 
 .. code-block:: yaml
 
@@ -914,7 +844,7 @@ files are identical.
 In short files like the example, it may be easier to simply list the
 included specs. However for more complicated examples involving many
 packages across many toolchains, separately factored lists make
-environments substantially more manageable.
+Environments substantially more manageable.
 
 Additionally, the ``-l`` option to the ``spack add`` command allows
 one to add to named lists in the definitions section of the manifest
@@ -933,7 +863,7 @@ named list ``compilers`` is ``['%gcc', '%clang', '%intel']`` on
    spack:
      definitions:
        - compilers: ['%gcc', '%clang']
-       - when: arch.satisfies('target=x86_64:')
+       - when: arch.satisfies('x86_64:')
          compilers: ['%intel']
 
 .. note::
@@ -1083,7 +1013,7 @@ file snippet we define a view named ``mpis``, rooted at
 ``/path/to/view`` in which all projections use the package name,
 version, and compiler name to determine the path for a given
 package. This view selects all packages that depend on MPI, and
-excludes those built with the GCC compiler at version 18.5.
+excludes those built with the PGI compiler at version 18.5.
 The root specs with their (transitive) link and run type dependencies
 will be put in the view due to the  ``link: all`` option,
 and the files in the view will be symlinks to the spack install
@@ -1097,7 +1027,7 @@ directories.
        mpis:
          root: /path/to/view
          select: [^mpi]
-         exclude: ['%gcc@18.5']
+         exclude: ['%pgi@18.5']
          projections:
            all: '{name}/{version}-{compiler.name}'
          link: all
@@ -1130,7 +1060,7 @@ true``). The argument ``--without-view`` can be used to create an
 environment without any view configured.
 
 The ``spack env view`` command can be used to change the manage views
-of an environment. The subcommand ``spack env view enable`` will add a
+of an Environment. The subcommand ``spack env view enable`` will add a
 view named ``default`` to an environment. It takes an optional
 argument to specify the path for the new default view. The subcommand
 ``spack env view disable`` will remove the view named ``default`` from
@@ -1298,7 +1228,7 @@ gets installed and is available for use in the ``env`` target.
    	$(SPACK) -e . env depfile -o $@ --make-prefix spack
 
    env: spack/env
-   	$(info environment installed!)
+   	$(info Environment installed!)
 
    clean:
    	rm -rf spack.lock env.mk spack/

lib/spack/docs/example_files/spack.yaml

@@ -0,0 +1,161 @@
+spack:
+  definitions:
+  - compiler-pkgs:
+    - 'llvm+clang@6.0.1 os=centos7'
+    - 'gcc@6.5.0 os=centos7'
+    - 'llvm+clang@6.0.1 os=ubuntu18.04'
+    - 'gcc@6.5.0 os=ubuntu18.04'
+  - pkgs:
+    - readline@7.0
+    # - xsdk@0.4.0
+  - compilers:
+    - '%gcc@5.5.0'
+    - '%gcc@6.5.0'
+    - '%gcc@7.3.0'
+    - '%clang@6.0.0'
+    - '%clang@6.0.1'
+  - oses:
+    - os=ubuntu18.04
+    - os=centos7
+
+  specs:
+  - matrix:
+    - [$pkgs]
+    - [$compilers]
+    - [$oses]
+    exclude:
+      - '%gcc@7.3.0 os=centos7'
+      - '%gcc@5.5.0 os=ubuntu18.04'
+
+  mirrors:
+    cloud_gitlab: https://mirror.spack.io
+
+  compilers:
+    # The .gitlab-ci.yml for this project picks a Docker container which does
+    # not have any compilers pre-built and ready to use, so we need to fake the
+    # existence of those here.
+    - compiler:
+        operating_system: centos7
+        modules: []
+        paths:
+          cc: /not/used
+          cxx: /not/used
+          f77: /not/used
+          fc: /not/used
+        spec: gcc@5.5.0
+        target: x86_64
+    - compiler:
+        operating_system: centos7
+        modules: []
+        paths:
+          cc: /not/used
+          cxx: /not/used
+          f77: /not/used
+          fc: /not/used
+        spec: gcc@6.5.0
+        target: x86_64
+    - compiler:
+        operating_system: centos7
+        modules: []
+        paths:
+          cc: /not/used
+          cxx: /not/used
+          f77: /not/used
+          fc: /not/used
+        spec: clang@6.0.0
+        target: x86_64
+    - compiler:
+        operating_system: centos7
+        modules: []
+        paths:
+          cc: /not/used
+          cxx: /not/used
+          f77: /not/used
+          fc: /not/used
+        spec: clang@6.0.1
+        target: x86_64
+
+    - compiler:
+        operating_system: ubuntu18.04
+        modules: []
+        paths:
+          cc: /not/used
+          cxx: /not/used
+          f77: /not/used
+          fc: /not/used
+        spec: clang@6.0.0
+        target: x86_64
+    - compiler:
+        operating_system: ubuntu18.04
+        modules: []
+        paths:
+          cc: /not/used
+          cxx: /not/used
+          f77: /not/used
+          fc: /not/used
+        spec: clang@6.0.1
+        target: x86_64
+    - compiler:
+        operating_system: ubuntu18.04
+        modules: []
+        paths:
+          cc: /not/used
+          cxx: /not/used
+          f77: /not/used
+          fc: /not/used
+        spec: gcc@6.5.0
+        target: x86_64
+    - compiler:
+        operating_system: ubuntu18.04
+        modules: []
+        paths:
+          cc: /not/used
+          cxx: /not/used
+          f77: /not/used
+          fc: /not/used
+        spec: gcc@7.3.0
+        target: x86_64
+
+  gitlab-ci:
+    bootstrap:
+      - name: compiler-pkgs
+        compiler-agnostic: true
+    mappings:
+      - # spack-cloud-ubuntu
+        match:
+          # these are specs, if *any* match the spec under consideration, this
+          # 'mapping' will be used to generate the CI job
+          - os=ubuntu18.04
+        runner-attributes:
+          # 'tags' and 'image' go directly onto the job, 'variables' will
+          # be added to what we already necessarily create for the job as
+          # a part of the CI workflow
+          tags:
+            - spack-k8s
+          image:
+            name: scottwittenburg/spack_builder_ubuntu_18.04
+            entrypoint: [""]
+      - # spack-cloud-centos
+        match:
+          # these are specs, if *any* match the spec under consideration, this
+          # 'mapping' will be used to generate the CI job
+          - 'os=centos7'
+        runner-attributes:
+          tags:
+            - spack-k8s
+          image:
+            name: scottwittenburg/spack_builder_centos_7
+            entrypoint: [""]
+
+  cdash:
+    build-group: Release Testing
+    url: http://cdash
+    project: Spack Testing
+    site: Spack Docker-Compose Workflow
+
+  repos: []
+  upstreams: {}
+  modules:
+    enable: []
+  packages: {}
+  config: {}

lib/spack/docs/extensions.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 

lib/spack/docs/features.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 

lib/spack/docs/frequently_asked_questions.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 
@@ -30,7 +31,7 @@ than always choosing the latest versions or default variants.
 
 .. note::
 
-    As a rule of thumb: requirements + constraints > strong preferences > reuse > preferences > defaults.
+    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.
@@ -56,19 +57,7 @@ common cases where concretization output may seem surprising at first.
       concretizer:
         reuse: dependencies  # other options are 'true' and 'false'
 
-3. :ref:`Strong preferences <package-strong-preferences>` configured in ``packages.yaml``
+3. :ref:`Package requirements <package-requirements>` configured in ``packages.yaml``,
-   are higher priority than reuse, and can be used to strongly prefer a specific version
-   or variant, without erroring out if it's not possible. Strong preferences are specified
-   as follows:
-
-   .. code-block:: yaml
-
-      packages:
-        foo:
-          prefer:
-          - "@1.1: ~mpi"
-
-4. :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:
 
@@ -78,8 +67,6 @@ common cases where concretization output may seem surprising at first.
         foo:
           require:
           - "@1.2: +mpi"
-          conflicts:
-          - "@1.4"
 
 Requirements and constraints restrict the set of possible solutions, while reuse
 behavior and preferences influence what an optimal solution looks like.

lib/spack/docs/getting_started.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 
@@ -34,7 +35,7 @@ A build matrix showing which packages are working on which systems is shown belo
       .. code-block:: console
 
          apt update
-         apt install bzip2 ca-certificates g++ gcc gfortran git gzip lsb-release patch python3 tar unzip xz-utils zstd
+         apt install build-essential ca-certificates coreutils curl environment-modules gfortran git gpg lsb-release python3 python3-distutils python3-venv unzip zip
 
    .. tab-item:: RHEL
 
@@ -42,14 +43,14 @@ A build matrix showing which packages are working on which systems is shown belo
 
          dnf install epel-release
          dnf group install "Development Tools"
-         dnf install gcc-gfortran redhat-lsb-core python3 unzip
+         dnf install curl findutils gcc-gfortran gnupg2 hostname iproute redhat-lsb-core python3 python3-pip python3-setuptools unzip python3-boto3
 
    .. tab-item:: macOS Brew
 
       .. code-block:: console
 
          brew update
-         brew install gcc git zip
+         brew install curl gcc git gnupg zip
 
 ------------
 Installation
@@ -60,15 +61,10 @@ Getting Spack is easy.  You can clone it from the `github repository
 
 .. code-block:: console
 
-   $ git clone -c feature.manyFiles=true --depth=2 https://github.com/spack/spack.git
+   $ git clone -c feature.manyFiles=true https://github.com/spack/spack.git
 
 This will create a directory called ``spack``.
 
-.. note::
-   ``-c feature.manyFiles=true`` improves git's performance on repositories with 1,000+ files.
-
-   ``--depth=2`` prunes the git history to reduce the size of the Spack installation.
-
 .. _shell-support:
 
 ^^^^^^^^^^^^^
@@ -147,22 +143,20 @@ The first time you concretize a spec, Spack will bootstrap automatically:
    --------------------------------
    zlib@1.2.13%gcc@9.4.0+optimize+pic+shared build_system=makefile arch=linux-ubuntu20.04-icelake
 
-The default bootstrap behavior is to use pre-built binaries. You can verify the
-active bootstrap repositories with:
-
-.. command-output:: spack bootstrap list
-
 If for security concerns you cannot bootstrap ``clingo`` from pre-built
 binaries, you have to disable fetching the binaries we generated with Github Actions.
 
 .. code-block:: console
 
-   $ spack bootstrap disable github-actions-v0.6
+   $ spack bootstrap disable github-actions-v0.4
-   ==> "github-actions-v0.6" is now disabled and will not be used for bootstrapping
+   ==> "github-actions-v0.4" is now disabled and will not be used for bootstrapping
-   $ spack bootstrap disable github-actions-v0.5
+   $ spack bootstrap disable github-actions-v0.3
-   ==> "github-actions-v0.5" is now disabled and will not be used for bootstrapping
+   ==> "github-actions-v0.3" is now disabled and will not be used for bootstrapping
+
+You can verify that the new settings are effective with:
+
+.. command-output:: spack bootstrap list
 
-You can verify that the new settings are effective with ``spack bootstrap list``.
 
 .. note::
 
@@ -254,11 +248,12 @@ directory.
 Compiler configuration
 ----------------------
 
-Spack has the ability to build packages with multiple compilers and compiler versions.
+Spack has the ability to build packages with multiple compilers and
-Compilers can be made available to Spack by specifying them manually in ``packages.yaml``,
+compiler versions. Compilers can be made available to Spack by
-or automatically by running ``spack compiler find``.
+specifying them manually in ``compilers.yaml`` or ``packages.yaml``,
-For convenience, Spack will automatically detect compilers the first time it needs them,
+or automatically by running ``spack compiler find``, but for
-if none is available.
+convenience Spack will automatically detect compilers the first time
+it needs them.
 
 .. _cmd-spack-compilers:
 
@@ -273,11 +268,20 @@ compilers`` or ``spack compiler list``:
 
    $ spack compilers
    ==> Available compilers
-   -- gcc ubuntu20.04-x86_64 ---------------------------------------
+   -- gcc ---------------------------------------------------------
-   gcc@9.4.0  gcc@8.4.0  gcc@10.5.0
+       gcc@4.9.0  gcc@4.8.0  gcc@4.7.0  gcc@4.6.2  gcc@4.4.7
-
+       gcc@4.8.2  gcc@4.7.1  gcc@4.6.3  gcc@4.6.1  gcc@4.1.2
-   -- llvm ubuntu20.04-x86_64 --------------------------------------
+   -- intel -------------------------------------------------------
-   llvm@12.0.0  llvm@11.0.0  llvm@10.0.0
+       intel@15.0.0  intel@14.0.0  intel@13.0.0  intel@12.1.0  intel@10.0
+       intel@14.0.3  intel@13.1.1  intel@12.1.5  intel@12.0.4  intel@9.1
+       intel@14.0.2  intel@13.1.0  intel@12.1.3  intel@11.1
+       intel@14.0.1  intel@13.0.1  intel@12.1.2  intel@10.1
+   -- clang -------------------------------------------------------
+       clang@3.4  clang@3.3  clang@3.2  clang@3.1
+   -- pgi ---------------------------------------------------------
+       pgi@14.3-0   pgi@13.2-0  pgi@12.1-0   pgi@10.9-0  pgi@8.0-1
+       pgi@13.10-0  pgi@13.1-1  pgi@11.10-0  pgi@10.2-0  pgi@7.1-3
+       pgi@13.6-0   pgi@12.8-0  pgi@11.1-0   pgi@9.0-4   pgi@7.0-6
 
 Any of these compilers can be used to build Spack packages.  More on
 how this is done is in :ref:`sec-specs`.
@@ -296,22 +300,16 @@ An alias for ``spack compiler find``.
 ``spack compiler find``
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-If you do not see a compiler in the list shown by:
+Lists the compilers currently available to Spack. If you do not see
+a compiler in this list, but you want to use it with Spack, you can
+simply run ``spack compiler find`` with the path to where the
+compiler is installed.  For example:
 
 .. code-block:: console
 
-   $ spack compiler list
+   $ spack compiler find /usr/local/tools/ic-13.0.079
-
+   ==> Added 1 new compiler to ~/.spack/linux/compilers.yaml
-but you want to use it with Spack, you can simply run ``spack compiler find`` with the
+       intel@13.0.079
-path to where the compiler is installed.  For example:
-
-.. code-block:: console
-
-   $ spack compiler find /opt/intel/oneapi/compiler/2025.1/bin/
-   ==> Added 1 new compiler to /home/user/.spack/packages.yaml
-       intel-oneapi-compilers@2025.1.0
-   ==> Compilers are defined in the following files:
-       /home/user/.spack/packages.yaml
 
 Or you can run ``spack compiler find`` with no arguments to force
 auto-detection.  This is useful if you do not know where compilers are
@@ -322,7 +320,7 @@ installed, but you know that new compilers have been added to your
 
    $ module load gcc/4.9.0
    $ spack compiler find
-   ==> Added 1 new compiler to /home/user/.spack/packages.yaml
+   ==> Added 1 new compiler to ~/.spack/linux/compilers.yaml
        gcc@4.9.0
 
 This loads the environment module for gcc-4.9.0 to add it to
@@ -331,7 +329,7 @@ This loads the environment module for gcc-4.9.0 to add it to
 .. note::
 
    By default, spack does not fill in the ``modules:`` field in the
-   ``packages.yaml`` file.  If you are using a compiler from a
+   ``compilers.yaml`` file.  If you are using a compiler from a
    module, then you should add this field manually.
    See the section on :ref:`compilers-requiring-modules`.
 
@@ -341,82 +339,91 @@ This loads the environment module for gcc-4.9.0 to add it to
 ``spack compiler info``
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-If you want to see additional information on some specific compilers, you can run ``spack compiler info`` on it:
+If you want to see specifics on a particular compiler, you can run
+``spack compiler info`` on it:
 
 .. code-block:: console
 
-   $ spack compiler info gcc
+   $ spack compiler info intel@15
-   gcc@=8.4.0 languages='c,c++,fortran' arch=linux-ubuntu20.04-x86_64:
+   intel@15.0.0:
-     prefix: /usr
+     paths:
-     compilers:
+       cc  = /usr/local/bin/icc-15.0.090
-       c: /usr/bin/gcc-8
+       cxx = /usr/local/bin/icpc-15.0.090
-       cxx: /usr/bin/g++-8
+       f77 = /usr/local/bin/ifort-15.0.090
-       fortran: /usr/bin/gfortran-8
+       fc  = /usr/local/bin/ifort-15.0.090
+     modules = []
+     operating_system = centos6
+   ...
 
-   gcc@=9.4.0 languages='c,c++,fortran' arch=linux-ubuntu20.04-x86_64:
+This shows which C, C++, and Fortran compilers were detected by Spack.
-     prefix: /usr
+Notice also that we didn't have to be too specific about the
-     compilers:
+version. We just said ``intel@15``, and information about the only
-       c: /usr/bin/gcc
+matching Intel compiler was displayed.
-       cxx: /usr/bin/g++
-       fortran: /usr/bin/gfortran
-
-   gcc@=10.5.0 languages='c,c++,fortran' arch=linux-ubuntu20.04-x86_64:
-     prefix: /usr
-     compilers:
-       c: /usr/bin/gcc-10
-       cxx: /usr/bin/g++-10
-       fortran: /usr/bin/gfortran-10
-
-This shows the details of the compilers that were detected by Spack.
-Notice also that we didn't have to be too specific about the version. We just said ``gcc``, and we got information
-about all the matching compilers.
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Manual compiler configuration
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If auto-detection fails, you can manually configure a compiler by editing your ``~/.spack/packages.yaml`` file.
+If auto-detection fails, you can manually configure a compiler by
-You can do this by running ``spack config edit packages``, which will open the file in
+editing your ``~/.spack/<platform>/compilers.yaml`` file.  You can do this by running
+``spack config edit compilers``, which will open the file in
 :ref:`your favorite editor <controlling-the-editor>`.
 
-Each compiler has an "external" entry in the file with some ``extra_attributes``:
+Each compiler configuration in the file looks like this:
 
 .. code-block:: yaml
 
-   packages:
-     gcc:
-       externals:
-       - spec: gcc@10.5.0 languages='c,c++,fortran'
-         prefix: /usr
-         extra_attributes:
    compilers:
-             c: /usr/bin/gcc-10
+   - compiler:
-             cxx: /usr/bin/g++-10
+       modules: []
-             fortran: /usr/bin/gfortran-10
+       operating_system: centos6
+       paths:
+         cc: /usr/local/bin/icc-15.0.024-beta
+         cxx: /usr/local/bin/icpc-15.0.024-beta
+         f77: /usr/local/bin/ifort-15.0.024-beta
+         fc: /usr/local/bin/ifort-15.0.024-beta
+       spec: intel@15.0.0
 
-The compiler executables are listed under ``extra_attributes:compilers``, and are keyed by language.
+For compilers that do not support Fortran (like ``clang``), put
-Once you save the file, the configured compilers will show up in the list displayed by ``spack compilers``.
+``None`` for ``f77`` and ``fc``:
 
-You can also add compiler flags to manually configured compilers. These flags should be specified in the
+.. code-block:: yaml
-``flags`` section of the compiler specification. The valid flags are ``cflags``, ``cxxflags``, ``fflags``,
+
+   compilers:
+   - compiler:
+       modules: []
+       operating_system: centos6
+       paths:
+         cc: /usr/bin/clang
+         cxx: /usr/bin/clang++
+         f77: None
+         fc: None
+       spec: clang@3.3svn
+
+Once you save the file, the configured compilers will show up in the
+list displayed by ``spack compilers``.
+
+You can also add compiler flags to manually configured compilers. These
+flags should be specified in the ``flags`` section of the compiler
+specification. The valid flags are ``cflags``, ``cxxflags``, ``fflags``,
 ``cppflags``, ``ldflags``, and ``ldlibs``. For example:
 
 .. code-block:: yaml
 
-   packages:
-     gcc:
-       externals:
-       - spec: gcc@10.5.0 languages='c,c++,fortran'
-         prefix: /usr
-         extra_attributes:
    compilers:
-             c: /usr/bin/gcc-10
+   - compiler:
-             cxx: /usr/bin/g++-10
+       modules: []
-             fortran: /usr/bin/gfortran-10
+       operating_system: centos6
+       paths:
+         cc: /usr/bin/gcc
+         cxx: /usr/bin/g++
+         f77: /usr/bin/gfortran
+         fc: /usr/bin/gfortran
        flags:
          cflags: -O3 -fPIC
          cxxflags: -O3 -fPIC
          cppflags: -O3 -fPIC
+       spec: gcc@4.7.2
 
 These flags will be treated by spack as if they were entered from
 the command line each time this compiler is used. The compiler wrappers
@@ -433,16 +440,16 @@ specification. The operations available to modify the environment are ``set``, `
 
 .. code-block:: yaml
 
-   packages:
-     intel-oneapi-compilers:
-       externals:
-       - spec: intel-oneapi-compilers@2025.1.0
-         prefix: /opt/intel/oneapi
-         extra_attributes:
    compilers:
-             c: /opt/intel/oneapi/compiler/2025.1/bin/icx
+   - compiler:
-             cxx: /opt/intel/oneapi/compiler/2025.1/bin/icpx
+       modules: []
-             fortran: /opt/intel/oneapi/compiler/2025.1/bin/ifx
+       operating_system: centos6
+       paths:
+         cc: /opt/intel/oneapi/compiler/latest/linux/bin/icx
+         cxx: /opt/intel/oneapi/compiler/latest/linux/bin/icpx
+         f77: /opt/intel/oneapi/compiler/latest/linux/bin/ifx
+         fc: /opt/intel/oneapi/compiler/latest/linux/bin/ifx
+       spec: oneapi@latest
        environment:
          set:
            MKL_ROOT: "/path/to/mkl/root"
@@ -451,24 +458,75 @@ 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.
+
+Note that the format for the ``paths`` field in the
+``extra_attributes`` section is different than in the ``compilers``
+config. For compilers configured as external packages, the section is
+named ``compilers`` and the dictionary maps language names (``c``,
+``cxx``, ``fortran``) to paths, rather than using the names ``cc``,
+``fc``, and ``f77``.
+
+.. 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:
+           compilers:
+             c: /usr/bin/clang-with-suffix
+             cxx: /usr/bin/clang++-with-extra-info
+             fortran: /usr/bin/gfortran
+           extra_rpaths:
+           - /usr/lib/llvm/
+
 ^^^^^^^^^^^^^^^^^^^^^^^
 Build Your Own Compiler
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-If you are particular about which compiler/version you use, you might wish to have Spack build it for you.
+If you are particular about which compiler/version you use, you might
-For example:
+wish to have Spack build it for you.  For example:
 
 .. code-block:: console
 
-   $ spack install gcc@14+binutils
+   $ spack install gcc@4.9.3
 
-Once the compiler is installed, you can start using it without additional configuration:
+Once that has finished, you will need to add it to your
+``compilers.yaml`` file.  You can then set Spack to use it by default
+by adding the following to your ``packages.yaml`` file:
 
-.. code-block:: console
+.. code-block:: yaml
 
-   $ spack install hdf5~mpi %gcc@14
+   packages:
-
+     all:
-The same holds true for compilers that are made available from buildcaches, when reusing them is allowed.
+       compiler: [gcc@4.9.3]
 
 .. _compilers-requiring-modules:
 
@@ -476,26 +534,30 @@ The same holds true for compilers that are made available from buildcaches, when
 Compilers Requiring Modules
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Many installed compilers will work regardless of the environment they are called with.
+Many installed compilers will work regardless of the environment they
-However, some installed compilers require environment variables to be set in order to run;
+are called with.  However, some installed compilers require
-this is typical for Intel and other proprietary compilers.
+``$LD_LIBRARY_PATH`` or other environment variables to be set in order
+to run; this is typical for Intel and other proprietary compilers.
 
-On typical HPC clusters, these environment modifications are usually delegated to some "module" system.
+In such a case, you should tell Spack which module(s) to load in order
-In such a case, you should tell Spack which module(s) to load in order to run the chosen compiler:
+to run the chosen compiler (If the compiler does not come with a
+module file, you might consider making one by hand).  Spack will load
+this module into the environment ONLY when the compiler is run, and
+NOT in general for a package's ``install()`` method.  See, for
+example, this ``compilers.yaml`` file:
 
 .. code-block:: yaml
 
-   packages:
-     gcc:
-       externals:
-       - spec: gcc@10.5.0 languages='c,c++,fortran'
-         prefix: /opt/compilers
-         extra_attributes:
    compilers:
-             c: /opt/compilers/bin/gcc-10
+   - compiler:
-             cxx: /opt/compilers/bin/g++-10
+       modules: [other/comp/gcc-5.3-sp3]
-             fortran: /opt/compilers/bin/gfortran-10
+       operating_system: SuSE11
-         modules: [gcc/10.5.0]
+       paths:
+         cc: /usr/local/other/SLES11.3/gcc/5.3.0/bin/gcc
+         cxx: /usr/local/other/SLES11.3/gcc/5.3.0/bin/g++
+         f77: /usr/local/other/SLES11.3/gcc/5.3.0/bin/gfortran
+         fc: /usr/local/other/SLES11.3/gcc/5.3.0/bin/gfortran
+       spec: gcc@5.3.0
 
 Some compilers require special environment settings to be loaded not just
 to run, but also to execute the code they build, breaking packages that
@@ -516,7 +578,7 @@ Licensed Compilers
 ^^^^^^^^^^^^^^^^^^
 
 Some proprietary compilers require licensing to use.  If you need to
-use a licensed compiler, the process is similar to a mix of
+use a licensed compiler (eg, PGI), the process is similar to a mix of
 build your own, plus modules:
 
 #. Create a Spack package (if it doesn't exist already) to install
@@ -526,21 +588,24 @@ build your own, plus modules:
    using Spack to load the module it just created, and running simple
    builds (eg: ``cc helloWorld.c && ./a.out``)
 
-#. Add the newly-installed compiler to ``packages.yaml`` as shown above.
+#. Add the newly-installed compiler to ``compilers.yaml`` as shown
+   above.
 
 .. _mixed-toolchains:
 
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^
-Fortran compilers on macOS
+Mixed Toolchains
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^
 
 Modern compilers typically come with related compilers for C, C++ and
 Fortran bundled together.  When possible, results are best if the same
 compiler is used for all languages.
 
-In some cases, this is not possible.  For example, XCode on macOS provides no Fortran compilers.
+In some cases, this is not possible.  For example, starting with macOS El
-The user is therefore forced to use a mixed toolchain: XCode-provided Clang for C/C++ and e.g.
+Capitan (10.11), many packages no longer build with GCC, but XCode
-GNU ``gfortran`` for Fortran.
+provides no Fortran compilers.  The user is therefore forced to use a
+mixed toolchain: XCode-provided Clang for C/C++ and GNU ``gfortran`` for
+Fortran.
 
 #. You need to make sure that Xcode is installed. Run the following command:
 
@@ -593,25 +658,45 @@ GNU ``gfortran`` for Fortran.
 
    Note: the flag is ``-license``, not ``--license``.
 
+#. Run ``spack compiler find`` to locate Clang.
+
 #. There are different ways to get ``gfortran`` on macOS. For example, you can
    install GCC with Spack (``spack install gcc``), with Homebrew (``brew install
    gcc``), or from a `DMG installer
    <https://github.com/fxcoudert/gfortran-for-macOS/releases>`_.
 
-#. Run ``spack compiler find`` to locate both Apple-Clang and GCC.
+#. The only thing left to do is to edit ``~/.spack/darwin/compilers.yaml`` to provide
+   the path to ``gfortran``:
 
-Since languages in Spack are modeled as virtual packages, ``apple-clang`` will be used to provide
+   .. code-block:: yaml
-C and C++, while GCC will be used for Fortran.
+
+      compilers:
+      - compiler:
+        # ...
+        paths:
+          cc: /usr/bin/clang
+          cxx: /usr/bin/clang++
+          f77: /path/to/bin/gfortran
+          fc: /path/to/bin/gfortran
+        spec: apple-clang@11.0.0
+
+
+   If you used Spack to install GCC, you can get the installation prefix by
+   ``spack location -i gcc`` (this will only work if you have a single version
+   of GCC installed). Whereas for Homebrew, GCC is installed in
+   ``/usr/local/Cellar/gcc/x.y.z``. With the DMG installer, the correct path
+   will be ``/usr/local/gfortran``.
 
 ^^^^^^^^^^^^^^^^^^^^^
 Compiler Verification
 ^^^^^^^^^^^^^^^^^^^^^
 
-You can verify that your compilers are configured properly by installing a simple package. For example:
+You can verify that your compilers are configured properly by installing a
+simple package.  For example:
 
 .. code-block:: console
 
-   $ spack install zlib-ng%gcc@5.3.0
+   $ spack install zlib%gcc@5.3.0
 
 
 .. _vendor-specific-compiler-configuration:
@@ -620,7 +705,9 @@ You can verify that your compilers are configured properly by installing a simpl
 Vendor-Specific Compiler Configuration
 --------------------------------------
 
-This section provides details on how to get vendor-specific compilers working.
+With Spack, things usually "just work" with GCC.  Not so for other
+compilers.  This section provides details on how to get specific
+compilers working.
 
 ^^^^^^^^^^^^^^^
 Intel Compilers
@@ -642,8 +729,8 @@ compilers:
       you have installed from the ``PATH`` environment variable.
 
       If you want use a version of ``gcc`` or ``g++`` other than the default
-      version on your system, you need to use either the ``--gcc-install-dir``
+      version on your system, you need to use either the ``-gcc-name``
-      or ``--gcc-toolchain`` compiler option to specify the path to the version of
+      or ``-gxx-name`` compiler option to specify the path to the version of
       ``gcc`` or ``g++`` that you want to use."
 
       -- `Intel Reference Guide <https://software.intel.com/en-us/node/522750>`_
@@ -651,12 +738,135 @@ compilers:
 Intel compilers may therefore be configured in one of two ways with
 Spack: using modules, or using compiler flags.
 
+""""""""""""""""""""""""""
+Configuration with Modules
+""""""""""""""""""""""""""
+
+One can control which GCC is seen by the Intel compiler with modules.
+A module must be loaded both for the Intel Compiler (so it will run)
+and GCC (so the compiler can find the intended GCC).  The following
+configuration in ``compilers.yaml`` illustrates this technique:
+
+.. code-block:: yaml
+
+   compilers:
+   - compiler:
+       modules: [gcc-4.9.3, intel-15.0.24]
+       operating_system: centos7
+       paths:
+         cc: /opt/intel-15.0.24/bin/icc-15.0.24-beta
+         cxx: /opt/intel-15.0.24/bin/icpc-15.0.24-beta
+         f77: /opt/intel-15.0.24/bin/ifort-15.0.24-beta
+         fc: /opt/intel-15.0.24/bin/ifort-15.0.24-beta
+       spec: intel@15.0.24.4.9.3
+
+
+.. note::
+
+   The version number on the Intel compiler is a combination of
+   the "native" Intel version number and the GNU compiler it is
+   targeting.
+
+""""""""""""""""""""""""""
+Command Line Configuration
+""""""""""""""""""""""""""
+
+One can also control which GCC is seen by the Intel compiler by adding
+flags to the ``icc`` command:
+
+#. Identify the location of the compiler you just installed:
+
+   .. code-block:: console
+
+       $ spack location --install-dir gcc
+       ~/spack/opt/spack/linux-centos7-x86_64/gcc-4.9.3-iy4rw...
+
+#. Set up ``compilers.yaml``, for example:
+
+   .. code-block:: yaml
+
+       compilers:
+       - compiler:
+           modules: [intel-15.0.24]
+           operating_system: centos7
+           paths:
+             cc: /opt/intel-15.0.24/bin/icc-15.0.24-beta
+             cxx: /opt/intel-15.0.24/bin/icpc-15.0.24-beta
+             f77: /opt/intel-15.0.24/bin/ifort-15.0.24-beta
+             fc: /opt/intel-15.0.24/bin/ifort-15.0.24-beta
+           flags:
+             cflags: -gcc-name ~/spack/opt/spack/linux-centos7-x86_64/gcc-4.9.3-iy4rw.../bin/gcc
+             cxxflags: -gxx-name ~/spack/opt/spack/linux-centos7-x86_64/gcc-4.9.3-iy4rw.../bin/g++
+             fflags: -gcc-name ~/spack/opt/spack/linux-centos7-x86_64/gcc-4.9.3-iy4rw.../bin/gcc
+           spec: intel@15.0.24.4.9.3
+
+
+^^^
+PGI
+^^^
+
+PGI comes with two sets of compilers for C++ and Fortran,
+distinguishable by their names.  "Old" compilers:
+
+.. code-block:: yaml
+
+    cc:  /soft/pgi/15.10/linux86-64/15.10/bin/pgcc
+    cxx: /soft/pgi/15.10/linux86-64/15.10/bin/pgCC
+    f77: /soft/pgi/15.10/linux86-64/15.10/bin/pgf77
+    fc:  /soft/pgi/15.10/linux86-64/15.10/bin/pgf90
+
+"New" compilers:
+
+.. code-block:: yaml
+
+    cc:  /soft/pgi/15.10/linux86-64/15.10/bin/pgcc
+    cxx: /soft/pgi/15.10/linux86-64/15.10/bin/pgc++
+    f77: /soft/pgi/15.10/linux86-64/15.10/bin/pgfortran
+    fc:  /soft/pgi/15.10/linux86-64/15.10/bin/pgfortran
+
+Older installations of PGI contains just the old compilers; whereas
+newer installations contain the old and the new.  The new compiler is
+considered preferable, as some packages
+(``hdf``) will not build with the old compiler.
+
+When auto-detecting a PGI compiler, there are cases where Spack will
+find the old compilers, when you really want it to find the new
+compilers.  It is best to check this ``compilers.yaml``; and if the old
+compilers are being used, change ``pgf77`` and ``pgf90`` to
+``pgfortran``.
+
+Other issues:
+
+* There are reports that some packages will not build with PGI,
+  including ``libpciaccess`` and ``openssl``.  A workaround is to
+  build these packages with another compiler and then use them as
+  dependencies for PGI-build packages.  For example:
+
+  .. code-block:: console
+
+     $ spack install openmpi%pgi ^libpciaccess%gcc
+
+
+* PGI requires a license to use; see :ref:`licensed-compilers` for more
+  information on installation.
+
+.. note::
+
+   It is believed the problem with HDF 4 is that everything is
+   compiled with the ``F77`` compiler, but at some point some Fortran
+   90 code slipped in there. So compilers that can handle both FORTRAN
+   77 and Fortran 90 (``gfortran``, ``pgfortran``, etc) are fine.  But
+   compilers specific to one or the other (``pgf77``, ``pgf90``) won't
+   work.
+
+
 ^^^
 NAG
 ^^^
 
-The Numerical Algorithms Group provides a licensed Fortran compiler.
+The Numerical Algorithms Group provides a licensed Fortran compiler. Like Clang,
-It is recommended to use GCC for your C/C++ compilers.
+this requires you to set up a :ref:`mixed-toolchains`. It is recommended to use
+GCC for your C/C++ compilers.
 
 The NAG Fortran compilers are a bit more strict than other compilers, and many
 packages will fail to install with error messages like:
@@ -673,40 +883,44 @@ the command line:
 
    $ spack install openmpi fflags="-mismatch"
 
-Or it can be set permanently in your ``packages.yaml``:
+Or it can be set permanently in your ``compilers.yaml``:
 
 .. code-block:: yaml
 
-   packages:
+   - compiler:
-     nag:
+    modules: []
-       externals:
+    operating_system: centos6
-       - spec: nag@6.1
+    paths:
-         prefix: /opt/nag/bin
+      cc: /soft/spack/opt/spack/linux-x86_64/gcc-5.3.0/gcc-6.1.0-q2zosj3igepi3pjnqt74bwazmptr5gpj/bin/gcc
-         extra_attributes:
+      cxx: /soft/spack/opt/spack/linux-x86_64/gcc-5.3.0/gcc-6.1.0-q2zosj3igepi3pjnqt74bwazmptr5gpj/bin/g++
-           compilers:
+      f77: /soft/spack/opt/spack/linux-x86_64/gcc-4.4.7/nag-6.1-jt3h5hwt5myezgqguhfsan52zcskqene/bin/nagfor
-             fortran: /opt/nag/bin/nagfor
+      fc: /soft/spack/opt/spack/linux-x86_64/gcc-4.4.7/nag-6.1-jt3h5hwt5myezgqguhfsan52zcskqene/bin/nagfor
     flags:
       fflags: -mismatch
+    spec: nag@6.1
+
 
 ---------------
 System Packages
 ---------------
 
-Once compilers are configured, one needs to determine which pre-installed system packages,
+Once compilers are configured, one needs to determine which
-if any, to use in builds.  These are also configured in the ``~/.spack/packages.yaml`` file.
+pre-installed system packages, if any, to use in builds.  This is
-For example, to use an OpenMPI installed in /opt/local, one would use:
+configured in the file ``~/.spack/packages.yaml``.  For example, to use
+an OpenMPI installed in /opt/local, one would use:
 
 .. code-block:: yaml
 
     packages:
         openmpi:
-       buildable: False
             externals:
             - spec: openmpi@1.10.1
               prefix: /opt/local
+            buildable: False
 
-In general, *Spack is easier to use and more reliable if it builds all of its own dependencies*.
+In general, Spack is easier to use and more reliable if it builds all of
-However, there are several packages for which one commonly needs to use system versions:
+its own dependencies.  However, there are several packages for which one
+commonly needs to use system versions:
 
 ^^^
 MPI
@@ -719,7 +933,8 @@ you are unlikely to get a working MPI from Spack.  Instead, use an
 appropriate pre-installed MPI.
 
 If you choose a pre-installed MPI, you should consider using the
-pre-installed compiler used to build that MPI.
+pre-installed compiler used to build that MPI; see above on
+``compilers.yaml``.
 
 ^^^^^^^
 OpenSSL
@@ -1169,7 +1384,6 @@ Required:
 * Microsoft Visual Studio
 * Python
 * Git
-* 7z
 
 Optional:
 * Intel Fortran (needed for some packages)
@@ -1235,13 +1449,6 @@ as the project providing Git support on Windows. This is additionally the recomm
 for installing Git on Windows, a link to which can be found above. Spack requires the
 utilities vendored by this project.
 
-"""
-7zip
-"""
-
-A tool for extracting ``.xz`` files is required for extracting source tarballs. The latest 7zip
-can be located at https://sourceforge.net/projects/sevenzip/.
-
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Step 2: Install and setup Spack
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -1268,14 +1475,16 @@ in a Windows CMD prompt.
 Step 3: Run and configure Spack
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-On Windows, Spack supports both primary native shells, Powershell and the traditional command prompt.
+To use Spack, run ``bin\spack_cmd.bat`` (you may need to Run as Administrator) from the top-level spack
-To use Spack, pick your favorite shell, and run ``bin\spack_cmd.bat`` or ``share/spack/setup-env.ps1``
+directory. This will provide a Windows command prompt with an environment properly set up with Spack
-(you may need to Run as Administrator) from the top-level spack
+and its prerequisites. If you receive a warning message that Python is not in your ``PATH``
-directory. This will provide a Spack enabled shell. If you receive a warning message that Python is not in your ``PATH``
 (which may happen if you installed Python from the website and not the Windows Store) add the location
 of the Python executable to your ``PATH`` now. You can permanently add Python to your ``PATH`` variable
 by using the ``Edit the system environment variables`` utility in Windows Control Panel.
 
+.. note::
+   Alternatively, Powershell can be used in place of CMD
+
 To configure Spack, first run the following command inside the Spack console:
 
 .. code-block:: console
@@ -1283,9 +1492,9 @@ To configure Spack, first run the following command inside the Spack console:
    spack compiler find
 
 This creates a ``.staging`` directory in our Spack prefix, along with a ``windows`` subdirectory
-containing a ``packages.yaml`` file. On a fresh Windows install with the above packages
+containing a ``compilers.yaml`` file. On a fresh Windows install with the above packages
 installed, this command should only detect Microsoft Visual Studio and the Intel Fortran
-compiler will be integrated within the first version of MSVC present in the ``packages.yaml``
+compiler will be integrated within the first version of MSVC present in the ``compilers.yaml``
 output.
 
 Spack provides a default ``config.yaml`` file for Windows that it will use unless overridden.
@@ -1340,7 +1549,7 @@ and not tabs, so ensure that this is the case when editing one directly.
 
 .. note:: Cygwin
    The use of Cygwin is not officially supported by Spack and is not tested.
-   However Spack will not prevent this, so use if choosing to use Spack
+   However Spack will not throw an error, so use if choosing to use Spack
    with Cygwin, know that no functionality is garunteed.
 
 ^^^^^^^^^^^^^^^^^
@@ -1354,12 +1563,21 @@ Spack console via:
 
    spack install cpuinfo
 
-If in the previous step, you did not have CMake or Ninja installed, running the command above should install both packages
+If in the previous step, you did not have CMake or Ninja installed, running the command above should bootstrap both packages
 
-.. note:: Spec Syntax Caveats
+"""""""""""""""""""""""""""
-   Windows has a few idiosyncrasies when it comes to the Spack spec syntax and the use of certain shells
+Windows Compatible Packages
-   See the Spack spec syntax doc for more information
+"""""""""""""""""""""""""""
 
+Not all spack packages currently have Windows support. Some are inherently incompatible with the
+platform, and others simply have yet to be ported. To view the current set of packages with Windows
+support, the list command should be used via `spack list -t windows`. If there's a package you'd like
+to install on Windows but is not in that list, feel free to reach out to request the port or contribute
+the port yourself.
+
+.. note::
+   This is by no means a comprehensive list, some packages may have ports that were not tagged
+   while others may just work out of the box on Windows and have not been tagged as such.
 
 ^^^^^^^^^^^^^^
 For developers
@@ -1369,3 +1587,6 @@ The intent is to provide a Windows installer that will automatically set up
 Python, Git, and Spack, instead of requiring the user to do so manually.
 Instructions for creating the installer are at
 https://github.com/spack/spack/blob/develop/lib/spack/spack/cmd/installer/README.md
+
+Alternatively a pre-built copy of the Windows installer is available as an artifact of Spack's Windows CI
+available at each run of the CI on develop or any PR.

lib/spack/docs/gpu_configuration.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 
@@ -23,6 +24,7 @@ components for use by dependent packages:
 
    packages:
      all:
+       compiler: [rocmcc@=5.3.0]
        variants: amdgpu_target=gfx90a
      hip:
        buildable: false
@@ -69,15 +71,16 @@ This is in combination with the following compiler definition:
 
 .. code-block:: yaml
 
-   packages:
-     llvm-amdgpu:
-       externals:
-       - spec: llvm-amdgpu@=5.3.0
-         prefix: /opt/rocm-5.3.0
    compilers:
-           c: /opt/rocm-5.3.0/bin/amdclang
+   - compiler:
+       spec: rocmcc@=5.3.0
+       paths:
+         cc: /opt/rocm-5.3.0/bin/amdclang
          cxx: /opt/rocm-5.3.0/bin/amdclang++
-           fortran: null
+         f77: null
+         fc: /opt/rocm-5.3.0/bin/amdflang
+       operating_system: rhel8
+       target: x86_64
 
 This includes the following considerations:
 

lib/spack/docs/include_yaml.rst

@@ -1,65 +0,0 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
-
-   SPDX-License-Identifier: (Apache-2.0 OR MIT)
-
-.. _include-yaml:
-
-===============================
-Include Settings (include.yaml)
-===============================
-
-Spack allows you to include configuration files through ``include.yaml``.
-Using the ``include:`` heading results in pulling in external configuration
-information to be used by any Spack command.
-
-Included configuration files are required *unless* they are explicitly optional
-or the entry's condition evaluates to ``false``. Optional includes are specified
-with the ``optional`` clause and conditional with the ``when`` clause. For
-example,
-
-.. code-block:: yaml
-
-   include:
-   - /path/to/a/required/config.yaml
-   - path: /path/to/$os/$target/config
-     optional: true
-   - path: /path/to/os-specific/config-dir
-     when: os == "ventura"
-
-shows all three. The first entry, ``/path/to/a/required/config.yaml``,
-indicates that included ``config.yaml`` file is required (so must exist).
-Use of ``optional: true`` for ``/path/to/$os/$target/config`` means
-the path is only included if it exists. The condition ``os == "ventura"``
-in the ``when`` clause for ``/path/to/os-specific/config-dir`` means the
-path is only included when the operating system (``os``) is ``ventura``.
-
-The same conditions and variables in `Spec List References 
-<https://spack.readthedocs.io/en/latest/environments.html#spec-list-references>`_
-can be used for conditional activation in the ``when`` clauses.
-
-Included files can be specified by path or by their parent directory.
-Paths may be absolute, relative (to the configuration file including the path), 
-or specified as URLs. Only the ``file``, ``ftp``, ``http`` and ``https`` protocols (or
-schemes) are supported. Spack-specific, environment and user path variables
-can be used. (See :ref:`config-file-variables` for more information.)
-
-A ``sha256`` is required for remote file URLs and must be specified as follows:
-
-.. code-block:: yaml
-
-   include:
-   - path: https://github.com/path/to/raw/config/compilers.yaml
-     sha256: 26e871804a92cd07bb3d611b31b4156ae93d35b6a6d6e0ef3a67871fcb1d258b
-
-Additionally, remote file URLs must link to the **raw** form of the file's
-contents (e.g., `GitHub
-<https://docs.github.com/en/repositories/working-with-files/using-files/viewing-and-understanding-files#viewing-or-copying-the-raw-file-content>`_
-or `GitLab
-<https://docs.gitlab.com/ee/api/repository_files.html#get-raw-file-from-repository>`_).
-
-.. warning::
-
-   Recursive includes are not currently processed in a breadth-first manner
-   so the value of a configuration option that is altered by multiple included
-   files may not be what you expect. This will be addressed in a future
-   update.

lib/spack/docs/index.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 
@@ -11,6 +12,10 @@
 Spack
 ===================
 
+.. epigraph::
+
+   `These are docs for the Spack package manager. For sphere packing, see` `pyspack <https://pyspack.readthedocs.io>`_.
+
 Spack is a package management tool designed to support multiple
 versions and configurations of software on a wide variety of platforms
 and environments.  It was designed for large supercomputing centers,
@@ -34,15 +39,10 @@ package:
 
 .. code-block:: console
 
-   $ git clone -c feature.manyFiles=true --depth=2 https://github.com/spack/spack.git
+   $ git clone -c feature.manyFiles=true https://github.com/spack/spack.git
    $ cd spack/bin
    $ ./spack install libelf
 
-.. note::
-   ``-c feature.manyFiles=true`` improves git's performance on repositories with 1,000+ files.
-
-   ``--depth=2`` prunes the git history to reduce the size of the Spack installation.
-
 If you're new to spack and want to start using it, see :doc:`getting_started`,
 or refer to the full manual below.
 
@@ -71,7 +71,6 @@ or refer to the full manual below.
 
    configuration
    config_yaml
-   include_yaml
    packages_yaml
    build_settings
    environments

lib/spack/docs/mirrors.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 

lib/spack/docs/module_file_support.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 
@@ -456,13 +457,14 @@ For instance, the following config options,
        tcl:
          all:
            suffixes:
-             ^python@3: 'python{^python.version.up_to_2}'
+             ^python@3.12: 'python-3.12'
              ^openblas: 'openblas'
 
-will add a ``python3.12`` to module names of packages compiled with Python 3.12, and similarly for
+will add a ``python-3.12`` version string to any packages compiled with
-all specs depending on ``python@3``. This is useful to know which version of Python a set of Python
+Python matching the spec, ``python@3.12``. This is useful to know which
-extensions is associated with. Likewise, the ``openblas`` string is attached to any program that
+version of Python a set of Python extensions is associated with. Likewise, the
-has openblas in the spec, most likely via the ``+blas`` variant specification.
+``openblas`` string is attached to any program that has openblas in the spec,
+most likely via the ``+blas`` variant specification.
 
 The most heavyweight solution to module naming is to change the entire
 naming convention for module files. This uses the projections format

lib/spack/docs/packages_yaml.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 
@@ -486,8 +487,6 @@ present. For instance with a configuration like:
 
 you will use ``mvapich2~cuda %gcc`` as an ``mpi`` provider.
 
-.. _package-strong-preferences:
-
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Conflicts and strong preferences
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -557,13 +556,14 @@ preferences.
    FAQ: :ref:`Why does Spack pick particular versions and variants? <faq-concretizer-precedence>`
 
 
-The ``target`` and ``providers`` 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]

lib/spack/docs/packaging_guide.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 
@@ -236,7 +237,8 @@ for details):
 .. code-block:: python
    :linenos:
 
-   # Copyright Spack Project Developers. See COPYRIGHT file for details.
+   # 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)
 
@@ -1261,11 +1263,6 @@ Git fetching supports the following parameters to ``version``:
   option ``--depth 1`` will be used if the version of git and the specified
   transport protocol support it, and ``--single-branch`` will be used if the
   version of git supports it.
-* ``git_sparse_paths``: Use ``sparse-checkout`` to only clone these relative paths.
-  This feature requires ``git`` to be version ``2.25.0`` or later but is useful for
-  large repositories that have separate portions that can be built independently.
-  If paths provided are directories then all the subdirectories and associated files
-  will also be cloned.
 
 Only one of ``tag``, ``branch``, or ``commit`` can be used at a time.
 
@@ -1364,41 +1361,6 @@ Submodules
   For more information about git submodules see the manpage of git: ``man
   git-submodule``.
 
-Sparse-Checkout
-  You can supply ``git_sparse_paths`` at the package or version level to utilize git's
-  sparse-checkout feature. This will only clone the paths that are specified in the
-  ``git_sparse_paths`` attribute for the package along with the files in the top level directory.
-  This feature allows you to only clone what you need from a large repository.
-  Note that this is a newer feature in git and requries git ``2.25.0`` or greater.
-  If ``git_sparse_paths`` is supplied and the git version is too old
-  then a warning will be issued and that package will use the standard cloning operations instead.
-  ``git_sparse_paths`` should be supplied as a list of paths, a callable function for versions,
-  or a more complex package attribute using the ``@property`` decorator. The return value should be
-  a list for a callable implementation of ``git_sparse_paths``.
-
-  .. code-block:: python
-
-    def sparse_path_function(package)
-        """a callable function that can be used in side a version"""
-        # paths can be directories or functions, all subdirectories and files are included
-        paths = ["doe", "rae", "me/file.cpp"]
-        if package.spec.version >  Version("1.2.0"):
-            paths.extend(["fae"])
-        return paths
-
-    class MyPackage(package):
-        # can also be a package attribute that will be used if not specified in versions
-        git_sparse_paths = ["doe", "rae"]
-
-        # use the package attribute
-        version("1.0.0")
-        version("1.1.0")
-        # use the function
-        version("1.1.5", git_sparse_paths=sparse_path_func)
-        version("1.2.0", git_sparse_paths=sparse_path_func)
-        version("1.2.5", git_sparse_paths=sparse_path_func)
-        version("1.1.5", git_sparse_paths=sparse_path_func)
-
 .. _github-fetch:
 
 ^^^^^^
@@ -1926,29 +1888,71 @@ to the empty list.
 String. A URL pointing to license setup instructions for the software.
 Defaults to the empty string.
 
-For example, let's take a look at the Arm Forge package.
+For example, let's take a look at the package for the PGI compilers.
 
 .. code-block:: python
 
    # Licensing
    license_required = True
    license_comment  = "#"
-   license_files = ["licences/Licence"]
+   license_files    = ["license.dat"]
-   license_vars = [
+   license_vars     = ["PGROUPD_LICENSE_FILE", "LM_LICENSE_FILE"]
-       "ALLINEA_LICENSE_DIR",
+   license_url      = "http://www.pgroup.com/doc/pgiinstall.pdf"
-       "ALLINEA_LICENCE_DIR",
-       "ALLINEA_LICENSE_FILE",
-       "ALLINEA_LICENCE_FILE",
-   ]
-   license_url = "https://developer.arm.com/documentation/101169/latest/Use-Arm-Licence-Server"
 
-Arm Forge requires a license. Its license manager uses the ``#`` symbol to denote a comment.
+As you can see, PGI requires a license. Its license manager, FlexNet, uses
-It expects the license file to be named ``License`` and to be located in a ``licenses`` directory
+the ``#`` symbol to denote a comment. It expects the license file to be
-in the installation prefix.
+named ``license.dat`` and to be located directly in the installation prefix.
+If you would like the installation file to be located elsewhere, simply set
+``PGROUPD_LICENSE_FILE`` or ``LM_LICENSE_FILE`` after installation. For
+further instructions on installation and licensing, see the URL provided.
 
-If you would like the installation file to be located elsewhere, simply set ``ALLINEA_LICENSE_DIR`` or
+Let's walk through a sample PGI installation to see exactly what Spack is
-one of the other license variables after installation. For further instructions on installation and
+and isn't capable of. Since PGI does not provide a download URL, it must
-licensing, see the URL provided.
+be downloaded manually. It can either be added to a mirror or located in
+the current directory when ``spack install pgi`` is run. See :ref:`mirrors`
+for instructions on setting up a mirror.
+
+After running ``spack install pgi``, the first thing that will happen is
+Spack will create a global license file located at
+``$SPACK_ROOT/etc/spack/licenses/pgi/license.dat``. It will then open up the
+file using :ref:`your favorite editor <controlling-the-editor>`. It will look like
+this:
+
+.. code-block:: sh
+
+   # A license is required to use pgi.
+   #
+   # The recommended solution is to store your license key in this global
+   # license file. After installation, the following symlink(s) will be
+   # added to point to this file (relative to the installation prefix):
+   #
+   #   license.dat
+   #
+   # Alternatively, use one of the following environment variable(s):
+   #
+   #   PGROUPD_LICENSE_FILE
+   #   LM_LICENSE_FILE
+   #
+   # If you choose to store your license in a non-standard location, you may
+   # set one of these variable(s) to the full pathname to the license file, or
+   # port@host if you store your license keys on a dedicated license server.
+   # You will likely want to set this variable in a module file so that it
+   # gets loaded every time someone tries to use pgi.
+   #
+   # For further information on how to acquire a license, please refer to:
+   #
+   #   http://www.pgroup.com/doc/pgiinstall.pdf
+   #
+   # You may enter your license below.
+
+You can add your license directly to this file, or tell FlexNet to use a
+license stored on a separate license server. Here is an example that
+points to a license server called licman1:
+
+.. code-block:: none
+
+   SERVER licman1.mcs.anl.gov 00163eb7fba5 27200
+   USE_SERVER
 
 If your package requires the license to install, you can reference the
 location of this global license using ``self.global_license_file``.
@@ -2459,14 +2463,15 @@ with. For example, suppose that in the ``libdwarf`` package you write:
 
    depends_on("libelf@0.8")
 
-Now ``libdwarf`` will require ``libelf`` in the range ``0.8``, which
+Now ``libdwarf`` will require ``libelf`` at *exactly* version ``0.8``.
-includes patch versions ``0.8.1``, ``0.8.2``, etc. Apart from version
+You can also specify a requirement for a particular variant or for
-restrictions, you can also specify variants if this package requires
+specific compiler flags:
-optional features of the dependency.
 
 .. code-block:: python
 
-   depends_on("libelf@0.8 +parser +pic")
+   depends_on("libelf@0.8+debug")
+   depends_on("libelf debug=True")
+   depends_on("libelf cppflags='-fPIC'")
 
 Both users *and* package authors can use the same spec syntax to refer
 to different package configurations. Users use the spec syntax on the
@@ -2474,82 +2479,46 @@ command line to find installed packages or to install packages with
 particular constraints, and package authors can use specs to describe
 relationships between packages.
 
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^
-Specifying backward and forward compatibility
+Version ranges
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^
 
-Packages are often compatible with a range of versions of their
+Although some packages require a specific version for their dependencies,
-dependencies. This is typically referred to as backward and forward
+most can be built with a range of versions. For example, if you are
-compatibility. Spack allows you to specify this in the ``depends_on``
+writing a package for a legacy Python module that only works with Python
-directive using version ranges.
+2.4 through 2.6, this would look like:
-
-**Backwards compatibility** means that the package requires at least a
-certain version of its dependency:
 
 .. code-block:: python
 
-   depends_on("python@3.10:")
+   depends_on("python@2.4:2.6")
 
-In this case, the package requires Python 3.10 or newer.
+Version ranges in Spack are *inclusive*, so ``2.4:2.6`` means any version
-
+greater than or equal to ``2.4`` and up to and including any ``2.6.x``. If
-Commonly, packages drop support for older versions of a dependency as
+you want to specify that a package works with any version of Python 3 (or
-they release new versions. In Spack you can conveniently add every
+higher), this would look like:
-backward compatibility rule as a separate line:
 
 .. code-block:: python
 
-   # backward compatibility with Python
+   depends_on("python@3:")
-   depends_on("python@3.8:")
-   depends_on("python@3.9:", when="@1.2:")
-   depends_on("python@3.10:", when="@1.4:")
 
-This means that in general we need Python 3.8 or newer; from version
+Here we leave out the upper bound. If you want to say that a package
-1.2 onwards we need Python 3.9 or newer; from version 1.4 onwards we
+requires Python 2, you can similarly leave out the lower bound:
-need Python 3.10 or newer. Notice that it's fine to have overlapping
-ranges in the ``when`` clauses.
-
-**Forward compatibility** means that the package requires at most a
-certain version of its dependency. Forward compatibility rules are
-necessary when there are breaking changes in the dependency that the
-package cannot handle. In Spack we often add forward compatibility
-bounds only at the time a new, breaking version of a dependency is
-released. As with backward compatibility, it is typical to see a list
-of forward compatibility bounds in a package file as seperate lines:
 
 .. code-block:: python
 
-   # forward compatibility with Python
+   depends_on("python@:2")
-   depends_on("python@:3.12", when="@:1.10")
-   depends_on("python@:3.13", when="@:1.12")
 
-Notice how the ``:`` now appears before the version number both in the
+Notice that we didn't use ``@:3``. Version ranges are *inclusive*, so
-dependency and in the ``when`` clause. This tells Spack that in general
+``@:3`` means "up to and including any 3.x version".
-we need Python 3.13 or older up to version ``1.12.x``, and up to version
-``1.10.x`` we need Python 3.12 or older. Said differently, forward compatibility
-with Python 3.13 was added in version 1.11, while version 1.13 added forward
-compatibility with Python 3.14.
 
-Notice that a version range ``@:3.12`` includes *any* patch version
+You can also simply write
-number ``3.12.x``, which is often useful when specifying forward compatibility
-bounds.
-
-So far we have seen open-ended version ranges, which is by far the most
-common use case. It is also possible to specify both a lower and an upper bound
-on the version of a dependency, like this:
 
 .. code-block:: python
 
-   depends_on("python@3.10:3.12")
+   depends_on("python@2.7")
 
-There is short syntax to specify that a package is compatible with say any
+to tell Spack that the package needs Python 2.7.x. This is equivalent to
-``3.x`` version:
+``@2.7:2.7``.
-
-.. code-block:: python
-
-   depends_on("python@3")
-
-The above is equivalent to ``depends_on("python@3:3")``, which means at least
-Python version 3 and at most any version ``3.x.y``.
 
 In very rare cases, you may need to specify an exact version, for example
 if you need to distinguish between ``3.2`` and ``3.2.1``:
@@ -2923,9 +2892,9 @@ make sense during the build phase may not be needed at runtime, and vice versa.
 it makes sense to let a dependency set the environment variables for its dependents. To allow all
 this, Spack provides four different methods that can be overridden in a package:
 
-1. :meth:`setup_build_environment <spack.builder.BaseBuilder.setup_build_environment>`
+1. :meth:`setup_build_environment <spack.builder.Builder.setup_build_environment>`
 2. :meth:`setup_run_environment <spack.package_base.PackageBase.setup_run_environment>`
-3. :meth:`setup_dependent_build_environment <spack.builder.BaseBuilder.setup_dependent_build_environment>`
+3. :meth:`setup_dependent_build_environment <spack.builder.Builder.setup_dependent_build_environment>`
 4. :meth:`setup_dependent_run_environment <spack.package_base.PackageBase.setup_dependent_run_environment>`
 
 The Qt package, for instance, uses this call:
@@ -4898,15 +4867,15 @@ If your package has a virtual dependency like ``mpi``, then referring to
 ``spec["mpi"]`` within ``install()`` will get you the concrete ``mpi``
 implementation in your dependency DAG.  That is a spec object just like
 the one passed to install, only the MPI implementations all set some
-additional properties on it to help you out.  E.g., in openmpi, you'll
+additional properties on it to help you out.  E.g., in mvapich2, you'll
 find this:
 
-.. literalinclude:: _spack_root/var/spack/repos/builtin/packages/openmpi/package.py
+.. literalinclude:: _spack_root/var/spack/repos/builtin/packages/mvapich2/package.py
-   :pyobject: Openmpi.setup_dependent_package
+   :pyobject: Mvapich2.setup_dependent_package
 
-That code allows the ``openmpi`` package to associate an ``mpicc`` property
+That code allows the mvapich2 package to associate an ``mpicc`` property
-with the ``openmpi`` node in the DAG, so that dependents can access it.
+with the ``mvapich2`` node in the DAG, so that dependents can access it.
-``mvapich2`` and ``mpich`` do similar things.  So, no matter what MPI
+``openmpi`` and ``mpich`` do similar things.  So, no matter what MPI
 you're using, spec["mpi"].mpicc gets you the location of the MPI
 compilers. This allows us to have a fairly simple polymorphic interface
 for information about virtual dependencies like MPI.
@@ -5135,7 +5104,7 @@ other checks.
      - Not applicable
    * - :ref:`PythonPackage <pythonpackage>`
      - Not applicable
-     - ``test_imports`` (module imports)
+     - ``test`` (module imports)
    * - :ref:`QMakePackage <qmakepackage>`
      - ``check`` (``make check``)
      - Not applicable
@@ -5144,7 +5113,7 @@ other checks.
      - Not applicable
    * - :ref:`SIPPackage <sippackage>`
      - Not applicable
-     - ``test_imports`` (module imports)
+     - ``test`` (module imports)
    * - :ref:`WafPackage <wafpackage>`
      - ``build_test`` (must be overridden)
      - ``install_test`` (must be overridden)
@@ -7069,46 +7038,6 @@ might write:
    CXXFLAGS += -I$DWARF_PREFIX/include
    CXXFLAGS += -L$DWARF_PREFIX/lib
 
-.. _abi_compatibility:
-
-----------------------------
-Specifying ABI Compatibility
-----------------------------
-
-Packages can include ABI-compatibility information using the
-``can_splice`` directive. For example, if ``Foo`` version 1.1 can
-always replace version 1.0, then the package could have:
-
-.. code-block:: python
-
-   can_splice("foo@1.0", when="@1.1")
-
-For virtual packages, packages can also specify ABI-compabitiliby with
-other packages providing the same virtual. For example, ``zlib-ng``
-could specify:
-
-.. code-block:: python
-
-   can_splice("zlib@1.3.1", when="@2.2+compat")
-
-Some packages have ABI-compatibility that is dependent on matching
-variant values, either for all variants or for some set of
-ABI-relevant variants. In those cases, it is not necessary to specify
-the full combinatorial explosion. The ``match_variants`` keyword can
-cover all single-value variants.
-
-.. code-block:: python
-
-   can_splice("foo@1.1", when="@1.2", match_variants=["bar"])  # any value for bar as long as they're the same
-   can_splice("foo@1.2", when="@1.3", match_variants="*")  # any variant values if all single-value variants match
-
-The concretizer will use ABI compatibility to determine automatic
-splices when :ref:`automatic splicing<automatic_splicing>` is enabled.
-
-.. note::
-
-   The ``can_splice`` directive is experimental, and may be replaced
-   by a higher-level interface in future versions of Spack.
 
 .. _package_class_structure:
 

lib/spack/docs/pipelines.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 
@@ -58,7 +59,7 @@ Functional Example
 ------------------
 
 The simplest fully functional standalone example of a working pipeline can be
-examined live at this example `project <https://gitlab.com/spack/pipeline-quickstart>`_
+examined live at this example `project <https://gitlab.com/scott.wittenburg/spack-pipeline-demo>`_
 on gitlab.com.
 
 Here's the ``.gitlab-ci.yml`` file from that example that builds and runs the
@@ -66,46 +67,39 @@ pipeline:
 
 .. code-block:: yaml
 
-   stages: [ "generate", "build" ]
+   stages: [generate, build]
 
    variables:
-     SPACK_REPOSITORY: "https://github.com/spack/spack.git"
+     SPACK_REPO: https://github.com/scottwittenburg/spack.git
-     SPACK_REF: "develop-2024-10-06"
+     SPACK_REF: pipelines-reproducible-builds
-     SPACK_USER_CONFIG_PATH: ${CI_PROJECT_DIR}
-     SPACK_BACKTRACE: 1
 
    generate-pipeline:
-     tags:
-       - saas-linux-small-amd64
      stage: generate
+     tags:
+       - docker
      image:
-       name: ghcr.io/spack/ubuntu20.04-runner-x86_64:2023-01-01
+       name: ghcr.io/scottwittenburg/ecpe4s-ubuntu18.04-runner-x86_64:2020-09-01
-     script:
+       entrypoint: [""]
-       - git clone ${SPACK_REPOSITORY}
+     before_script:
-       - cd spack && git checkout ${SPACK_REF} && cd ../
+       - git clone ${SPACK_REPO}
+       - pushd spack && git checkout ${SPACK_REF} && popd
        - . "./spack/share/spack/setup-env.sh"
-       - spack --version
+     script:
        - spack env activate --without-view .
-       - spack -d -v --color=always
+       - spack -d ci generate
-         ci generate
-         --check-index-only
          --artifacts-root "${CI_PROJECT_DIR}/jobs_scratch_dir"
-         --output-file "${CI_PROJECT_DIR}/jobs_scratch_dir/cloud-ci-pipeline.yml"
+         --output-file "${CI_PROJECT_DIR}/jobs_scratch_dir/pipeline.yml"
      artifacts:
        paths:
          - "${CI_PROJECT_DIR}/jobs_scratch_dir"
 
-   build-pipeline:
+   build-jobs:
      stage: build
      trigger:
        include:
-         - artifact: jobs_scratch_dir/cloud-ci-pipeline.yml
+         - artifact: "jobs_scratch_dir/pipeline.yml"
            job: generate-pipeline
        strategy: depend
-     needs:
-       - artifacts: True
-         job: generate-pipeline
-
 
 The key thing to note above is that there are two jobs: The first job to run,
 ``generate-pipeline``, runs the ``spack ci generate`` command to generate a
@@ -120,93 +114,82 @@ And here's the spack environment built by the pipeline represented as a
    spack:
      view: false
      concretizer:
-       unify: true
+       unify: false
-       reuse: false
 
      definitions:
      - pkgs:
        - zlib
-       - bzip2 ~debug
+       - bzip2
-     - compiler:
+     - arch:
-       - '%gcc'
+       - '%gcc@7.5.0 arch=linux-ubuntu18.04-x86_64'
 
      specs:
      - matrix:
        - - $pkgs
-       - - $compiler
+       - - $arch
+
+     mirrors: { "mirror": "s3://spack-public/mirror" }
 
      ci:
-       target: gitlab
+       enable-artifacts-buildcache: True
-
+       rebuild-index: False
        pipeline-gen:
        - any-job:
-           tags:
-             - saas-linux-small-amd64
-           image:
-             name: ghcr.io/spack/ubuntu20.04-runner-x86_64:2023-01-01
            before_script:
-           - git clone ${SPACK_REPOSITORY}
+             - git clone ${SPACK_REPO}
-           - cd spack && git checkout ${SPACK_REF} && cd ../
+             - pushd spack && git checkout ${SPACK_CHECKOUT_VERSION} && popd
              - . "./spack/share/spack/setup-env.sh"
-           - spack --version
+       - build-job:
-           - export SPACK_USER_CONFIG_PATH=${CI_PROJECT_DIR}
+           tags: [docker]
-           - spack config blame mirrors
+           image:
+             name: ghcr.io/scottwittenburg/ecpe4s-ubuntu18.04-runner-x86_64:2020-09-01
+             entrypoint: [""]
 
 
+The elements of this file important to spack ci pipelines are described in more
+detail below, but there are a couple of things to note about the above working
+example:
+
 .. note::
-   The use of ``reuse: false`` in spack environments used for pipelines is
+   There is no ``script`` attribute specified for here. The reason for this is
-   almost always what you want, as without it your pipelines will not rebuild
+   Spack CI will automatically generate reasonable default scripts. More
-   packages even if package hashes have changed. This is due to the concretizer
+   detail on what is in these scripts can be found below.
-   strongly preferring known hashes when ``reuse: true``.
 
-The ``ci`` section in the above environment file contains the bare minimum
+   Also notice the ``before_script`` section. It is required when using any of the
-configuration required for ``spack ci generate`` to create a working pipeline.
+   default scripts to source the ``setup-env.sh`` script in order to inform
-The ``target: gitlab`` tells spack that the desired pipeline output is for
+   the default scripts where to find the ``spack`` executable.
-gitlab.  However, this isn't strictly required, as currently gitlab is the
-only possible output format for pipelines. The ``pipeline-gen`` section
-contains the key information needed to specify attributes for the generated
-jobs.  Notice that it contains a list which has only a single element in
-this case.  In real pipelines it will almost certainly have more elements,
-and in those cases, order is important: spack starts at the bottom of the
-list and works upwards when applying attributes.
 
-But in this simple case, we use only the special key ``any-job`` to
+Normally ``enable-artifacts-buildcache`` is not recommended in production as it
-indicate that spack should apply the specified attributes (``tags``, ``image``,
+results in large binary artifacts getting transferred back and forth between
-and ``before_script``) to any job it generates.  This includes jobs for
+gitlab and the runners.  But in this example on gitlab.com where there is no
-building/pushing all packages, a ``rebuild-index`` job at the end of the
+shared, persistent file system, and where no secrets are stored for giving
-pipeline, as well as any ``noop`` jobs that might be needed by gitlab when
+permission to write to an S3 bucket, ``enabled-buildcache-artifacts`` is the only
-no rebuilds are required.
+way to propagate binaries from jobs to their dependents.
 
-Something to note is that in this simple case, we rely on spack to
+Also, it is usually a good idea to let the pipeline generate a final "rebuild the
-generate a reasonable script for the package build jobs (it just creates
+buildcache index" job, so that subsequent pipeline generation can quickly determine
-a script that invokes ``spack ci rebuild``).
+which specs are up to date and which need to be rebuilt (it's a good idea for other
+reasons as well, but those are out of scope for this discussion).  In this case we
+have disabled it (using ``rebuild-index: False``) because the index would only be
+generated in the artifacts mirror anyway, and consequently would not be available
+during subsequent pipeline runs.
 
-Another thing to note is the use of the ``SPACK_USER_CONFIG_DIR`` environment
+.. note::
-variable in any generated jobs.  The purpose of this is to make spack
+   With the addition of reproducible builds (#22887) a previously working
-aware of one final file in the example, the one that contains the mirror
+   pipeline will require some changes:
-configuration.  This file, ``mirrors.yaml`` looks like this:
 
-.. code-block:: yaml
+   * In the build-jobs, the environment location changed.
+     This will typically show as a ``KeyError`` in the failing job. Be sure to
+     point to ``${SPACK_CONCRETE_ENV_DIR}``.
 
-   mirrors:
+   * When using ``include`` in your environment, be sure to make the included
-     buildcache-destination:
+     files available in the build jobs. This means adding those files to the
-       url: oci://registry.gitlab.com/spack/pipeline-quickstart
+     artifact directory. Those files will also be missing in the reproducibility
-       binary: true
+     artifact.
-       access_pair:
-         id_variable: CI_REGISTRY_USER
-         secret_variable: CI_REGISTRY_PASSWORD
 
-
+   * Because the location of the environment changed, including files with
-Note the name of the mirror is ``buildcache-destination``, which is required
+     relative path may have to be adapted to work both in the project context
-as of Spack 0.23 (see below for more information).  The mirror url simply
+     (generation job) and in the concrete env dir context (build job).
-points to the container registry associated with the project, while
-``id_variable`` and ``secret_variable`` refer to to environment variables
-containing the access credentials for the mirror.
-
-When spack builds packages for this example project, they will be pushed to
-the project container registry, where they will be available for subsequent
-jobs to install as dependencies, or for other pipelines to use to build runnable
-container images.
 
 -----------------------------------
 Spack commands supporting pipelines
@@ -330,7 +313,7 @@ that ``--tests`` is passed to ``spack ci rebuild`` as part of the
           - spack --version
           - cd ${SPACK_CONCRETE_ENV_DIR}
           - spack env activate --without-view .
-          - spack config add "config:install_tree:projections:${SPACK_JOB_SPEC_PKG_NAME}:'morepadding/{architecture.platform}-{architecture.target}/{name}-{version}-{hash}'"
+          - spack config add "config:install_tree:projections:${SPACK_JOB_SPEC_PKG_NAME}:'morepadding/{architecture}/{compiler.name}-{compiler.version}/{name}-{version}-{hash}'"
            - mkdir -p ${SPACK_ARTIFACTS_ROOT}/user_data
            - if [[ -r /mnt/key/intermediate_ci_signing_key.gpg ]]; then spack gpg trust /mnt/key/intermediate_ci_signing_key.gpg; fi
            - if [[ -r /mnt/key/spack_public_key.gpg ]]; then spack gpg trust /mnt/key/spack_public_key.gpg; fi
@@ -434,6 +417,15 @@ configuration with a ``script`` attribute. Specifying a signing job without a sc
 does not create a signing job and the job configuration attributes will be ignored.
 Signing jobs are always assigned the runner tags ``aws``, ``protected``, and ``notary``.
 
+^^^^^^^^^^^^^^^^^
+Cleanup (cleanup)
+^^^^^^^^^^^^^^^^^
+
+When using ``temporary-storage-url-prefix`` the cleanup job will destroy the mirror
+created for the associated Gitlab pipeline. Cleanup jobs do not allow modifying the
+script, but do expect that the spack command is in the path and require a
+``before_script`` to be specified that sources the ``setup-env.sh`` script.
+
 .. _noop_jobs:
 
 ^^^^^^^^^^^^
@@ -600,77 +592,6 @@ the attributes will be merged starting from the bottom match going up to the top
 
 In the case that no match is found in a submapping section, no additional attributes will be applied.
 
-
-^^^^^^^^^^^^^^^^^^^^^^^^
-Dynamic Mapping Sections
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-For large scale CI where cost optimization is required, dynamic mapping allows for the use of real-time
-mapping schemes served by a web service. This type of mapping does not support the ``-remove`` type
-behavior, but it does follow the rest of the merge rules for configurations.
-
-The dynamic mapping service needs to implement a single REST API interface for getting
-requests ``GET <URL>[:PORT][/PATH]?spec=<pkg_name@pkg_version +variant1+variant2%compiler@compiler_version>``.
-
-example request.
-
-.. code-block::
-
-  https://my-dyn-mapping.spack.io/allocation?spec=zlib-ng@2.1.6 +compat+opt+shared+pic+new_strategies arch=linux-ubuntu20.04-x86_64_v3%gcc@12.0.0
-
-
-With an example response the updates kubernetes request variables, overrides the max retries for gitlab,
-and prepends a note about the modifications made by the my-dyn-mapping.spack.io service.
-
-.. code-block::
-
-  200 OK
-
-  {
-    "variables":
-    {
-      "KUBERNETES_CPU_REQUEST": "500m",
-      "KUBERNETES_MEMORY_REQUEST": "2G",
-    },
-    "retry": { "max:": "1"}
-    "script+:":
-    [
-      "echo \"Job modified by my-dyn-mapping.spack.io\""
-    ]
-  }
-
-
-The ci.yaml configuration section takes the URL endpoint as well as a number of options to configure how responses are handled.
-
-It is possible to specify a list of allowed and ignored configuration attributes under ``allow`` and ``ignore``
-respectively. It is also possible to configure required attributes under ``required`` section.
-
-Options to configure the client timeout and SSL verification using the ``timeout`` and ``verify_ssl`` options.
-By default, the ``timeout`` is set to the option in ``config:timeout`` and ``veryify_ssl`` is set the the option in ``config::verify_ssl``.
-
-Passing header parameters to the request can be achieved through the ``header`` section. The values of the variables passed to the
-header may be environment variables that are expanded at runtime, such as a private token configured on the runner.
-
-Here is an example configuration pointing to ``my-dyn-mapping.spack.io/allocation``.
-
-
-.. code-block:: yaml
-
-  ci:
-  - dynamic-mapping:
-      endpoint: my-dyn-mapping.spack.io/allocation
-      timeout: 10
-      verify_ssl: True
-      header:
-        PRIVATE_TOKEN: ${MY_PRIVATE_TOKEN}
-        MY_CONFIG: "fuzz_allocation:false"
-      allow:
-      - variables
-      ignore:
-      - script
-      require: []
-
-
 ^^^^^^^^^^^^^
 Bootstrapping
 ^^^^^^^^^^^^^
@@ -742,13 +663,26 @@ build the package.
 
 When including a bootstrapping phase as in the example above, the result is that
 the bootstrapped compiler packages will be pushed to the binary mirror (and the
-local artifacts mirror) before the actual release specs are built.
+local artifacts mirror) before the actual release specs are built. In this case,
+the jobs corresponding to subsequent release specs are configured to
+``install_missing_compilers``, so that if spack is asked to install a package
+with a compiler it doesn't know about, it can be quickly installed from the
+binary mirror first.
 
 Since bootstrapping compilers is optional, those items can be left out of the
 environment/stack file, and in that case no bootstrapping will be done (only the
 specs will be staged for building) and the runners will be expected to already
 have all needed compilers installed and configured for spack to use.
 
+^^^^^^^^^^^^^^^^^^^
+Pipeline Buildcache
+^^^^^^^^^^^^^^^^^^^
+
+The ``enable-artifacts-buildcache`` key
+takes a boolean and determines whether the pipeline uses artifacts to store and
+pass along the buildcaches from one stage to the next (the default if you don't
+provide this option is ``False``).
+
 ^^^^^^^^^^^^^^^^
 Broken Specs URL
 ^^^^^^^^^^^^^^^^
@@ -820,69 +754,6 @@ presence of a ``SPACK_CDASH_AUTH_TOKEN`` environment variable during the
 build group on CDash called "Release Testing" (that group will be created if
 it didn't already exist).
 
-.. _ci_artifacts:
-
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-CI Artifacts Directory Layout
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-When running the CI build using the command ``spack ci rebuild`` a number of directories are created for
-storing data generated during the CI job. The default root directory for artifacts is ``job_scratch_root``.
-This can be overridden by passing the argument ``--artifacts-root`` to the ``spack ci generate`` command
-or by setting the ``SPACK_ARTIFACTS_ROOT`` environment variable in the build job scripts.
-
-The top level directories under the artifact root are ``concrete_environment``, ``logs``, ``reproduction``,
-``tests``, and ``user_data``. Spack does not restrict what is written to any of these directories nor does
-it require user specified files be written to any specific directory.
-
-------------------------
-``concrete_environment``
-------------------------
-
-The directory ``concrete_environment`` is used to communicate the ci generate processed ``spack.yaml`` and
-the concrete ``spack.lock`` for the CI environment.
-
---------
-``logs``
---------
-
-The directory ``logs`` contains the spack build log, ``spack-build-out.txt``, and the spack build environment
-modification file, ``spack-build-mod-env.txt``. Additionally all files specified by the packages ``Builder``
-property ``archive_files`` are also copied here (ie. ``CMakeCache.txt`` in ``CMakeBuilder``).
-
-----------------
-``reproduction``
-----------------
-
-The directory ``reproduction`` is used to store the files needed by the ``spack reproduce-build`` command.
-This includes ``repro.json``, copies of all of the files in ``concrete_environment``, the concrete spec
-JSON file for the current spec being built, and all of the files written in the artifacts root directory.
-
-The ``repro.json`` file is not versioned and is only designed to work with the version of spack CI was run with.
-An example of what a ``repro.json`` may look like is here.
-
-.. code:: json
-
-  {
-    "job_name": "adios2@2.9.2 /feaevuj %gcc@11.4.0 arch=linux-ubuntu20.04-x86_64_v3 E4S ROCm External",
-    "job_spec_json": "adios2.json",
-    "ci_project_dir": "/builds/spack/spack"
-  }
-
----------
-``tests``
----------
-
-The directory ``tests`` is used to store output from running ``spack test <job spec>``. This may or may not have
-data in it depending on the package that was built and the availability of tests.
-
--------------
-``user_data``
--------------
-
-The directory ``user_data`` is used to store everything else that shouldn't be copied to the ``reproduction`` direcotory.
-Users may use this to store additional logs or metrics or other types of files generated by the build job.
-
 -------------------------------------
 Using a custom spack in your pipeline
 -------------------------------------

lib/spack/docs/replace_conda_homebrew.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 

lib/spack/docs/repositories.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 

lib/spack/docs/requirements.txt

@@ -1,13 +1,13 @@
-sphinx==8.2.3
+sphinx==7.4.7
-sphinxcontrib-programoutput==0.18
+sphinxcontrib-programoutput==0.17
 sphinx_design==0.6.1
-sphinx-rtd-theme==3.0.2
+sphinx-rtd-theme==2.0.0
-python-levenshtein==0.27.1
+python-levenshtein==0.25.1
-docutils==0.21.2
+docutils==0.20.1
-pygments==2.19.1
+pygments==2.18.0
-urllib3==2.3.0
+urllib3==2.2.2
-pytest==8.3.5
+pytest==8.3.2
-isort==6.0.1
+isort==5.13.2
-black==25.1.0
+black==24.8.0
-flake8==7.1.2
+flake8==7.1.1
 mypy==1.11.1

lib/spack/docs/signing.rst

@@ -1,4 +1,5 @@
-.. Copyright Spack Project Developers. See COPYRIGHT file for details.
+.. 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)
 

lib/spack/docs/spack.yaml

@@ -1,4 +1,5 @@
-# Copyright Spack Project Developers. See COPYRIGHT file for details.
+# 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)
 

lib/spack/docs/tables/system_prerequisites.csv

@@ -8,6 +8,7 @@ unzip, , , Compress/Decompress archives
 bzip2, , , Compress/Decompress archives
 xz, , , Compress/Decompress archives
 zstd, , Optional, Compress/Decompress archives
+file, , , Create/Use Buildcaches
 lsb-release, , , Linux: identify operating system version
 gnupg2, , , Sign/Verify Buildcaches
 git, , , Manage Software Repositories

lib/spack/env/aocc/clang

@@ -0,0 +1 @@
+../cc

lib/spack/env/aocc/clang++

@@ -0,0 +1 @@
+../cpp

lib/spack/env/aocc/flang

@@ -0,0 +1 @@
+../fc