Appendix A. The configure utility

Table of Contents
Options to configure
Environment variables recognized by configure

The configure utility provides a flexible way to specify a particular 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 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 running 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).

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).

Options to configure

All configuration options can be specified using command line arguments to configure and this is the recommended practice. Options specified via command line arguments take precedence over options specified any other way.

At the next level of precedence a few options can be specified by setting environment variables. And finally, at the lowest precedence, many options have hard-coded defaults. Most of these are located in the files $CAM_ROOT/models/atm/cam/bld/config_files/defaults_*.xml. A few that depend on the values of other options are set by logic contained in the configure script (a Perl script). The hard-coded defaults are designed to produce the standard production configurations of CAM.

The configure script allows the user to specify compile time options such as model resolution, dynamical core type, additional compiler flags, and many other aspects. The user can type configure --help for a complete list of available options.

The following options may all be specified with either one or two leading dashes, e.g., -help or --help. The few options that can be expressed as single letter switches may not be clumped, e.g., -h -s -v may NOT be expressed as -hsv. When multiple options are listed separated by a vertical bar either version may be used.

CAM configuration

These options will have an effect whether running CAM as part of CESM or running in a CAM standalone mode:


Switch on [off] age of air tracers. Default: on for waccm_phys, otherwise off.

-chem <name>

Build CAM with specified prognostic chemistry package [ waccm_mozart | waccm_ghg | trop_mozart | trop_ghg | trop_bam | trop_mam3 | trop_mam7 | super_fast_llnl | super_fast_llnl_mam3 | none ] Default: trop_mam3 if the physics package is cam5, otherwise default is none.


This option is meant to be used with the -ccsm_seq option. It modifies the CAM configuration by increasing the number of advected constituents by 4. Default: not set.

-comp_intf [mct | esmf]

Specify the component interfaces Default: mct.

-cppdefs <string>

A string of user specified CPP defines appended to Makefile defaults. E.g. -cppdefs '-DVAR1 -DVAR2'. Note that a string containing whitespace will need to be quoted.

-dyn [eul | sld | fv | homme ]

Build CAM with specified dynamical core. Default: fv.


Envokes CAMCHEM_EDITOR to allow the user to edit the chemistry mechanism file.

-hgrid <name>

Specify horizontal grid. For spectral grids use nlatxnlon where nlat and nlon are the number of latitude and longitude grid points respectively in the Gaussian grid. For FV grids use dlatxdlon where dlat and dlon are the grid cell size in degrees for latitude and longitude respectively. For the HOMME cubed sphere grid use nexnp.

-microphys [mg | rk]

Microphysics package. Default: mg if the physics package is cam5, otherwise rk.

-nadv <n>

Set total number of advected species to <n>.

-nadv_tt <n>

Set number of advected test tracers to <n>. Default: 0.

-nlev <n>

Set number of levels to <n>. Default: 30 if the physics package is cam5, ideal, or adiabatic. 26 if the physics package is cam4. 66 if the chemistry package is waccm_*.

-pbl [uw | hb | hbr]

PBL package. Default: uw if the physics package is cam5, otherwise hb.

-pcols <n>

Set maximum number of columns in a chunk to <n>. Default: 16.


Switch enables building CAM for perturbation growth tests. Only valid with cam4 physics package.

-phys [cam4 | cam5 | ideal | adiabatic]

Physics package. Default: cam5.

-prog_species <list>

Comma separated list of prognostic mozart species packages. Currently available: DST,SSLT,SO4,GHG,OC,BC,CARBON16

-rad [rrtmg | camrt]

Radiation package. Default: rrtmg if the physics package is cam5, otherwise camrt.

-usr_mech_infile <name>

Pathname of the user supplied chemistry mechanism file.


Switch enables the use of WACCM physics in any chemistry configuration. The user does not need to set this if one of the waccm chemistry options is chosen.

SCAM configuration


Configure CAM to generate an IOP file that can be used to drive SCAM. This switch only works with the Eulerian dycore.


Compiles model in single column mode. Only works with Eulerian dycore.

CAM parallelization


Switch on [off] SMP parallelism (OpenMP).


Switch on [off] SPMD parallelism (MPI).

CICE decomposition

When CAM is running standalone with CICE the CICE decomposition must be explicitly set using the following options:

