make util build options consistent

INSTALL.md

@@ -0,0 +1,115 @@
+## Build and Install Instructions
+---
+
+### Prerequisites
+A supported C and Fortran compiler (see table below).  Other versions may work, in particular if close to the versions listed below.
+
+| Compiler vendor | Supported (tested) versions                                |
+|-----------------|------------------------------------------------------------|
+| Intel           | 18.0.3.222 and above                                       |
+| GNU             | 10.3.0 and above                                           |
+
+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                                |
+|-----------------|------------------------------------------------------------|
+| MPICH           | 3.3.1 and above                                            |
+| Open MPI        | 3.1.5 and above                                            |
+| Intel MPI       | 2018.0.4 and above                                         |
+
+Third-party libraries (TPL) compiled with the same compiler and MPI library (where applicable).
+
+| Library         | Supported (tested) versions                                |
+|-----------------|------------------------------------------------------------|
+| CMake           | 3.20.1 and above                                           |
+| HDF5            | 1.10.4 and above                                           |
+| NetCDF-C        | 4.7.3 and above                                            |
+| NetCDF-Fortran  | 4.5.2 and above                                            |
+
+NCEP Libraries (NCEPLibs) compiled with the same compiler and MPI library (where applicable).
+
+| Library         | Supported (tested) versions                                |
+|-----------------|------------------------------------------------------------|
+| BUFR            | 11.4.0 and above                                           |
+| CRTM            | 2.3.0 and above                                            |
+| IP              | 3.3.3 and above                                            |
+| SP              | 2.3.3 and above                                            |
+| BACIO           | 2.4.1 and above                                            |
+| W3EMC           | 2.9.1 and above                                            |
+| SIGIO           | 2.3.2 and above                                            |
+| SFCIO           | 1.4.1 and above                                            |
+| NEMSIO          | 2.5.2 and above                                            |
+| NCIO            | 1.0.0 and above                                            |
+| WRF_IO          | 1.2.0 and above                                            |
+
+### Building the GSI
+
+`CMake` employs an out-of-source build.  Create a directory for configuring the build and cd into it:
+
+```bash
+mkdir -p build && cd build
+```
+
+Set the compilers, if needed, to match those being used for compiling the TPL and NCEPLibs listed above: `CC` and `FC` environment variables can be used to point to the desired C and Fortran compilers.
+
+Execute `cmake` from inside your build directory.
+
+```bash
+cmake -DCMAKE_INSTALL_PREFIX=<install-prefix> <CMAKE_OPTIONS> /path/to/GSI-source
+```
+
+If the dependencies 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.
+
+The installation prefix for GSI is provided by the `cmake` command-line argument `-DCMAKE_INSTALL_PREFIX=<install-prefix>`
+
+To build and install:
+
+```
+make -j<x>
+make install
+```
+
+### CMake Options
+
+CMake allows for various options that can be specified on the command line via `-DCMAKE_OPTION=VALUE` or from within the ccmake gui. The list of options currently available is as follows:
+
+| Option              | Description (Default)                                  |
+|---------------------|--------------------------------------------------------|
+| `OPENMP`              | Enable OpenMP Threading (`OFF`)                      |
+| `ENABLE_MKL`          | Use MKL (`ON`), If not found use LAPACK              |
+| `BUILD_NCDIAG`        | Build GSI NetCDF Diagnostics Library (`ON`)          |
+| `BUILD_GSDCLOUD`      | Build GSD Cloud Library (`OFF`)                      |
+| `BUILD_GSI`           | Build GSI library and executable (`ON`)              |
+| `BUILD_ENKF`          | Build EnKF library and executable (`ON`)             |
+| `BUILD_REG_TESTING`   | Enable Regression Testing (`ON`)                     |
+| `BUILD_UTIL`          | Build Utilities (`ON`)                               |
+| `BUILD_UTIL_AERODA`   | Build Aerosol DA utility (`OFF`)                     |
+| `BUILD_UTIL_COV_CALC` | Build Correlated Obs. Error utility (`OFF`)          |
+| `BUILD_UTIL_EFSOI`    | Build Ensemble FSOI application (`OFF`)              |
+| `BUILD_UTIL_ENKF_GFS` | Build GFS ensemble utilities (`OFF`)                 |
+| `BUILD_UTIL_ENKF_ARW` | Build ARW ensemble utilities (`OFF`)                 |
+| `BUILD_UTIL_MON`      | Build Observation Monitoring utilities (`OFF`)       |
+| `BUILD_UTIL_NCIO`     | Build NetCDF IO utilities (`OFF`)                    |
+| `BUILD_UTIL_COM`      | Build Miscellaneous community utilities (`ON`)       |
+| `BUILD_UTIL_BKGERR`   | Build Background Error utility (`OFF`)               |
+
+The flavor of GSI and EnKF can be defined with the use of the following options:
+
+| CMake Option        | Description (Default)        | Valid Options                  |
+|---------------------|------------------------------|--------------------------------|
+| `GSI_MODE`          | GSI application mode (`GFS`) | `GFS`, `Regional`              |
+| `ENKF_MODE`         | EnKF application mode (`GFS`)| `GFS`, `WRF`, `NMMB`, `FV3REG` |
+
+### Regression Testing
+
+When Regression tests are enabled (`-DBUILD_REG_TESTING=ON`), it is necessary to provide
+the path to search for the control GSI and EnKF executables.  This can be provided with the option `CONTROLPATH`.  Other search variables are `GSICONTROLPATH` or `ENKFCONTROLPATH` for GSI and EnKF control executables respectively.
+
+If the control executables are not found, the Regression tests will be disabled.
+
+Once the build is complete and control executables have been found, regression testing can be launched from the build directory by executing:
+```bash
+ctest
+```
+
+Refer to the `ctest` manual for more information on `ctest` framework.

