2. Building ComFLOW¶

The build procedure may be summarized as follows:

# Step 1: Clone the Git repository and update the sub-modules:
git clone user@address:/some/path/comflow_program.git -b some_branch .
cd build
git submodule update --init
git submodule foreach git submodule update --init
# ./update_submodules.sh    # convenience script that combines the above two commands

# Step 2: Create and enter directory in which to build the binaries
mkdir make_files
cd make_files

# Step 3: Configure the CMake project using the
# normal alternative
ccmake [options] ..             # NB: options are omitted here
                                # press 'C' (Configure) followed by 'G' (Generate)
# or the minimalistic alternative
../cmake/cmake_minimal.sh ..

# Step 4: Build the binaries and optionally install them
make -j
make install

Do not copy these commands one-on-one to your console. These commands are only intended to give a quick overview of the steps that are required to build ComFLOW. More details are provided in the following sections.

2.1. Linux / OSX / Windows CLI¶

Step 1.

In order to obtain the source code it is necessary to clone the ComFLOW Git repository. This can be done using the following command:

git clone user@address:/some/path/comflow_program.git -b some_branch

The ComFLOW program depends on several sub-modules. Before building the program it is required to make sure these are up-to-date by running the commands:

git submodule update --init
git submodule foreach git submodule update --init

For convenience these commands have been combined in the bash file update_submodules.sh.

Step 2.

Once the source code is in place and up-to-date we can proceed with the setup of the CMake project. First create a directory which will be used for the build output.

cd build
mkdir my_make_files
cd my_make_files

Step 3.

Before proceeding with this step, make sure a recent version of CMake is installed (see also Section 1.2)

For setting up the CMake project we recommend using the utility ccmake which forms part of the standard CMake installation. This utility presents a graphical menu which guides you through the setup of the CMake project. Run ccmake as follows:

ccmake ..    # NB: options are omitted

Note that the above command is in its most basic form. No settings are provided on the command line and settings have to be adjusted manually. It is strongly recommended to provide all essential settings on the command line directly, because changing settings afterwards may result in unexpected behavior. More details can be found in Section 2.3.

Once the cofiguration menu is displayed, press ‘C’ (Configure) to start the actual configuration of the project. If necessary adjust the project settings and reconfigure by pressing ‘C’ again.

Once the configuration is complete. The build environment can be generated by pressing ‘G’ (Generate).

Step 4.

Build the ComFLOW program and optionally install it:

make -j
make install

2.2. Windows GUI¶

When using the Windows graphical user interface the same steps have to be performed as when using the command line interface. For cloning the Git repository it is recommended to use TortoiseGit. Use the option ‘Git clone’ in the shell context menu and fill in the required settings.

In the CMake GUI fill in the appropriate locations::

Where is the source code:       C:\Some\Directory\comflow_program\build
Where to build the binaries:    C:\Some\Directory\comflow_program\build\vs_project

Then press ‘Configure’. A menu will be presented in which the appropriate generator has to be selected. Make sure to select the 64-bits version of the Visual Studio generator.

After configuring press ‘Generate’ and open the Visual Studio solution.

2.3. CMake project configuration¶

A large number of options are available for the ComFLOW CMake project. A brief overview of the most important options is provided below.

It is strongly recommended to include all non-standard project settings directly on the command line. This reduces the risk of incompatible settings. For examples consult Section 2.3.3

2.3.1. Options¶

Only the most important options are explained here. More details may be found in the CMake file CMakeLists.txt.

COMFLOW_ENABLE_MPI	Enable or disable MPI support (NB: requires an appropriate compiler such as `mpifort` or `mpif90` if switched on)
COMFLOW_ENABLE_PROFILER	Enable or disable the built-in profiler
COMFLOW_HDF5_SOURCE	Select the location of the HDF5 library. By default the HDF5 library is built locally. In order to use a pre-built version of the HDF5 library, select the option $HDF5_ROOT and set the environment variable to the path of the library.
PLUGINS_BUILD_XMFMOORINGMODULE	Build the XMF mooring module (NB: requires the XMF library if switched on)

2.3.2. Minimalistic settings¶

If you have troubles building ComFLOW or if certain prerequisites are missing you may try to build a minimalistic version. For this purpose the shell scripts build/cmake/{cmake_minimal.sh, ccmake_minimal.sh} were introduced. These scripts configure ComFLOW using minimalistic settings and can be used in the same way as the regular cmake or ccmake commands, for example:

cmake_minimal.sh ..     # configure using default compiler
make -j                 # build

2.3.3. Aliases¶

It is advised to use aliases or bash files for common CMake commands. The following aliases could serve as an example:

# aliases for GNU/Intel setup of CMake
shopt -s expand_aliases
alias ccmake_intel_mpi='ccmake -D CMAKE_Fortran_COMPILER:STRING=mpiifort -DCOMFLOW_ENABLE_MPI:BOOL=ON'
alias ccmake_intel='ccmake -D CMAKE_Fortran_COMPILER:STRING=ifort -DCOMFLOW_ENABLE_MPI:BOOL=OFF'
alias ccmake_gnu='ccmake -D CMAKE_Fortran_COMPILER:STRING=gfortran -DCOMFLOW_ENABLE_MPI:BOOL=OFF'
alias ccmake_pgfortran='ccmake -D CMAKE_Fortran_COMPILER:STRING=pgfortran -DCOMFLOW_ENABLE_MPI:BOOL=OFF'
alias ccmake_gnu_openmpi='ccmake -D CMAKE_Fortran_COMPILER:STRING=mpifort -DCOMFLOW_ENABLE_MPI:BOOL=ON'

Using these aliases the appropriate settings can be selected by means of a single command, for example:

# build an MPI-parallel project using GFortran:
ccmake_gnu_openmpi ..

# build a project without MPI parallelization using GFortran:
ccmake_gnu ..

# build a project without MPI parallelization using Intel Fortran:
ccmake_intel ..

More examples can be found in the shell script build/cmake/cmake_aliases.sh. Include a sourced call to cmake_aliases.sh in the shell startup script (typically ~/.bashrc) to make the aliases available anywhere:

. cmake_aliases.sh