Using CMake to Build C++ Boost Python Libraries


The Boost Project has a Python library that makes it easy to seamlessly integrate C++ and Python code. Unfortunately, the documentation recommends using bjam. If you build Boost from source, then this is largely a non-issue. If, however, you are using Boost from preinstalled binaries or from a Gentoo ebuild, then you don't want to use bjam at all!

CMake is an excellent, cross-platform build system tool (e.g., like make but much better). CMake has the ability to determine platform-specific options required to build code. This saves one from having to specify each and every compiler, linker, etc. option including specific system paths, etc. In short, CMake makes is a lot easier to compile and run programs from source.

This post details how to build a minimal C++ library with its code compiled as a module capable of being loaded by Python (version 2.6 or higher) using CMake (version 2.8) and Boost (version 1.45.0). The text below assumes:

  • you are using a BASH shell on a Linux / Unix system,
  • you are using GCC's g++,
  • you already have CMake installed,
  • you already have Boost installed, and,
  • you already have Python installed.


Step 1: Create Your Development Directory & Set Your PATH

You'll want to create a new directory (e.g., "src") with a "build" subdirectory in it:

$ mkdir -p src/build

and change your current working directory to the new directory:

$ cd src

In order to run the Python code later, also ensure that "." appears in your PATH environment variable:

$ export PATH

This will permit Python to load the module that is built. You may want to add these two lines to your ~/.bashrc script to avoid having to always set this in any new shells.

Step 2: Create CMakeLists.txt

Now, you can write the file that CMake will use to build the C++ code into a Python module. This module will be compiled as a Shared Object Library file (i.e., a .so file).

NOTE: In Windows, shared objects are Dynamically Linked Libraries (DLLs). Please note that under Linux / Unix, libraries are typically named with a "lib" prefix and a ".so" suffix. Under Windows, libraries simply have a ".dll" suffix. The instructions below are for Linux / Unix and so the "yay" library that is built will be called "", whereas, under Windows it would be called "yay.dll". Thus, if you are using Windows, you may have to make some minor adjustments to the files below.

Your CMakeLists.txt file should contain:


FIND_PACKAGE(Boost 1.45.0)
  INCLUDE_DIRECTORIES("${Boost_INCLUDE_DIRS}" "/usr/include/python2.6")
  FIND_PACKAGE(Boost 1.45.0 COMPONENTS python)

  ADD_LIBRARY(yay SHARED yay.cxx)
  MESSAGE(FATAL_ERROR "Unable to find correct Boost version. Did you set BOOST_ROOT?")

  MESSAGE(FATAL_ERROR "CMakeLists.txt has not been tested/written for your compiler.")

Notice that the output will be a shared library file called "yay". It is important to specify both the Boost include path as well as the Python include path with INCLUDE_DIRECTORIES in order for the code to compile properly.

Step 3: Create yay.cxx

Now create yay.cxx:

#include <boost/python.hpp>

char const* yay()
  return "Yay!";

  using namespace boost::python;
  def("yay", yay);

It is very important that "libyay" in BOOST_PYTHON_MODULE(libyay) matches the name of the library you're generating in CMakeLists.txt (without the extension).

NOTE: On Linux / Unix systems you will need to prefix the name with "lib" as CMake defaults to prepending the file with "lib" as per convention on Linux / Unix systems.

Essentially, the BOOST_PYTHON_MODULE clause exports the "yay" function as the Python symbol name "yay". This will allow you to call the "yay" function from Python later.

Step 4: Build The Python Module

The best way to invoke CMake is to invoke it in a special build directory. This is why Step 1 mentioned to create a build directory as well. Before you can make the library, you need to have cmake generate the neccessary files to perform the build:

$ cd build
$ cmake ..

(You only need to run "cmake .." after changes are made to CMakeLists.txt.) Now, you can build the program by running make:

$ make

If all went well, you will see a file in the current directory! If you need to clean up files, then run "make clean". If the build directory is a complete mess and you want to start over, then remove all of its contents, run "cmake ..", and then "make".

Step 5: Create A Python Script To Call yay()

Now you can test your efforts by writing the following python script:

import libyay
print libyay.yay()

When you run it, it should output "Yay" (assuming the library file is somewhere in PATH, or, in the standard location for your system's Python libraries).

Step 6: Have Fun!

That's it! More information on how to export more symbols and call functions (either way) is available in the Boost Python library documentation.