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` and in `single precision (r4)`
  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
  65 -DCONSTANTS             "Build with <X> constants parameter definitions"     DEFAULT:GFDL  OPTIONS:GFS|GEOS|GFDL
  66 -DINTERNAL_FILE_NML     "Enable compiler definition -DINTERNAL_FILE_NML"     DEFAULT: ON
  67 -DENABLE_QUAD_PRECISION "Enable compiler definition -DENABLE_QUAD_PRECISION" DEFAULT: ON
  68 -DGFS_PHYS              "Enable compiler definition -DGFS_PHYS"              DEFAULT:OFF
  69 -DLARGEFILE             "Enable compiler definition -Duse_LARGEFILE"         DEFAULT:OFF
  70 -DWITH_YAML             "Enable compiler definition -Duse_yaml"              DEFAULT:OFF
  71 ```
  72
  73 ## 3. Installation structure
  74
  75 When the above command finishes, the `<prefix>` will have an `include_r4` and a `lib` directory. The `lib ` directory will have these files:
  76
  77 ```
  78 libfms_r4.a
  79 cmake/fms/fms-targets.cmake
  80 cmake/fms/fms-targets-release.cmake
  81 cmake/fms/fms-config.cmake
  82 cmake/fms/fms-config-version.cmake
  83 ```
  84
  85 ## 4. Using FMS in your application
  86
  87 FMS built with `cmake` provides transient targets with its package configuration.
  88 To be able to look for FMS in your application, set the following environment variable:
  89 ```
  90 export FMS_ROOT=<prefix>
  91 ```
  92 where `<prefix>` is the full path to FMS installation.
  93
  94 To find FMS in your application `CMakeLists.txt`:
  95
  96 ```
  97 find_package(FMS)
  98 ```
  99
 100 To link your application with FMS library:
 101 ```
 102 target_link_libraries(appName FMS::fms_r4)
 103 ```
 104
 105 If your application does not provide a means to locate the NetCDF installation via cmake, this may help:
 106 ```
 107 -DCMAKE_MODULE_PATH=<FMS_SRC_DIR>/cmake
 108 ```