|
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]](../images/note.png) |
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
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 |
|---|---|
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:
Jamroot
immediately following python-extension,
and
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)