Update docs NewSiteConfigs.rst for spack v1

doc/source/MaintainersSection.rst

@@ -129,7 +129,7 @@ Pre-configuring sites
 Preface/general instructions
 ------------------------------
 
-Preconfigured sites are defined through spack configuration files in the spack-stack directory ``configs/sites``, for example ``configs/sites/orion``. All files in the site-specific subdirectory will be copied into the environment into ``envs/env-name/site``. Site-specific configurations consist of general definitions (``config.yaml``), packages (``packages.yaml``, ``packages_*.yaml``), compilers (``compilers.yaml``), modules (``modules.yaml``), mirrors (``mirrors.yaml``) etc. These configurations overwrite the common configurations that are copied from ``configs/common`` into ``envs/env-name/common``.
+Preconfigured sites are defined through spack configuration files in the spack-stack directory ``configs/sites``, for example ``configs/sites/orion``. All files in the site-specific subdirectory will be copied into the environment into ``envs/env-name/site``. Site-specific configurations consist of general definitions (``config.yaml``), packages (``packages.yaml``, ``packages_*.yaml``), compilers, modules (``modules.yaml``), mirrors (``mirrors.yaml``) etc. These configurations overwrite the common configurations that are copied from ``configs/common`` into ``envs/env-name/common``.
 
 The instructions below are platform-specific tasks that only need to be done once and can be reused for new spack environments. To build new environments on preconfigured platforms, follow the instructions in :numref:`Section %s <Preconfigured_Sites_ExtendingEnvironments>`.
 

doc/source/NewSiteConfigs.rst

@@ -282,35 +282,30 @@ Remember to activate the ``lua`` module environment and have MacTeX in your sear
 
   spack config --scope system add packages:pkg-config:buildable:false  # Intel based Mac only
 
-5. Find compilers, add to site config's ``compilers.yaml``
+5. Find compilers, add to ``site/packages.yaml`` as externals
 
 .. code-block:: console
 
    spack compiler find --scope system
 
 .. _apple-clang-15-workaround:
 .. note::
-  When using apple-clang@15.x (or newer) compilers, you need to manually add the following ldflags spec in the `site/compilers.yaml` file.
+  When using apple-clang@15.x (or newer) compilers, you need to manually add the following ldflags spec in the `site/packages.yaml` file.
   There are known issues with new features in the Apple linker/loader that comes with the 15.x compiler set, and this change tells the linker/loader to use its legacy features which work fine.
 
 .. code-block:: yaml
   :emphasize-lines: 9,10
 
-  compilers:
-  - compiler:
-      spec: apple-clang@=15.0.0
-      paths:
-        cc: /usr/bin/clang
-        cxx: /usr/bin/clang++
-        f77: /opt/homebrew/bin/gfortran-12
-        fc: /opt/homebrew/bin/gfortran-12
-      flags:
-        ldflags: '-Wl,-ld_classic'         # Add this ldflags spec
-      operating_system: sonoma
-      target: aarch64
-      modules: []
-      environment: {}
-      extra_rpaths: []
+  apple-clang:
+    externals:
+    - spec: apple-clang@=15.0.0
+      prefix: /usr
+      extra_attributes:
+        compilers:
+          c: /usr/bin/clang
+          cxx: /usr/bin/clang++
+        flags:
+          ldflags: '-Wl,-ld_classic'         # Add this ldflags spec
 
 .. note::
   Apple is aware of this issue (Apple ticket number FB13208302) and working on a solution, so this is a temporary workaround that will be removed once the linker/loader issues are repaired.
@@ -464,8 +459,11 @@ The following instructions were used to prepare a basic Ubuntu 20.04 or 22.04 LT
    apt-get update
    apt-get upgrade
 
-   # Compilers
-   apt install -y gcc g++ gfortran gdb
+   # Compilers. Note you can select other versions of gcc, g++, and gfortran by changing the version number.
+   apt install -y gcc-13 g++-13 gfortran-13 gdb
+   update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-13 100 && \
+   update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-13 100 && \
+   update-alternatives --install /usr/bin/gfortran gfortran /usr/bin/gfortran-13 100
 
    # Environment module support
    # Note: lmod is available in 22.04, but is out of date: https://github.com/JCSDA/spack-stack/issues/593
@@ -539,12 +537,10 @@ It is recommended to increase the stacksize limit by using ``ulimit -S -s unlimi
 .. code-block:: console
 
    spack external find --scope system \
-       --exclude cmake \
+       --exclude bison --exclude meson \
        --exclude curl --exclude openssl \
        --exclude openssh --exclude python
    spack external find --scope system grep
-   spack external find --scope system sed
-   spack external find --scope system perl
    spack external find --scope system wget
 
    # Note - only needed for running JCSDA's
