Shall we add a build summary and fms_meta.h file?

Is your feature request related to a problem? Please describe. Installing climate model software is complex. There are many choices and settings that must be correct. However, in the flow of output from the configure, it is not easy to pick out the important settings to confirm they are correct. And other software packages, using FMS, have to adjust to the features it was built with, so must have a way of easily finding them.

In many packages, including netcdf-c, netcdf-fortran, PIO, and the upcoming UFS short range weather model, there is a nice summary of what is going to be built. Here's an example from PIO:

# PIO Configuration Summary
==============================

# General
-------
PIO Version:        2.5.1-development
Configured On:      Fri Jul 17 14:58:16 MDT 2020
Host System:        x86_64-pc-linux-gnu
Build Directory:    /var/lib/jenkins/workspace/AAA_ejh_PIO
Install Prefix:         /usr/local

# Compiling Options
-----------------
C Compiler:     /usr/local/bin/mpicc
CFLAGS:         -g -Wall
CPPFLAGS:       -I/usr/local/netcdf-c-4.8.0-development_hdf5-1.10.6_szip_mpich/include -I/usr/local/pnetcdf-1.12.1/include -I/usr/local/netcdf-fortran-4.5.4-development_szip_mpich/include
LDFLAGS:        -L/usr/local/netcdf-c-4.8.0-development_hdf5-1.10.6_szip_mpich/lib -L/usr/local/pnetcdf-1.12.1/lib -L/usr/local/netcdf-fortran-4.5.4-development_szip_mpich/lib
Shared Library:     yes
Static Library:     yes
Extra libraries:    -lpnetcdf -lnetcdf 

# Features
--------
PnetCDF Support:    yes
SZIP Write Support:     yes
Parallel Filters:       yes

A pio_meta.h file is also produced:

/*! \file pio_meta.h
 *
 * Meta information for libpio which can be used by other packages which
 * depend on libpio.
 *
 * This file is automatically generated by the build system
 * at configure time, and contains information related to
 * how libpio was built.  It will not be required to
 * include this file unless you want to probe the capabilities
 * of libpio. This should ideally only happen when configuring
 * a project which depends on libpio.  At configure time,
 * the dependent project can set its own macros which can be used
 * in conditionals.
 *
 * Ed Hartnett, 7/14/20 Happy Bastille Day!
 */

#ifndef PIO_META_H
#define PIO_META_H

#define PIO_VERSION_MAJOR 2 /*!< pio-c major version. */
#define PIO_VERSION_MINOR 5 /*!< pio-c minor version. */
#define PIO_VERSION_PATCH 1 /*!< pio-c patch version. */
#define PIO_VERSION       "2.5.1-development"

#define PIO_HAS_SZIP_WRITE 1 /*!< szip write support */
#define PIO_HAS_PNETCDF   1 /*!< PnetCDF support. */
#define PIO_HAS_PAR_FILTERS 1 /* NetCDF supports parallel I/O with filters. */

#endif

This is used by other libraries using PIO, which can easily find out PIO capabilities in either autoconf or CMake, something like this example from netcdf-fortran.

AC_MSG_CHECKING([if netCDF was built with CDF5])
AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [[
#include <netcdf_meta.h>
#if !defined(NC_HAS_CDF5) || NC_HAS_CDF5 == 0
      choke me
#endif]])], [nc_has_cdf5=yes], [nc_has_cdf5=no])
if test "x$nc_has_cdf5" = xyes; then
   AC_DEFINE([ENABLE_CDF5], [1], [Enable CDF-5 file format])
fi
AC_MSG_RESULT([$nc_has_cdf5])

Describe the solution you'd like I would like to add this to FMS, to aid in installation (via the text summary) and in use (via the fms_meta.h file, which other packages can use to easily learn the capabilities of PIO and how it was built).

This is implemented with the addition of two files: libfms.settings.in and fms_meta.h.in. At compile-time, these files are turned into libfms.settings and fms_meta.h, both of which are installed with FMS. This requires some lines of code in configure.ac and the top-level CMakeLists.txt file, to capture the values of the settings you deem worthy of inclusion.

Describe alternatives you've considered The alternative to the text summary is the current configure output, which contains all the relevant information, buried in a lot of other text. It is not captured, so not seen by any user of FMS, only the installer.

The alternative to the fms_meta.h file is less savory. As the years go by, you will add features to FMS that will be optional, selected at build time. (Handling such variation is one of the main tasks of the build system.) This information is not readily available to users of the FMS library. They may probe the capabilities of FMS by attempting to call a function that was introduced in a particular version. This is clumsy at best and does not capture many changes in capability which occur without a new function being introduced.

Other libraries, using FMS, will need to learn these settings at their own build time, just as netcdf-fortran needs to learn whether netcdf-c was built with CDF5. The fms_meta.h file will allow users to easily see what important settings were selected at FMS build-time.

Additional context

This is a very popular feature in netCDF which has resolved a lot of recurring support issues. Basically it presents a simple, central way to inform FMS users what the library can do, and how it was built, without them having to figure it out themselves, which they will probably get wrong frequently.

Due to the usefulness of the netcdf-c text summary in a recent round of installing netcdf-c on NOAA operational systems, I recently added this summary to PIO, and Ward added it to netcdf-fortran. The NOAA HPC installer reported that it made it significantly easier to check that he got all the settings correct, and that the configure script came up with all the expected answers.

NOAA-GFDL / FMS

Shall we add a build summary and fms_meta.h file? #533