Update README.md to include Spack

NOAA-EMC · Jan 8, 2024 · ea831c0 · ea831c0
1 parent 561694a
commit ea831c0
Showing 1 changed file with 106 additions and 42 deletions.
diff --git a/README.md b/README.md
@@ -3,49 +3,68 @@
 ## Introduction
 
 This is a collection of libraries commonly known as NCEPLIBS that are
-required for several NCEP applications e.g. UFS, GSI, UPP, etc. For
+required for several NCEP applications, e.g., UFS, GSI, UPP, etc. For
 general information about NCEPLIBS, the user is referred to the
 [Wiki](https://github.com/NOAA-EMC/NCEPLIBS/wiki).
 
 For full documentation of each package see
 https://noaa-emc.github.io/NCEPLIBS/.
 
-For installing NCEPLIBS on NOAA HPC systems, see the
-[hpc-stack](https://github.com/NOAA-EMC/hpc-stack) project. To install
-the third-party libraries needed by NCEPLIBS, see
-[NCEPLIBS-external](https://github.com/NOAA-EMC/NCEPLIBS-external).
+For installing NCEPLIBS on [NOAA HPC
+systems](https://spack-stack.readthedocs.io/en/latest/PreConfiguredSites.html),
+see the
+[documentation](https://spack-stack.readthedocs.io/en/latest/Overview.html#getting-started)
+for the [spack-stack](https://github.com/JCSDA/spack-stack) project. The
+documentation provides instructions for using spack-stack to [build software
+stacks from
+scratch](https://spack-stack.readthedocs.io/en/latest/CreatingEnvironments.html#creatingenvironment),
+as well as to [build stacks that are chained to existing
+environments](https://spack-stack.readthedocs.io/en/latest/AddingTestPackages.html#add-test-packages)
+in order to re-use dependencies already provided by official spack-stack
+deployments. **Note** that users are recommended to use existing spack-stack
+installations as much as possible when using NOAA R&D systems, and to use
+spack-stack as much as possible when developing for applications that
+spack-stack is intended to support, namely, UFS applications, Global Workflow,
+and JEDI applications (i.e., users developing the UFS Weather Model on a
+personal machine are recommended to use their own installation of spack-stack).
+Outside of these platforms and applications, users are recommended to install
+NCEPLIBS either through CMake or through regular Spack (not spack-stack); see
+instructions below.
 
 NCEPLIBS is comprised of the following libraries:
 
- NCEP library         | Description
-----------------------|---------------------------------------------------
-[NCEPLIBS-bacio](https://github.com/NOAA-EMC/NCEPLIBS-bacio)             | binary I/O for the NCEP models
-[NCEPLIBS-bufr](https://github.com/NOAA-EMC/NCEPLIBS-bufr)               | working with the BUFR format
-[NCEPLIBS-g2](https://github.com/NOAA-EMC/NCEPLIBS-g2)                   | coding/decoding GRIB2 messages
-[NCEPLIBS-g2c](https://github.com/NOAA-EMC/NCEPLIBS-g2c)                 | C decoder/encoder routines for GRIB edition 2
-[NCEPLIBS-g2tmpl](https://github.com/NOAA-EMC/NCEPLIBS-g2tmpl)           | Utilities for GRIB2 templates
-[NCEPLIBS-gfsio](https://github.com/NOAA-EMC/NCEPLIBS-gfsio)             | convert GFS Gaussian output into grib output
-[NCEPLIBS-ip](https://github.com/NOAA-EMC/NCEPLIBS-ip)                   | general interpolation library 
-[NCEPLIBS-landsfcutil](https://github.com/NOAA-EMC/NCEPLIBS-landsfcutil) | initializing land-surface states
-[NCEPLIBS-ncio](https://github.com/NOAA-EMC/NCEPLIBS-ncio)               | read the GFS forecast files
-[NCEPLIBS-nemsio](https://github.com/NOAA-EMC/NCEPLIBS-nemsio)           | I/O for the NCEP models using NEMS
-[NCEPLIBS-nemsiogfs](https://github.com/NOAA-EMC/NCEPLIBS-nemsiogfs)     | I/O for the NEMS-GFS model
-[NCEPLIBS-sfcio](https://github.com/NOAA-EMC/NCEPLIBS-sfcio)             | surface files I/O
-[NCEPLIBS-sigio](https://github.com/NOAA-EMC/NCEPLIBS-sigio)             | I/O on the sigma restart file of the global spectral model
-[NCEPLIBS-sp](https://github.com/NOAA-EMC/NCEPLIBS-sp)                   | spectral transform library 
-[NCEPLIBS-w3emc](https://github.com/NOAA-EMC/NCEPLIBS-w3emc)             | decoder/encoder routines for GRIB edition 1
-[NCEPLIBS-w3nco](https://github.com/NOAA-EMC/NCEPLIBS-w3nco)             | decoder/encoder routines for GRIB edition 1
-[NCEPLIBS-wrf_io](https://github.com/NOAA-EMC/NCEPLIBS-wrf_io)           | lightweight WRF-IO API library for Unified Post Processor (UPP)
-[NCEPLIBS-ip2](https://github.com/NOAA-EMC/NCEPLIBS-ip2)                 | general interpolation library 2
+ NCEP library         | Spack package name | Description
+----------------------|--------------------|-----------------------------------------------------
+[NCEPLIBS-bacio](https://github.com/NOAA-EMC/NCEPLIBS-bacio)             | bacio              | Binary I/O for the NCEP models
+[NCEPLIBS-bufr](https://github.com/NOAA-EMC/NCEPLIBS-bufr)               | bufr               | Working with the BUFR format
+[NCEPLIBS-g2](https://github.com/NOAA-EMC/NCEPLIBS-g2)                   | g2                 | Coding/decoding GRIB2 messages
+[NCEPLIBS-g2c](https://github.com/NOAA-EMC/NCEPLIBS-g2c)                 | g2c                | C decoder/encoder routines for GRIB edition 2
+[NCEPLIBS-g2tmpl](https://github.com/NOAA-EMC/NCEPLIBS-g2tmpl)           | g2tmpl             | Utilities for GRIB2 templates
+[NCEPLIBS-gfsio](https://github.com/NOAA-EMC/NCEPLIBS-gfsio)             | gfsio              | Convert GFS Gaussian output into grib output
+[NCEPLIBS-ip](https://github.com/NOAA-EMC/NCEPLIBS-ip)                   | ip                 | General interpolation library 
+[NCEPLIBS-landsfcutil](https://github.com/NOAA-EMC/NCEPLIBS-landsfcutil) | landsfcutil        | Initializing land-surface states
+[NCEPLIBS-ncio](https://github.com/NOAA-EMC/NCEPLIBS-ncio)               | ncio               | Read the GFS forecast files
+[NCEPLIBS-nemsio](https://github.com/NOAA-EMC/NCEPLIBS-nemsio)           | nemsio             | I/O for the NCEP models using NEMS
+[NCEPLIBS-nemsiogfs](https://github.com/NOAA-EMC/NCEPLIBS-nemsiogfs)     | nemsiogfs          | I/O for the NEMS-GFS model
+[NCEPLIBS-sfcio](https://github.com/NOAA-EMC/NCEPLIBS-sfcio)             | sfcio              | Surface files I/O
+[NCEPLIBS-sigio](https://github.com/NOAA-EMC/NCEPLIBS-sigio)             | sigio              | I/O on the sigma restart file of the global spectral model
+[NCEPLIBS-sp](https://github.com/NOAA-EMC/NCEPLIBS-sp)                   | sp                 | Spectral transform library 
+[NCEPLIBS-w3emc](https://github.com/NOAA-EMC/NCEPLIBS-w3emc)             | w3emc              | Decoder/encoder routines for GRIB edition 1
+[NCEPLIBS-wrf_io](https://github.com/NOAA-EMC/NCEPLIBS-wrf_io)           | wrf-io             | Lightweight WRF-IO API library for Unified Post Processor (UPP)
+
+The [NCEPLIBS-w3nco](https://github.com/NOAA-EMC/NCEPLIBS-w3nco) and
+[NCEPLIBS-ip2](https://github.com/NOAA-EMC/NCEPLIBS-ip2) libraries
+('w3nco' and 'ip2' in Spack, respectively) are deprecated, and
+NCEPLIBS-w3emc and NCEPLIBS-ip, respectively, should be used instead.
 
 The following projects are also related to the NCEPLIBS project:
- - [NCEPLIBS-grib_util](https://github.com/NOAA-EMC/NCEPLIBS-grib_util)
- - [NCEPLIBS-prod_util](https://github.com/NOAA-EMC/NCEPLIBS-prod_util)
- - [UFS_UTILS](https://github.com/NOAA-EMC/UFS_UTILS)
+ - [NCEPLIBS-grib_util](https://github.com/NOAA-EMC/NCEPLIBS-grib_util) ('grib-util' in Spack)
+ - [NCEPLIBS-prod_util](https://github.com/NOAA-EMC/NCEPLIBS-prod_util) ('prod-util' in Spack)
+ - [UFS_UTILS](https://github.com/NOAA-EMC/UFS_UTILS) ('ufs-utils' in Spack)
 
 ## Required Software
 
-A supported C/C++ and Fortran compiler (see table below).  Other
+ - A supported C/C++ and Fortran compiler (see table below).  Other
 versions may work, in particular if close to the versions listed
 below.
 
@@ -54,7 +73,7 @@ below.
 | Intel           | 18.0.3.222, 18.0.5.274, 19.0.2.187, 19.0.5.281, 19.1.0.166 |
 | GNU             | 8.3.0, 9.X.0                                               |
 
-A supported MPI library (see table below).  Other versions may work,
+ - A supported MPI library (see table below).  Other versions may work,
 in particular if close to the versions listed below.
 
 | MPI library     | Supported (tested) versions                                |
@@ -65,8 +84,8 @@ in particular if close to the versions listed below.
 | Intel MPI       | 2018.0.4, 2019.6.154, 2020.0.166                           |
 | SGI MPT         | 2.19                                                       |
 
-A software stack consisting of the following third-party libraries
-(TPL), compiled with the same compiler and MPI library (where
+ - A software stack consisting of the following third-party libraries,
+compiled with the same compiler and MPI library (where
 applicable). Other versions may work, in particular if close to the
 versions listed below. To install the third-party libraries needed by
 NCEPLIBS, see
@@ -83,33 +102,74 @@ NCEPLIBS, see
 | NetCDF          | netcdf-c-4.7.3, netcdf-fortran-4.5.2                       |
 
 The [NCEPLIBS-external](https://github.com/NOAA-EMC/NCEPLIBS-external)
-project provides an convenient way to install the required TPL on
-supported platforms such as generic Linux/macOS systems.
+project provides an convenient way to install the required third-party libraries
+on supported platforms such as generic Linux/macOS systems.
+
+## Obtaining, Building, and Using NCEPLIBS
+
+### With Spack
+All of the NCEPLIBS can be installed through the [Spack](https://spack.io/)
+package manager. One significant benefit of using Spack is that it will
+automatically install any dependencies needed, including CMake, or even
+compilers. See the [Spack
+documentation](https://spack.readthedocs.io/en/latest/basic_usage.html) for
+details of configuring and executing Spack installations. Spack also has
+extensive capabilities including source and build caching, parallel
+installation, dynamically generating Tcl and Lmod environment modules,
+and creating Docker and Singularity container images.
+
+In the simplest case, with the `spack` command loaded into the current
+environment, run, for example, `spack install ip` to install the latest release
+of the NCEPLIBS-ip library along with any needed dependencies. See the above
+table for each package's name in Spack. The develop branch for each library can
+be installed by specifying the 'develop' version, i.e., `spack install
+w3emc@develop`.
+
+Here is a typical set of steps for installing and using NCEPLIBS using Spack,
+assuming that Spack's
+[prerequisites](https://spack.readthedocs.io/en/latest/getting_started.html#system-prerequisites)
+are already installed:
+```
+git clone https://github.com/spack/spack
+. spack/share/spack/setup-env.sh # assuming bash, zsh, or dash shell
+spack external find cmake gmake # find external packages to save time
+spack install ip@develop precision=4 ^sp@2.4.0 precision=4
+spack load ip
+```
+The `spack load` command configures the $CMAKE_PREFIX_PATH variable,
+in this example making the ip library available to downstream CMake builds.
+
+For any bugs or other issues with Spack-based installations, such as incorrect
+dependencies in a package's recipe, please file an issue under the appropriate
+NCEPLIBS repository.
 
-## Obtaining, Building, Using NCEPLIBS
+### With CMake
+#### External dependencies
+See [NCEPLIBS-external](https://github.com/NOAA-EMC/NCEPLIBS-external) for
+building external dependencies.
 
-### Obtaining the code
+#### Obtaining the code
 
 Clone the repository:
 
 `git clone https://github.com/NOAA-EMC/NCEPLIBS`
 
-### Building the libraries
+#### Building the libraries
 
 `CMake` employs an out-of-source build.  Create a directory for
 configuring the build and cd into it:
 
 `mkdir -p build && cd build`
 
 Set the compilers, if needed, to match those being used for compiling
-the TPL listed above: `FC`, `CC`, and `CXX` environment variables can
+the third-party libraries listed above: `FC`, `CC`, and `CXX` environment variables can
 be used to point to the desired Fortran, C, and C++ compilers.
 
 Execute `cmake` from inside your build directory.
 
 `cmake -DCMAKE_INSTALL_PREFIX=<nceplibs-prefix> ../NCEPLIBS`
 
-If the TPL are not located in a path recognized by `cmake`
+If the third-party libraries are not located in a path recognized by `cmake`
 e.g. `/usr/local`, it may be necessary to provide the appropriate
 environment variables e.g. `<package_ROOT>` or `CMAKE_PREFIX_PATH` so
 that `cmake` is able to locate these dependencies.
@@ -158,11 +218,15 @@ the tarball, and use the cmake command line option `USE_LOCAL` as
 `-DUSE_LOCAL=ON`.  This will use the source code from the download
 directory.
 
-### Usage
+## Usage
 
-`NCEPLIBS` can be used in any application that uses `cmake` to
+NCEPLIBS can be used in any application that uses `cmake` to
 configure and build by adding `-DCMAKE_PREFIX_PATH=<nceplibs-prefix>`
-to the cmake command line during configuration.
+to the cmake command line during configuration. Note that if NCEPLIBS
+are installed through Spack, loading the packages, either through
+Spack-built environment modules or using the `spack load` command,
+will populate the `$CMAKE_PREFIX_PATH` environment variable with
+the appropriate paths.
 
 ## Disclaimer