# Editing Template Files Before Configure

The last kind of customization that you can do for a case, before configure is run is to edit the templates. The &clm; template is in `models/lnd/clm/bld/clm.cpl7.template`, the &datm; template is in `models/atm/datm/bld/datm.cpl7.template`, and the driver templates are in the `models/drv/bld` directory and are named: `ccsm.template` and `cpl.template`. When a case is created they are also copied to the `Tools/Templates` directory underneath your case. If you want to make changes that will impact all your cases, you should edit the template files under the `models` directory, but if you want to make a change ONLY for a particular case you should edit the template under that specific case.

Editing the template files is NOT for the faint of heart! We recommend this ONLY for experts! It's difficult to do because the template is a script that actually creates another script. So part of the script is echoing the script to be created and part of it is a script that is run when "configure -case" is run. As a result any variables in the part of the script that is being echoed have to be escaped like this:

    \$VARIABLE

But, in other parts of the script that is run, you can NOT escape variables. So you need to understand if you are in a part of the script that is echoing the script to be created, or in the part of the script that is actually run.

If you can customize your case using: compsets, `env_*.xml` variables, or a user namelist, as outlined in you should do so. The main reason to actually edit the template files, is if you are in a situation where the template aborts when you try it run it when "configure -case" is run. The other reason to edit the template is if you are &clm; developer and need to make adjustments to the template because of code or script updates. An example of modifying the &datm; template is in where sed is used to modify the path for &CPLHIST; data.

## Outline of the &clm; template

The outline of the &clm; template is as follows:

    # set up options for clm configure and then run clm configure
    $CODEROOT/lnd/clm*/bld/configure <options>
    # set up options for clm build-namelist and then run clm build-namelist
    $CODEROOT/lnd/clm*/bld/build-namelist <options>
    # echo the $CASEBUILD/clm.buildnml.csh script out
    cat >! $CASEBUILD/clm.buildnml.csh << EOF1
    # NOTE: variables in this section must be escaped
    EOF1
    # Remove temporary namelist files

    # echo the $CASEBUILD/clm.buildexe.csh script out
    cat > $CASEBUILD/clm.buildexe.csh <<EOF2
    # NOTE: variables in this section must be escaped
    EOF2
    # Remove temporary configure files

## Outline of the &datm; template

The outline of the &datm; template is as follows:

    # Check $GRID to set the $DOMAINFILE and $DOMAINPATH

    # Check DATM_PRESAERO to set the prescribed aerosol option
    # If &CLMUSRDAT; is set and $DOMAINFILE is NOT -- set it by &CLMUSRDAT;
    # Ensure $DOMAINFILE is set or else abort

    #==============================================================================
    # Create resolved prestage data script
    #==============================================================================
    cat >! $CASEBUILD/datm.buildnml.csh << EOF1
    # NOTE: variables in this section must be escaped
    EOF1
    # Major if blocks look at DATM_MODE:
    # the if blocks setup streams and run Tools/build_streams to create stream files
    #----- CLM_QIAN mode ----------------------------------------------------------
    else if ($DATM_MODE == "&CLMQIAN;" ) then
    .
       # Customize &CLMQIAN; options here

       # A.) Setup datm_atm_in namelist
    cat >! $CASEBUILD/datm.buildnml.csh << EOF
    cat >! datm_atm_in << EOF1
    # NOTE: variables in this section must be escaped
    EOF1
    EOF

       # B.) Setup options to build_streams
    .
    .
    .
    #----- CLM1PT   mode ----------------------------------------------------------
    else if ($DATM_MODE == "CLM1PT" ) then
    .
       # Customize CLM1PT options here

       # A.) Setup datm_atm_in namelist
    cat >! $CASEBUILD/datm.buildnml.csh << EOF
    cat >! datm_atm_in << EOF1
    # NOTE: variables in this section must be escaped
    EOF1
    EOF

       # B.) Setup options to build_streams
    .
    .
    .
    .
    #----- CPLHIST 3-hourly time-averaging mode
    ----------------------------------------------------------
    else if ($DATM_MODE == "&CPLHIST;" ) then
    .
       # Customize &CPLHIST; options here

       # A.) Setup datm_atm_in namelist
    cat >! $CASEBUILD/datm.buildnml.csh << EOF
    cat >! datm_atm_in << EOF1
    # NOTE: variables in this section must be escaped
    EOF1
    EOF

       # B.) Setup options to build_streams
    .
    .
    .
    .

    #----- INVALID mode -----------------------------------------------------------else
      echo "ERROR: unrecognized DATM_MODE = \$DATM_MODE "
      exit -1
    endif

    #==============================================================================
    # Create prescribed aero streams if appropriate
    #==============================================================================
    .
    .
    .
    #==============================================================================
    # Create remaining resolved namelist
    #==============================================================================

    cat >! $CASEBUILD/datm.buildnml.csh << EOF
    cat >! datm_in << EOF1
    # NOTE: variables in this section must be escaped
    .
    .
    .
    EOF1

    EOF

    #==============================================================================
    #  Create script to build executable
    #==============================================================================

    cat > $CASEBUILD/datm.buildexe.csh <<EOF
    #! /bin/csh -f
    # NOTE: variables in this section must be escaped
    EOF

    #==============================================================================
    # end of script
    #==============================================================================

