The configure utility provides a flexible way to specify a particular configuration of CAM. By default it will produce the configuration files required to build the standard production version of CAM (currently Eulerian dynamics at T42 spectral resolution with 26 levels).
configure produces the configuration build files Filepath, misc.h, params.h, preproc.h, and Makefile. Each of these files specify compile-time parameters and settings needed to build the model. In addition, a configuration cache file (config_cache.xml by default) is written which may be used in a subsequent invocation of configure to exactly reproduce the configuration files. 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).
All configuration options can be specified in the following ways, listed in order of decreasing precedence:
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 file config_cache_defaults.xml in the configuration script directory. A few that depend on previous settings are hard-coded in configure (a perl script). The hard-coded defaults will produce the standard production configuration of CAM.
The interactive prompting mode has two levels: basic and expert. The basic mode, which is enabled by the -i option, asks the user all questions required to configure CAM, assuming that the model is built entirely from code that is contained in the distribution. The expert mode, which is enabled by setting the -x option in addition to -i, allows the user to specify that various pieces of code required to build CAM may come from directories outside the distribution. All the flexibility available in the expert interactive mode is also available from the specific options set on the command-line or from a user specified cache file.
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. Options that can be expressed as single letter switches may not be clumped, e.g., -i -x may NOT be expressed as -ix. When multiple options are listed separated by a vertical bar (|), either version may be used.
| Option Name | Description | Default |
|---|---|---|
| file specifies the pathname of the output configuration cache file. This file is not used in the build process (i.e., the Makefile does not depend on it), but is used instead to archive a complete description of the configuration of a CAM executable. This file is used by the build-namelist utility for setting default namelist values that depend on the configuration of the CAM executable (e.g., which dynamics package and what resolution are used). | config_cache.xml | |
| dir is the directory where CAM will be built. The configuration build files produced by invoking configure are written to this directory. It will eventually contain all the .o and .mod files produced by the build. | directory from which configure is invoked | |
| dir is the directory that contains the CAM configuration scripts, which includes perl modules as well as various defaults files that are required by configure. It is possible (but not recommended) to move configure to another directory, but then the configuration script directory must be explicitly specified so that configure can find its support files. Normally this directory will be determined by looking at the pathname that is used to invoke configure (assuming that configure has not been moved from the configuration script directory). If configure is not in the configuration script directory, then that directory can be specified either by this option, by setting the environment variable CAM_CFGDIR to the configuration script directory, or by setting the environment variable CAM_ROOT to the root directory of the CAM distribution assuming that the configuration directory is $CAM_ROOT/models/atm/cam/bld. | directory part of the absolute pathname used to invoke configure | |
| name is the name of the CAM executable file. | cam | |
| dir is the directory where the CAM executable will be created. | the CAM build directory | |
| dir specifies the top level directory of a CAM distribution. This directory must contain the subdirectory models which must contain the subdirectories atm, csm_share, ice, and lnd. The CAM root directory can also be specified by setting the environment variable CAM_ROOT. | config_dir/../../../.. where config_dir is the directory containing the configure executable. | |
| name specifies the C compiler. This allows the user to override the default setting in the Makefile (Linux only). The C compiler can also be specified by setting the environment variable USER_CC. | pgcc if using pgf90, otherwise use cc | |
| Enable the compiler debugging options that are specified in the Makefile. | no debugging | |
| file specifies the pathname of a configuration cache file that will used to provide default values, e.g. a config_cache.xml from a previous invocation of configure. Note that by default the current configuration will be written to a file named config_cache.xml, so the user should avoid running configure in the same directory in which the defaults file is located. Alternatively the output cache file can be renamed by using the -cache option. | none | |
| name specifies the dynamics package to be used when running CAM. The valid options are eul (Eulerian spectral dynamics), sld (semi-Lagrangian spectral dynamics), and fv (finite-volume dynamics). | eul | |
| dir is the top level directory where the ESMF library will be built. It will contain the directories mod, lib/libg and/or lib/libO which each contain subdirectories that contain machine architecture specific files. | cam_bld/esmf, where cam_bld is the build directory for CAM. | |
| dir is the top level directory for the ESMF distribution. This directory contains the main makefile for the ESMF library. The ESMF root directory can also be specified by setting the environment variable ESMF_ROOT. Note that the ESMF library is supplied as part of the CAM distribution, and by default the supplied library is built and used by CAM. This option allows for a custom build of CAM that builds an ESMF library using source code from outside the CAM distribution. | $CAM_ROOT/ models/utils/esmf, where cam_root is the root directory of the CAM distribution. | |
| name specifies the Fortran compiler. This allows the user to override the default setting in the Makefile. The Fortran compiler can also be specified by setting the environment variable USER_FC. | OS dependent | |
| The Fortran compiler options specified by string will be appended to the default setting of FFLAGS in the Makefile. If string contains any whitespace it must be quoted. | ||
| 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 if testing will be done (see -test). | The names 'gmake', 'gnumake', and 'make' are checked in order. | |
| Print usage to STDOUT. | ||
| Turns on the basic interactive prompting mode. In the basic prompt mode only questions required to obtain a standard configuration of CAM will be asked. To allow configurations which require code from outside the CAM distribution, an expert prompt mode can be enabled by additionally specifying the -x option. In either mode a default value for each setting will be determined based on, in order of decreasing precedence, the specific command-line option for that setting, a user specified default configuration cache file, an environment variable, or a hard-coded default. This default value may then be accepted by entering ``return'', or overridden by the user. Values are checked when possible for legality and consistency. | ||
| dir is the directory that contains the MPI library include files. Only SPMD versions of CAM require MPI. The MPI include directory can also be specified by setting the environment variable INC_MPI. | /usr/local/include except on IBM systems. The IBM Fortran compilers mpxlf90 and mpxlf90_r have the MPI include file location built in. | |
| dir is the directory that contains the MPI library. Only SPMD versions of CAM require MPI. The MPI library directory can also be specified by setting the environment variable LIB_MPI. | /usr/local/lib except on IBM systems. The IBM Fortran compilers mpxlf90 and mpxlf90_r have the MPI library location built in. | |
| num is the number of advected constituents. This value must be at least 3 because water vapor, cloud liquid, and cloud ice are always advected constituents. | 3 | |
| dir is the directory that contains the NetCDF library include files. All configurations of CAM require NetCDF. The NetCDF include directory can also be specified by setting the environment variable INC_NETCDF. | /usr/local/include | |
| dir is the directory that contains the NetCDF library. All configurations of CAM require NetCDF. The NetCDF library directory can also be specified by setting the environment variable LIB_NETCDF. | /usr/local/lib | |
| num is the number of model grid latitudes. This option is only recognized when the -res option is set to custom. | 64 | |
| num is the number of model vertical layers. | 26 | |
| num is the number of distinct model grid longitudes. This option is only recognized when the -res option is set to custom. | 128 | |
| num is the number of non-advected constituents. The default value is 0. | 0 | |
| Select an ocean model. name can be either dom, which indicates the data ocean model, or som, which indicates the slab ocean model. | dom | |
| Configure CAM to enable perturbation growth experiments. Note that this option disables parts of the CAM code that have been found to produce rapid growth of roundoff size perturbations. | ||
| name specifies the horizontal resolution. For spectral dynamics the horizonal grid is Gaussian and is specified as nlat x nlon where nlat is the number of Gaussian latitudes and nlon is the number of distinct longitudes. For finite-volume dynamics the meridional grid is equally spaced and includes the pole points. It is specified as dlatxdlon where dlat is the latitude cell size and dlon is the longitude cell size, both in degrees. All of the valid resolutions are listed in the resolution_parameters.xml file in the configuration script directory. Commonly used resolutions include 48x96, 64x128, and 128x256 for the spectral dycores, and 2x2.5 for the FV dycore. To configure CAM for a resolution that is not in the resolution_parameters.xml file the value of -res must be set to custom. NOTE: some resolutions recognized by this option are for development purposes only. The recognition of a resolution by this option does NOT imply the existence of a validated control run. | 64x128 | |
| Turns off all output to STDOUT. Fatal error messages will still be issued to STDERR. | ||
| -smp enables an SMP configuration of CAM (via openMP). -nosmp disables an SMP configuration of CAM. | SMP is enabled by default only on IBM and SGI systems. | |
| -spmd enables an SPMD configuration of CAM (via MPI). -nospmd disables an SPMD configuration of CAM. | SPMD is enabled by default only on IBM systems. | |
| -test enables testing the Fortran compiler and external libraries and -notest disables testing. The tests are: 1. Check that the Fortran compiler will successfully build a ``hello world'' program that uses Fortran 90 module syntax. 2. Check that the Fortran compiler will successfully build a test program that contains an external reference to a NetCDF library function. 3. Check that the Fortran compiler will successfully build a test program that contains an external reference to an MPI library function, if SPMD is enabled. | testing off except in interactive prompting mode | |
| num is the spectral resolution parameter that specifies the highest degree of the associated Legendre polynomials. This option is only recognized when the -res option is set to custom. | 42 | |
| num is the spectral resolution parameter that specifies the maximum Fourier wavenumber. This option is only recognized when the -res option is set to custom. | 42 | |
| num is the spectral resolution parameter that specifies the highest degree of the Legendre polynomials for m=0. This option is only recognized when the -res option is set to custom. | 42 | |
| dir1[,dir2[,dir3[...]]] specifies the directories containing user source code. These directories will be placed, in the order in which they are specified, at the beginning of the Filepath file. The Filepath file is used by the CAM Makefile to determine which source files will be compiled. The list of source files is comprised of all files with .F90, .F, or .c extensions in each directory listed in Filepath plus the current directory. The Filepath file is also used by the CAM Makefile to determine which directories will be searched when looking for a source file that can be used to build an object file. The search begins in the current directory, and then proceeds to the directories in the Filepath file, in the order in which they are specified. The first file found will be the one used by make to create the object file. | none | |
| num specifies the verbosity level of the output to STDOUT. Level 1 echos only the names of the files produced by configure. Level 2 adds echoing of the configuration specifications associated with a standard build of CAM. Level 3 adds echoing of the specifications associated with an ``expert'' build of CAM. | 1 | |
Echo the CVS tag
name that was
used to check out the CAM distribution, then exit. If no tag was
used for the check-out then the string  will be echoed. |
||
| Turns on the ``expert'' interactive mode. See the -i option for more details. |
The environment variables recognized by configure are presented in Table 2.2.
| Variable Name | Description |
|---|---|
| The root directory of the CAM distribution. The directory containing the configuration scripts is $CAM_ROOT/models/atm/cam/bld. | |
| The directory that contains the CAM configuration scripts. This is provided only for the special case that the configuration scripts are taken from a directory outside of the CAM distribution. | |
| Root directory to the ESMF source code. | |
| Directory containing the NetCDF include files. | |
| Directory containing the NetCDF library. | |
| Directory containing the MPI include files. This is only required when CAM is built with SPMD enabled. | |
| Directory containing the MPI library. This is only required when CAM is built with SPMD enabled. | |
| User specified Fortran compiler. Overrides Makefile default. | |
| User specified C compiler. Overrides Makefile default. Currently only recognized on linux systems. |