Building guide: Windows

Building with Windows Subsystem for Linux and Ubuntu 20 LTS

Alternatively to Cygwin, Windows 10 and Windows Server 2019 are able to run Linux executables natively with an compatibility layer developed by Microsoft, the Windows Subsystem for Linux (WSL). Different Linux distributions are available from the Microsoft store for installation into the WSL, including Ubuntu 20.04 LTS. After setup of WSL and installation of Ubuntu 20.04 LTS (Focal Fossa) within WSL, the build process of IDSimF is the same as in Ubuntu 20.04 LTS.

Note

This guide assumes that you have basic familiarity with Linux / Unix shells and you can invoke commands, change directories, list directory contents etc. within a shell.

Install Windows Subsystem for Linux (WSL) and Ubuntu 20.04 LTS

Install Windows Subsystem for Linux (WSL) according to the installation guide. Install Ubuntu 20.04 LTS from the Microsoft Store.

After the installation of Ubuntu 20.04 (Focal Fossa) in WSL, you should have an “Ubuntu” tile in your Windows menu, which starts a new shell within the Ubuntu installation.

Build and test IDSimF within Ubuntu 20.04 LTS in WSL

The build process of IDSimF in the Ubuntu system within WSL is exactly the same as in a natively installed Ubuntu system. Refer to the Ubuntu 20.04 LTS installation guide for the remaining build process.

Building with Cygwin

Cygwin Cygwin is an UNIX (Posix compatible) programming and runtime environment. It provides basically a Linux distribution which runs natively under Windows. IDSimF can be built and run in the Cygwin environment.

Note

This guide assumes that you have basic familiarity with Linux / Unix shells and you can invoke commands, change directories, list directory contents etc. within a shell.

Install Cygwin and required Cygwin packages

Use the Cygwin setup program to install Cygwin and the following packages:

  • git

  • cmake

  • g++`

  • gnu make

  • hdf5

This makes all required tools available in the Cygwin environment. You can check if git cmake and a c++ compiler is available in the Cygwin environment by checking the versions of the individual tools in a cygwin shell:

$ git --version
git version 2.28.0

$ cmake --version
cmake version 3.14.5

$ g++ --version
g++ (GCC) 9.3.0
Copyright (C) 2019 Free Software Foundation, Inc.

Clone the IDSimF repository

Within a Cygwin shell, 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

The optional FMM libraries, exafmm-t and FMM3D were not yet tested with cygwin. It should be possible to compile them within the cygwin environment if all dependencies of those libraries are available within cygwin.

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.