ush/build_all_cmake.sh

@@ -123,15 +123,11 @@ cmake_opts+=" -DCMAKE_INSTALL_BINDIR=exec"
 cmake_opts+=" -DGSI_MODE=Regional -DENKF_MODE=GFS"
 
 # Build utilities:
-cmake_opts+=" -DBUILD_COV_CALC=ON -DBUILD_ENKF_GFS=ON -DBUILD_EFSOI_UTIL=ON -DBUILD_MON_UTIL=ON"
+cmake_opts+=" -DBUILD_UTIL_COV_CALC=ON -DBUILD_UTIL_ENKF_GFS=ON -DBUILD_UTIL_EFSOIL=ON -DBUILD_UTIL_MON=ON"
 
 # Build regression test
 cmake_opts+=" -DBUILD_REG_TESTING=ON -DCONTROLPATH=${CONTROLPATH:-}"
 
-# Valid combination of applications are:
-# Global  : -DGSI_MODE=GFS -DENKF_MODE=GFS
-# Regional: -DGSI_MODE=Regional -DENKF_MODE=WRF|NMMB|FV3REG
-
 cmake $cmake_opts $dir_root
 
 # Build apps.  Echo extra printout for NCO build

util/CMakeLists.txt

@@ -30,28 +30,28 @@ option(OPENMP "Enable OpenMP Threading" OFF)
 option(ENABLE_MKL "Use MKL for LAPACK implementation (if available)" ON)
 
 # Build options
-option(BUILD_AERODA_UTIL "Build Aerosol DA utilities" OFF)
-option(BUILD_COV_CALC "Build Correlated Observation Error Utility" OFF)
-option(BUILD_EFSOI_UTIL "Build EFSOI Utilities" OFF)
-option(BUILD_ENKF_GFS "Build EnKF GFS Utilities" OFF)
-option(BUILD_ENKF_ARW "Build EnKF ARW Utilities" OFF)
-option(BUILD_MON_UTIL "Build Monitoring Utilities" OFF)
-option(BUILD_NCIO_UTIL "Build NetCDF IO Utilities" OFF)
+option(BUILD_UTIL_AERODA "Build Aerosol DA utilities" OFF)
+option(BUILD_UTIL_COV_CALC "Build Correlated Observation Error Utility" OFF)
+option(BUILD_UTIL_EFSOI "Build EFSOI Utilities" OFF)
+option(BUILD_UTIL_ENKF_GFS "Build EnKF GFS Utilities" OFF)
+option(BUILD_UTIL_ENKF_ARW "Build EnKF ARW Utilities" OFF)
+option(BUILD_UTIL_MON "Build Monitoring Utilities" OFF)
+option(BUILD_UTIL_NCIO "Build NetCDF IO Utilities" OFF)
 option(BUILD_UTIL_COM "Build community utilities" OFF)
-option(BUILD_BKGERR_UTIL "Build Background Error Utilities" OFF)
+option(BUILD_UTIL_BKGERR "Build Background Error Utilities" OFF)
 
 # Echo user options
 message(STATUS "Utils: OPENMP ................. ${OPENMP}")
 message(STATUS "Utils: ENABLE_MKL ............. ${ENABLE_MKL}")
