Building with Autotools

Autotools Build System Documentation

This document describes the autotools-based build system for FMS.

Introduction to Autotools

Autoconf, automake, and libtool and the GNU/Linux standard build tools. When building a package based on autotools, the user does something like:

./configure && make check install

The configure step queries the system about many things, and contructs makefiles.

The make step uses the generated Makefiles to build, test, and install the software.

Standard environment variables and configure options can be used to control many aspects of the build. Custom configure options can easily be added to support additional needs.

Caution Concerning Generated Files

Autotools creates many generated files, which should not be edited or checked into the repository. Simply ignore them. Do not try to edit generated Makefiles, do not move or rename any of the shell scripts that autoreconf puts in place to let autotools work. These files have been added to .gitignore and should never be added to the repo.

How to Build FMS

Previously, everyone built FMS by checking out code from git. However, with the new build system, only those who want to contribute to the code base need check out the code from git.

As an FMS Developer

All FMS developers will need a reasobably reacent version of tools autoconf, automake, and libtool. These are available on package management systems. (Ex. yum install automake autoconf libtool).

The process of building FMS from the repo is:

1. Clone repo and cd into repo directory.
2. Run autoreconf -i to build the developer build system.
3. Run ./configure to configure.
4. Run make to build.

As an FMS User

Users start with a tarball, not the git repo. They do not have to have any of the autotools installed. Thier build process is:

1. Unpack the tarball and cd into the directory.
2. Run ./configure –prefix=/my/installdir
3. Run make install

Precious Flags for configure

Some environment variables are important to the autotools build system, these are known as "precious" variables. One example is CC, which should be set to the C compiler.

It's common to set some precious vars before the build. Commonly used ones include:

• CC the C compiler
• FC the Fortran compiler
• CPPFLAGS C (and Fortran) pre-processor flags
• FCFLAGS Fortran compiler flags
• LDFLAGS Linker flags

Standard Configure Options

The configure script has some standard options, including:

• –prefix allows user to specify install directory
• –disable-shared disables building of shared library
• –help prints message showing all options

FMS Configure Options

Configure build options for FMS:

• --with-yaml : Build with support for yaml input files(requires the libyaml library and headers)
• --enable-mixed-mode : Build in mixed precision mode, with default 4 byte reals and 8 byte real overloads
• --disable-setting-flags : Build without automatically setting flags during configuration
• --with-mpi : Build with MPI support, enabled by default
• --enable-overload-r4 : Compiles with 4 byte real routine overloads
• --enable-overload-c4 : Compiles with 4 byte complex routine overloads
• --enable-overload-c8 : Compiles with 8 byte complex routine overloads
• --disable-8byte-int : Compiles with only 4 byte integer routines

Standard Make Targets

Some of the useful make targets include:

• make or make all - build code
• make install - build code (as needed) and install
• make check - build code (as needed) and run tests
• make clean - clean back build
• make distclean - clean configure output and build
• make dist - create a tarball for distribution
• make distcheck - create a tarball, unpack it, build and run tests, then then clean it.