How do I build my model

The following summarizes details of building the model exectuable.

How do I build my model?

After calling cesm_setup, you can build the model executable by running ./$CASE.build. Running this will:

1. create the component namelists in $RUNDIR (by calling the Buildconf/$component.buildnml.csh scripts).
2. check for the required input data sets and download missing data automatically on local disk, and if successful proceed to the following steps.
3. create the necessary utility libraries by calling Buildconf/mct.buildlib, Buildconf/pio.buildlib and Buildconf/gptl.buildlib and Buildconf/csm_share.buildlib.
4. create the necessary component libraries by calling Buildconf/$component.buildexe.csh, where $component is the name of atm, lnd, rof, ocn, cice, glc and cpl components (which depends on the compset being used).
5. create the model executable by calling Buildconf/cesm.buildexe.csh.

$CASEROOT/Tools/Makefile and $CASEROOT/Macros (generated by calling cesm_setup) are used to generate the utility and component libraries and the model executable. You do not need to change the default build settings to create the executable. However, since the CESM scripts provide you with a great deal of flexibility in customizing various aspects of the build process, it is useful to become familiar with these in order to make optimal use of the system.

The env_build.xml variables, control various aspects of building the model executable. Most of the variables should not be modified by users. Among the variables that you can modify are EXEROOT, RUNDIR, BUILD_THREADED, DEBUG and GMAKE_J. Full documentation for each variable is provided in the env_build.xml variables.

> cd $CASEROOT
> ./$CASE.build

Diagnostic comments will appear as the build proceeds. The following line indicates that the component namelists have been generated successfully::

....
CCSM BUILDNML SCRIPT HAS FINISHED SUCCESSFULLY
....

When the required case input data in $DIN_LOC_ROOT has been successfully checked, you will see::

CCSM PRESTAGE SCRIPT STARTING
...
CCSM PRESTAGE SCRIPT HAS FINISHED SUCCESSFULLY

Finally, the build script generates the utility and component libraries and the model executable. There should be a line for the mct, pio, and gptl libraries, as well as each of the components. Each is date stamped, and a pointer to the build log file for that library or component is shown. Successful completion is indicated by:

CCSM BUILDEXE SCRIPT HAS FINISHED SUCCESSFULLY

The build log files have names of the form $model.bldlog.$datestamp and are located in $RUNDIR. If they are compressed (indicated by a .gz file extension), then the build ran successfully.

Invoking $CASE.build creates the following directory structure in $EXEROOT:

$EXEROOT/atm
$EXEROOT/cesm
$EXEROOT/cpl
$EXEROOT/csm_share
$EXEROOT/glc
$EXEROOT/ice
$EXEROOT/lib
$EXEROOT/lnd
$EXEROOT/mct
$EXEROOT/ocn
$EXEROOT/pio
$EXEROOT/rof

The atm/, cesm/, cpl/, glc/, ice/, lnd/, ocn/ and rof/ subdirectories in $EXEROOT each contain an 'obj/' directory where the compiled object files for the target model component is placed. These object files are collected into libraries that are placed in 'lib/' along with the mct/mpeu, pio, gptl, and csm_share libraries. Special include modules are also placed in lib/include. The model executable 'cesm.exe' is placed directly in $EXEROOT. On the other hand, component namelists, component logs, output datasets, and restart files are placed in $RUNDIR. It is important to note that in CESM $RUNDIR and $EXEROOT are independent variables which are set in the file config_machines.xml in the directory $CCSMROOT/scripts/ccsm_utils/Machines/.