-message(STATUS "Utils: BUILD_AERODA_UTIL ...... ${BUILD_AERODA_UTIL}")
-message(STATUS "Utils: BUILD_COV_CALC ......... ${BUILD_COV_CALC}")
-message(STATUS "Utils: BUILD_EFSOI_UTIL ....... ${BUILD_EFSOI_UTIL}")
-message(STATUS "Utils: BUILD_ENKF_GFS ......... ${BUILD_ENKF_GFS}")
-message(STATUS "Utils: BUILD_ENKF_ARW ......... ${BUILD_ENKF_ARW}")
-message(STATUS "Utils: BUILD_MON_UTIL ......... ${BUILD_MON_UTIL}")
-message(STATUS "Utils: BUILD_NCIO_UTIL ........ ${BUILD_NCIO_UTIL}")
+message(STATUS "Utils: BUILD_UTIL_AERODA ...... ${BUILD_UTIL_AERODA}")
+message(STATUS "Utils: BUILD_UTIL_COV_CALC .... ${BUILD_UTIL_COV_CALC}")
+message(STATUS "Utils: BUILD_UTIL_EFSOI ....... ${BUILD_UTIL_EFSOI}")
+message(STATUS "Utils: BUILD_UTIL_ENKF_GFS .... ${BUILD_UTIL_ENKF_GFS}")
+message(STATUS "Utils: BUILD_UTIL_ENKF_ARW .... ${BUILD_UTIL_ENKF_ARW}")
+message(STATUS "Utils: BUILD_UTIL_MON ......... ${BUILD_UTIL_MON}")
+message(STATUS "Utils: BUILD_UTIL_NCIO ........ ${BUILD_UTIL_NCIO}")
 message(STATUS "Utils: BUILD_UTIL_COM ......... ${BUILD_UTIL_COM}")
-message(STATUS "Utils: BUILD_BKGERR_UTIL ...... ${BUILD_BKGERR_UTIL}")
+message(STATUS "Utils: BUILD_UTIL_BKGERR ...... ${BUILD_UTIL_BKGERR}")
 
 # Dependencies
 if(ENABLE_MKL)
@@ -99,23 +99,23 @@ target_link_libraries(nemsio::nemsio INTERFACE w3emc::w3emc_d bacio::bacio_4)
 # Get compiler flags for the utilities
 include(gsiutils_compiler_flags)
 
-if(BUILD_AERODA_UTIL)
+if(BUILD_UTIL_AERODA)
   add_subdirectory(AeroDA)
 endif()
 
-if(BUILD_COV_CALC)
+if(BUILD_UTIL_COV_CALC)
   add_subdirectory(Correlated_Obs)
 endif()
 
-if(BUILD_EFSOI_UTIL)
+if(BUILD_UTIL_EFSOI)
   add_subdirectory(EFSOI_Utilities)
 endif()
 
-if(BUILD_ENKF_GFS OR BUILD_ENKF_ARW)
+if(BUILD_UTIL_ENKF_GFS OR BUILD_UTIL_ENKF_ARW)
   add_subdirectory(EnKF)
 endif()
 
-if(BUILD_NCIO_UTIL)
+if(BUILD_UTIL_NCIO)
   add_subdirectory(netcdf_io)
 endif()
 
@@ -125,16 +125,17 @@ if(BUILD_UTIL_COM)
   add_subdirectory(radar_process)
 endif()
 
-if(BUILD_BKGERR_UTIL)
+if(BUILD_UTIL_BKGERR)
   add_subdirectory(NMC_Bkerror)
 endif()
 
-if(BUILD_MON_UTIL)
+if(BUILD_UTIL_MON)
   add_subdirectory(Conventional_Monitor)
   add_subdirectory(Ozone_Monitor)
   add_subdirectory(Radiance_Monitor)
 endif()
 
+# These don't fall into any category
 add_subdirectory(FOV_utilities)
 add_subdirectory(Single_Observation)
 add_subdirectory(zero_biascoeff)

util/EnKF/CMakeLists.txt

@@ -1,8 +1,8 @@
-if(BUILD_ENKF_GFS)
+if(BUILD_UTIL_ENKF_GFS)
   add_subdirectory(gfs)
 endif()
 
-if(BUILD_ENKF_ARW)
+if(BUILD_UTIL_ENKF_ARW)
   if(NOT TARGET gsi)
     if(NOT gsi_FOUND)
       message(FATAL_ERROR "Utils: GSI library was not found for EnKF ARW utilities")