INSTALL.md

   1 \page install Installation
   2 # libFMS Installation
   3
   4 ## External Requirements
   5
   6 The following external libraries are required when building libFMS
   7
   8 * NetCDF C and Fortran (77/90) headers and libraries
   9 * Fortran 2003 standard compiler
  10 * Fortran compiler that supports Cray Pointer
  11 * MPI C and Fortran headers and libraries (optional)
  12 * Libyaml header and libraries (optional)
  13 * Linux or Unix style system
  14
  15 ## Supported Compilers
  16
  17 We strive to have libFMS built with as many C and Fortran compilers on as many
  18 Unix/Linux type systems as possible.  However, internally, we only use libFMS
  19 compiled with the Intel compilers.  Some groups have had success using libFMS
  20 when compiled with the GNU C and Fortran compilers.
  21
  22 ## MPI Support
  23
  24 The default way to build libFMS is with MPI support.  We have found that using
  25 the MPI aware compiler, or the MPI compiler wrappers (mpif90, mpicc, etc.), in
  26 general, offer the best results when building with MPI support.  If you decide
  27 to not use an MPI aware compiler, you should pass the include and library
  28 locations to the build system.
  29
  30 libFMS can be built without MPI support (sometimes called "no-comm mode").  To
  31 build libFMS without MPI support, pass to `configure` the `--with-mpi=no` flag.
  32
  33 ## Supported Build Systems
  34
  35 The FMS repository has two build systems in place, GNU autotools and CMake.
  36 It is also compiled with the GFDL's internally-developed build tool, [mkmf](https://github.com/noaa-gfdl/mkmf)
  37
  38 CMake and Autotools have some variation in options and the resulting build targets.
  39
  40 Autotools will build with 64 bit real defaults unless configured with `--enable-mixed-mode` in
  41 which case it will default to 32 bit reals and add overloads to allow for both 32 bit and 64 bit
  42 operations. This results in one library with both 32 bit and 64 bit routines (defaulting to 32 bit reals).
  43
  44 By default CMake will build the library with 32 bit reals. It also has an option for 64 bit defaults
  45 , and if enabled will build an additional library with 64 bit reals. This results in distinct 32 bit and 64 bit libraries (libfms_r4.a and libfms_r8.a)
  46
  47 ### GNU Autoconf/Automake
  48
  49 In many cases, running the shell command `./configure && make && make install`
  50 will build and install this package.  Since libFMS requires the netCDF libraries,
  51 you will likely need to tell configure where to find the C and Fortran netCDF
  52 headers and libraries via the `CPPFLAGS`, `FCFLAGS` and `LDFLAGS` variables
  53
  54 ```bash
  55 > ./configure CPPFLAGS="-I/path/to/netcdf/include" \
  56               FCFLAGS="-I/path/to/netcdff/include" \
  57               LDFLAGS="-L/path/to/netcdf/lib -L/path/to/netcdff/lib"
  58 ```
  59
  60 When building from a GitHub clone, the user must run `autoreconf -i` before
  61 running the `./configure` script.
  62
  63 The `./configure` script will guess as many compiler options as required to
  64 build libFMS.  In some cases you may be required to supply additional compiler
  65 flags for your system.  Additional compiler options can be passed to the build
  66 with the `CPPFLAGS`, `CFLAGS` and `FCFLAGS` variable.  The `./configure` option
  67 `--disable-setting-flags` will not guess required compiler flags.  Using this
  68 configure option will require the user to give all required flags.
  69
  70 Run `./configure --help` to see other available configure options.
  71
  72 For more information on building with autotools and build options please see
  73  [BUILD_SYSTEM.md](https://github.com/NOAA-GFDL/FMS/blob/main/libFMS/BUILD_SYSTEM.md)
  74
  75 ### CMake
  76
  77 To build using CMake, follow the instructions in
  78 [CMAKE_INSTRUCTIONS.mk](https://github.com/NOAA-GFDL/FMS/blob/main/CMAKE_INSTRUCTIONS.md).
  79 Currently the CMake configuration is the most restrictive build option as the
  80 compiler flags are immutable.
  81
  82 ### GFDL MKMF
  83
  84 Make Makefile ([MKMF](https://github.com/NOAA-GFDL/mkmf)) is the GFDL developed
  85 makefile generator application.  MKMF uses a list of file, or a list of
  86 directories that contain Fortran or C file, a Make template file, and writes
  87 a Makefile with the correct dependencies to build a library or executable.  To
  88 use MKMF to build libFMS, do the following.
  89
  90 1. Clone the MKMF repository from GitHub
  91    `git clone https://github.com/NOAA-GFDL/mkmf.git`
  92 2. Add the `mkmf/bin` directory to your PATH
  93    `export PATH=/path/to/mkmf/bin:${PATH}`
  94    or
  95    `setenv PATH /path/to/mkmf/bin:${PATH}`
  96 3. Run the `list_paths` command, on the FMS directory
  97    `list_paths path/to/FMS`
  98    This will create a path_names file in the current directory
  99 4. Pick a MKMF template from the `mkmf/templates` directory that most closely
 100    matches you system and compiler.  Make any modifications as need
 101 5. Run `mkmf`
 102    ```shell
 103    mkmf -c "-Duse_netCDF -Duse_libMPI" \
 104          -I /path/to/netcdff/include \
 105          -I /path/to/netcdf/include \
 106          -t /path/to/mkmf/template. \
 107          -p libfms.a \
 108          path_names
 109    ```
 110 6. Once built, place the `libfms.a`, `*.mod`, `include/\*` files in your install
 111    location.
 112
 113 While MKMF has been the build system used by GFDL to build all the GFDL models
 114 for some time, this build method requires the most user intervention when
 115 building libFMS on a new system.