Note: This tutorial works only for Linux and Mac OS X command line bash environments.

New Developers

The main development of coolfluid3 is hosted as a git repository on github .

Developers are required to create a github account at https://github.com and create a fork of their own version of coolfluid3 from https://github.com/coolfluid/coolfluid3 .

Developers new to git or github should read github's excellent help pages.

You should now have your own repository of coolfluid3 at https://github.com/your_name/coolfluid3 .

Get the sources

Make sure you have git installed, and configured for github as described here.

Create a directory to hold your sources and the build files:

$> mkdir coolfluid3
$> cd coolfluid3
$> git clone git@github.com:your_name/coolfluid3.git coolfluid3

Lets remember this directory (the parent of your git source tree) to help the rest of the installation:

$> export CF3=$PWD

Prerequisites

COOLFluiD 3 depends on several third-party libraries, to enable extra functionality. Of all the third-party libraries, only 4 are absolutely necessary. These dependencies will allow coolfluid to build with minimum functionality, and several disabled coolfluid libraries.

CMake version 2.8.2 or higher.

Boost C++ Libraries , offering a multitude of nice additions to C++.

Mandatory boost build options:

--with-test --with-thread --with-iostreams --with-filesystem --with-system --with-regex --with-date_time --with-program_options

Extra recommended boost build options:
```
--with-python 
```

open-mpi or any other MPI distribution.
The Eigen 3 matrix library

Besides creating C++ applications using the coolfluid libraries, coolfluid libraries can also be used from Python scripts. It is therefore highly recommended to make sure following dependency is also available:

Python scripting.
- Python must be available
- boost must be compiled with Python support

Other recommended third party libraries:

Any of these parallel distributed mesh-partitioning libraries:
- PTScotch
- Zoltan (also sub-package of Trilinos)
Trilinos for solving parallel distributed linear systems, required for the finite element solver UFEM
CGNS to read and write meshes in cgns format
Paraview libraries compiled with MPI for use with the coolfluid-client user interface, to visualize meshes.

Other supported third party libraries of little use at the moment:

CGAL for geometry related algorithms and mesh triangulation
google-perftools to inspect performance
superlu to solve linear systems (not parallel)

Installation of dependencies

Dependencies are most easily installed using the package manager on Linux or homebrew on Mac OS X The following is a list of packages that can be installed on a "fresh" Fedora linux system to provide a working development environment:

gcc-c++
gcc-gfortran
openmpi-devel
blas-devel
lapack-devel
cmake-gui
boost-devel
python-devel
git
eigen3-devel

On Fedora and certain other linux distributions, the MPI commands need to be made available using a module command:

module load mpi/openmpi-x86_64

This can be put into the .bashrc or equivalent file to make it automatic on login.

Trilinos is not available on many systems as a package (Homebrew on OS X and the Arch Linux AUR being exceptions). It will therefore need to be installed manually. We recommend using the latest version from the 11 series, currently Trilinos 11.14.3. After unpacking the Trilinos source code and creating an empty build directory, the following script allows configuring Trilinos with appropriate settings for Coolfluid:

#!/bin/bash

sourcedir=$HOME/coolfluid/dependencies/sources/trilinos-11.12.1-Source
depsdir=$CF3/deps

CC=mpicc
CXX=mpic++
FC=mpif77

ccmake -D CMAKE_INSTALL_PREFIX:PATH=$depsdir -D CMAKE_BUILD_TYPE:STRING=RELEASE \
-D Trilinos_ENABLE_DEFAULT_PACKAGES:BOOL=OFF \
-D Trilinos_ENABLE_ALL_OPTIONAL_PACKAGES:BOOL=ON \
-D Trilinos_ENABLE_TESTS:BOOL=OFF \
-D Trilinos_ENABLE_Amesos:BOOL=ON \
-D Trilinos_ENABLE_AztecOO:BOOL=ON \
-D Trilinos_ENABLE_Belos:BOOL=ON \
-D Trilinos_ENABLE_Didasko:BOOL=OFF \
-D Didasko_ENABLE_TESTS:BOOL=OFF \
-D Didasko_ENABLE_EXAMPLES:BOOL=OFF \
-D Trilinos_ENABLE_Epetra:BOOL=ON \
-D Trilinos_ENABLE_EpetraExt:BOOL=ON \
-D Trilinos_ENABLE_ShyLU:BOOL=ON \
-D Trilinos_ENABLE_Tpetra:BOOL=ON \
-D Trilinos_ENABLE_Teko:BOOL=ON \
-D Trilinos_ENABLE_TpetraExt:BOOL=ON \
-D Trilinos_ENABLE_Ifpack:BOOL=ON \
-D Trilinos_ENABLE_Meros:BOOL=ON \
-D Trilinos_ENABLE_ML:BOOL=ON \
-D Trilinos_ENABLE_RTOp:BOOL=ON \
-D Trilinos_ENABLE_Teuchos:BOOL=ON \
-D Trilinos_ENABLE_Thyra:BOOL=ON \
-D Trilinos_ENABLE_ThyraCore:BOOL=ON \
-D Trilinos_ENABLE_Triutils:BOOL=ON \
-D Trilinos_ENABLE_Stratimikos:BOOL=ON \
-D Trilinos_ENABLE_Zoltan:BOOL=ON \
-D Zoltan_ENABLE_EXAMPLES:BOOL=ON \
-D Zoltan_ENABLE_TESTS:BOOL=ON \
-D Zoltan_ENABLE_ULLONG_IDS:Bool=ON \
-D TPL_ENABLE_BLAS:BOOL=ON \
-D TPL_ENABLE_LAPACK:BOOL=ON \
-D TPL_ENABLE_MPI:BOOL=ON \
-D BUILD_SHARED_LIBS:BOOL=ON \
-D Trilinos_VERBOSE_CONFIGURE:BOOL=FALSE \
  $sourcedir

