Introduction


The FCM provides a set of powerful tools for managing and building Fortran applications and FCM-make is one of those tools. The FCM is open source and is freely available for general use. The FCM has been used in code development of some models, e.g. Unified Model (UM). The advantage of using FCM-make for CABLE build has three:

(1) Given source code location in the fcm-make configuration file, fcm-make can automatically figure out the dependencies among Fotran modules as it is invoked; This means that you do not need specify dependency like "X.o: X.F90 Y.o Z.o" in the make configuration file.

(2) The fcm-make provides incremental build mode --- meaning when a file is modified, only this file and the files depending on it will be re-compiled other than all files. The FCM-make checks actual content changes by using md5-checksum of source files, targets and compiler flags other than checking timestamps of modified files as used in existing GNU make files.

(3) Using single fcm-make configuration file to handle three different cases ( serial, mpi and static library for UM) of CABLE build instead of using three make configuration files (Makefile_offline, Makefile_mpi, and Makefile_CABLE-UM)

How to build CABLE with FCM-make tool


You need to be a valid CABLE user so that you can checkout the fcm-make configuration files from CABLE code repository. Below we will take CABLE code tagged version 2.1.2 as an example to show you how to build CABLE with FCM-make tool on machine RAIJIN at NCI

(1) Make sure that fcm has been installed in your system. If not, you can get FCM from github in your chosen format. The FCM installation should be easy enough (see the installation instruction ). Please email FCM team for any FCM-related issues.

On machine RAIJIN/NCI, FCM has been installed. You need to be in access group for using FCM and you can check available FCM versions in ~access/modules/fcm.To use FCM, run:
module use ~access/modules; module load fcm/2013-12

For non-access group users, you can request to be added into access group or install FCM yourself in any directories you have access to. When more non-access group users use FCM, it can be considered moving to a common place on RAIJIN/NCI

You should have following loaded modules on RAIJIN/NCI:
intel-cc/12.1.9.293
intel-fc/12.1.9.293
openmpi/1.6.3
netcdf/4.2.1.1
fcm/2013-12

(2) Checkout CABLE code to cable-2.1.2/src in your current directory, run: svn co https://trac.nci.org.au/svn/cable/tagged/CABLE-2.1.2 cable-2.1.2/src

(3) Enter sub-dir cable-2.1.2, run: cd cable-2.1.2

(4) Checkout FCM-make configuration files, run: svn co https://trac.nci.org.au/svn/cable/branches/Share/FCM-make/config

(5) If you are on RAIJIN/NCI, you do not need modify any things and then proceed to step (6). For any other machines, you should have specific configuration files to your systems. Please refer to config/fcm/arch/raijin/ and config/fcm/netcdf/raijin.cfg as examples for your modifications. The following settings are relevant to your environment:

$CABLE_CFG_HOST
$CABLE_CFG_COMP
$CABLE_CFG_BLD
$CABLE_CFG_NCDF
$CABLE_CFG_MPI

You can make permanent changes to above environment variables in the configuration file config/fcm/cable-make.cfg.

(6) start to build CABLE:

(a) serial build: setenv CABLE_CFG_RUNTYPE serial (Tcsh) or export CABLE_CFG_RUNTYPE=serial (Bash)

(b) mpi build: setenv CABLE_CFG_RUNTYPE mpi (Tcsh) or export CABLE_CFG_RUNTYPE=mpi (Bash)

(c) static library for UM: setenv CABLE_CFG_RUNTYPE um (Tcsh) or export CABLE_CFG_RUNTYPE=um (Bash)

(d) run: fcm make -f config/fcm/make-cable.cfg

The executables( cable and cable_mpi) and static library for UM ( libcable.a) will be generated in build/bin and build/lib, respectively.

Note: if you want to get CABLE compiled with debug mode, replacing "default" with "debug" in the line "$CABLE_CFG_BLD{?} = default " in the file make-cable.cfg.
Alternatively, do not assign any values to "$CABLE_CFG_BLD{?} = " and then
run: setenv CABLE_CFG_BLD debug or export CABLE_CFG_BLD=debug before initiating "fcm make"

How to run CABLE-offline


In the directory cable-2.1.2, setup a sub-dir named run or your favourite name: mkdir run; cd run

In the directory run, setup a link to the executable in build/bin: ln -s ../build/bin/cable . or ln -s ../build/bin/cable-mpi .

Then you can make CABLE runs like you did before. You can place cable.nml, input files including met forcings or restart files under the run directory or setup links to corresponding data locations.

Note that a file ~/.cable_rev may be needed and you can create it by running:

svn info ../src | grep Revis |cut -c 11-18 > ~/.cable_rev

If you have any corrections or comments, please feel free to email us on cable_help@nf.nci.org.au so that we can continue to update this instruction over time.