2.2. Compilation

Important

If you do not plan to modify the AFF3CT source code and you want to use the simulator/library as is, you can download one of the latest builds from the download page of the AFF3CT website and skip this section.

This project uses CMake in order to generate any type of projects (Makefile, Visual Studio, Eclipse, CLion, XCode, etc.).

AFF3CT is portable and can be compiled on Windows, macOS and Linux. Of course it works on traditional x86 architectures like Intel and AMD CPUs but it also works on embedded architectures like ARM CPUs.

AFF3CT supports many C++11 compliant compilers, until now the following compilers have been tested: GNU (g++), Clang (clang++), Intel (icpc) and Microsoft (MSVC). In this section, a focus is given to compile AFF3CT with:

1. the GNU compiler on Windows and Linux (Makefile project),

2. the Microsoft compiler on Windows (Visual Studio 2017 solution),

3. the Clang compiler on macOS (Makefile project).

2.2.1. CMake Installation

2.2.1.1. Windows/macOS

Download CMake from the official web page and launch the installer. Just press the Next button until the installation is over.

Important

On Windows, if you plan to build AFF3CT from the Visual Studio IDE you can skip the CMake installation and directly go to the Compilation with Visual Studio section.

Note

On Windows, it is recommended to download a version of CMake with an installer: it looks like cmake-x.x.x-win64-x64.msi.

Warning

It is recommended to add CMake to your system PATH during the installation.

Danger

The CMake minimal version requirement is 3.0.2.

2.2.1.2. Linux

Install Make and CMake from the package manager:

sudo apt install make cmake

Note

On CentOS-like systems you have to replace apt by yum.

2.2.2. C++ GNU Compiler Installation

2.2.2.1. Windows

Download the latest MinGW build from the official web page (tested with MinGW x86_64-6.2.0). Unzip the archive. Copy the extracted mingw64 folder in the C:\Programs\Git\ folder (overwrite all the duplicated files).

Note

We suppose that you have installed Git for Windows has explained in the Git Installation on Windows section and consequently you have Git Bash installed.

2.2.2.2. macOS

The instructions to install the C++ GNU compiler are not given for macOS because the native Clang compiler will be used instead in the next steps. Directly go to the Compilation with a Makefile project on macOS section.

2.2.2.3. Linux

Install the C++ GNU compiler from the package manager:

sudo apt install g++

Note

On CentOS-like systems you have to replace apt by yum.

2.2.3. Compilation with a Makefile Project

Go into the directory where you cloned AFF3CT, this directory will be refereed as $AFF3CT_ROOT.

2.2.3.1. Windows

Generate the Makefile from CMake:

mkdir build
cd build
cmake .. -G"MinGW Makefiles"

This last command line should fail but you can ignore it, continue with:

cmake .. -DCMAKE_CXX_COMPILER="g++.exe" -DCMAKE_BUILD_TYPE="Release" -DCMAKE_CXX_FLAGS="-funroll-loops -march=native"

Build AFF3CT with the Makefile:

mingw32-make -j4

Once finished, the AFF3CT executable should be located in the $AFF3CT_ROOT/build/bin folder.

Danger

Run the previous commands on Git Bash (Start Menu > Git > Git Bash) and not on the Windows Command Prompt. If you try to run the previous commands on the Windows Command Prompt, CMake will not find the GNU compiler (g++.exe and gcc.exe commands) because it has not been added to the system PATH, same for the mingw32-make command.

2.2.3.2. macOS

Generate the Makefile from CMake:

mkdir build
cd build
cmake .. -G"Unix Makefiles" -DCMAKE_CXX_COMPILER="clang++" -DCMAKE_BUILD_TYPE="Release" -DCMAKE_CXX_FLAGS="-funroll-loops -march=native"

Build AFF3CT with the Makefile:

make -j4

Once finished, the AFF3CT executable should be located in the $AFF3CT_ROOT/build/bin folder.

2.2.3.3. Linux

Generate the Makefile from CMake:

mkdir build
cd build
cmake .. -G"Unix Makefiles" -DCMAKE_CXX_COMPILER="g++" -DCMAKE_BUILD_TYPE="Release" -DCMAKE_CXX_FLAGS="-funroll-loops -march=native"

Build AFF3CT with the Makefile:

make -j4

Once finished, the AFF3CT executable should be located in the $AFF3CT_ROOT/build/bin folder.

2.2.4. Compilation with a Visual Studio 2017 Solution

Since Microsoft Visual Studio 2017, Visual natively supports CMake. To generate the AFF3CT solution, open the $AFF3CT_ROOT folder from the IDE.

Select the Release target and press the green play button aff3ct.exe to start the compilation.

Once AFF3CT is compiled you can browse the build by right clicking on CMakeList.txt > Cache > Open Cache Folder.

Note

Visual Studio should not be mixed up with Visual Studio Code. Visual Studio is the Windows native IDE and Visual Studio Code is a portable code editor.

Note

Visual Studio 2017 Community is free for Open-source contributors, students and freelance developers.

Warning

The Visual Studio default compiler (MSVC) is known to generate significantly slower AFF3CT executable than the GNU compiler. If you target an high speed executable it is recommended to use the GNU or Clang compilers.

Danger

When compiling AFF3CT in debug mode, the src\Factory\Module\Decoder\Polar\Decoder_polar.cpp file generates the following error: fatal error C1128. To fix this, you need to compile with the /bigobj parameter.

