Building QuantLib using CMake
- Running Tests and Examples
- Build Options
- Using Ninja
- Adding Extensions
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).
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:
- Ubuntu or Debian:
sudo apt install libboost-all-dev
- Fedora or RedHat:
sudo yum install boost-devel
- MacOS using Homebrew:
brew install boost
- MacOS using Mac Ports:
sudo port install boost
- Windows using Chocolatey:
- For Visual Studio 2022:
choco install boost-msvc-14.3
- For Visual Studio 2019:
choco install boost-msvc-14.2
- For Visual Studio 2017:
choco install boost-msvc-14.1
- For Visual Studio 2022:
- Windows using manual installers: Boost Binaries on SourceForge
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.
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 (
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
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.
Running Tests and Examples
QuantLib builds all unit tests into a single executable called
It is located in the
test-suite directory relative to the build folder
and can be run as:
--help to see all available command-line options.)
The examples can be found in the
Examples folder inside the build tree
and executed directly.
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
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
INSTALL in Visual Studio projects)
which accomplishes the task when built.
For example for a Makefiles generator, run:
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.
||Build test suite||
||Detect and use OpenMP||
||Enable the parallel unit test runner||
||Singletons return different instances for different sessions||
||Enable the thread-safe observer pattern||
||Tracing messages should be allowed||
||Error messages should include current function information||
||Error messages should include file and line information||
||Extra safety checks should be performed||
||Enable date resolution down to microseconds||
||Enable the implementation of Null as template functions||
||Install test suite||
||Library names use layout tags||
||Use clang-tidy when building||
||Use indexed coupons instead of par coupons||
||Use standard smart pointers instead of Boost ones||
||Use std::function and std::bind instead of Boost ones||
||Use std::tuple instead of boost::tuple||
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
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.
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
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
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
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.