Appendix A. The configure utility

The configure utility provides a flexible way to specify any configuration of CAM. The best way to communicate to another user how you built CAM is to simply supply them with the configure commandline that was used (along with the source code version).

configure has two distinct operating modes which correspond to the two distinct ways of building CAM, i.e., either using the CESM scripts, or using CAM standalone scripts. By default configure runs in the mode used by the standalone scripts. In this mode configure is responsible for setting the filepaths and CPP macros needed to build not only CAM, but all the components of the standalone configuration including the land, sea ice, data ocean, and driver. In the mode used when building CAM from the CESM scripts configure is only responsible for setting the filepaths and CPP macros needed to build a library containing just the CAM component.

When configuring a build of standalone CAM, configure produces the files Filepath and Makefile. In addition, a configuration cache file (config_cache.xml by default) is written which contains the values of all the configuration parameters set by configure. The files produced by configure are written to the directory where CAM will be built, which by default is the directory from which configure is executed, but can be specified to be elsewhere (see the -cam_bld option).

When configuring CAM for a build using the CESM scripts, configure doesn't write a Makefile, but instead writes a file CCSM_cppdefs which is used by the CESM Makefile. Also, the Filepath file only contains paths for the CAM component.

In both modes configure is responsible for setting the correct filepaths and CPP macros to produce the desired configuration of CAM's dynamical core, physics parameterizations and chemistry scheme. The options that are involved in making these choices are described in the Section called CAM configuration below. The subsequent sections describe options used by the CAM standalone scripts.

configure will optionally perform tests to validate that the Fortran compiler is operational and Fortran 90 compliant, and that the linker can resolve references to required external libraries (NetCDF and possibly MPI). These tests will point out problems with the user environment in a way that is much easier to understand than looking at the output from a failed build of CAM. We strongly recommend that the first time CAM is built on any new machine, configure should be invoked to execute these tests (see the -test option).