Tips & Tricks

Working with QuantLib in CLion

This blog post is about QuantLib and how to get it working in CLion. For those of you who are unaware of what QuantLib is, it is an open-source quantitative finance library, covering many aspects of financial mathematics, including instrument pricing, financial calendars, and more. It has some sophisticated math, and also exhibits some interesting design patterns that C++ practitioners might find interesting.

QuantLib is originally configured as a Visual Studio solution, so we are going to take a look at how to

  • Build the Boost libraries, which QuantLib is dependent upon
  • Create a CMake-compliant project file for QuantLib
  • Build QuantLib using CLion

Upd. Initial CMake support pull request was accepted to the QuantLib master, that means you can work with QuantLib in CLion out of the box.

Including Boost

QuantLib depends on the Boost libraries, which need to be installed and built in order to successfully build QuantLib. Some parts of Boost are header-only (no compilation at all required), but other parts are not, meaning they have to be built and, unfortunately, QuantLib uses these Boost libraries, so we have no choice but to compile. The general procedure is as follows:

  • Windows: under the default (Visual Studio) scenario, you can download the Boost source code, compile it and produce sets of binaries. However, since CLion is configured to use either MinGW or Cygwin, you will need to compile Boost under those environments – you cannot use MSVC-compiled binaries.
  • Linux: you are in luck, you can simply sudo apt-get install libboost-dev-all and you’re set!
  • OS X: the simplest way to install Boost is to use a package manager such as Brew — that way you can simply enter brew install boost into the terminal, and you’re done.

Building Boost on Windows

My recommendation is to investigate a little and fine-tune the compilation of Boost to your liking. For example, in my case, I use a RAM disk (about 20Gb) to build Boost in, including the following options:

  • Build using the Intel compiler (desktop). I also selectively build Boost libraries for MIC (Xeon Phi).
  • Both 32-bit and 64-bit libraries (in case you’re wondering, 32-bit ones are required to use Boost in Visual Studio plug-ins, since VS itself is a 32-bit process). Warning: Boost does not include bitness in the name of the library. So, to build both 32-bit and 64-bit versions, you must put them in separate folders.
  • Both Debug and Release versions. Boost headers reference these automatically, so you really want to have both.
  • Statically linked libraries, but with dynamic linking to the CRT. This is your choice, but I am personally averse to both having Boost as dynamic libraries (which just feels weird) as well as having a dynamic runtime dependency (which might, depending on platform, require you to run a separate CRT installer).
  • Parallel compilation with -j 32 (or however many CPU cores you actually have). I am unaware of getting Boost to build with IncrediBuild, but if you know — leave a comment!
  • Enable MPI build for the Intel MPI. MPI support in Boost is pretty good (and more or less essential, IMHO, as MPI itself is a rather infriendly API), but it needs to be enabled explicitly with a --with-mpi switch… and yes, you need to specify paths to the actual MPI libraries for Boost to find.

There are plenty of settings for fine tuning your build of Boost including various optimization options. Don’t ignore them – significant gains can be made! I typically keep around a rather complicated script file which has all the settings that are fed into Boost’s b2 compilation command. Here’s an example of a command I might run:

b2 toolset="intel-15.0" address-model=64 threading=multi variant=debug,release link=static -j8 runtime-link=shared --clean

Note also, that in case of Cygwin, you can install Boost headers from Cygwin (just select the corresponding package when running Cygwin installer). This will make it easier for CMake to find your Boost headers.

Creating a CMake File

First of all, you’ll need actual QuantLib sources. You can take them from the GitHub repository, though if you plan to actually hack on QuantLib, you might want to fork it on GitHub and then clone from your repository fork.

We now need to import the QuantLib project into CLion wholesale. To do so, choose Import Project from Sources from the start menu. If you cloned QuantLib sources into c:\lib\quantlib, then the folder you want import is c:\lib\quantlib\QuantLib:

1

I typically don’t configure any additional include_directories path at this step.

CLion will take a bit of time to load the entire project — be patient! Now, we need just a few more steps of customization in the CMakeLists.txt file for QuantLib to build:

  • Use the incboost live template to add a reference to Boost. Typically, this is all you need to start using Boost in a CMake project. If CMake does not find your installation of Boost automatically, you can set the proper variables in you CMake file manually:
    set(BOOST_ROOT )
    set(Boost_INCLUDE_DIR )
    set(Boost_LIBRARY_DIR )
    
    include_directories(${BOOST_ROOT})
    include_directories(${Boost_INCLUDE_DIRS})
    link_directories(${Boost_LIBRARY_DIRS})
    
  • In order for files to be able to reference each other using the ql/ prefix (e.g., #include <ql/real.hpp>), we need to add the root directory to the list of search directories:
    include_directories(${CMAKE_CURRENT_SOURCE_DIR})
    
  • When it comes to QuantLib itself, you probably want to build a library rather than an executable. So change that add_executable call to add_library. This is sensible because linking is not a cheap process, so if you decide to keep relinking the whole of QuantLib together with your samples, well, be my guest.

Now, of course, we have a question of how to consume the library.

First of all, pick or make the executable that you want to use with QuantLib. Check out the \Samples folder for some examples. If you want to build such a sample, there are two simple steps to follow:

  • Create a new target with the example .cpp file
  • Use the target_link_libraries() CMake directive to link against QuantLib

So, the last few lines of your CMakeLists.txt file might look something like the following:

add_library(QuantLib ${SOURCE_FILES})
set(SAMPLE_FILES
  Examples/BasketLosses/BasketLosses.cpp)
add_executable(BasketLosses ${SAMPLE_FILES})
target_link_libraries(BasketLosses QuantLib)

That’s it! You can now compile QuantLib and run a sample app! And now that you got things working, you have many options on how to use QuantLib:

  • If you plan to simply use QuantLib as a library without any modifications, simply compile it as a static or dynamic library and make use of it in your C++ apps.
  • If you don’t intend to change QuantLib, you can also build a wrapper for another language or platform, such as Python, R or even Microsoft Excel. This gives you the added benefit of being able to use REPL as well as being able to plot data with tools such as Matplotlib.
  • You can do decide to hack on QuantLib, you’ve already got everything you need. CLion’s VCS integration should also come in handy here.

Have fun! ■

image description