Building QuantLib using CMake

Contents

Prerequisites

C++ Compiler Toolset

You will need a C++ compiler toolset to build QuantLib.

In Linux, this is typically the GNU C++ compiler along with linker and make. For example in Debian and Ubuntu, these can be installed with sudo apt install build-essential. In Fedora or RedHat, the equivalent is sudo yum install gcc g++ make.

In Windows, you can use a recent Visual Studio edition (available for free for individuals).

In MacOS, the XCode command-line tools are sufficient. Note that these get automatically installed with Homebrew.

Boost

You will need the boost libraries installed before you can build QuantLib. Depending on the platform and operating system, you can install them in different ways. For example:

CMake

You will also need a recent version of CMake (minimum version 3.15.0). You can also install this with your favourite package manager (e.g. apt, yum, homebrew, chocolatey as above), or obtain it from the CMake downloads page.

Note that Microsoft ships Visual Studio with a suitable command-line only version of CMake since Visual Studio 2019 (the Visual Studio 2017 CMake version is outdated). It is available in the PATH from a Visual Studio command prompt and can alternatively be used directly from the IDE.

QuantLib Sources

You can download the latest release from the releases page. Alternatively, you can obtain the latest development sources by cloning the GitHub repository.

Building

CMake is a meta-build tool, i.e. it generates native build files for various targets from the same set of cross-platform description file (CMakeLists.txt). It can generate Unix Makefiles, Visual Studio projects and solutions, XCode projects, and more, for a huge variety of compilers, architectures, and operating systems. It works by using an out-of-source build folder, where it places the generated files.

Using the command-line, build files can be generated as (example for Makefiles in Release mode): 

mkdir build
cd build
cmake .. -G "Unix Makefiles" -D CMAKE_BUILD_TYPE=Release

The project can then be built using the native build tools, for example by running make or opening the generated Visual Studio solution. The supported generators are listed in the CMake Documentation.

Alternatively, the CMake GUI can be used to generate build files.

In Visual Studio 2019 or higher, it is more convenient to use Open Folder.. when starting the IDE and select the QuantLib folder. Then the IDE will detect the CMake files and configure the project automatically. For more information, please see Microsoft's CMake project documentation.

Similarly, Visual Studio Code with the CMake Tools extension can be used on all platforms.

Running Tests and Examples

QuantLib builds all unit tests into a single executable called quantlib-test-suite. It is located in the test-suite directory relative to the build folder and can be run as: 

./quantlib-test-suite --log_level=message

(Use --help to see all available command-line options.)

The examples can be found in the Examples folder inside the build tree and executed directly.

Installing

The final build artifacts (the library, headers, etc.) can be installed into a directory outside of the build tree for use from other projects. This separates the build by-products from the final results and also allows packaging of the binaries.

In CMake, you can select the installation prefix using the CMAKE_INSTALL_PREFIX variable. That is, configuring the project using: 

cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/install/dir

would install the binaries into the given folder. CMake generates a build target named install (or INSTALL in Visual Studio projects) which accomplishes the task when built. For example for a Makefiles generator, run: 

make install

Build Options

QuantLib exposes a number of CMake options to configure the build. These are the CMake equivalents of the configuration flags described in the reference documentation, which give a more detailed description of their effect.

Option Description Default
QL_BUILD_BENCHMARK Build benchmark ON
QL_BUILD_EXAMPLES Build examples ON
QL_BUILD_TEST_SUITE Build test suite ON
QL_ENABLE_OPENMP Detect and use OpenMP OFF
QL_ENABLE_PARALLEL_UNIT_TEST_RUNNER Enable the parallel unit test runner OFF
QL_ENABLE_SESSIONS Singletons return different instances for different sessions OFF
QL_ENABLE_THREAD_SAFE_OBSERVER_PATTERN Enable the thread-safe observer pattern OFF
QL_ENABLE_TRACING Tracing messages should be allowed OFF
QL_ERROR_FUNCTIONS Error messages should include current function information OFF
QL_ERROR_LINES Error messages should include file and line information OFF
QL_EXTRA_SAFETY_CHECKS Extra safety checks should be performed OFF
QL_HIGH_RESOLUTION_DATE Enable date resolution down to microseconds OFF
QL_NULL_AS_FUNCTIONS Enable the implementation of Null as template functions OFF
QL_INSTALL_BENCHMARK Install benchmark ON
QL_INSTALL_EXAMPLES Install examples ON
QL_INSTALL_TEST_SUITE Install test suite ON
QL_TAGGED_LAYOUT Library names use layout tags ON in Visual Studio
QL_USE_CLANG_TIDY Use clang-tidy when building OFF
QL_USE_INDEXED_COUPON Use indexed coupons instead of par coupons OFF
QL_USE_STD_CLASSES Enable all QL_USE_STD_* options OFF
QL_USE_STD_SHARED_PTR Use standard smart pointers instead of Boost ones OFF
QL_USE_STD_FUNCTION Use std::function and std::bind instead of Boost ones OFF
QL_USE_STD_TUPLE Use std::tuple instead of boost::tuple OFF

Using Ninja

Traditional build tools like make or MS Build are comparably slow when it comes to checking dependencies, determining which parts of the project need to be rebuilt in incremental builds, and which parts can be built in paralel. The Ninja build tool addresses these issues and generally results in faster builds and better use of the available processor cores.

Ninja configuration files are typically not written by humans (unlike Makefiles) - CMake can automatically generate them.

In order to use Ninja for your builds, you first need to install the package as described in their wiki page. Then you can generate Ninja configure CMake to generate Ninja files, for example in Linux or MacOS: 

cmake -G Ninja ... # (add other options as before)

The project can then be built by running ninja instead of make. Note that ninja automatically deteremines the available cores and builds in parallel.

On the Windows platform in Visual Studio, we recommend to use the built-in CMake support in version 2019 or later. This uses Ninja by default for the build.

Adding extensions

QuantLib exposes a CMake extension hook which allows external modules to adjust the QuantLib build directly, for example adding more source files, adjusting compiler flags, etc. An example use case is enabling adjoint algorithmic differentiation (AAD) by replacing QuantLib's Real type with an operator-overloaded alternative from a separate library, though many other types of extensions are possible.

Note: Currently QuantLib's build extension hook is only available when using CMake.

The CMake option QL_EXTERNAL_SUBDIRECTORIES may contain a list of external source directories that should be added to QuantLib's build (by means of add_subdirectory). Multiple directories can be added by separating the paths using a semicolon.

Further, the CMake option QL_EXTRA_LINK_LIBRARIES may list CMake library targets that should be linked to QuantLib. QuantLib uses the target_link_libraries(...) CMake command, which is more general than pure linking. It allows to add any compiler flags, linker options, extra sources, or other parameters to the build as well.

These two CMake options allow for a highly flexible extension point into the QuantLib build itself.

An example on how this extension hook can be used is in the qlxad repository, which integrates the open source XAD AAD tool into the QuantLib build.