Building guide: Linux - Ubuntu 18 LTS (Bionic Beaver)

IDSimF was tested on Ubuntu 18 LTS extensively. Therefore this guide uses Ubuntu 18 LTS as example how to compile IDSimF on a Linux system. The configuration and compilation process should be very similar on other Debian derived Linux distributions. Configuration and compilation on other distribution families should also be similar, if the required dependencies are available on the target platform.

Update package sources, Check / install Git and cmake:

First the package sources should be updated:

sudo apt update

Usually git should be installed already, however check if git is really installed:

git --version

prints the installed git version. If git is not installed, install it with

sudo apt install git

cmake is usually not installed. Install it with

sudo apt install cmake

Install a modern C++ compiler:

The default C++ compiler in Ubuntu is too old to support all used C++17 features. Therefore, a modern / recent compiler has to be installed. The c++ compiler of gnu compiler collection (gcc) gnu compiler collection (g++ ) in major version 8 is readily available on Ubuntu 18 and is compatible with IDSimF. Install it with

sudo apt install g++-8

Alternatively the llvm c++ frontend clang 10 / llvm is also available and can be used to compile IDSimF. Install it with

sudo apt install clang-10

Note that you have to install both packages (g++-8 and clang-10) to use clang, since the clang-10 package is missing some header files.

Clone the IDSimF repository

Clone the IDSimF repository to your local machine with git from GitHub:

git clone https://github.com/IPAMS/IDSimF.git

This clones the IDSimF repository to a local folder IDSimF.

Configuration and building with cmake

Preparing the build

IDSimF uses cmake as helping tool for configuration and compilation. cmake allows a so called “out of source build”. This creates a separated “binary tree” in a separated build folder, in which the compilation of executable binaries takes place without interfering with the cloned sources.

To do an out of source build, change into the cloned IDSimF folder and create a build folder, for example build in it and change into it:

cd IDSimF
mkdir build
cd build

Basically cmake prepares a build tree in the current folder if it is called with an source folder as argument. However, since we do not want to build with the default compiler of the system, we have to set some options for cmake. This is done with optional arguments of the form -D<OPTION NAME>=<VALUE>.

In the build folder, prepare build / binary tree with

cmake .. -DCMAKE_CXX_COMPILER=/usr/bin/g++-8 -DCMAKE_BUILD_TYPE=Release -DUSE_CPP_FSLIB=on

The build options mean the following:

-DCMAKE_CXX_COMPILER=/usr/bin/g++-8 sets the used c++ compiler to the g++-8 which is installed at /usr/bin/.

-DCMAKE_BUILD_TYPE=Release sets the build type to Release which means, that optimizations are switched on and debugging information is removed from the compiled binary. This results in a significantly faster binary than when building with debugging information switched on (-DCMAKE_BUILD_TYPE=Debug) which is required to analyze the compiled binary with debugging tools.

-DUSE_CPP_FSLIB=on switches on explicitly linking against the filesystem library. This is explicitly required by gcc until gcc 9. With gcc 8, the build will fail without this linking.

Configuring the build with clang is very similar: :

cmake .. -DCMAKE_CXX_COMPILER=/usr/bin/clang++-10 -DCMAKE_BUILD_TYPE=Release

Here the c++ compiler installed with the clang-10 package, clang++-10, is used as compiler. Explicitly linking the filesystem library is not necessary with clang.

Optional FMM Libraries

Exafmm-t

Clone / download exafmm-t into a local directory and follow the installation guide. If all dependencies are available, configuration is done by changing into the exafmm-t directory and using autotools:

cd exafmm-t
./configure

Then building and testing the build is done with:

make check

After building, exafmm-t can be used in an IDSimF build by providing the path into the exafmm-t directory as EXAFMMT_PATH parameter. For example, if exafmm-t was cloned to /usr/libs/exafmm-t, the additional cmake option is:

-DEXAFMMT_PATH=/usr/libs/exafmm-t

FMM3D

Clone / download FMM3D into a local directory and follow the install instructions install instructions. If all dependencies are available, configuration is done by running make in the FMM3D directory:

cd FMM3D
make lib

After building, FMM3D can be used in an IDSimF build by providing the path into the FMM3D directory as FMM_3D_PATH parameter. For example, if exafmm-t was cloned to /usr/libs/FMM3D, the additional cmake option is:

-DFMM_3D_PATH=/usr/libs/FMM3D

Building

After configuration, the individual built targets (IDSimF modules, simulation applications and tests) can be built with cmake --build <path to a target>. Since the root of the build tree is also a target for the whole project, all build targets in IDSimF are built serially (with no parallelization in the build process) with

cmake --build .

cmake supports parallelized builds since version 3.12, but Ubuntu 18 LTS installs an older cmake version. However, the native build tool used by cmake to actually build is make which itself supports parallelized builds. cmake is able to pass options to the native build tool. A parallelized build with cmake and make is done with

cmake --build . -- -j <number of parallel jobs>

Alternatively, make can also be used directly:

make -j <number of parallel jobs>

Test the build

After compilation has finished without problems, the IDSimF build can be tested by running tests or benchmarks.