Building a Case

Once the case has been created and set up, it’s time to build the executable. Several directories full of source code must be built all with the same compiler and flags. case.build performs all build operations (setting dependencies, invoking Make/CMake, creating the executable).

Build Process

The case.build command generates the utility/component libraries and the model executable. Each utility and component build has a log file generated named in the form: $component.bldlog.$datestamp. They are located in $BLDDIR. If they are compressed (as indicated by a .gz file extension), the build ran successfully.

Invoking case.build creates the following directory structure in $EXEROOT if the Intel compiler is used:

atm/
cpl/
esp/
glc/
ice/
intel/
lib/
lnd/
ocn/
rof/
wav/

Except for intel/ and lib/, each directory contains an obj/ subdirectory for the target model component’s compiled object files.

The mct, pio, gptl, and csm_share libraries are placed in a directory tree that reflects their dependencies. See the bldlog for a given component to locate the library.

Special include modules are placed in lib/include. The model executable (cesm.exe or e3sm.exe, for example) is placed directly in $EXEROOT.

Component namelists, component logs, output data sets, and restart files are placed in $RUNDIR.

Important

It is important to note that $RUNDIR and $EXEROOT are independent variables that are set in the $CASEROOT/env_run.xml file.

The default values for $RUNDIR and $EXEROOT respectively are $CIME_OUTPUT_ROOT/$CASE/run and $CIME_OUTPUT_ROOT/$CASE/bld. Changing the $CIME_OUTPUT_ROOT variable will change the location of the run and build directories.

Configuring the Build

You do not need to change the default build settings to create the executable, but it may be useful to change them to make optimal use of the system. CIME provides the xmlquery and xmlchange commands to view and modify the build settings.

Below are some variables that affect the build process and output.

Variable

Description

BUILD_THREADED

If TRUE the model will be built with OpenMP.

DEBUG

If TRUE the model is compiled with debugging instead of optimization flags.

GMAKE_J

The number of threads GNU Make should use while building.

Building the Model

After calling case.setup, running case.build will:

  1. Create the component namelists in $RUNDIR and $CASEROOT/CaseDocs.

  2. Create the necessary compiled libraries used by coupler and component models mct, pio, gptl, and csm_share. The libraries will be placed in a path below $SHAREDLIBROOT.

  3. Create the necessary compiled libraries for each component model. These are placed in $EXEROOT/bld/lib.

  4. Create the model executable $MODEL.exe, which is placed in $EXEROOT.

Rebuilding the Model

The model will need to be rebuilt if any of the following is changed:

  • env_build.xml is modified

  • Macros.make is modified

  • Code is added to SourceMods/src

Note

Macros.make may or may not be present. It’s dependent on the model and whether Make or CMake is used.

It’s safest to clean the build and rebuild from scratch in these cases.

./case.build --clean-all
./case.build

If threading has been changed (turned on or off) in any component since the previous build, the build script should fail with the following error and suggestion that the model be rebuilt from scratch:

ERROR SMP STATUS HAS CHANGED
SMP_BUILD = a0l0i0o0g0c0
SMP_VALUE = a1l0i0o0g0c0
A manual clean of your obj directories is strongly recommended.
You should execute the following:
  ./case.build --clean
  ./case.build

---- OR ----

You can override this error message at your own risk by executing:
  ./xmlchange SMP_BUILD=0
Then rerun the build script interactively.

Important

If there is any doubt, rebuild.

Run this to clean all of the model components (except for support libraries such as mct and gptl):

./case.build --clean

Run this to clean everything associated with the build:

./case.build --clean-all

You can also clean an individual component as shown here, where “compname” is the name of the component you want to clean (for example, atm, clm, pio, and so on).

./case.build --clean compname