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. The case.build script performs all build operations (setting dependencies, invoking Make/CMake, creating the executable).
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 |
DEBUG |
If |
GMAKE_J |
The number of threads GNU Make should use while building. |
Building the Model
Running case.build
will:
Create the component namelists in
$RUNDIR
and$CASEROOT/CaseDocs
.Build the shared libraries, utilities (e.g.
cprnc
) and place them in$SHAREDLIBROOT
.Build the components and model executables, which is placed in
$EXEROOT
.
Each utility, component, and the model will generate a log file in the form $name.bldlog.$datestamp
in the $EXEROOT
directory.
If the logs are compressed (as indicated by a .gz file extension), the build ran successfully.
Note
The following is just an example and can vary based on the model, compiler, and compset.
Running case.build
typically results in a directory structure similar to the following in $EXEROOT
.
.
├── atm
│ └── obj
├── cpl
│ └── obj
├── esp
│ └── obj
├── glc
│ └── obj
├── iac
│ └── obj
├── ice
│ └── obj
├── lib
│ └── include
├── lnd
│ └── obj
├── ocn
│ └── obj
├── oneapi-ifx
│ └── mpich
│ └── nodebug
│ └── nothreads
│ ├── gptl
│ ├── include
│ ├── lib
│ ├── mct
│ └── spio
├── rof
│ └── obj
└── wav
└── obj
In this example, the model is built with the Intel oneAPI compiler and uses MPICH for parallel communication (denoted by the oneapi-ifx
and mpich
directories). The nodebug
and nothreads
directories indicate that the build is not using debugging flags or threading.
The directories under oneapi-ifx/mpich/nodebug/nothreads
contains the external libraries used by the model.
The lib/include
directory contains special include modules.
The model executable is placed directly in the $EXEROOT
directory, which is typically named after the model (e.g., cesm.exe or e3sm.exe).
In the $EXEROOT
directory is where you’ll find the build logs for each component, external library, and the model executable.
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.
Rebuilding the Model
The model will need to be rebuilt if any of the following is changed:
env_build.xml
is modifiedMacros.make
is modifiedCode 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