Here, the sourcedir variable at the top should point to the unpacked source directory, while depsdir is the directory where Trilinos will be installed ($CF3/deps in this tutorial). Next, still in the build directory run:

make -j <number of CPUs> 
make install

Build COOLFluiD

On this phase you will select your building options for cf3 Repeat this phase as often as you need and whenever you want to refresh your build directory.

Create a build directory separate from the sources

$> cd $CF3
$> mkdir build

Configure the build with your options

Unlike COOLFluiD 2, there is no prepare.pl script. The developer must now call CMake directly. CMake is a cross platform configuration/build system. The developer is advised to read the CMake documentation for advanced configuration.

$> cd $CF3
$> mkdir build # this can be anywhere, really
$> cd build
$> CC=mpicc CXX=mpic++ FC=mpif77 cmake -DDEPS_ROOT:PATH=$CF3/deps -DBOOST_ROOT:PATH=/usr -DCMAKE_BUILD_TYPE:STRING=Debug $CF3/coolfluid3

On OS X, BOOST_ROOT is /usr/local when using Homebrew.

Build type options

The above command builds a Debug build. You can select from the following types:

-DCMAKE_BUILD_TYPE=RelWithDebInfo
-DCMAKE_BUILD_TYPE=Release (no debug symbols)
-DCMAKE_BUILD_TYPE=Debug (no optimization)

Some more configuration options

To force a specific compiler:

-DCMAKE_C_COMPILER=$CF3/deps/bin/mpicc
-DCMAKE_CXX_COMPILER=$CF3/deps/bin/mpicxx

If CMake cannot find the MPI environment:

-DMPI_C_COMPILER=$CF3/deps/bin/mpicc
-DMPI_CXX_COMPILER=$CF3/deps/bin/mpicxx

A few other options that can be used:

-DCF3_CXX_FLAGS="-march=Core2"       # Architecture optimization for Core2
-DCF3_SKIP_FORTRAN=ON                # When you don't need or don't have Fortran installed
-DCF3_ENABLE_WARNINGS=OFF            # For users that don't want to see all the warnings
-DCF3_ENABLE_GUI=OFF                 # When the gui is not to be built

Customizing configuration further

Calling the command

$> cd $CF3/build
$> ccmake ./

This will show the interactive CMake configuration, where all available options are visible and can be changed. Press 'c' to configure, and afterwards 'g' to generate the build files.

Compiling COOLFluiD

By default, the CMake configuration generates makefiles to compile COOLFluiD. This is used by

$> cd $CF3/build
$> make -j2

with the "-j2" assigning 2 processes to the compilation (e.g. for dual core)

Running COOLFluiD tests

Coolfluid has many unit tests and acceptance tests. Unit tests are small executables that run each a maximum of 1 to 2 seconds, and test various classes and functions of coolfluid. They serve also as mini-manuals and examples of how to use coolfluid. Acceptance tests are typically more full simulations that take a longer time to finish. They are typically made in the form of a script that gets executed by a coolfluid command-line interpreter coolfluid-command.

To compile the tests, the developer has to make sure that the flags "-DCF3_ENABLE_UNIT_TESTS" and "-DCF3_ENABLE_ACCEPTANCE_TESTS" are passed to the CMake configuration. (They are on by default, but can be changed using "ccmake") To run the tests:

$> cd $CF3/build
$> ctest

Individual tests can be selected. The developer is referred to the CTest documentation.