Skip to content

Commit 0dfc0d2

Browse files
AlexanderRichert-NOAAAlexanderRichert-NOAA
authored
Update README.md to include Spack (#212)
* Update README.md to include Spack * COMPONENTS: Update bufr version
1 parent 561694a commit 0dfc0d2

File tree

2 files changed

+107
-43
lines changed

2 files changed

+107
-43
lines changed

‎COMPONENTS

+1-1
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,6 @@ g2c | v1.6.2 | 1.6.2
1919
crtm | v2.3.0 | 2.3.0
2020
upp | upp_v10.0.0 | 10.0.0
2121
wrf_io | v1.2.0 | 1.2.0
22-
bufr | bufr_v11.5.0 | 11.5.0
22+
bufr | v12.0.1 | 12.0.1
2323
wgrib2 | v2.0.8-cmake-v6 | 2.0.8
2424
--------------------------------------------------------

‎README.md

+106-42
Original file line numberDiff line numberDiff line change
@@ -3,49 +3,68 @@
33
## Introduction
44

55
This is a collection of libraries commonly known as NCEPLIBS that are
6-
required for several NCEP applications e.g. UFS, GSI, UPP, etc. For
6+
required for several NCEP applications, e.g., UFS, GSI, UPP, etc. For
77
general information about NCEPLIBS, the user is referred to the
88
[Wiki](https://github.com/NOAA-EMC/NCEPLIBS/wiki).
99

1010
For full documentation of each package see
1111
https://noaa-emc.github.io/NCEPLIBS/.
1212

13-
For installing NCEPLIBS on NOAA HPC systems, see the
14-
[hpc-stack](https://github.com/NOAA-EMC/hpc-stack) project. To install
15-
the third-party libraries needed by NCEPLIBS, see
16-
[NCEPLIBS-external](https://github.com/NOAA-EMC/NCEPLIBS-external).
13+
For installing NCEPLIBS on [NOAA HPC
14+
systems](https://spack-stack.readthedocs.io/en/latest/PreConfiguredSites.html),
15+
see the
16+
[documentation](https://spack-stack.readthedocs.io/en/latest/Overview.html#getting-started)
17+
for the [spack-stack](https://github.com/JCSDA/spack-stack) project. The
18+
documentation provides instructions for using spack-stack to [build software
19+
stacks from
20+
scratch](https://spack-stack.readthedocs.io/en/latest/CreatingEnvironments.html#creatingenvironment),
21+
as well as to [build stacks that are chained to existing
22+
environments](https://spack-stack.readthedocs.io/en/latest/AddingTestPackages.html#add-test-packages)
23+
in order to re-use dependencies already provided by official spack-stack
24+
deployments. **Note** that users are recommended to use existing spack-stack
25+
installations as much as possible when using NOAA R&D systems, and to use
26+
spack-stack as much as possible when developing for applications that
27+
spack-stack is intended to support, namely, UFS applications, Global Workflow,
28+
and JEDI applications (i.e., users developing the UFS Weather Model on a
29+
personal machine are recommended to use their own installation of spack-stack).
30+
Outside of these platforms and applications, users are recommended to install
31+
NCEPLIBS either through CMake or through regular Spack (not spack-stack); see
32+
instructions below.
1733

1834
NCEPLIBS is comprised of the following libraries:
1935

20-
NCEP library | Description
21-
----------------------|---------------------------------------------------
22-
[NCEPLIBS-bacio](https://github.com/NOAA-EMC/NCEPLIBS-bacio) | binary I/O for the NCEP models
23-
[NCEPLIBS-bufr](https://github.com/NOAA-EMC/NCEPLIBS-bufr) | working with the BUFR format
24-
[NCEPLIBS-g2](https://github.com/NOAA-EMC/NCEPLIBS-g2) | coding/decoding GRIB2 messages
25-
[NCEPLIBS-g2c](https://github.com/NOAA-EMC/NCEPLIBS-g2c) | C decoder/encoder routines for GRIB edition 2
26-
[NCEPLIBS-g2tmpl](https://github.com/NOAA-EMC/NCEPLIBS-g2tmpl) | Utilities for GRIB2 templates
27-
[NCEPLIBS-gfsio](https://github.com/NOAA-EMC/NCEPLIBS-gfsio) | convert GFS Gaussian output into grib output
28-
[NCEPLIBS-ip](https://github.com/NOAA-EMC/NCEPLIBS-ip) | general interpolation library
29-
[NCEPLIBS-landsfcutil](https://github.com/NOAA-EMC/NCEPLIBS-landsfcutil) | initializing land-surface states
30-
[NCEPLIBS-ncio](https://github.com/NOAA-EMC/NCEPLIBS-ncio) | read the GFS forecast files
31-
[NCEPLIBS-nemsio](https://github.com/NOAA-EMC/NCEPLIBS-nemsio) | I/O for the NCEP models using NEMS
32-
[NCEPLIBS-nemsiogfs](https://github.com/NOAA-EMC/NCEPLIBS-nemsiogfs) | I/O for the NEMS-GFS model
33-
[NCEPLIBS-sfcio](https://github.com/NOAA-EMC/NCEPLIBS-sfcio) | surface files I/O
34-
[NCEPLIBS-sigio](https://github.com/NOAA-EMC/NCEPLIBS-sigio) | I/O on the sigma restart file of the global spectral model
35-
[NCEPLIBS-sp](https://github.com/NOAA-EMC/NCEPLIBS-sp) | spectral transform library
36-
[NCEPLIBS-w3emc](https://github.com/NOAA-EMC/NCEPLIBS-w3emc) | decoder/encoder routines for GRIB edition 1
37-
[NCEPLIBS-w3nco](https://github.com/NOAA-EMC/NCEPLIBS-w3nco) | decoder/encoder routines for GRIB edition 1
38-
[NCEPLIBS-wrf_io](https://github.com/NOAA-EMC/NCEPLIBS-wrf_io) | lightweight WRF-IO API library for Unified Post Processor (UPP)
39-
[NCEPLIBS-ip2](https://github.com/NOAA-EMC/NCEPLIBS-ip2) | general interpolation library 2
36+
NCEP library | Spack package name | Description
37+
----------------------|--------------------|-----------------------------------------------------
38+
[NCEPLIBS-bacio](https://github.com/NOAA-EMC/NCEPLIBS-bacio) | bacio | Binary I/O for the NCEP models
39+
[NCEPLIBS-bufr](https://github.com/NOAA-EMC/NCEPLIBS-bufr) | bufr | Working with the BUFR format
40+
[NCEPLIBS-g2](https://github.com/NOAA-EMC/NCEPLIBS-g2) | g2 | Coding/decoding GRIB2 messages
41+
[NCEPLIBS-g2c](https://github.com/NOAA-EMC/NCEPLIBS-g2c) | g2c | C decoder/encoder routines for GRIB edition 2
42+
[NCEPLIBS-g2tmpl](https://github.com/NOAA-EMC/NCEPLIBS-g2tmpl) | g2tmpl | Utilities for GRIB2 templates
43+
[NCEPLIBS-gfsio](https://github.com/NOAA-EMC/NCEPLIBS-gfsio) | gfsio | Convert GFS Gaussian output into grib output
44+
[NCEPLIBS-ip](https://github.com/NOAA-EMC/NCEPLIBS-ip) | ip | General interpolation library
45+
[NCEPLIBS-landsfcutil](https://github.com/NOAA-EMC/NCEPLIBS-landsfcutil) | landsfcutil | Initializing land-surface states
46+
[NCEPLIBS-ncio](https://github.com/NOAA-EMC/NCEPLIBS-ncio) | ncio | Read the GFS forecast files
47+
[NCEPLIBS-nemsio](https://github.com/NOAA-EMC/NCEPLIBS-nemsio) | nemsio | I/O for the NCEP models using NEMS
48+
[NCEPLIBS-nemsiogfs](https://github.com/NOAA-EMC/NCEPLIBS-nemsiogfs) | nemsiogfs | I/O for the NEMS-GFS model
49+
[NCEPLIBS-sfcio](https://github.com/NOAA-EMC/NCEPLIBS-sfcio) | sfcio | Surface files I/O
50+
[NCEPLIBS-sigio](https://github.com/NOAA-EMC/NCEPLIBS-sigio) | sigio | I/O on the sigma restart file of the global spectral model
51+
[NCEPLIBS-sp](https://github.com/NOAA-EMC/NCEPLIBS-sp) | sp | Spectral transform library
52+
[NCEPLIBS-w3emc](https://github.com/NOAA-EMC/NCEPLIBS-w3emc) | w3emc | Decoder/encoder routines for GRIB edition 1
53+
[NCEPLIBS-wrf_io](https://github.com/NOAA-EMC/NCEPLIBS-wrf_io) | wrf-io | Lightweight WRF-IO API library for Unified Post Processor (UPP)
54+
55+
The [NCEPLIBS-w3nco](https://github.com/NOAA-EMC/NCEPLIBS-w3nco) and
56+
[NCEPLIBS-ip2](https://github.com/NOAA-EMC/NCEPLIBS-ip2) libraries
57+
('w3nco' and 'ip2' in Spack, respectively) are deprecated, and
58+
NCEPLIBS-w3emc and NCEPLIBS-ip, respectively, should be used instead.
4059

4160
The following projects are also related to the NCEPLIBS project:
42-
- [NCEPLIBS-grib_util](https://github.com/NOAA-EMC/NCEPLIBS-grib_util)
43-
- [NCEPLIBS-prod_util](https://github.com/NOAA-EMC/NCEPLIBS-prod_util)
44-
- [UFS_UTILS](https://github.com/NOAA-EMC/UFS_UTILS)
61+
- [NCEPLIBS-grib_util](https://github.com/NOAA-EMC/NCEPLIBS-grib_util) ('grib-util' in Spack)
62+
- [NCEPLIBS-prod_util](https://github.com/NOAA-EMC/NCEPLIBS-prod_util) ('prod-util' in Spack)
63+
- [UFS_UTILS](https://github.com/NOAA-EMC/UFS_UTILS) ('ufs-utils' in Spack)
4564

4665
## Required Software
4766

48-
A supported C/C++ and Fortran compiler (see table below). Other
67+
- A supported C/C++ and Fortran compiler (see table below). Other
4968
versions may work, in particular if close to the versions listed
5069
below.
5170

@@ -54,7 +73,7 @@ below.
5473
| Intel | 18.0.3.222, 18.0.5.274, 19.0.2.187, 19.0.5.281, 19.1.0.166 |
5574
| GNU | 8.3.0, 9.X.0 |
5675

57-
A supported MPI library (see table below). Other versions may work,
76+
- A supported MPI library (see table below). Other versions may work,
5877
in particular if close to the versions listed below.
5978

6079
| MPI library | Supported (tested) versions |
@@ -65,8 +84,8 @@ in particular if close to the versions listed below.
6584
| Intel MPI | 2018.0.4, 2019.6.154, 2020.0.166 |
6685
| SGI MPT | 2.19 |
6786

68-
A software stack consisting of the following third-party libraries
69-
(TPL), compiled with the same compiler and MPI library (where
87+
- A software stack consisting of the following third-party libraries,
88+
compiled with the same compiler and MPI library (where
7089
applicable). Other versions may work, in particular if close to the
7190
versions listed below. To install the third-party libraries needed by
7291
NCEPLIBS, see
@@ -83,33 +102,74 @@ NCEPLIBS, see
83102
| NetCDF | netcdf-c-4.7.3, netcdf-fortran-4.5.2 |
84103

85104
The [NCEPLIBS-external](https://github.com/NOAA-EMC/NCEPLIBS-external)
86-
project provides an convenient way to install the required TPL on
87-
supported platforms such as generic Linux/macOS systems.
105+
project provides an convenient way to install the required third-party libraries
106+
on supported platforms such as generic Linux/macOS systems.
107+
108+
## Obtaining, Building, and Using NCEPLIBS
109+
110+
### With Spack
111+
All of the NCEPLIBS can be installed through the [Spack](https://spack.io/)
112+
package manager. One significant benefit of using Spack is that it will
113+
automatically install any dependencies needed, including CMake, or even
114+
compilers. See the [Spack
115+
documentation](https://spack.readthedocs.io/en/latest/basic_usage.html) for
116+
details of configuring and executing Spack installations. Spack also has
117+
extensive capabilities including source and build caching, parallel
118+
installation, dynamically generating Tcl and Lmod environment modules,
119+
and creating Docker and Singularity container images.
120+
121+
In the simplest case, with the `spack` command loaded into the current
122+
environment, run, for example, `spack install ip` to install the latest release
123+
of the NCEPLIBS-ip library along with any needed dependencies. See the above
124+
table for each package's name in Spack. The develop branch for each library can
125+
be installed by specifying the 'develop' version, i.e., `spack install
126+
w3emc@develop`.
127+
128+
Here is a typical set of steps for installing and using NCEPLIBS using Spack,
129+
assuming that Spack's
130+
[prerequisites](https://spack.readthedocs.io/en/latest/getting_started.html#system-prerequisites)
131+
are already installed:
132+
```
133+
git clone https://github.com/spack/spack
134+
. spack/share/spack/setup-env.sh # assuming bash, zsh, or dash shell
135+
spack external find cmake gmake # find external packages to save time
136+
spack install ip@develop precision=4 ^sp@2.4.0 precision=4
137+
spack load ip
138+
```
139+
The `spack load` command configures the $CMAKE_PREFIX_PATH variable,
140+
in this example making the ip library available to downstream CMake builds.
141+
142+
For any bugs or other issues with Spack-based installations, such as incorrect
143+
dependencies in a package's recipe, please file an issue under the appropriate
144+
NCEPLIBS repository.
88145

89-
## Obtaining, Building, Using NCEPLIBS
146+
### With CMake
147+
#### External dependencies
148+
See [NCEPLIBS-external](https://github.com/NOAA-EMC/NCEPLIBS-external) for
149+
building external dependencies.
90150

91-
### Obtaining the code
151+
#### Obtaining the code
92152

93153
Clone the repository:
94154

95155
`git clone https://github.com/NOAA-EMC/NCEPLIBS`
96156

97-
### Building the libraries
157+
#### Building the libraries
98158

99159
`CMake` employs an out-of-source build. Create a directory for
100160
configuring the build and cd into it:
101161

102162
`mkdir -p build && cd build`
103163

104164
Set the compilers, if needed, to match those being used for compiling
105-
the TPL listed above: `FC`, `CC`, and `CXX` environment variables can
165+
the third-party libraries listed above: `FC`, `CC`, and `CXX` environment variables can
106166
be used to point to the desired Fortran, C, and C++ compilers.
107167

108168
Execute `cmake` from inside your build directory.
109169

110170
`cmake -DCMAKE_INSTALL_PREFIX=<nceplibs-prefix> ../NCEPLIBS`
111171

112-
If the TPL are not located in a path recognized by `cmake`
172+
If the third-party libraries are not located in a path recognized by `cmake`
113173
e.g. `/usr/local`, it may be necessary to provide the appropriate
114174
environment variables e.g. `<package_ROOT>` or `CMAKE_PREFIX_PATH` so
115175
that `cmake` is able to locate these dependencies.
@@ -158,11 +218,15 @@ the tarball, and use the cmake command line option `USE_LOCAL` as
158218
`-DUSE_LOCAL=ON`. This will use the source code from the download
159219
directory.
160220

161-
### Usage
221+
## Usage
162222

163-
`NCEPLIBS` can be used in any application that uses `cmake` to
223+
NCEPLIBS can be used in any application that uses `cmake` to
164224
configure and build by adding `-DCMAKE_PREFIX_PATH=<nceplibs-prefix>`
165-
to the cmake command line during configuration.
225+
to the cmake command line during configuration. Note that if NCEPLIBS
226+
are installed through Spack, loading the packages, either through
227+
Spack-built environment modules or using the `spack load` command,
228+
will populate the `$CMAKE_PREFIX_PATH` environment variable with
229+
the appropriate paths.
166230

167231
## Disclaimer
168232

0 commit comments

Comments
 (0)