Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.
PrevUpHomeNext

No-Install Quickstart

Basic Procedure
In Case of Trouble
In Case Everything Seemed to Work
Modifying the Example Project

There is no need to “install Boost” in order to get started using Boost.Python. These instructions use Boost.Build projects, which will build those binaries as soon as they're needed. Your first tests may take a little longer while you wait for Boost.Python to build, but doing things this way will save you from worrying about build intricacies like which library binaries to use for a specific compiler configuration and figuring out the right compiler options to use yourself.

[Note] Note

Of course it's possible to use other build systems to build Boost.Python and its extensions, but they are not officially supported by Boost. Moreover 99% of all “I can't build Boost.Python” problems come from trying to use another build system without first following these instructions.

If you want to use another system anyway, we suggest that you follow these instructions, and then invoke bjam with the

-a -ofilename

options to dump the build commands it executes to a file, so you can see what your alternate build system needs to do.

1. Get Boost; see sections 1 and 2 of the Boost Getting Started Guide.

2. Get the bjam build driver. See section 5 of the Boost Getting Started Guide.

3. cd into the example/quickstart/ directory of your Boost.Python installation, which contains a small example project.

4. Invoke bjam. Replace the “stage“ argument from the example invocation from section 5 of the Boost Getting Started Guide with “test,“ to build all the test targets. Also add the argument “--verbose-test” to see the output generated by the tests when they are run. On Windows, your bjam invocation might look something like:

C:\\...\\quickstart> bjam toolset=msvc --verbose-test test

and on Unix variants, perhaps,

.../quickstart$ bjam toolset=gcc --verbose-test test
[Note] Note

For the sake of concision, the rest of this guide will use unix-style forward slashes in pathnames instead of the backslashes with which Windows users may be more familiar. The forward slashes should work everywhere except in Command Prompt windows, where you should use backslashes.

If you followed this procedure successfully, you will have built an extension module called extending and tested it by running a Python script called test_extending.py. You will also have built and run a simple application called embedding that embeds python.

If you're seeing lots of compiler and/or linker error messages, it's probably because Boost.Build is having trouble finding your Python installation. You might want to pass the --debug-configuration option to bjam the first few times you invoke it, to make sure that Boost.Build is correctly locating all the parts of your Python installation. If it isn't, consider Configuring Boost.Build as detailed below.

If you're still having trouble, Someone on one of the following mailing lists may be able to help:

Rejoice! If you're new to Boost.Python, at this point it might be a good idea to ignore build issues for a while and concentrate on learning the library by going through the Tutorial and perhaps some of the Reference Manual, trying out what you've learned about the API by modifying the quickstart project.

If you're content to keep your extension module forever in one source file called extending.cpp, inside your Boost.Python distribution, and import it forever as extending, then you can stop here. However, it's likely that you will want to make a few changes. There are a few things you can do without having to learn Boost.Build in depth.

The project you just built is specified in two files in the current directory: boost-build.jam, which tells bjam where it can find the interpreted code of the Boost build system, and Jamroot, which describes the targets you just built. These files are heavily commented, so they should be easy to modify. Take care, however, to preserve whitespace. Punctuation such as ; will not be recognized as intended by bjam if it is not surrounded by whitespace.

You'll probably want to copy this project elsewhere so you can change it without modifying your Boost distribution. To do that, simply

a. copy the entire example/quickstart/ directory into a new directory.

b. In the new copies of boost-build.jam and Jamroot, locate the relative path near the top of the file that is clearly marked by a comment, and edit that path so that it refers to the same directory your Boost distribution as it referred to when the file was in its original location in the example/quickstart/ directory.

For example, if you moved the project from /home/dave/boost_1_34_0/libs/python/example/quickstart to /home/dave/my-project, you could change the first path in boost-build.jam from

../../../../tools/build/src

to

/home/dave/boost_1_34_0/tools/build/src

and change the first path in Jamroot from

../../../..

to

/home/dave/boost_1_34_0

The names of additional source files involved in building your extension module or embedding application can be listed in Jamroot right alongside extending.cpp or embedding.cpp respectively. Just be sure to leave whitespace around each filename:

 file1.cpp file2.cpp file3.cpp 

Naturally, if you want to change the name of a source file you can tell Boost.Build about it by editing the name in Jamroot.

The name of the extension module is determined by two things:

  1. the name in Jamroot immediately following python-extension, and
  2. the name passed to BOOST_PYTHON_MODULE in extending.cpp.

To change the name of the extension module from extending to hello, you'd edit Jamroot, changing

python-extension extending : extending.cpp ;

to

python-extension hello : extending.cpp ;

and you'd edit extending.cpp, changing

BOOST_PYTHON_MODULE(extending)

to

BOOST_PYTHON_MODULE(hello)

PrevUpHomeNext