CMAKE_INSTRUCTIONS.md

   1 \page cmake Building with CMake
   2 # Instructions for building FMS with cmake
   3
   4 ## 1. Environment Variables
   5
   6 ### For GNU compilers on Linux with the bash shell:
   7
   8 ```
   9 export FC=mpifort
  10 export CC=mpicc
  11 ```
  12
  13 ### For Intel Compilers on Linux with the bash shell:
  14
  15 ```
  16 export FC=mpiifort
  17 export CC=mpiicc
  18 ```
  19
  20 ### NetCDF is provided via the `nc-config` command:
  21 ```
  22 export NetCDF_ROOT=`nc-config --prefix`
  23 ```
  24
  25 ### If building with yaml parser (-DWITH_YAML)
  26 ```
  27 export LIBYAML_ROOT=<your libyaml install directory>
  28 ```
  29
  30 ### Setting custom flags with the bash shell
  31 To override the default compiler flags:
  32 ```
  33 export FCFLAGS="<fortran flags>"
  34 export CFLAGS="<c flags>"
  35 ```
  36 In addition, the flag below must be included with the cmake command:
  37 ```
  38 cmake <any other options> -DCMAKE_BUILD_TYPE=Debug ..
  39 ```
  40
  41 ## 2. Build and install FMS with CMake
  42 `<prefix>` is the full install directory for FMS provided by user
  43
  44 ```
  45 cd FMS
  46 mkdir -p build && cd build
  47 cmake -DCMAKE_INSTALL_PREFIX=<prefix> ..
  48 make -j4
  49 make install
  50 ```
  51
  52 ### User configurable options:
  53 By default, FMS is built without `OpenMP`, in `single precision (r4)` and delivered in static library files.
  54
  55 The 64BIT and 32BIT precision options will build distinct libraries when enabled with the given default
  56 real size, libfms_r4 or libfms_r8.
  57
  58 The following build options are available:
  59 ```
  60 -DOPENMP      "Build FMS with OpenMP support"        DEFAULT: OFF
  61 -D32BIT       "Build 32-bit (r4) FMS library"        DEFAULT: ON
  62 -D64BIT       "Build 64-bit (r8) FMS library"        DEFAULT: OFF
  63 -DFPIC        "Build with position independent code" DEFAULT: OFF
  64 -DSHARED_LIBS "Build shared/dynamic libraries"       DEFAULT: OFF
  65
  66 -DCONSTANTS             "Build with <X> constants parameter definitions"     DEFAULT:GFDL  OPTIONS:GFS|GEOS|GFDL
  67 -DINTERNAL_FILE_NML     "Enable compiler definition -DINTERNAL_FILE_NML"     DEFAULT: ON
  68 -DENABLE_QUAD_PRECISION "Enable compiler definition -DENABLE_QUAD_PRECISION" DEFAULT: ON
  69 -DPORTABLE_KINDS        "Enable compiler definition -DPORTABLE_KINDS"        DEFAULT:OFF
  70 -DGFS_PHYS              "Enable compiler definition -DGFS_PHYS"              DEFAULT:OFF
  71 -DLARGEFILE             "Enable compiler definition -Duse_LARGEFILE"         DEFAULT:OFF
  72 -DWITH_YAML             "Enable compiler definition -Duse_yaml"              DEFAULT:OFF
  73 ```
  74
  75 ## 3. Installation structure
  76
  77 When the above command finishes, the `<prefix>` will have an `include_r4` and a `lib` directory. The `lib ` directory will have these files:
  78
  79 ```
  80 libfms_r4.a
  81 cmake/fms/fms-targets.cmake
  82 cmake/fms/fms-targets-release.cmake
  83 cmake/fms/fms-config.cmake
  84 cmake/fms/fms-config-version.cmake
  85 ```
  86
  87 ## 4. Using FMS in your application
  88
  89 FMS built with `cmake` provides transient targets with its package configuration.
  90 To be able to look for FMS in your application, set the following environment variable:
  91 ```
  92 export FMS_ROOT=<prefix>
  93 ```
  94 where `<prefix>` is the full path to FMS installation.
  95
  96 To find FMS in your application `CMakeLists.txt`:
  97
  98 ```
  99 find_package(FMS)
 100 ```
 101
 102 To link your application with FMS library:
 103 ```
 104 target_link_libraries(appName FMS::fms_r4)
 105 ```
 106
 107 If your application does not provide a means to locate the NetCDF installation via cmake, this may help:
 108 ```
 109 -DCMAKE_MODULE_PATH=<FMS_SRC_DIR>/cmake
 110 ```