@@ -554,12 +550,19 @@ It is recommended to increase the stacksize limit by using ``ulimit -S -s unlimi
    # Note - only needed for generating documentation
    spack external find --scope system texlive
 
-5. Find compilers, add to site config's ``compilers.yaml``
+5. Find compilers, add to site config's ``packages.yaml``.
+
+.. note::
+   As of spack-stack 2.0, this step no longer adds compilers to ``compilers.yaml``. Instead, compilers are added at the top of ``packages.yaml`` as externals. If you have multiple versions of a compiler you will need to manually remove the unwanted versions prevent their use.
 
 .. code-block:: console
 
+   # Add compilers to the top of site/packages.yaml.
    spack compiler find --scope system
 
+   # Edit site/packages.yaml to delete or comment unwanted compiler versions.
+   vi site/packages.yaml
+
 6. Do **not** forget to unset the ``SPACK_SYSTEM_CONFIG_PATH`` environment variable and restore the ``SPACK_DISABLE_LOCAL_CONFIG`` variable!
 
 .. code-block:: console
@@ -571,48 +574,25 @@ It is recommended to increase the stacksize limit by using ``ulimit -S -s unlimi
 
 .. code-block:: console
 
-   # Check your gcc version then add it to your site compiler config.
-   gcc --version
-   spack config add "packages:all:compiler:[gcc@YOUR-VERSION]"
-
-   # Example for Red Hat 8 following the above instructions
-   spack config add "packages:all:providers:mpi:[openmpi@5.0.3]"
-
-   # Example for Ubuntu 20.04 or 22.04 following the above instructions
-   spack config add "packages:all:providers:mpi:[mpich@4.2.1]"
+   # Configure preferred mpi and compiler for your environment.
+   spack config add "packages:mpi:require:['openmpi@5.0.8']"
+   spack config add "packages:all:prefer:['%gcc']"
 
-.. warning::
-   On some systems, the default compiler (e.g., ``gcc`` on Ubuntu 20) may not get used by spack if a newer version is found. Compare your entry to the output of the concretization step later and adjust the entry, if necessary.
-
-8. Set a few more package variants and versions to avoid linker errors and duplicate packages being built (for both Red Hat and Ubuntu):
-
-.. code-block:: console
-
-   spack config add "packages:fontconfig:variants:+pic"
-   spack config add "packages:pixman:variants:+pic"
-   spack config add "packages:cairo:variants:+pic"
-
-   If the environment will be used to run JCSDA's JEDI-Skylab experiments using R2D2 with a local MySQL server, run the following command:
-
-.. code-block:: console
-
-   spack config add "packages:ewok-env:variants:+mysql"
-
-9. If you have manually installed lmod, you will need to update the site module configuration to use lmod instead of tcl. Skip this step if you followed the Ubuntu or Red Hat instructions above.
+8. If you have manually installed lmod, you will need to update the site module configuration to use lmod instead of tcl. Skip this step if you followed the Ubuntu or Red Hat instructions above.
 
 .. code-block:: console
 
    sed -i 's/tcl/lmod/g' site/modules.yaml
 
