Configure generates buildnml and buildexe scripts for each component in the Buildconf directory. It also generates build, run, l_archive, and clean_build scripts in the CASEROOT directory. These scripts generate namelist for components and build and run the CESM1 model.
configure (invoked with the -case option) uses variables in env xml
files to generate a new
Buildconf/ directory and several new files in
$CASEROOT.
Note: Any user modifications to env_conf.xml and env_mach_pes.xml must be done before configure is invoked. In the simplest case, configure can be run without modifying either of these files and default settings will be then be used.
Before exploring the details of configure, it is important to understand the concept of locked env files. The env files are "locked" after the variables have been used by other parts of the system and cannot be changed. The scripts do this by "locking" a file and not permitting the user to modify that file. More information on locking files can be found in the Section called Why is there file locking and how does it work? in Chapter 11
The configure command must be run in the $CASEROOT
directory and must be invoked with one of the following options:
configure [-help] [-case] \
[-cleanmach] [-cleannamelist] [-cleanall]
|
-case
sets up the case for build and run phases.
It creates Buildconf/,
$CASE.$MACH.run,
$CASE.$MACH.build,
$CASE.$MACH.clean_build,
$CASE.$MACH.l_archive,
directories and files in $CASEROOT.
-cleanmachMoves all machine-related files to a date-stamped backup directory under MachinesHist/. These files include: Macros.$MACH, $CASE.$MACH.build, $CASE.$MACH.clean_build, $CASE.$MACH.l_archive, and $CASE.$MACH.run. It also unlocks env_mach_pes.xml, Macros.$MACH, and env_build.xml, so users can reset machine tasks and threads and rerun configure. Reconfiguring with -cleanmach results in the loss of any local modifications to the local build and run scripts. But the Buildconf/ directory will not be updated in this process. As a result, local changes to namelists will be preserved.
If you only modify env_mach_pes.xml after running configure, do the following:
> configure -cleanmach > # Make changes to env_mach_pes.xml > configure -case |
-cleannamelistMoves Buildconf/ to a date-stamped backup directory under MachinesHist/ and unlocks env_conf.xml. Reconfiguring with -cleannamelist results in the loss of any local modifications to the Buildconf buildnml and buildexe files. But the local build and run scripts will be preserved.
If you only want to modify env_conf.xml after running configure, do the following:
> configure -cleannamelist > # Make changes to env_conf.xml here > configure -case |
-cleanall
This performs the functions of both the -cleanmach and -cleannamelist
options. All files associated with the previous invocation of
configure are moved to a time-stamped directory in
MachinesHist. The $CASEROOT directory will now
appear as if create_newcase had just been run with the exception
that local modifications to the env_*.xml files
are preserved. After further modifications are made to env_conf.xml
and env_mach_pes.xml, you must run configure -case
before you can build and run the model. Reconfiguring results in the
loss of all local modifications to the component buildnml or buildexe
files in Buildconf as well as the loss of all local modifications to
the local build and run scripts.
-helpLists all options with short descriptions.
Configure generates buildnml and buildexe scripts for each component in the Buildconf directory. It also generates build, run, l_archive, and clean_build scripts in the CASEROOT directory. These scripts are now sufficient to build and run the model.
Table 3-1. Result of invoking configure
| File or Directory | Description |
|---|---|
| Buildconf/ | Contains scripts that generate component libraries and utility libraries (e.g., PIO, MCT) and scripts that generate component namelists. |
| $CASE.$MACH.build | Creates the component and utility libraries and model executable (see building CESM). |
| $CASE.$MACH.run | Runs the CESM model and performs short-term archiving of output data (see running CESM). Contains the necessary batch directives to run the model on the required machine for the requested PE layout. |
| $CASE.$MACH.l_archive | Performs long-term archiving of output data (see long-term archiving). This script will only be created if long-term archiving is available on the target machine. |
| $CASE.$MACH.clean_build | Removes all object files and libraries and unlocks Macros.$MACH and env_build.xml. This step is required before a clean build of the system. |
| env_derived | Contains environmental variables derived from other settings. Should not be modified by the user. |