Update documentation after compiler as deps (#49715)

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

lib/spack/docs/configuration.rst

@@ -11,7 +11,7 @@ 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>`
@@ -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``, ``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

@@ -686,7 +686,7 @@ the environment.
    spack:
      include:
      - environment/relative/path/to/config.yaml
-     - https://github.com/path/to/raw/config/compilers.yaml
+     - https://github.com/path/to/raw/config/packages.yaml
      - /absolute/path/to/packages.yaml
      - path: /path/to/$os/$target/environment
        optional: true

lib/spack/docs/getting_started.rst

@@ -254,12 +254,11 @@ directory.
 Compiler configuration
 ----------------------
 
-Spack has the ability to build packages with multiple compilers and
+Spack has the ability to build packages with multiple compilers and compiler versions.
-compiler versions. Compilers can be made available to Spack by
+Compilers can be made available to Spack by specifying them manually in ``packages.yaml``,
-specifying them manually in ``compilers.yaml`` or ``packages.yaml``,
+or automatically by running ``spack compiler find``.
-or automatically by running ``spack compiler find``, but for
+For convenience, Spack will automatically detect compilers the first time it needs them,
-convenience Spack will automatically detect compilers the first time
+if none is available.
-it needs them.
 
 .. _cmd-spack-compilers:
 
@@ -274,16 +273,11 @@ compilers`` or ``spack compiler list``:
 
    $ spack compilers
    ==> Available compilers
-   -- gcc ---------------------------------------------------------
+   -- gcc ubuntu20.04-x86_64 ---------------------------------------
-       gcc@4.9.0  gcc@4.8.0  gcc@4.7.0  gcc@4.6.2  gcc@4.4.7
+   gcc@9.4.0  gcc@8.4.0  gcc@10.5.0
-       gcc@4.8.2  gcc@4.7.1  gcc@4.6.3  gcc@4.6.1  gcc@4.1.2
+
-   -- intel -------------------------------------------------------
+   -- llvm ubuntu20.04-x86_64 --------------------------------------
-       intel@15.0.0  intel@14.0.0  intel@13.0.0  intel@12.1.0  intel@10.0
+   llvm@12.0.0  llvm@11.0.0  llvm@10.0.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
 
 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
+If you do not see a compiler in the list shown by:
-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 find /usr/local/tools/ic-13.0.079
+   $ spack compiler list
-   ==> Added 1 new compiler to ~/.spack/linux/compilers.yaml
+
-       intel@13.0.079
+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
+If you want to see additional information on some specific compilers, you can run ``spack compiler info`` on it:
-``spack compiler info`` on it:
 
 .. code-block:: console
 
-   $ spack compiler info intel@15
+   $ spack compiler info gcc
-   intel@15.0.0:
+   gcc@=8.4.0 languages='c,c++,fortran' arch=linux-ubuntu20.04-x86_64:
-     paths:
+     prefix: /usr
-       cc  = /usr/local/bin/icc-15.0.090
+     compilers:
-       cxx = /usr/local/bin/icpc-15.0.090
+       c: /usr/bin/gcc-8
-       f77 = /usr/local/bin/ifort-15.0.090
+       cxx: /usr/bin/g++-8
-       fc  = /usr/local/bin/ifort-15.0.090
+       fortran: /usr/bin/gfortran-8
-     modules = []
-     operating_system = centos6
-   ...
 
-This shows which C, C++, and Fortran compilers were detected by Spack.
+   gcc@=9.4.0 languages='c,c++,fortran' arch=linux-ubuntu20.04-x86_64:
-Notice also that we didn't have to be too specific about the
+     prefix: /usr
-version. We just said ``intel@15``, and information about the only
+     compilers:
-matching Intel compiler was displayed.
+       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
+If auto-detection fails, you can manually configure a compiler by editing your ``~/.spack/packages.yaml`` file.
-editing your ``~/.spack/<platform>/compilers.yaml`` file.  You can do this by running
+You can do this by running ``spack config edit packages``, which will open the file in
-``spack config edit compilers``, 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:
+   packages:
-   - compiler:
+     gcc:
-       modules: []
+       externals:
-       operating_system: centos6
+       - spec: gcc@10.5.0 languages='c,c++,fortran'
-       paths:
+         prefix: /usr
-         cc: /usr/local/bin/icc-15.0.024-beta
+         extra_attributes:
-         cxx: /usr/local/bin/icpc-15.0.024-beta
+           compilers:
-         f77: /usr/local/bin/ifort-15.0.024-beta
+             c: /usr/bin/gcc-10
-         fc: /usr/local/bin/ifort-15.0.024-beta
+             cxx: /usr/bin/g++-10
-       spec: intel@15.0.0
+             fortran: /usr/bin/gfortran-10
 
-For compilers that do not support Fortran (like ``clang``), put
+The compiler executables are listed under ``extra_attributes:compilers``, and are keyed by language.
-``None`` for ``f77`` and ``fc``:
+Once you save the file, the configured compilers will show up in the list displayed by ``spack compilers``.
 
-.. code-block:: yaml
+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``,
-   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
 
-   compilers:
+   packages:
-   - compiler:
+     gcc:
-       modules: []
+       externals:
-       operating_system: centos6
+       - spec: gcc@10.5.0 languages='c,c++,fortran'
-       paths:
+         prefix: /usr
-         cc: /usr/bin/gcc
+         extra_attributes:
-         cxx: /usr/bin/g++
+           compilers:
-         f77: /usr/bin/gfortran
+             c: /usr/bin/gcc-10
-         fc: /usr/bin/gfortran
+             cxx: /usr/bin/g++-10
-       flags:
+             fortran: /usr/bin/gfortran-10
-         cflags: -O3 -fPIC
+           flags:
-         cxxflags: -O3 -fPIC
+             cflags: -O3 -fPIC
-         cppflags: -O3 -fPIC
+             cxxflags: -O3 -fPIC
-       spec: gcc@4.7.2
+             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:
+     intel-oneapi-compilers:
-       external:
+       externals:
-       - spec: gcc@12.2.0 arch=linux-rhel8-skylake
+       - spec: intel-oneapi-compilers@2025.1.0
-         prefix: /usr
+         prefix: /opt/intel/oneapi
-         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
+             c: /opt/intel/oneapi/compiler/2025.1/bin/icx
-             cxx: /usr/bin/clang++-with-extra-info
+             cxx: /opt/intel/oneapi/compiler/2025.1/bin/icpx
-             fortran: /usr/bin/gfortran
+             fortran: /opt/intel/oneapi/compiler/2025.1/bin/ifx
-           extra_rpaths:
+           environment:
-           - /usr/lib/llvm/
+             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
+If you are particular about which compiler/version you use, you might wish to have Spack build it for you.
-wish to have Spack build it for you.  For example:
+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
+Once the compiler is installed, you can start using it without additional configuration:
-``compilers.yaml`` file.  You can then set Spack to use it by default
-by adding the following to your ``packages.yaml`` file:
 
-.. code-block:: yaml
+.. code-block:: console
 
-   packages:
+   $ spack install hdf5~mpi %gcc@14
-     all:
+
-       compiler: [gcc@4.9.3]
+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
+Many installed compilers will work regardless of the environment they are called with.
-are called with.  However, some installed compilers require
+However, some installed compilers require environment variables to be set in order to run;
-``$LD_LIBRARY_PATH`` or other environment variables to be set in order
+this is typical for Intel and other proprietary compilers.
-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
+On typical HPC clusters, these environment modifications are usually delegated to some "module" system.
-to run the chosen compiler (If the compiler does not come with a
+In such a case, you should tell Spack which module(s) to load in order to run the chosen compiler:
-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
 
-   compilers:
+   packages:
-   - compiler:
+     gcc:
-       modules: [other/comp/gcc-5.3-sp3]
+       externals:
-       operating_system: SuSE11
+       - spec: gcc@10.5.0 languages='c,c++,fortran'
-       paths:
+         prefix: /opt/compilers
-         cc: /usr/local/other/SLES11.3/gcc/5.3.0/bin/gcc
+         extra_attributes:
-         cxx: /usr/local/other/SLES11.3/gcc/5.3.0/bin/g++
+           compilers:
-         f77: /usr/local/other/SLES11.3/gcc/5.3.0/bin/gfortran
+             c: /opt/compilers/bin/gcc-10
-         fc: /usr/local/other/SLES11.3/gcc/5.3.0/bin/gfortran
+             cxx: /opt/compilers/bin/g++-10
-       spec: gcc@5.3.0
+             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
+#. Add the newly-installed compiler to ``packages.yaml`` as shown above.
-   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
+In some cases, this is not possible.  For example, XCode on macOS provides no Fortran compilers.
-Capitan (10.11), many packages no longer build with GCC, but XCode
+The user is therefore forced to use a mixed toolchain: XCode-provided Clang for C/C++ and e.g.
-provides no Fortran compilers.  The user is therefore forced to use a
+GNU ``gfortran`` for Fortran.
-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:
 
@@ -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
+#. Run ``spack compiler find`` to locate both Apple-Clang and GCC.
-   the path to ``gfortran``:
 
-   .. code-block:: yaml
+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.
-      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
+You can verify that your compilers are configured properly by installing a simple package. For example:
-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
+This section provides details on how to get vendor-specific compilers working.
-compilers.  This section provides details on how to get 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``
+      version on your system, you need to use either the ``--gcc-install-dir``
-      or ``-gxx-name`` compiler option to specify the path to the version of
+      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,
+The Numerical Algorithms Group provides a licensed Fortran compiler.
-this requires you to set up a :ref:`mixed-toolchains`. It is recommended to use
+It is recommended to use GCC for your C/C++ compilers.
-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:
+   packages:
-    modules: []
+     nag:
-    operating_system: centos6
+       externals:
-    paths:
+       - spec: nag@6.1
-      cc: /soft/spack/opt/spack/linux-x86_64/gcc-5.3.0/gcc-6.1.0-q2zosj3igepi3pjnqt74bwazmptr5gpj/bin/gcc
+         prefix: /opt/nag/bin
-      cxx: /soft/spack/opt/spack/linux-x86_64/gcc-5.3.0/gcc-6.1.0-q2zosj3igepi3pjnqt74bwazmptr5gpj/bin/g++
+         extra_attributes:
-      f77: /soft/spack/opt/spack/linux-x86_64/gcc-4.4.7/nag-6.1-jt3h5hwt5myezgqguhfsan52zcskqene/bin/nagfor
+           compilers:
-      fc: /soft/spack/opt/spack/linux-x86_64/gcc-4.4.7/nag-6.1-jt3h5hwt5myezgqguhfsan52zcskqene/bin/nagfor
+             fortran: /opt/nag/bin/nagfor
-    flags:
+         flags:
-      fflags: -mismatch
+           fflags: -mismatch
-    spec: nag@6.1
-
 
 ---------------
 System Packages
 ---------------
 
-Once compilers are configured, one needs to determine which
+Once compilers are configured, one needs to determine which pre-installed system packages,
-pre-installed system packages, if any, to use in builds.  This is
+if any, to use in builds.  These are also configured in the ``~/.spack/packages.yaml`` file.
-configured in the file ``~/.spack/packages.yaml``.  For example, to use
+For example, to use an OpenMPI installed in /opt/local, one would use:
-an OpenMPI installed in /opt/local, one would use:
 
 .. code-block:: yaml
 
-    packages:
+   packages:
-        openmpi:
+     openmpi:
-            externals:
+       buildable: False
-            - spec: openmpi@1.10.1
+       externals:
-              prefix: /opt/local
+       - spec: openmpi@1.10.1
-            buildable: False
+         prefix: /opt/local
 
-In general, Spack is easier to use and more reliable if it builds all of
+In general, *Spack is easier to use and more reliable if it builds all of its own dependencies*.
-its own dependencies.  However, there are several packages for which one
+However, there are several packages for which one commonly needs to use system versions:
-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
+pre-installed compiler used to build that MPI.
-``compilers.yaml``.
 
 ^^^^^^^
 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.