-10. Edit site config files and common config files, for example to remove duplicate versions of external packages that are unwanted, add specs in ``spack.yaml``, etc.
+9. Edit site config files and common config files, for example to remove duplicate versions of external packages that are unwanted, add specs in ``spack.yaml``, etc.
 
 .. code-block:: console
 
    vi spack.yaml
    vi common/*.yaml
    vi site/*.yaml
 
-11. Process the specs and install
+10. Process the specs and install
 
 It is recommended to save the output of concretize in a log file and inspect that log file manually and also using the :ref:`show_duplicate_packages.py <Duplicate_Checker>` utility.
 The former is to ensure that the correct compiler and MPI libraries are being used. The latter is done to find and eliminate duplicate package specifications which can cause issues at the module creation step below.
@@ -625,19 +605,19 @@ See the :ref:`documentation <Duplicate_Checker>` for usage information including
    ${SPACK_STACK_DIR}/util/show_duplicate_packages.py
    spack install [--verbose] [--fail-fast] 2>&1 | tee log.install
 
-12. Create tcl module files (replace ``tcl`` with ``lmod`` if you have manually installed lmod)
+11. Create tcl module files (replace ``tcl`` with ``lmod`` if you have manually installed lmod)
 
 .. code-block:: console
 
    spack module tcl refresh
 
-13. Create meta-modules for compiler, mpi, python
+11. Create meta-modules for compiler, mpi, python
 
 .. code-block:: console
 
    spack stack setup-meta-modules
 
-14. You now have a spack-stack environment that can be accessed by running ``module use ${SPACK_STACK_DIR}/envs/unified-env.mylinux/install/modulefiles/Core``. The modules defined here can be loaded to build and run code as described in :numref:`Section %s <UsingSpackEnvironments>`.
+12. You now have a spack-stack environment that can be accessed by running ``module use ${SPACK_STACK_DIR}/envs/unified-env.mylinux/install/modulefiles/Core``. The modules defined here can be loaded to build and run code as described in :numref:`Section %s <UsingSpackEnvironments>`.
 
 ..  _NewSiteConfigs_Linux_CreateEnv_Nvidia:
 
@@ -741,7 +721,7 @@ Optionally, to run code that may use the CUDA runtime libraries, also install:
    spack external find --scope system cmake
    spack external find --scope system xz
 
-8. Find compilers, add to site config's ``compilers.yaml``
+8. Find compilers, add to ``site/packages.yaml`` as externals
 
 .. code-block:: console
 
@@ -760,12 +740,11 @@ Optionally, to run code that may use the CUDA runtime libraries, also install:
 
    packages:
      all:
+       prefer: ['%nvhpc']
        providers:
          mpi: [openmpi@3.1.5]
          zlib-api: [zlib]
          blas: [nvhpc]
-       compiler:
-       - nvhpc@24.9
      nvhpc:
        externals:
        - spec: nvhpc@24.9 %nvhpc

doc/source/PreConfiguredSites.rst

@@ -208,7 +208,7 @@ The following is required for building new spack environments with any supported
 NOAA Acorn (WCOSS2 test system)
 -------------------------------
 
-On WCOSS2 OpenSUSE sets ``CONFIG_SITE`` which causes libraries to be installed in ``lib64``, breaking the ``lib`` assumption made by some packages. Therefore, ``CONFIG_SITE`` should remain set to empty in ``compilers.yaml``.
+On WCOSS2 OpenSUSE sets ``CONFIG_SITE`` which causes libraries to be installed in ``lib64``, breaking the ``lib`` assumption made by some packages. Therefore, ``CONFIG_SITE`` should remain set to empty in the ``intel-oneapi-compilers`` external spec.
 
 For official deployments on ``spack-stack`` on Acorn, be mindful of umask and group ownership, as these can be finicky. The umask value should be 002, otherwise various files can be assigned to the wrong group. In any case, running something to the effect of ``chgrp nceplibs <spack-stack dir> -R`` and ``chmod o+rX <spack-stack dir> -R`` after the whole installation is done is a good idea.
 
@@ -548,7 +548,7 @@ The following instructions apply to the basic environments (``unified-dev``, ``s
    cd envs/unified-dev.hera.intel/
    spack env activate [-p] .
 
-   # Optionally edit config files (spack.yaml, packages.yaml compilers.yaml, modules.yaml, ...)
+   # Optionally edit config files (spack.yaml, packages.yaml, modules.yaml, ...)
    emacs spack.yaml
    emacs common/*.yaml
    emacs site/*.yaml
@@ -584,7 +584,7 @@ For installing chained environments, the user is referred to section :numref:`%s
 
 The ``cylc`` environment is another special environment. This environment is not chained, thus the instructions provided above until and including the ``spack install`` are still valid. The following differences apply:
 
-1. The ``cylc`` environment can only be built with a reasonably recent version of the GNU compilers (``gcc`` version ``10`` or later, as long as spack-stack in general supports the version; see section :numref:`%s <NewSiteConfigs>` for a compiler compatibility matrix). Further, on Cray systems, the Cray compiler wrappers can not be used (see the comment in ``configs/sites/tier1/narwhal/compilers.yaml``). Note that, as long as the ``cylc`` environment does not use MPI (which is currently the case), it is not necessary to toggle the ``wrappers`` variant for the external ``cray-mpich`` package when using the native compilers without the Cray wrappers.
+1. The ``cylc`` environment can only be built with a reasonably recent version of the GNU compilers (``gcc`` version ``10`` or later, as long as spack-stack in general supports the version; see section :numref:`%s <NewSiteConfigs>` for a compiler compatibility matrix). Further, on Cray systems, the Cray compiler wrappers can not be used. Note that, as long as the ``cylc`` environment does not use MPI (which is currently the case), it is not necessary to toggle the ``wrappers`` variant for the external ``cray-mpich`` package when using the native compilers without the Cray wrappers.
 
 2. Instead of creating ``tcl`` or ``lmod`` modules and the associated meta-modules, this environment creates a spack environment view in ``/path/to/spack-stack/envs/env-name/view``. In order to use the ``cylc`` installation provided in that view, the user is advised to create a ``cylc-wrapper`` similar to the following bash script, and then create an alias ``cylc`` pointing to the wrapper script. This approach ensures that the environment in which ``cylc`` operates is encapsulated from the environment that users or ``cylc`` tasks operate in.