Note: *** Either set all of -cice_bsizex, -cice_bsizey, -cice_maxblocks and cice_decomptype or set -ntasks and/or -nthreads which are used to determine defaults for the cice decomposition. ***

-cice_bsizex <n>

CICE block size in longitude dimension. This size must evenly divide the number of longitude points in the global grid.

-cice_bsizey <n>

CICE block size in latitude dimension. This size must evenly divide the number of latitude points in the global grid.

-cice_maxblocks <n>

Maximum number of CICE blocks per processor.

-cice_decomptype <name>

CICE decomposition type [ cartesian | spacecurve ].

-ntasks <n>

Number of MPI tasks. Setting ntasks > 0 implies -spmd. Use -nospmd to turn off linking with an MPI library. To configure for pure MPI specify "-ntasks N -nosmp". ntasks is used to determine default grid decompositions. Currently only used by CICE.

-nthreads <n>

Number of OpenMP threads per process. Setting nthreads > 0 implies -smp. Use -nosmp to turn off compilation of OMP directives. For pure OpenMP set "-nthreads N -nospmd" nthreads is used to determine default grid decompositions. Currently only used by CICE.

General options

-cache <name>

Name of output cache file. Default: config_cache.xml.

-cachedir <dir>

Name of directory where output cache file is written. Default: CAM build directory.


Switch to specify that CAM is being built from within the CESM scripts.

-help | -h

Print usage to STDOUT.

-silent | -s

Turns on silent mode - only fatal messages printed to STDOUT.


Switch on [off] testing of Fortran compiler and linking to external libraries.

-verbose | -v

Turn on verbose echoing of settings made by configure.


Echo the repository tag name used to check out this CAM distribution.

Surface components

Options for surface components used in standalone CAM mode:


Switch on VOC emissions in CLM. Default: off.

-ice [cice | sice | csim4 | none]

Specify the sea ice component. Default: cice.

-lnd [clm | slnd | none]

Specify the land component. Default: clm.

-ocn [docn | socn | dom | none]

Specify ocean component. Default: docn.

CAM standalone build

Options for building CAM via standalone scripts:

-cam_bld <dir>

Directory where CAM will be built. This is where configure will write the output files it generates (Makefile, Filepath, etc...). Default: ./

-cam_exe <name>

Name of the CAM executable. Default: cam.

-cam_exedir <dir>

Directory where CAM executable will be created. Default: CAM build directory.

-cc <name>

User specified C compiler. Overrides Makefile default.

-cflags <string>

A string of user specified C compiler options. Appended to Makefile defaults.


Switch to turn on building CAM with compiler options for debugging.

-defaults <name>

Specify a configuration file which will be used to supply defaults instead of one of the config_files/defaults_*.xml files. This file is used to specify model configuration parameters only. Parameters relating to the build which are system dependent will be ignored.

-esmf_libdir <dir>

Directory containing ESMF library and the file.

-fc <name>

User specified Fortran compiler. Overrides Makefile default.

-fflags <string>

A string of user specified Fortran compiler flags. Appended to Makefile defaults. See -fopt to override optimization flags.

-fopt <string>

A string of user specified Fortran compiler optimization flags. Overrides Makefile defaults.

-gmake <name>

Name of the GNU make program on your system. Supply the absolute pathname if the program is not in your path (or fix your path). This is only needed by configure for running tests via the -test option.

-lapack_libdir <dir>

Directory containing LAPACK library.

-ldflags <string>

A string of user specified load options. Appended to Makefile defaults.

-linker <name>

User specified linker. Overrides Makefile default of FC.

-mpi_inc <dir>

Directory containing MPI include files.

-mpi_lib <dir>

Directory containing MPI library.

-nc_inc <dir>

Directory containing NetCDF include files.

-nc_lib <dir>

Directory containing NetCDF library.

-nc_mod <dir>

Directory containing NetCDF module files.

-pnc_inc <dir>

Directory containing PnetCDF include files.

-pnc_lib <dir>

Directory containing PnetCDF library.


Build CAM with the offline radiation driver. This produces an executable that can only be used for offline radiation calculations.

-target_os <name>

Override the OS setting for cross platform compilation from the following list [aix|irix|linux| bgl|bgp ]. Default: OS on which configure is executed as defined by the Perl $OSNAME variable.

-usr_src <dir1>[,<dir2>[,<dir3>[...]]]

Directories containing user source code.