## Adding a new DATM_MODE to the &datm; template

### The steps to adding a new DATM_MODE

1. ### Add a new "if" block to the &datm; template

   As you can see from above there are major "if" blocks for the different DATM_MODE's. So adding a new DATM_MODE means adding a new "if" block. The two major parts of each DATM_MODE block are:

   - Setup `datm_atm_in` namelist
   - Setup options to `build_streams`

2. ### In the "if" block create the `datm_atm_in` namelist

   See for some notes about the &datm; namelist and streams files. That and the &datm; User's Guide should give you guidance on how to setup the namelist for your case.

3. ### In the "if" block create options to and call `build_streams`

   The next part of the "if" block in the &datm; template file to work with is the call to `build_streams`. You may need to add additional options to it. You may also need to call it multiple times for multiple streams. You will also likely need to add a new source option to it with the "-s" option. For more information on `build_streams` do the following.

   ### Getting help with `build_streams` for &datm;

       > scripts/ccsm_utils/Tools/build_streams -help

   The output of the above command is:

       &build_streams_help;

4. ### Add new streams templates to the &datm; `datm.template.streams.xml` file

   As part of modifying the behavior of `build_streams` you will also have to edit the `models/atm/datm7/bld/datm.template.streams.xml` file as well (or the local version in your `$CASENAME/Tools/Templates` directory for a particular case). The template is an XML file much like the output streams file, but there are attributes to distinguish which fields will be used based on things like: RESOLUTION or datasource. And there are filename indicators (starting with a "%") that get translated into various things such as:

       %c   = Case (from above -case command line option)
       %do  = Use domain file
       %y   = Year (through range given from begyear to endyear)
       %ym  = Year-Month (all 12 months through year range)
       %6ym = Like %ym but 6 digit year (ie. %YYYYYY-MM).  (can replace the 6 with any digit 1-9)

5. ### Add a new valid_value to the `config_definition.xml` file in scripts.

   Adding a new DATM_MODE also requires adding a new valid_value to `scripts/ccsm_utils/Case.template/config_definition.xml`. This enables the scripts to recognize the new value as a valid option to DATM_MODE in the &envconf; file.

# Building the Users-Guide Documentation for &clm;

All of the documentation for &clm; can be built using GNU Makefiles that are available in the appropriate directories. The Makefiles require the following utilities: `docbook2html`, `docbook2pdf`, `protex`, and `latex2html`.

To build the Users Guide for &clm; (requires docbook).

    > cd models/lnd/clm/doc/UsersGuide
    > gmake

Note, that when the Users-Guide is built it will get output from other &clm; utilities that by nature abort, and hence stop the make from continuing. However, this is expected so you should simply run `gmake` again until it either completes or comes upon a legitimate issue. Here is what a sample warning looks like when `gmake` is run.

    The following line will fail in the make as it calls die -- but that is expected
    Check that the output config_help.tlog is good and redo your make
    ../../bld/configure -help >&` config_help.tlog
    make: *** [config_help.tlog] Error 255

To build the Code Reference Guide for &clm; (requires `protex` and `latex2html`). The make here uses a `Filepath` file that points to the list of directories that you want `protex` to run over. You should examine this file and make sure it is appropriate for what you need to do, before running the make.

    > cd models/lnd/clm/doc/CodeReference
    > gmake

To build the table of tests for the &clm; test suite. The make here runs a UNIX shell script to create a html table of the list of tests run on the different machines from the &clm; test suite.

    > cd models/lnd/clm/test/system
    > gmake