Building.md

Building SWAT+

SWAT+ will be built out-of-source, which means that all intermediate and final files are not entangled with the sources. This allows keeping the source tree clean, all generated resources by the build can be quickly removed. In addition, multiple SWAT+ build flavors can be build using the single source tree.

file(GLOB sources src/*.f90)
add_executable(${SWATPLUS_EXE} ${sources})

Generate the Build files

Make the swatplus directory the current working directory. All command examples below assume this.

$ cd <dir>/swatplus

Now, create all build files. Issue one of the following commands to configure and generate the build files. This does not build SWAT+ yet. CMake will process the content of the file CMakeLists.txt and will generate the build system.

The command below reads the CMakeLists.txt source file from the current directory ., creates a directory build and stores all resources for the build in it.

$ cmake -S . -B build
  <or short>
$ cmake -B build

You can force cmake to use the GCC gfortran compiler.

$ cmake -B build -D CMAKE_Fortran_COMPILER=gfortran

If you want to use Intel Fortran to build SWAT+, configure as below. It defaults to gfortran otherwise.

The Intel ifort Fortran compiler will be deprecated in 2024 and is being replaced with the LLVM-based version, ifx. Therefore, the use of ifx is preferred. To generate the build files on Linux:

$ cmake -B build -D CMAKE_Fortran_COMPILER=ifort
  <or better>
$ cmake -B build -D CMAKE_Fortran_COMPILER=ifx

On Windows you can use VS Code to build SWAT+ or you can issue the commands below to use the different compilers:

$ cmake -B build -D CMAKE_GENERATOR_TOOLSET=fortran=ifort
$ cmake -B build -D CMAKE_GENERATOR_TOOLSET=fortran=ifx
$ cmake -B build -G "Ninja" -D CMAKE_Fortran_COMPILER=gfortran

Note: ifort and ifx use a different generator toolset than `gfortran`` on Windows, also use the windows default CLI, not Powershell to build on the command line.

If you want to create a Debug version of SWAT+ that includes symbols for debugging, configure as below. Use the Release flag for building a release version instead.

$ cmake -B build -D CMAKE_BUILD_TYPE=Debug

If you want to delete all files created by cmake, simply remove the build folder and start over, e.g. on Linux

$ rm -rf build

or using the Windows terminal:

> rd /s /q build

Compiling/Linking the Executable

To build the SWAT+ executable, use the cmake --build command in the swatplus directory. It will process the previously generated files in build and place all intermediate resources (*.o, *.mod files) into the build directory.

 $ cmake --build build

Use the -j option to compile the source files in parallel. The example below is using 8 CPU cores in parallel. This greatly speeds up the compile process.

 $ cmake --build build -j 8

You can find the SWAT+ executable in the build folder as swatplus-<version>-<arch>.exe (for Windows). The Linux and Mac executable will not have an .exe extension.

Call the build target clean to remove all generated object files (.o) and modules files (.mod). Alternatively, you can do (cd build; make clean).

 $ cmake --build build --target clean

Building the swat model is supported for various platforms and compilers as described in the Readme.md file. It contains the specific instructions for Windows and Mac builds.

Note: For Linux, if your distribution does not come with static library for gfortran (libgfortran.a), then you can compile it using the dynamic library libgfortran.so by removing the corresponding link_libraries("static") line in CMakeLists.txt. Doing so will require the dynamic libraries to be present in the system while running the compiled binary (other libraries like libm, libc etc will also be needed). Run the ldd <binary> command to see which dynamic libraries are needed if you need to package it.

If you run into compilation issues specific to your OS (or you find a manual fix), please make an issue on GitHub (or a pull request) with details about your OS, compilation errors and any fixes you found.

Installing

Finally, you can install the swatplus executable by using the --install CMake option. Specify the installation directory that will receive a copy of the SWAT+ executable, generated in build. The --prefix option takes as an argument the base of the binary directory. Not using --prefix will copy swatplus into the system default binary directory. You don't have to use this step if you want to manage moving the swat executable yourself.

$ cmake --install build --prefix ~/bin