Building guide: Linux - Ubuntu 20 LTS (Focal Fossa)

IDSimF can be compiled on Ubuntu 20 LTS (Focal Fossa) with comparably small effort. 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 GCC C++ compiler:

The c++ compiler of gnu compiler collection (gcc) gnu compiler collection (g++ ) in major version 9 is readily available on Ubuntu 20 LTS and is fully compatible with IDSimF. Install it with

sudo apt install g++

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. Optional parameters for the build configuration are set with optional arguments the form -D<OPTION NAME>=<VALUE>.

In the build folder, prepare build / binary tree with

cmake .. -DCMAKE_BUILD_TYPE=Release

The build option mean the following:

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

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 which use multiple cpu cores. To perform a parallelized build, pass the -j option with the number of parallel jobs to the cmake build command:

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

For example, to build all IDSimF targets with 8 cores use

cmake --build . -j 8

Test the build

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