Building ComFLOW
===================================

The build procedure may be summarized as follows:

.. code-block:: bash

    # 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.


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:

    .. code-block:: bash

        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:

    .. code-block:: bash

        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.

    .. code-block:: bash

        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 :numref:`Section % s <installing_cmake>`)

    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:

    .. code-block:: bash

        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 :numref:`Section % s <cmake_project>`.

    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:

    .. code-block:: bash

        make -j
        make install

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.


.. _cmake_project:

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 :numref:`Section % s <cmake_aliases>`


Options
.......................

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

.. list-table::
    :widths: 30 70

    *   - 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)

.. _cmake_minimal:

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:

.. code-block:: bash

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

.. _cmake_aliases:

Aliases
.........

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


.. code-block:: bash

    # 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:

.. code-block:: bash

    # 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:

.. code-block:: bash

    . cmake_aliases.sh