not == to !=

Signed-off-by: Todd Gamblin <tgamblin@llnl.gov>

.github/workflows/audit.yaml

@@ -59,7 +59,6 @@ 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

.github/workflows/ci.yaml

@@ -9,6 +9,7 @@ on:
     branches:
       - develop
       - releases/**
+  merge_group:
 
 concurrency:
   group: ci-${{github.ref}}-${{github.event.pull_request.number || github.run_number}}
@@ -25,13 +26,17 @@ jobs:
       packages: ${{ steps.filter.outputs.packages }}
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
-        if: ${{ github.event_name == 'push' }}
+        if: ${{ github.event_name == 'push' || github.event_name == 'merge_group' }}
         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
@@ -76,10 +81,11 @@ jobs:
 
   prechecks:
     needs: [ changes ]
-    uses: ./.github/workflows/valid-style.yml
+    uses: ./.github/workflows/prechecks.yml
     secrets: inherit
     with:
       with_coverage: ${{ needs.changes.outputs.core }}
+      with_packages: ${{ needs.changes.outputs.packages }}
 
   import-check:
     needs: [ changes ]
@@ -93,7 +99,7 @@ jobs:
     - name: Success
       run: |
         if [ "${{ needs.prechecks.result }}" == "failure" ] || [ "${{ needs.prechecks.result }}" == "canceled" ]; then
-          echo "Unit tests failed." 
+          echo "Unit tests failed."
           exit 1
         else
           exit 0
@@ -101,6 +107,7 @@ jobs:
 
   coverage:
     needs: [ unit-tests, prechecks ]
+    if: ${{ needs.changes.outputs.core }}
     uses: ./.github/workflows/coverage.yml
     secrets: inherit
 
@@ -113,10 +120,10 @@ jobs:
     - name: Status summary
       run: |
         if [ "${{ needs.unit-tests.result }}" == "failure" ] || [ "${{ needs.unit-tests.result }}" == "canceled" ]; then
-          echo "Unit tests failed." 
+          echo "Unit tests failed."
           exit 1
         elif [ "${{ needs.bootstrap.result }}" == "failure" ] || [ "${{ needs.bootstrap.result }}" == "canceled" ]; then
-          echo "Bootstrap tests failed." 
+          echo "Bootstrap tests failed."
           exit 1
         else
           exit 0

.github/workflows/prechecks.yml

@@ -1,4 +1,4 @@
-name: style
+name: prechecks
 
 on:
   workflow_call:
@@ -6,6 +6,9 @@ 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}}
@@ -30,6 +33,7 @@ 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
@@ -53,12 +57,25 @@ 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'
+
+  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

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

@@ -1,7 +1,7 @@
 black==25.1.0
 clingo==5.7.1
-flake8==7.1.2
-isort==6.0.0
-mypy==1.11.2
-types-six==1.17.0.20241205
+flake8==7.2.0
+isort==6.0.1
+mypy==1.15.0
+types-six==1.17.0.20250304
 vermin==1.6.0

.github/workflows/unit_tests.yaml

@@ -19,9 +19,6 @@ jobs:
         on_develop:
         - ${{ github.ref == 'refs/heads/develop' }}
         include:
-        - python-version: '3.6'
-          os: ubuntu-20.04
-          on_develop: ${{ github.ref == 'refs/heads/develop' }}
         - python-version: '3.7'
           os: ubuntu-22.04
           on_develop: ${{ github.ref == 'refs/heads/develop' }}

.gitignore

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

etc/spack/defaults/concretizer.yaml

@@ -54,9 +54,15 @@ concretizer:
       # 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

etc/spack/defaults/config.yaml

@@ -19,7 +19,7 @@ config:
   install_tree:
     root: $spack/opt/spack
     projections:
-      all: "{architecture}/{compiler.name}-{compiler.version}/{name}-{version}-{hash}"
+      all: "{architecture.platform}-{architecture.target}/{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

etc/spack/defaults/darwin/packages.yaml

@@ -15,12 +15,11 @@
 # -------------------------------------------------------------------------
 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]
@@ -50,3 +49,12 @@ 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,19 +15,18 @@
 # -------------------------------------------------------------------------
 packages:
   all:
-    compiler: [gcc, clang, oneapi, xl, nag, fj, aocc]
     providers:
       awk: [gawk]
       armci: [armcimpi]
       blas: [openblas, amdblis]
-      c: [gcc]
-      cxx: [gcc]
+      c: [gcc, llvm, intel-oneapi-compilers]
+      cxx: [gcc, llvm, intel-oneapi-compilers]
       D: [ldc]
       daal: [intel-oneapi-daal]
       elf: [elfutils]
       fftw-api: [fftw, amdfftw]
       flame: [libflame, amdlibflame]
-      fortran: [gcc]
+      fortran: [gcc, llvm, intel-oneapi-compilers]
       fortran-rt: [gcc-runtime, intel-oneapi-runtime]
       fuse: [libfuse]
       gl: [glx, osmesa]

etc/spack/defaults/windows/packages.yaml

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

lib/spack/docs/basic_usage.rst

@@ -1409,27 +1409,29 @@ that executables will run without the need to set ``LD_LIBRARY_PATH``.
 
 .. code-block:: yaml
 
-  compilers:
-    - compiler:
-        spec: gcc@4.9.3
-        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
-          set:
-            GOOD_VARIABLE_NUM: 1
-            GOOD_VARIABLE_STR: good
-          prepend_path:
-            PATH: /path/to/binutils
-          append_path:
-            LD_LIBRARY_PATH: /opt/gcc/lib
-        extra_rpaths:
-        - /path/to/some/compiler/runtime/directory
-        - /path/to/some/other/compiler/runtime/directory
+  packages:
+    gcc:
+      externals:
+      - spec: gcc@4.9.3
+        prefix: /opt/gcc
+        extra_attributes:
+          compilers:
+            c: /opt/gcc/bin/gcc
+            cxx: /opt/gcc/bin/g++
+            fortran: /opt/gcc/bin/gfortran
+          environment:
+            unset:
+              - BAD_VARIABLE
+            set:
+              GOOD_VARIABLE_NUM: 1
+              GOOD_VARIABLE_STR: good
+            prepend_path:
+              PATH: /path/to/binutils
+            append_path:
+              LD_LIBRARY_PATH: /opt/gcc/lib
+          extra_rpaths:
+          - /path/to/some/compiler/runtime/directory
+          - /path/to/some/other/compiler/runtime/directory
 
 
 ^^^^^^^^^^^^^^^^^^^^^^^
@@ -1761,19 +1763,24 @@ 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 command will check, for every
-file in each package, whether any of those attributes have changed. It
-will also check for newly added files or deleted files from the
-installation prefix. Spack can either check all installed packages
+time, hash, and size. The ``spack verify manifest`` command will check,
+for every file in each package, whether any of those attributes have
+changed. It will also check for newly added files or deleted files from
+the 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`` command can also verify for individual files that
-they haven't been altered since installation time. If the given file
+The ``spack verify manifest`` command can also verify for individual files
+that 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.
@@ -1788,6 +1795,22 @@ 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/build_systems.rst

@@ -63,7 +63,6 @@ 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/inteloneapipackage.rst

@@ -33,9 +33,6 @@ 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
 ========
@@ -50,34 +47,8 @@ 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
-
-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 ::
+To build the ``patchelf`` Spack package with ``icx``, do::
 
   spack install patchelf%oneapi
 
@@ -92,15 +63,6 @@ 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
@@ -149,7 +111,7 @@ Compilers
 ---------
 
 To use the compilers, add some information about the installation to
-``compilers.yaml``. For most users, it is sufficient to do::
+``packages.yaml``. For most users, it is sufficient to do::
 
   spack compiler add /opt/intel/oneapi/compiler/latest/bin
 
@@ -157,7 +119,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
-``compilers.yaml`` as described in :ref:`Compiler configuration
+``packages.yaml`` as described in :ref:`Compiler configuration
 <compiler-config>`.
 
 Before 2024, the directory structure was different::
@@ -200,15 +162,5 @@ 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/rocmpackage.rst

@@ -12,8 +12,7 @@ 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
-``compilers.yaml`` and ``packages.yaml`` files) at
+You can find the source for this package (and suggestions for setting up your ``packages.yaml`` file) at
 `<https://github.com/spack/spack/blob/develop/lib/spack/spack/build_systems/rocm.py>`__.
 
 ^^^^^^^^

lib/spack/docs/conf.py

@@ -223,6 +223,10 @@ def setup(sphinx):
     ("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

@@ -125,6 +125,8 @@ 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``
 --------------------
@@ -146,15 +148,16 @@ this can expose you to attacks.  Use at your own risk.
 ``ssl_certs``
 --------------------
 
-Path to custom certificats for SSL verification. The value can be a 
+Path to custom certificats for SSL verification. The value can be a
 filesytem path, or an environment variable that expands to an absolute file path.
 The default value is set to the environment variable ``SSL_CERT_FILE``
 to use the same syntax used by many other applications that automatically
 detect custom certificates.
 When ``url_fetch_method:curl`` the ``config:ssl_certs`` should resolve to
 a single file.  Spack will then set the environment variable ``CURL_CA_BUNDLE``
-in the subprocess calling ``curl``.
-If ``url_fetch_method:urllib`` then files and directories are supported i.e. 
+in the subprocess calling ``curl``. If additional ``curl`` arguments are required,
+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.
 In all cases the expanded path must be absolute for Spack to use the certificates.
@@ -334,3 +337,52 @@ 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

@@ -11,9 +11,10 @@ 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:`compilers.yaml <compiler-config>`
+* :ref:`packages.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>`
@@ -94,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``, ``compilers.yaml``, or ``mirrors.yaml``.  When
+such as ``config.yaml``, ``packages.yaml``, or ``mirrors.yaml``.  When
 configurations conflict, settings from higher-precedence scopes override
 lower-precedence settings.
 

lib/spack/docs/environments.rst

@@ -457,6 +457,13 @@ 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
@@ -660,34 +667,56 @@ a ``packages.yaml`` file) could contain:
      # ...
      packages:
        all:
-         compiler: [intel]
+         providers:
+           mpi: [openmpi]
      # ...
 
-This configuration sets the default compiler for all packages to
-``intel``.
+This configuration sets the default mpi provider to be openmpi.
 
 ^^^^^^^^^^^^^^^^^^^^^^^
 Included configurations
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-Spack environments allow an ``include`` heading in their yaml
-schema. This heading pulls in external configuration files and applies
-them to the environment.
+Spack environments allow an ``include`` heading in their yaml schema.
+This heading pulls in external configuration files and applies them to
+the environment.
 
 .. code-block:: yaml
 
    spack:
      include:
-     - relative/path/to/config.yaml
-     - https://github.com/path/to/raw/config/compilers.yaml
+     - environment/relative/path/to/config.yaml
+     - path: 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.
-Spack supports ``file``, ``http``, ``https`` and ``ftp`` protocols (or
-schemes). Spack-specific, environment and user path variables may be
-used in these paths. See :ref:`config-file-variables` for more information.
 
 ^^^^^^^^^^^^^^^^^^^^^^^^
 Configuration precedence

lib/spack/docs/example_files/spack.yaml

@@ -1,161 +0,0 @@
-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/frequently_asked_questions.rst

@@ -30,7 +30,7 @@ than always choosing the latest versions or default variants.
 
 .. note::
 
-    As a rule of thumb: requirements + constraints > reuse > preferences > defaults.
+    As a rule of thumb: requirements + constraints > strong preferences > 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,7 +56,19 @@ common cases where concretization output may seem surprising at first.
       concretizer:
         reuse: dependencies  # other options are 'true' and 'false'
 
-3. :ref:`Package requirements <package-requirements>` configured in ``packages.yaml``,
+3. :ref:`Strong preferences <package-strong-preferences>` 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:
 
@@ -66,6 +78,8 @@ 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

@@ -254,12 +254,11 @@ directory.
 Compiler configuration
 ----------------------
 
-Spack has the ability to build packages with multiple compilers and
-compiler versions. Compilers can be made available to Spack by
-specifying them manually in ``compilers.yaml`` or ``packages.yaml``,
-or automatically by running ``spack compiler find``, but for
-convenience Spack will automatically detect compilers the first time
-it needs them.
+Spack has the ability to build packages with multiple compilers and compiler versions.
+Compilers can be made available to Spack by specifying them manually in ``packages.yaml``,
+or automatically by running ``spack compiler find``.
+For convenience, Spack will automatically detect compilers the first time it needs them,
+if none is available.
 
 .. _cmd-spack-compilers:
 
@@ -274,16 +273,11 @@ compilers`` or ``spack compiler list``:
 
    $ spack compilers
    ==> Available compilers
-   -- gcc ---------------------------------------------------------
-       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
-   -- intel -------------------------------------------------------
-       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
+   -- gcc ubuntu20.04-x86_64 ---------------------------------------
+   gcc@9.4.0  gcc@8.4.0  gcc@10.5.0
+
+   -- llvm ubuntu20.04-x86_64 --------------------------------------
+   llvm@12.0.0  llvm@11.0.0  llvm@10.0.0
 
 Any of these compilers can be used to build Spack packages.  More on
 how this is done is in :ref:`sec-specs`.
@@ -302,16 +296,22 @@ An alias for ``spack compiler find``.
 ``spack compiler find``
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-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:
+If you do not see a compiler in the list shown by:
 
 .. code-block:: console
 
-   $ spack compiler find /usr/local/tools/ic-13.0.079
-   ==> Added 1 new compiler to ~/.spack/linux/compilers.yaml
-       intel@13.0.079
+   $ spack compiler 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 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 +322,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 ~/.spack/linux/compilers.yaml
+   ==> Added 1 new compiler to /home/user/.spack/packages.yaml
        gcc@4.9.0
 
 This loads the environment module for gcc-4.9.0 to add it to
@@ -331,7 +331,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
-   ``compilers.yaml`` file.  If you are using a compiler from a
+   ``packages.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,91 +341,82 @@ This loads the environment module for gcc-4.9.0 to add it to
 ``spack compiler info``
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-If you want to see specifics on a particular compiler, you can run
-``spack compiler info`` on it:
+If you want to see additional information on some specific compilers, you can run ``spack compiler info`` on it:
 
 .. code-block:: console
 
-   $ spack compiler info intel@15
-   intel@15.0.0:
-     paths:
-       cc  = /usr/local/bin/icc-15.0.090
-       cxx = /usr/local/bin/icpc-15.0.090
-       f77 = /usr/local/bin/ifort-15.0.090
-       fc  = /usr/local/bin/ifort-15.0.090
-     modules = []
-     operating_system = centos6
-   ...
+   $ spack compiler info gcc
+   gcc@=8.4.0 languages='c,c++,fortran' arch=linux-ubuntu20.04-x86_64:
+     prefix: /usr
+     compilers:
+       c: /usr/bin/gcc-8
+       cxx: /usr/bin/g++-8
+       fortran: /usr/bin/gfortran-8
 
-This shows which C, C++, and Fortran compilers were detected by Spack.
-Notice also that we didn't have to be too specific about the
-version. We just said ``intel@15``, and information about the only
-matching Intel compiler was displayed.
+   gcc@=9.4.0 languages='c,c++,fortran' arch=linux-ubuntu20.04-x86_64:
+     prefix: /usr
+     compilers:
+       c: /usr/bin/gcc
+       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/<platform>/compilers.yaml`` file.  You can do this by running
-``spack config edit compilers``, which will open the file in
+If auto-detection fails, you can manually configure a compiler by editing your ``~/.spack/packages.yaml`` file.
+You can do this by running ``spack config edit packages``, which will open the file in
 :ref:`your favorite editor <controlling-the-editor>`.
 
-Each compiler configuration in the file looks like this:
+Each compiler has an "external" entry in the file with some ``extra_attributes``:
 
 .. code-block:: yaml
 
-   compilers:
-   - compiler:
-       modules: []
-       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
+   packages:
+     gcc:
+       externals:
+       - spec: gcc@10.5.0 languages='c,c++,fortran'
+         prefix: /usr
+         extra_attributes:
+           compilers:
+             c: /usr/bin/gcc-10
+             cxx: /usr/bin/g++-10
+             fortran: /usr/bin/gfortran-10
 
-For compilers that do not support Fortran (like ``clang``), put
-``None`` for ``f77`` and ``fc``:
+The compiler executables are listed under ``extra_attributes:compilers``, and are keyed by language.
+Once you save the file, the configured compilers will show up in the list displayed by ``spack compilers``.
 
-.. code-block:: yaml
-
-   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``,
+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
 
-   compilers:
-   - compiler:
-       modules: []
-       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
+   packages:
+     gcc:
+       externals:
+       - spec: gcc@10.5.0 languages='c,c++,fortran'
+         prefix: /usr
+         extra_attributes:
+           compilers:
+             c: /usr/bin/gcc-10
+             cxx: /usr/bin/g++-10
+             fortran: /usr/bin/gfortran-10
+           flags:
+             cflags: -O3 -fPIC
+             cxxflags: -O3 -fPIC
+             cppflags: -O3 -fPIC
 
 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
@@ -440,95 +431,44 @@ These variables should be specified in the ``environment`` section of the compil
 specification. The operations available to modify the environment are ``set``, ``unset``,
 ``prepend_path``, ``append_path``, and ``remove_path``. For example:
 
-.. code-block:: yaml
-
-   compilers:
-   - compiler:
-       modules: []
-       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"
-         unset: # A list of environment variables to unset
-           - CC
-         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
+     intel-oneapi-compilers:
+       externals:
+       - spec: intel-oneapi-compilers@2025.1.0
+         prefix: /opt/intel/oneapi
          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/
+             c: /opt/intel/oneapi/compiler/2025.1/bin/icx
+             cxx: /opt/intel/oneapi/compiler/2025.1/bin/icpx
+             fortran: /opt/intel/oneapi/compiler/2025.1/bin/ifx
+           environment:
+             set:
+               MKL_ROOT: "/path/to/mkl/root"
+             unset: # A list of environment variables to unset
+               - CC
+             prepend_path: # Similar for append|remove_path
+               LD_LIBRARY_PATH: /ld/paths/added/by/setvars/sh
 
 ^^^^^^^^^^^^^^^^^^^^^^^
 Build Your Own Compiler
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-If you are particular about which compiler/version you use, you might
-wish to have Spack build it for you.  For example:
+If you are particular about which compiler/version you use, you might wish to have Spack build it for you.
+For example:
 
 .. code-block:: console
 
-   $ spack install gcc@4.9.3
+   $ spack install gcc@14+binutils
 
-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:
+Once the compiler is installed, you can start using it without additional configuration:
 
-.. code-block:: yaml
+.. code-block:: console
 
-   packages:
-     all:
-       compiler: [gcc@4.9.3]
+   $ spack install hdf5~mpi %gcc@14
+
+The same holds true for compilers that are made available from buildcaches, when reusing them is allowed.
 
 .. _compilers-requiring-modules:
 
@@ -536,30 +476,26 @@ by adding the following to your ``packages.yaml`` file:
 Compilers Requiring Modules
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Many installed compilers will work regardless of the environment they
-are called with.  However, some installed compilers require
-``$LD_LIBRARY_PATH`` or other environment variables to be set in order
-to run; this is typical for Intel and other proprietary compilers.
+Many installed compilers will work regardless of the environment they are called with.
+However, some installed compilers require environment variables to be set in order to run;
+this is typical for Intel and other proprietary compilers.
 
-In such a case, you should tell Spack which module(s) to load in order
-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:
+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 to run the chosen compiler:
 
 .. code-block:: yaml
 
-   compilers:
-   - compiler:
-       modules: [other/comp/gcc-5.3-sp3]
-       operating_system: SuSE11
-       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
+   packages:
+     gcc:
+       externals:
+       - spec: gcc@10.5.0 languages='c,c++,fortran'
+         prefix: /opt/compilers
+         extra_attributes:
+           compilers:
+             c: /opt/compilers/bin/gcc-10
+             cxx: /opt/compilers/bin/g++-10
+             fortran: /opt/compilers/bin/gfortran-10
+         modules: [gcc/10.5.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
@@ -580,7 +516,7 @@ Licensed Compilers
 ^^^^^^^^^^^^^^^^^^
 
 Some proprietary compilers require licensing to use.  If you need to
-use a licensed compiler (eg, PGI), the process is similar to a mix of
+use a licensed compiler, 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
@@ -590,24 +526,21 @@ 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 ``compilers.yaml`` as shown
-   above.
+#. Add the newly-installed compiler to ``packages.yaml`` as shown above.
 
 .. _mixed-toolchains:
 
-^^^^^^^^^^^^^^^^
-Mixed Toolchains
-^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+Fortran compilers on macOS
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 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, starting with macOS El
-Capitan (10.11), many packages no longer build with GCC, but XCode
-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.
+In some cases, this is not possible.  For example, XCode on macOS provides no Fortran compilers.
+The user is therefore forced to use a mixed toolchain: XCode-provided Clang for C/C++ and e.g.
+GNU ``gfortran`` for Fortran.
 
 #. You need to make sure that Xcode is installed. Run the following command:
 
@@ -660,45 +593,25 @@ 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>`_.
 
-#. The only thing left to do is to edit ``~/.spack/darwin/compilers.yaml`` to provide
-   the path to ``gfortran``:
+#. Run ``spack compiler find`` to locate both Apple-Clang and GCC.
 
-   .. code-block:: yaml
-
-      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``.
+Since languages in Spack are modeled as virtual packages, ``apple-clang`` will be used to provide
+C and C++, while GCC will be used for Fortran.
 
 ^^^^^^^^^^^^^^^^^^^^^
 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%gcc@5.3.0
+   $ spack install zlib-ng%gcc@5.3.0
 
 
 .. _vendor-specific-compiler-configuration:
@@ -707,9 +620,7 @@ simple package.  For example:
 Vendor-Specific Compiler Configuration
 --------------------------------------
 
-With Spack, things usually "just work" with GCC.  Not so for other
-compilers.  This section provides details on how to get specific
-compilers working.
+This section provides details on how to get vendor-specific compilers working.
 
 ^^^^^^^^^^^^^^^
 Intel Compilers
@@ -731,8 +642,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-name``
-      or ``-gxx-name`` compiler option to specify the path to the version of
+      version on your system, you need to use either the ``--gcc-install-dir``
+      or ``--gcc-toolchain`` 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>`_
@@ -740,76 +651,12 @@ 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
-
-
 ^^^
 NAG
 ^^^
 
-The Numerical Algorithms Group provides a licensed Fortran compiler. Like Clang,
-this requires you to set up a :ref:`mixed-toolchains`. It is recommended to use
-GCC for your C/C++ compilers.
+The Numerical Algorithms Group provides a licensed Fortran compiler.
+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:
@@ -826,44 +673,40 @@ the command line:
 
    $ spack install openmpi fflags="-mismatch"
 
-Or it can be set permanently in your ``compilers.yaml``:
+Or it can be set permanently in your ``packages.yaml``:
 
 .. code-block:: yaml
 
-   - compiler:
-    modules: []
-    operating_system: centos6
-    paths:
-      cc: /soft/spack/opt/spack/linux-x86_64/gcc-5.3.0/gcc-6.1.0-q2zosj3igepi3pjnqt74bwazmptr5gpj/bin/gcc
-      cxx: /soft/spack/opt/spack/linux-x86_64/gcc-5.3.0/gcc-6.1.0-q2zosj3igepi3pjnqt74bwazmptr5gpj/bin/g++
-      f77: /soft/spack/opt/spack/linux-x86_64/gcc-4.4.7/nag-6.1-jt3h5hwt5myezgqguhfsan52zcskqene/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
-
+   packages:
+     nag:
+       externals:
+       - spec: nag@6.1
+         prefix: /opt/nag/bin
+         extra_attributes:
+           compilers:
+             fortran: /opt/nag/bin/nagfor
+         flags:
+           fflags: -mismatch
 
 ---------------
 System Packages
 ---------------
 
-Once compilers are configured, one needs to determine which
-pre-installed system packages, if any, to use in builds.  This is
-configured in the file ``~/.spack/packages.yaml``.  For example, to use
-an OpenMPI installed in /opt/local, one would use:
+Once compilers are configured, one needs to determine which pre-installed system packages,
+if any, to use in builds.  These are also configured in the ``~/.spack/packages.yaml`` file.
+For example, to use an OpenMPI installed in /opt/local, one would use:
 
 .. code-block:: yaml
 
-    packages:
-        openmpi:
-            externals:
-            - spec: openmpi@1.10.1
-              prefix: /opt/local
-            buildable: False
+   packages:
+     openmpi:
+       buildable: False
+       externals:
+       - spec: openmpi@1.10.1
+         prefix: /opt/local
 
-In general, Spack is easier to use and more reliable if it builds all of
-its own dependencies.  However, there are several packages for which one
-commonly needs to use system versions:
+In general, *Spack is easier to use and more reliable if it builds all of its own dependencies*.
+However, there are several packages for which one commonly needs to use system versions:
 
 ^^^
 MPI
@@ -876,8 +719,7 @@ 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; see above on
-``compilers.yaml``.
+pre-installed compiler used to build that MPI.
 
 ^^^^^^^
 OpenSSL
@@ -1441,9 +1283,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 ``compilers.yaml`` file. On a fresh Windows install with the above packages
+containing a ``packages.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 ``compilers.yaml``
+compiler will be integrated within the first version of MSVC present in the ``packages.yaml``
 output.
 
 Spack provides a default ``config.yaml`` file for Windows that it will use unless overridden.

lib/spack/docs/gpu_configuration.rst

@@ -23,7 +23,6 @@ components for use by dependent packages:
 
    packages:
      all:
-       compiler: [rocmcc@=5.3.0]
        variants: amdgpu_target=gfx90a
      hip:
        buildable: false
@@ -70,16 +69,15 @@ This is in combination with the following compiler definition:
 
 .. code-block:: yaml
 
-   compilers:
-   - compiler:
-       spec: rocmcc@=5.3.0
-       paths:
-         cc: /opt/rocm-5.3.0/bin/amdclang
-         cxx: /opt/rocm-5.3.0/bin/amdclang++
-         f77: null
-         fc: /opt/rocm-5.3.0/bin/amdflang
-       operating_system: rhel8
-       target: x86_64
+   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
+           cxx: /opt/rocm-5.3.0/bin/amdclang++
+           fortran: null
 
 This includes the following considerations:
 

lib/spack/docs/include_yaml.rst

@@ -0,0 +1,65 @@
+.. 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

@@ -71,6 +71,7 @@ or refer to the full manual below.
 
    configuration
    config_yaml
+   include_yaml
    packages_yaml
    build_settings
    environments

lib/spack/docs/packages_yaml.rst

@@ -486,6 +486,8 @@ present. For instance with a configuration like:
 
 you will use ``mvapich2~cuda %gcc`` as an ``mpi`` provider.
 
+.. _package-strong-preferences:
+
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Conflicts and strong preferences
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -555,14 +557,13 @@ preferences.
    FAQ: :ref:`Why does Spack pick particular versions and variants? <faq-concretizer-precedence>`
 
 
-Most package preferences (``compilers``, ``target`` and ``providers``)
+The ``target`` and ``providers`` preferences
 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/pipelines.rst

@@ -330,7 +330,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}/{compiler.name}-{compiler.version}/{name}-{version}-{hash}'"
+          - spack config add "config:install_tree:projections:${SPACK_JOB_SPEC_PKG_NAME}:'morepadding/{architecture.platform}-{architecture.target}/{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

lib/spack/docs/requirements.txt

@@ -1,13 +1,13 @@
-sphinx==8.2.0
+sphinx==8.2.3
 sphinxcontrib-programoutput==0.18
 sphinx_design==0.6.1
 sphinx-rtd-theme==3.0.2
-python-levenshtein==0.26.1
+python-levenshtein==0.27.1
 docutils==0.21.2
 pygments==2.19.1
 urllib3==2.3.0
-pytest==8.3.4
-isort==6.0.0
+pytest==8.3.5
+isort==6.0.1
 black==25.1.0
 flake8==7.1.2
 mypy==1.11.1

lib/spack/env/aocc/clang

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

lib/spack/env/aocc/clang++

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

lib/spack/env/aocc/flang

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

lib/spack/env/arm/armclang

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

lib/spack/env/arm/armclang++

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

lib/spack/env/arm/armflang

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

lib/spack/env/c++

@@ -1 +0,0 @@
-cc

lib/spack/env/c89

@@ -1 +0,0 @@
-cc

lib/spack/env/c99

@@ -1 +0,0 @@
-cc

lib/spack/env/case-insensitive/CC

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

lib/spack/env/cce/case-insensitive/CC

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

lib/spack/env/cce/case-insensitive/crayCC

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

lib/spack/env/cce/cc

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

lib/spack/env/cce/craycc

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

lib/spack/env/cce/crayftn

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

lib/spack/env/cce/ftn

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

lib/spack/env/clang/clang

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

lib/spack/env/clang/clang++

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

lib/spack/env/clang/flang

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

lib/spack/env/clang/gfortran

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

lib/spack/env/cpp

@@ -1 +0,0 @@
-cc

lib/spack/env/f77

@@ -1 +0,0 @@
-cc

lib/spack/env/f90

@@ -1 +0,0 @@
-cc

lib/spack/env/f95

@@ -1 +0,0 @@
-cc

lib/spack/env/fc

@@ -1 +0,0 @@
-cc

lib/spack/env/fj/case-insensitive/FCC

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

lib/spack/env/fj/fcc

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

lib/spack/env/fj/frt

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

lib/spack/env/ftn

@@ -1 +0,0 @@
-cc

lib/spack/env/gcc/g++

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

lib/spack/env/gcc/gcc

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

lib/spack/env/gcc/gfortran

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

lib/spack/env/intel/icc

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

lib/spack/env/intel/icpc

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

lib/spack/env/intel/ifort

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

lib/spack/env/ld

@@ -1 +0,0 @@
-cc

lib/spack/env/ld.gold

@@ -1 +0,0 @@
-cc

lib/spack/env/ld.lld

@@ -1 +0,0 @@
-cc

lib/spack/env/nag/nagfor

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

lib/spack/env/nvhpc/nvc

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

lib/spack/env/nvhpc/nvc++

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

lib/spack/env/nvhpc/nvfortran

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

lib/spack/env/oneapi/dpcpp

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

lib/spack/env/oneapi/icpx

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

lib/spack/env/oneapi/icx

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

lib/spack/env/oneapi/ifx

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

lib/spack/env/pgi/pgc++

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

lib/spack/env/pgi/pgcc

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

lib/spack/env/pgi/pgfortran

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

lib/spack/env/rocmcc/amdclang

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

lib/spack/env/rocmcc/amdclang++

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

lib/spack/env/rocmcc/amdflang

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

lib/spack/env/xl/xlc

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

lib/spack/env/xl/xlc++

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

lib/spack/env/xl/xlf

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

lib/spack/env/xl/xlf90

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

lib/spack/env/xl_r/xlc++_r

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

lib/spack/env/xl_r/xlc_r

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

lib/spack/env/xl_r/xlf90_r

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

lib/spack/env/xl_r/xlf_r

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

lib/spack/llnl/util/filesystem.py

@@ -7,6 +7,7 @@
 import fnmatch
 import glob
 import hashlib
+import io
 import itertools
 import numbers
 import os
@@ -20,6 +21,7 @@
 from contextlib import contextmanager
 from itertools import accumulate
 from typing import (
+    IO,
     Callable,
     Deque,
     Dict,
@@ -2454,26 +2456,69 @@ class WindowsSimulatedRPath:
     and vis versa.
     """
 
-    def __init__(self, package, link_install_prefix=True):
+    def __init__(
+        self,
+        package,
+        base_modification_prefix: Optional[Union[str, pathlib.Path]] = None,
+        link_install_prefix: bool = True,
+    ):
         """
         Args:
             package (spack.package_base.PackageBase): Package requiring links
+            base_modification_prefix (str|pathlib.Path): Path representation indicating
+                the root directory in which to establish the simulated rpath, ie where the
+                symlinks that comprise the "rpath" behavior will be installed.
+
+                Note: This is a mutually exclusive option with `link_install_prefix` using
+                both is an error.
+
+                Default: None
             link_install_prefix (bool): Link against package's own install or stage root.
                 Packages that run their own executables during build and require rpaths to
-                the build directory during build time require this option. Default: install
+                the build directory during build time require this option.
+
+                Default: install
                 root
+
+                Note: This is a mutually exclusive option with `base_modification_prefix`, using
+                both is an error.
         """
         self.pkg = package
-        self._addl_rpaths = set()
+        self._addl_rpaths: set[str] = set()
+        if link_install_prefix and base_modification_prefix:
+            raise RuntimeError(
+                "Invalid combination of arguments given to WindowsSimulated RPath.\n"
+                "Select either `link_install_prefix` to create an install prefix rpath"
+                " or specify a `base_modification_prefix` for any other link type. "
+                "Specifying both arguments is invalid."
+            )
+        if not (link_install_prefix or base_modification_prefix):
+            raise RuntimeError(
+                "Insufficient arguments given to WindowsSimulatedRpath.\n"
+                "WindowsSimulatedRPath requires one of link_install_prefix"
+                " or base_modification_prefix to be specified."
+                " Neither was provided."
+            )
+
         self.link_install_prefix = link_install_prefix
-        self._additional_library_dependents = set()
+        if base_modification_prefix:
+            self.base_modification_prefix = pathlib.Path(base_modification_prefix)
+        else:
+            self.base_modification_prefix = pathlib.Path(self.pkg.prefix)
+        self._additional_library_dependents: set[pathlib.Path] = set()
+        if not self.link_install_prefix:
+            tty.debug(f"Generating rpath for non install context: {base_modification_prefix}")
 
     @property
     def library_dependents(self):
         """
         Set of directories where package binaries/libraries are located.
         """
-        return set([pathlib.Path(self.pkg.prefix.bin)]) | self._additional_library_dependents
+        base_pths = set()
+        if self.link_install_prefix:
+            base_pths.add(pathlib.Path(self.pkg.prefix.bin))
+        base_pths |= self._additional_library_dependents
+        return base_pths
 
     def add_library_dependent(self, *dest):
         """
@@ -2489,6 +2534,12 @@ def add_library_dependent(self, *dest):
                 new_pth = pathlib.Path(pth).parent
             else:
                 new_pth = pathlib.Path(pth)
+            path_is_in_prefix = new_pth.is_relative_to(self.base_modification_prefix)
+            if not path_is_in_prefix:
+                raise RuntimeError(
+                    f"Attempting to generate rpath symlink out of rpath context:\
+{str(self.base_modification_prefix)}"
+                )
             self._additional_library_dependents.add(new_pth)
 
     @property
@@ -2577,6 +2628,33 @@ def establish_link(self):
                 self._link(library, lib_dir)
 
 
+def make_package_test_rpath(pkg, test_dir: Union[str, pathlib.Path]):
+    """Establishes a temp Windows simulated rpath for the pkg in the testing directory
+    so an executable can test the libraries/executables with proper access
+    to dependent dlls
+
+    Note: this is a no-op on all other platforms besides Windows
+
+    Args:
+        pkg (spack.package_base.PackageBase): the package for which the rpath should be computed
+        test_dir: the testing directory in which we should construct an rpath
+    """
+    # link_install_prefix as false ensures we're not linking into the install prefix
+    mini_rpath = WindowsSimulatedRPath(pkg, link_install_prefix=False)
+    # add the testing directory as a location to install rpath symlinks
+    mini_rpath.add_library_dependent(test_dir)
+
+    # check for whether build_directory is available, if not
+    # assume the stage root is the build dir
+    build_dir_attr = getattr(pkg, "build_directory", None)
+    build_directory = build_dir_attr if build_dir_attr else pkg.stage.path
+    # add the build dir & build dir bin
+    mini_rpath.add_rpath(os.path.join(build_directory, "bin"))
+    mini_rpath.add_rpath(os.path.join(build_directory))
+    # construct rpath
+    mini_rpath.establish_link()
+
+
 @system_path_filter
 @memoized
 def can_access_dir(path):
@@ -2805,6 +2883,20 @@ def keep_modification_time(*filenames):
             os.utime(f, (os.path.getatime(f), mtime))
 
 
+@contextmanager
+def temporary_file_position(stream):
+    orig_pos = stream.tell()
+    yield
+    stream.seek(orig_pos)
+
+
+@contextmanager
+def current_file_position(stream: IO[str], loc: int, relative_to=io.SEEK_CUR):
+    with temporary_file_position(stream):
+        stream.seek(loc, relative_to)
+        yield
+
+
 @contextmanager
 def temporary_dir(
     suffix: Optional[str] = None, prefix: Optional[str] = None, dir: Optional[str] = None

lib/spack/llnl/util/lang.py

@@ -11,10 +11,11 @@
 import re
 import sys
 import traceback
+import types
 import typing
 import warnings
 from datetime import datetime, timedelta
-from typing import Callable, Dict, Iterable, List, Tuple, TypeVar
+from typing import Callable, Dict, Iterable, List, Mapping, Optional, Tuple, TypeVar
 
 # Ignore emacs backups when listing modules
 ignore_modules = r"^\.#|~$"
@@ -72,7 +73,7 @@ def index_by(objects, *funcs):
     if isinstance(f, str):
         f = lambda x: getattr(x, funcs[0])
     elif isinstance(f, tuple):
-        f = lambda x: tuple(getattr(x, p) for p in funcs[0])
+        f = lambda x: tuple(getattr(x, p, None) for p in funcs[0])
 
     result = {}
     for o in objects:
@@ -707,14 +708,24 @@ def __init__(self, wrapped_object):
 
 
 class Singleton:
-    """Simple wrapper for lazily initialized singleton objects."""
+    """Wrapper for lazily initialized singleton objects."""
 
-    def __init__(self, factory):
+    def __init__(self, factory: Callable[[], object]):
         """Create a new singleton to be inited with the factory function.
 
+        Most factories will simply create the object to be initialized and
+        return it.
+
+        In some cases, e.g. when bootstrapping some global state, the singleton
+        may need to be initialized incrementally. If the factory returns a generator
+        instead of a regular object, the singleton will assign each result yielded by
+        the generator to the singleton instance. This allows methods called by
+        the factory in later stages to refer back to the singleton.
+
         Args:
-            factory (function): function taking no arguments that
-                creates the singleton instance.
+            factory (function): function taking no arguments that creates the
+                singleton instance.
+
         """
         self.factory = factory
         self._instance = None
@@ -722,7 +733,16 @@ def __init__(self, factory):
     @property
     def instance(self):
         if self._instance is None:
-            self._instance = self.factory()
+            instance = self.factory()
+
+            if isinstance(instance, types.GeneratorType):
+                # if it's a generator, assign every value
+                for value in instance:
+                    self._instance = value
+            else:
+                # if not, just assign the result like a normal singleton
+                self._instance = instance
+
         return self._instance
 
     def __getattr__(self, name):
@@ -996,11 +1016,8 @@ def _receive_forwarded(self, context: str, exc: Exception, tb: List[str]):
     def grouped_message(self, with_tracebacks: bool = True) -> str:
         """Print out an error message coalescing all the forwarded errors."""
         each_exception_message = [
-            "{0} raised {1}: {2}{3}".format(
-                context,
-                exc.__class__.__name__,
-                exc,
-                "\n{0}".format("".join(tb)) if with_tracebacks else "",
+            "\n\t{0} raised {1}: {2}\n{3}".format(
+                context, exc.__class__.__name__, exc, f"\n{''.join(tb)}" if with_tracebacks else ""
             )
             for context, exc, tb in self.exceptions
         ]
@@ -1080,3 +1097,88 @@ def __set__(self, instance, value):
 
     def factory(self, instance, owner):
         raise NotImplementedError("must be implemented by derived classes")
+
+
+KT = TypeVar("KT")
+VT = TypeVar("VT")
+
+
+class PriorityOrderedMapping(Mapping[KT, VT]):
+    """Mapping that iterates over key according to an integer priority. If the priority is
+    the same for two keys, insertion order is what matters.
+
+    The priority is set when the key/value pair is added. If not set, the highest current priority
+    is used.
+    """
+
+    _data: Dict[KT, VT]
+    _priorities: List[Tuple[int, KT]]
+
+    def __init__(self) -> None:
+        self._data = {}
+        # Tuple of (priority, key)
+        self._priorities = []
+
+    def __getitem__(self, key: KT) -> VT:
+        return self._data[key]
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    def __iter__(self):
+        yield from (key for _, key in self._priorities)
+
+    def __reversed__(self):
+        yield from (key for _, key in reversed(self._priorities))
+
+    def reversed_keys(self):
+        """Iterates over keys from the highest priority, to the lowest."""
+        return reversed(self)
+
+    def reversed_values(self):
+        """Iterates over values from the highest priority, to the lowest."""
+        yield from (self._data[key] for _, key in reversed(self._priorities))
+
+    def _highest_priority(self) -> int:
+        if not self._priorities:
+            return 0
+        result, _ = self._priorities[-1]
+        return result
+
+    def add(self, key: KT, *, value: VT, priority: Optional[int] = None) -> None:
+        """Adds a key/value pair to the mapping, with a specific priority.
+
+        If the priority is None, then it is assumed to be the highest priority value currently
+        in the container.
+
+        Raises:
+              ValueError: when the same priority is already in the mapping
+        """
+        if priority is None:
+            priority = self._highest_priority()
+
+        if key in self._data:
+            self.remove(key)
+
+        self._priorities.append((priority, key))
+        # We rely on sort being stable
+        self._priorities.sort(key=lambda x: x[0])
+        self._data[key] = value
+        assert len(self._data) == len(self._priorities)
+
+    def remove(self, key: KT) -> VT:
+        """Removes a key from the mapping.
+
+        Returns:
+            The value associated with the key being removed
+
+        Raises:
+            KeyError: if the key is not in the mapping
+        """
+        if key not in self._data:
+            raise KeyError(f"cannot find {key}")
+
+        popped_item = self._data.pop(key)
+        self._priorities = [(p, k) for p, k in self._priorities if k != key]
+        assert len(self._data) == len(self._priorities)
+        return popped_item

lib/spack/spack/__init__.py

@@ -13,6 +13,18 @@
 __version__ = "1.0.0.dev0"
 spack_version = __version__
 
+#: The current Package API version implemented by this version of Spack. The Package API defines
+#: the Python interface for packages as well as the layout of package repositories. The minor
+#: version is incremented when the package API is extended in a backwards-compatible way. The major
+#: version is incremented upon breaking changes. This version is changed independently from the
+#: Spack version.
+package_api_version = (1, 0)
+
+#: The minimum Package API version that this version of Spack is compatible with. This should
+#: always be a tuple of the form ``(major, 0)``, since compatibility with vX.Y implies
+#: compatibility with vX.0.
+min_package_api_version = (1, 0)
+
 
 def __try_int(v):
     try:
@@ -79,4 +91,6 @@ def get_short_version() -> str:
     "get_version",
     "get_spack_commit",
     "get_short_version",
+    "package_api_version",
+    "min_package_api_version",
 ]

lib/spack/spack/aliases.py

@@ -0,0 +1,20 @@
+# Copyright Spack Project Developers. See COPYRIGHT file for details.
+#
+# SPDX-License-Identifier: (Apache-2.0 OR MIT)
+"""Alias names to convert legacy compilers to builtin packages and vice-versa"""
+
+BUILTIN_TO_LEGACY_COMPILER = {
+    "llvm": "clang",
+    "intel-oneapi-compilers": "oneapi",
+    "llvm-amdgpu": "rocmcc",
+    "intel-oneapi-compiler-classic": "intel",
+    "acfl": "arm",
+}
+
+LEGACY_COMPILER_TO_BUILTIN = {
+    "clang": "llvm",
+    "oneapi": "intel-oneapi-compilers",
+    "rocmcc": "llvm-amdgpu",
+    "intel": "intel-oneapi-compiler-classic",
+    "arm": "acfl",
+}

lib/spack/spack/binary_distribution.py

@@ -110,6 +110,13 @@ def __init__(self, root):
         self._write_transaction_impl = llnl.util.lang.nullcontext
         self._read_transaction_impl = llnl.util.lang.nullcontext
 
+    def _handle_old_db_versions_read(self, check, db, *, reindex: bool):
+        if not self.is_readable():
+            raise spack_db.DatabaseNotReadableError(
+                f"cannot read buildcache v{self.db_version} at {self.root}"
+            )
+        return self._handle_current_version_read(check, db)
+
 
 class FetchCacheError(Exception):
     """Error thrown when fetching the cache failed, usually a composite error list."""
@@ -242,7 +249,7 @@ def _associate_built_specs_with_mirror(self, cache_key, mirror_url):
                 self._index_file_cache.init_entry(cache_key)
                 cache_path = self._index_file_cache.cache_path(cache_key)
                 with self._index_file_cache.read_transaction(cache_key):
-                    db._read_from_file(cache_path)
+                    db._read_from_file(pathlib.Path(cache_path))
             except spack_db.InvalidDatabaseVersionError as e:
                 tty.warn(
                     f"you need a newer Spack version to read the buildcache index for the "

lib/spack/spack/bootstrap/_common.py

@@ -234,14 +234,6 @@ def _root_spec(spec_str: str) -> str:
     # Add a compiler and platform requirement to the root spec.
     platform = str(spack.platforms.host())
 
-    if platform == "darwin":
-        spec_str += " %apple-clang"
-    elif platform == "windows":
-        spec_str += " %msvc"
-    elif platform == "linux":
-        spec_str += " %gcc"
-    elif platform == "freebsd":
-        spec_str += " %clang"
     spec_str += f" platform={platform}"
     target = archspec.cpu.host().family
     spec_str += f" target={target}"

lib/spack/spack/bootstrap/clingo.py

@@ -15,11 +15,13 @@
 
 import archspec.cpu
 
-import spack.compiler
-import spack.compilers
+import spack.compilers.config
+import spack.compilers.libraries
+import spack.config
 import spack.platforms
 import spack.spec
 import spack.traverse
+import spack.version
 
 from .config import spec_for_current_python
 
@@ -38,7 +40,7 @@ def __init__(self, configuration):
 
         self.external_cmake, self.external_bison = self._externals_from_yaml(configuration)
 
-    def _valid_compiler_or_raise(self) -> "spack.compiler.Compiler":
+    def _valid_compiler_or_raise(self):
         if str(self.host_platform) == "linux":
             compiler_name = "gcc"
         elif str(self.host_platform) == "darwin":
@@ -46,17 +48,30 @@ def _valid_compiler_or_raise(self) -> "spack.compiler.Compiler":
         elif str(self.host_platform) == "windows":
             compiler_name = "msvc"
         elif str(self.host_platform) == "freebsd":
-            compiler_name = "clang"
+            compiler_name = "llvm"
         else:
             raise RuntimeError(f"Cannot bootstrap clingo from sources on {self.host_platform}")
-        candidates = spack.compilers.compilers_for_spec(
-            compiler_name, arch_spec=self.host_architecture
-        )
+
+        candidates = [
+            x
+            for x in spack.compilers.config.CompilerFactory.from_packages_yaml(spack.config.CONFIG)
+            if x.name == compiler_name
+        ]
         if not candidates:
             raise RuntimeError(
                 f"Cannot find any version of {compiler_name} to bootstrap clingo from sources"
             )
-        candidates.sort(key=lambda x: x.spec.version, reverse=True)
+        candidates.sort(key=lambda x: x.version, reverse=True)
+        best = candidates[0]
+        # Get compilers for bootstrapping from the 'builtin' repository
+        best.namespace = "builtin"
+        # If the compiler does not support C++ 14, fail with a legible error message
+        try:
+            _ = best.package.standard_flag(language="cxx", standard="14")
+        except RuntimeError as e:
+            raise RuntimeError(
+                "cannot find a compiler supporting C++ 14 [needed to bootstrap clingo]"
+            ) from e
         return candidates[0]
 
     def _externals_from_yaml(
@@ -75,9 +90,6 @@ def _externals_from_yaml(
                 if not s.satisfies(requirements[pkg_name]):
                     continue
 
-                if not s.intersects(f"%{self.host_compiler.spec}"):
-                    continue
-
                 if not s.intersects(f"arch={self.host_architecture}"):
                     continue
 
@@ -110,11 +122,14 @@ def concretize(self) -> "spack.spec.Spec":
         # Tweak it to conform to the host architecture
         for node in s.traverse():
             node.architecture.os = str(self.host_os)
-            node.compiler = self.host_compiler.spec
             node.architecture = self.host_architecture
 
             if node.name == "gcc-runtime":
-                node.versions = self.host_compiler.spec.versions
+                node.versions = self.host_compiler.versions
+
+        # Can't use re2c@3.1 with Python 3.6
+        if self.host_python.satisfies("@3.6"):
+            s["re2c"].versions.versions = [spack.version.from_string("=2.2")]
 
         for edge in spack.traverse.traverse_edges([s], cover="edges"):
             if edge.spec.name == "python":
@@ -126,6 +141,9 @@ def concretize(self) -> "spack.spec.Spec":
             if edge.spec.name == "cmake" and self.external_cmake:
                 edge.spec = self.external_cmake
 
+            if edge.spec.name == self.host_compiler.name:
+                edge.spec = self.host_compiler
+
             if "libc" in edge.virtuals:
                 edge.spec = self.host_libc
 
@@ -141,12 +159,12 @@ def python_external_spec(self) -> "spack.spec.Spec":
         return self._external_spec(result)
 
     def libc_external_spec(self) -> "spack.spec.Spec":
-        result = self.host_compiler.default_libc
+        detector = spack.compilers.libraries.CompilerPropertyDetector(self.host_compiler)
+        result = detector.default_libc()
         return self._external_spec(result)
 
     def _external_spec(self, initial_spec) -> "spack.spec.Spec":
         initial_spec.namespace = "builtin"
-        initial_spec.compiler = self.host_compiler.spec
         initial_spec.architecture = self.host_architecture
         for flag_type in spack.spec.FlagMap.valid_compiler_flags():
             initial_spec.compiler_flags[flag_type] = []

lib/spack/spack/bootstrap/config.py

@@ -10,7 +10,7 @@
 
 from llnl.util import tty
 
-import spack.compilers
+import spack.compilers.config
 import spack.config
 import spack.environment
 import spack.modules
@@ -142,8 +142,8 @@ def _bootstrap_config_scopes() -> Sequence["spack.config.ConfigScope"]:
 
 def _add_compilers_if_missing() -> None:
     arch = spack.spec.ArchSpec.default_arch()
-    if not spack.compilers.compilers_for_arch(arch):
-        spack.compilers.find_compilers()
+    if not spack.compilers.config.compilers_for_arch(arch):
+        spack.compilers.config.find_compilers()
 
 
 @contextlib.contextmanager