AUTOTOOLS_INSTRUCTIONS.md

   1 \page autotools Building with Autotools
   2 # Autotools Build System Documentation
   3
   4 This document describes the autotools-based build system for FMS.
   5
   6 ## Introduction to Autotools
   7
   8 Autoconf, automake, and libtool and the GNU/Linux standard build
   9 tools. When building a package based on autotools, the user does
  10 something like:
  11
  12 ./configure && make check install
  13
  14 The configure step queries the system about many things, and contructs
  15 makefiles.
  16
  17 The make step uses the generated Makefiles to build, test, and install
  18 the software.
  19
  20 Standard environment variables and configure options can be used to
  21 control many aspects of the build. Custom configure options can easily
  22 be added to support additional needs.
  23
  24 ### Caution Concerning Generated Files
  25
  26 Autotools creates many generated files, which should not be edited or
  27 checked into the repository. Simply ignore them. Do not try to edit
  28 generated Makefiles, do not move or rename any of the shell scripts
  29 that autoreconf puts in place to let autotools work. These files have
  30 been added to .gitignore and should never be added to the repo.
  31
  32 # How to Build FMS
  33
  34 Previously, everyone built FMS by checking out code from git. However,
  35 with the new build system, only those who want to contribute to the
  36 code base need check out the code from git.
  37
  38 ## As an FMS Developer
  39
  40 All FMS developers will need a reasobably reacent version of tools
  41 autoconf, automake, and libtool. These are available on package
  42 management systems. (Ex. yum install automake autoconf libtool).
  43
  44 The process of building FMS from the repo is:
  45
  46 1. Clone repo and cd into repo directory.
  47 2. Run autoreconf -i to build the developer build system.
  48 3. Run ./configure to configure.
  49 4. Run make to build.
  50
  51 ## As an FMS User
  52
  53 Users start with a tarball, not the git repo. They do not have to have
  54 any of the autotools installed. Thier build process is:
  55
  56 1. Unpack the tarball and cd into the directory.
  57 2. Run ./configure --prefix=/my/installdir
  58 3. Run make install
  59
  60 ## Precious Flags for configure
  61
  62 Some environment variables are important to the autotools build
  63 system, these are known as "precious" variables. One example is CC,
  64 which should be set to the C compiler.
  65
  66 It's common to set some precious vars before the build. Commonly used
  67 ones include:
  68 * CC the C compiler
  69 * FC the Fortran compiler
  70 * CPPFLAGS C (and Fortran) pre-processor flags
  71 * FCFLAGS Fortran compiler flags
  72 * LDFLAGS Linker flags
  73
  74 ## Standard Configure Options
  75
  76 The configure script has some standard options, including:
  77 * --prefix allows user to specify install directory
  78 * --disable-shared disables building of shared library
  79 * --help prints message showing all options
  80
  81 ## FMS Configure Options
  82
  83 Configure build options for FMS:
  84 * `--with-yaml` : Build with support for yaml input files(requires the libyaml library and headers)
  85 * `--enable-mixed-mode` : Build in mixed precision mode, with default 4 byte reals and 8 byte real overloads
  86 * `--disable-setting-flags` : Build without automatically setting flags during configuration
  87 * `--with-mpi` : Build with MPI support, enabled by default
  88 * `--enable-overload-r4` : Compiles with 4 byte real routine overloads
  89 * `--enable-overload-c4` : Compiles with 4 byte complex routine overloads
  90 * `--enable-overload-c8` : Compiles with 8 byte complex routine overloads
  91 * `--disable-8byte-int`  : Compiles with only 4 byte integer routines
  92
  93 ## Standard Make Targets
  94
  95 Some of the useful make targets include:
  96 * make or make all - build code
  97 * make install - build code (as needed) and install
  98 * make check - build code (as needed) and run tests
  99 * make clean - clean back build
 100 * make distclean - clean configure output and build
 101 * make dist - create a tarball for distribution
 102 * make distcheck - create a tarball, unpack it, build and run tests, then then clean it.
 103