The compilation can also be started from the command line after calling the %VS_PATH%\VC\Auxiliary\Build\vcvars64.bat batch script (where %VS_PATH% is the location of Visual Studio on your system):

devenv /build Release aff3ct.sln

2.2.5. Compilation with a Visual Studio 2019 Solution

The compilation process on Visual Studio 2019 is almost the same than on Visual Studio 2017. Note that many improvements have been made on the MSVC compiler on Visual Studio 2019 and now the produced binaries are competitive with other standard compilers like GNU and Clang.

2.2.6. CMake Options

CMake allows to define project specific options. AFF3CT takes advantage of this feature and provides the following options:

Option	Type	Default	Description
AFF3CT_COMPILE_EXE	BOOLEAN	ON	Compile the executable.
AFF3CT_COMPILE_STATIC_LIB	BOOLEAN	OFF	Compile the static library.
AFF3CT_COMPILE_SHARED_LIB	BOOLEAN	OFF	Compile the shared library.
AFF3CT_LINK_GSL	BOOLEAN	OFF	Link with the GSL library (used in the channels).
AFF3CT_LINK_MKL	BOOLEAN	OFF	Link with the MKL library (used in the channels).
AFF3CT_MPI	BOOLEAN	OFF	Enable the MPI support.
AFF3CT_POLAR_BIT_PACKING	BOOLEAN	ON	Enable the bit packing technique for Polar code SC decoding.
AFF3CT_COLORS	BOOLEAN	ON	Enable the colors in the terminal.
AFF3CT_BACKTRACE	BOOLEAN	ON	Enable the backtrace display when and exception is raised. On Windows and macOS this option is not available and automatically set to OFF.
AFF3CT_EXT_STRINGS	BOOLEAN	ON	Enable external strings for the help documentation. If ON the help doc will be parsed from the strings.rst external file. If OFF the strings will be self-contained in the binary. On MSVC this option is not available and automatically set to ON.
AFF3CT_PREC	STRING	MULTI	Select the precision in bits (can be ‘8’, ‘16’, ‘32’, ‘64’ or ‘MULTI’).

Considering an option AFF3CT_OPTION we want to set to ON, here is the syntax to follow:

cmake .. -DAFF3CT_OPTION="ON"

2.2.7. Compiler Options

2.2.7.1. Build Type

CMake allows to select the type of build through the CMAKE_BUILD_TYPE built-in variable. Release and Debug are the common values that the variable can get. For instance, to compile in release mode:

cmake .. -DCMAKE_BUILD_TYPE="Release"

Note

In CMake it is recommended to not explicitly set the compiler optimization level flags (-O0, -O1, -O2, -O3, etc.). Those compiler options will be set automatically by the CMAKE_BUILD_TYPE built-in variable. For instance, with the GNU compiler, if CMAKE_BUILD_TYPE is set to Release, the code will be compiled with the -O3 flag.

Note

If you need to develop in AFF3CT it is recommended to compile in the Debug mode (or eventually RelWithDebInfo mode) during the development process to add the debug symbols in the binary files. It will certainly ease the debug process but be careful, the execution speed will be seriously affected in this mode, be sure to switch to the Release mode when the code is stable.

Note

In Visual Studio solutions, the CMAKE_BUILD_TYPE built-in variable has no effect and the build type is directly managed by Visual.

2.2.7.2. Specific Options

CMake has a built-in variable you can set to specify the compiler options: CMAKE_CXX_FLAGS. For instance, it can be used like this:

cmake .. -DCMAKE_CXX_FLAGS="-funroll-loops -march=native"

Many parts of the AFF3CT code use the SIMD parallelism and this type of instructions often requires additional compiler options to be enabled:

Option	Description
-msse2	Enable the SSE2 set of instructions on x86 CPUs (128-bit vector size, required for 32-bit and 64-bit data).
-mssse3	Enable the SSSE3 set of instructions on x86 CPUs (128-bit vector size, specifically required for 32-bit data and the SC FAST decoder, see the --dec-type, -D and --dec-implem parameters).
-msse4.1	Enable the SSE4.1 set of instructions on x86 CPUs (128-bit vector size, required for 8-bit and 16-bit data).
-mavx	Enable the AVX set of instructions on x86 CPUs (256-bit vector size, required for 32-bit and 64-bit data).
-mavx2	Enable the AVX2 set of instructions on x86 CPUs (256-bit vector size, required for 8-bit and 16-bit data).
-mavx512f	Enable the AVX-512F set of instructions on x86 CPUs (512-bit vector size, required for 32-bit and 64-bit data).
-mavx512bw	Enable the AVX-512BW set of instructions on x86 CPUs (512-bit vector size, required for 8-bit and 16-bit data).
-mfpu=neon	Enable the NEON set of instructions on ARMv7 and ARMv8 CPUs (128-bit vector size, required for 8-bit, 16-bit data and 32-bit data).
-march=native	Let the compiler choose the best set of instructions available on the current architecture (it does not work for ARMv7 architectures since the NEON instruction set is not IEEE 754 compliant).

Warning

Previous options are only valid for the GNU and the Clang compilers but it exists similar options for the other compilers like the Microsoft compiler (MSVC) or the Intel compiler (icpc).

Danger

Some AFF3CT routines require the floating-point operations to be IEEE-compliant: numerical instabilities has been reported when compiling with the --ffast-math flag. Be aware that the -Ofast option is the combination of -O3 and --ffast-math. We recommend to avoid the --ffast-math option unless you know what you are doing.