3.1   No-Install Quickstart

If you just want to get started quickly building and testing Boost.Python extension modules, or embedding Python in an executable, you don't need to worry about installing Boost.Python binaries explicitly. 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.

3.2   Installing Boost.Python on your System

If you need a regular, installation of the Boost.Python library binaries on your system, the Boost Getting Started Guide will walk you through the steps of installing one. If building binaries from source, you might want to supply the --with-python argument to bjam (or the --with-libraries=python argument to configure), so only the Boost.Python binary will be built, rather than all the Boost binaries.

7.1   Python Configuration Parameters

version

the version of Python to use. Should be in Major.Minor format, for example, 2.3. Do not include the subminor version (i.e. not 2.5.1). If you have multiple Python versions installed, the version will usually be the only additional argument required.

cmd-or-prefix

preferably, a command that invokes a Python interpreter. Alternatively, the installation prefix for Python libraries and header files. Use the alternative formulation if there is no appropriate Python executable available.

includes

the #include path for Python headers.

libraries

the path to Python library binaries. On MacOS/Darwin, you can also pass the path of the Python framework.

condition

if specified, should be a set of Boost.Build properties that are matched against the build configuration when Boost.Build selects a Python configuration to use.

extension-suffix

A string to append to the name of extension modules before the true filename extension. You almost certainly don't need to use this. Usually this suffix is only used when targeting a Windows debug build of Python, and will be set automatically for you based on the value of the <python-debugging> feature. However, at least one Linux distribution (Ubuntu Feisty Fawn) has a specially configured python-dbg package that claims to use such a suffix.

7.2   Examples

Note that in the examples below, case and especially whitespace are significant.

• If you have both python 2.5 and python 2.4 installed, user-config.jam might contain:

  using python : 2.5 ;  # Make both versions of Python available
  
  using python : 2.4 ;  # To build with python 2.4, add python=2.4
                        # to your command line.
  

  The first version configured (2.5) becomes the default. To build against python 2.4, add python=2.4 to the bjam command line.

• If you have python installed in an unusual location, you might supply the path to the interpreter in the cmd-or-prefix parameter:

  using python : : /usr/local/python-2.6-beta/bin/python ;
  

• If you have a separate build of Python for use with a particular toolset, you might supply that toolset in the condition parameter:

  using python ;  # use for most toolsets
  
  # Use with Intel C++ toolset
  using python
       : # version
       : c:\\Devel\\Python-2.5-IntelBuild\\PCBuild\\python # cmd-or-prefix
       : # includes
       : # libraries
       : <toolset>intel # condition
       ;
  

• You can set up your user-config.jam so a bjam built under Windows can build/test both Windows and Cygwin python extensions. Just pass <target-os>cygwin in the condition parameter for the cygwin python installation:

  # windows installation
  using python ;
  
  # cygwin installation
  using python : : c:\\cygwin\\bin\\python2.5 : : : <target-os>cygwin ;
  

  when you put target-os=cygwin in your build request, it should build with the cygwin version of python:⁵

  bjam target-os=cygwin toolset=gcc

  This is supposed to work the other way, too (targeting windows python with a Cygwin bjam) but it seems as though the support in Boost.Build's toolsets for building that way is broken at the time of this writing.

• Note that because of the way Boost.Build currently selects target alternatives, you might have be very explicit in your build requests. For example, given:

  using python : 2.5 ; # a regular windows build
  using python : 2.4 : : : : <target-os>cygwin ;
  

  building with

  bjam target-os=cygwin
  

  will yield an error. Instead, you'll need to write:

  bjam target-os=cygwin/python=2.4
  

8.1   The Dynamic Binary

The dynamic library is the safest and most-versatile choice:

• A single copy of the library code is used by all extension modules built with a given toolset.³
• The library contains a type conversion registry. Because one registry is shared among all extension modules, instances of a class exposed to Python in one dynamically-loaded extension module can be passed to functions exposed in another such module.

8.2   The Static Binary

It might be appropriate to use the static Boost.Python library in any of the following cases:

• You are extending python and the types exposed in your dynamically-loaded extension module don't need to be used by any other Boost.Python extension modules, and you don't care if the core library code is duplicated among them.
• You are embedding python in your application and either:
  • You are targeting a Unix variant OS other than MacOS or AIX, where the dynamically-loaded extension modules can “see” the Boost.Python library symbols that are part of the executable.
  • Or, you have statically linked some Boost.Python extension modules into your application and you don't care if any dynamically-loaded Boost.Python extension modules are able to use the types exposed by your statically-linked extension modules (and vice-versa).