3.16.2 Using genmake2

To compile the code, first use the program genmake2 (located in the tools directory) to generate a Makefile. genmake2 is a shell script written to work with all ``sh''-compatible shells including bash v1, bash v2, and Bourne. Internally, genmake2 determines the locations of needed files, the compiler, compiler options, libraries, and Unix tools. It relies upon a number of ``optfiles'' located in the tools/build_options directory.

The purpose of the optfiles is to provide all the compilation options for particular ``platforms'' (where ``platform'' roughly means the combination of the hardware and the compiler) and code configurations. Given the combinations of possible compilers and library dependencies (eg. MPI and NetCDF) there may be numerous optfiles available for a single machine. The naming scheme for the majority of the optfiles shipped with the code is

OS

is the name of the operating system (generally the lower-case output of the 'uname' command)

HARDWARE

is a string that describes the CPU type and corresponds to output from the 'uname -m' command:

ia32

is for ``x86'' machines such as i386, i486, i586, i686, and athlon

ia64

is for Intel IA64 systems (eg. Itanium, Itanium2)

amd64

is AMD x86_64 systems

ppc

is for Mac PowerPC systems

COMPILER

is the compiler name (generally, the name of the FORTRAN executable)

In many cases, the default optfiles are sufficient and will result in usable Makefiles. However, for some machines or code configurations, new ``optfiles'' must be written. To create a new optfile, it is generally best to start with one of the defaults and modify it to suit your needs. Like genmake2, the optfiles are all written using a simple ``sh''-compatible syntax. While nearly all variables used within genmake2 may be specified in the optfiles, the critical ones that should be defined are:

FC

the FORTRAN compiler (executable) to use

DEFINES

the command-line DEFINE options passed to the compiler

CPP

the C pre-processor to use

NOOPTFLAGS

options flags for special files that should not be optimized

For example, the optfile for a typical Red Hat Linux machine (``ia32'' architecture) using the GCC (g77) compiler is

FC=g77
DEFINES='-D_BYTESWAPIO -DWORDLENGTH=4'
CPP='cpp  -traditional -P'
NOOPTFLAGS='-O0'
#  For IEEE, use the "-ffloat-store" option
if test "x$IEEE" = x ; then
    FFLAGS='-Wimplicit -Wunused -Wuninitialized'
    FOPTIM='-O3 -malign-double -funroll-loops'
else
    FFLAGS='-Wimplicit -Wunused -ffloat-store'
    FOPTIM='-O0 -malign-double'
fi

If you write an optfile for an unrepresented machine or compiler, you are strongly encouraged to submit the optfile to the MITgcm project for inclusion. Please send the file to the

In addition to the optfiles, genmake2 supports a number of helpful command-line options. A complete list of these options can be obtained from:

% genmake2 -h

The most important command-line options are:

-optfile=/PATH/FILENAME

specifies the optfile that should be used for a particular build.

If no "optfile" is specified (either through the command line or the MITGCM_OPTFILE environment variable), genmake2 will try to make a reasonable guess from the list provided in tools/build_options. The method used for making this guess is to first determine the combination of operating system and hardware (eg. "linux_ia32") and then find a working FORTRAN compiler within the user's path. When these three items have been identified, genmake2 will try to find an optfile that has a matching name.

-pdefault='PKG1 PKG2 PKG3 ...'

specifies the default set of packages to be used. The normal order of precedence for packages is as follows:

1. If available, the command line (-pdefault) settings over-rule any others.

2. Next, genmake2 will look for a file named ``packages.conf'' in the local directory or in any of the directories specified with the -mods option.

3. Finally, if neither of the above are available, genmake2 will use the /pkg/pkg_default file.

-pdepend=/PATH/FILENAME

specifies the dependency file used for packages.

If not specified, the default dependency file pkg/pkg_depend is used. The syntax for this file is parsed on a line-by-line basis where each line containes either a comment ("#") or a simple "PKGNAME1 (+|-)PKGNAME2" pairwise rule where the "+" or "-" symbol specifies a "must be used with" or a "must not be used with" relationship, respectively. If no rule is specified, then it is assumed that the two packages are compatible and will function either with or without each other.

-adof=/path/to/file

specifies the "adjoint" or automatic differentiation options file to be used. The file is analogous to the ``optfile'' defined above but it specifies information for the AD build process.

The default file is located in tools/adjoint_options/adjoint_default and it defines the "TAF" and "TAMC" compilers. An alternate version is also available at tools/adjoint_options/adjoint_staf that selects the newer "STAF" compiler. As with any compilers, it is helpful to have their directories listed in your $PATH environment variable.

-mods='DIR1 DIR2 DIR3 ...'

specifies a list of directories containing ``modifications''. These directories contain files with names that may (or may not) exist in the main MITgcm source tree but will be overridden by any identically-named sources within the ``MODS'' directories.

The order of precedence for this "name-hiding" is as follows:

• ``MODS'' directories (in the order given)
• Packages either explicitly specified or provided by default (in the order given)
• Packages included due to package dependencies (in the order that that package dependencies are parsed)
• The "standard dirs" (which may have been specified by the ``-standarddirs'' option)

-mpi

This option enables certain MPI features (using CPP #defines) within the code and is necessary for MPI builds (see Section 3.16.3).

-make=/path/to/gmake

Due to the poor handling of soft-links and other bugs common with the make versions provided by commercial Unix vendors, GNU make (sometimes called gmake) should be preferred. This option provides a means for specifying the make executable to be used.

-bash=/path/to/sh

On some (usually older UNIX) machines, the ``bash'' shell is unavailable. To run on these systems, genmake2 can be invoked using an ``sh'' (that is, a Bourne, POSIX, or compatible) shell. The syntax in these circumstances is:

% /bin/sh genmake2 -bash=/bin/sh [...options...]

where /bin/sh can be replaced with the full path and name of the desired shell.

Copyright © 2002 Massachusetts Institute of Technology