Building guide: MacOS

IDSimF is developed and tested on MacOS extensively. This guide is describing compilation on MacOS Monterey with the open source package management system Macports. However, compilation of IDSimF on other MacOS versions and with different package management systems, particularly Homebrew, should be possible in a similar way to this guide.

This installation guide assumes that you have Macports installed. Xcode and the Xcode commandline tools are required for Macports and are therefore assumed to be installed too. This guide also assumes that you have basic familiarity with the command line / terminal and the port command line tool of Macports.

Update package sources, install `git` and `cmake`:

First the macports installation and the package sources should be updated:

sudo port selfupdate

Install git with macports:

sudo port install git

Install cmake with macports:

sudo port install cmake

This should make git and cmake available. This can be verified by checking their versions:

$ git --version
git version 2.28.0

$ cmake --version
cmake version 3.23.3

Install a C++17 compatible C++ compiler :

IDSimF is written in C++17, therefore a recent compiler fully supporting the C++17 language standard has to be used to compile IDSimF. The c++ compiler of gnu compiler collection (gcc) gnu compiler collection (g++ ) in major version 12 is readily available with macports and is compatible with IDSimF. Install it with

sudo port install gcc12

Alternatively, the llvm c++ frontend clang in major version 14 is also available and can be used to compile IDSimF. Install it with

sudo port install clang-14

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 a build / binary tree for the compilation with g++: with

cmake .. -DCMAKE_CXX_COMPILER=g++-mp-12 -DCMAKE_BUILD_TYPE=Release

The build options are:

-DCMAKE_CXX_COMPILER=/opt/local/bin/g++-mp-12 sets the used c++ compiler to the g++-12 compiler with OpenMP parallelization support. Macports installs the compiler at /opt/local/bin/ but also sets the PATH variable, so that the path to the compiler has not to be set explicitly.

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

Configuring a build with clang is very similar:

cmake .. -DCMAKE_CXX_COMPILER=clang++-mp-14 -DCMAKE_BUILD_TYPE=Release

Here the c++ compiler with OpenMP parallelization support, installed with the clang-14 package, clang++-mp-14 is used as compiler.

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

Note

It was not possible to compile exafmm-t with Apple Sillicon (ARM) cpus due to missing SIMD instructions

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, after setting MacOS specific build configuration by replacing make.inc with the MacOS specific include file:

cd FMM3D
cp make.inc.macos.gnu make.inc
make install

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

Note

On newer MacOS versions, the compiled FMM3D library has to be installed into a system library directory with make install with administrator privileges due to security restrictions.

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.