| Building an Extension Module

## Building Boost.Python

Every Boost.Python extension module must be linked with the boost_python shared library. To build boost_python, use Boost.Build in the usual way from the `libs/python/build` subdirectory of your boost installation (if you have already built boost from the top level this may have no effect, since the work is already done).

## Configuration

You may need to configure the following variables to point Boost.Build at your Python installation:

Variable Name | Semantics | Default | Notes
`PYTHON_ROOT` | The root directory of your Python installation | Windows: `c:/tools/python Unix: /usr/local` | On Unix, this is the `--with-prefix=` directory used to configure Python
`PYTHON_VERSION` | The The 2-part python Major.Minor version number | Windows: 2.1 Unix: 1.5 | Be sure not to include a third number, e.g. not "2.2.1", even if that's the version you have.
`PYTHON_INCLUDES` | path to Python #include directories | Autoconfigured from `PYTHON_ROOT` |
`PYTHON_LIB_PATH` | path to Python library object. | Autoconfigured from `PYTHON_ROOT` |
`PYTHON_STDLIB_PATH` | path to Python standard library modules | Autoconfigured from `PYTHON_ROOT` |
`CYGWIN_ROOT` | path to the user's Cygwin installation | Autoconfigured from `PYTHON_ROOT` | Cygwin only. This and the following two settings are useful when building with multiple toolsets on Windows, since Cygwin requires a different build of Python.
`GCC_PYTHON_ROOT` | path to the user's Cygwin Python installation | `$(CYGWIN_ROOT) /usr/local` | Cygwin only
`GCC_DEBUG_PYTHON_ROOT` | path to the user's Cygwin pydebug build | `$(CYGWIN_ROOT) /usr/local/pydebug` | Cygwin only

## Results

The build process will create a `libs/python/build/bin-stage` subdirectory of the boost root (or of `$(ALL_LOCATE_TARGET)`, if you have set that variable), containing the built libraries. The libraries are actually built to unique directories for each toolset and variant elsewhere in the filesystem, and copied to the bin-stage directory as a convenience, so if you build with multiple toolsets at once, the product of later toolsets will overwrite that of earlier toolsets in bin-stage.

## Testing

To build and test Boost.Python from within the `libs/python/build directory`, invoke

        bjam -sTOOLS=toolset test

This will update all of the Boost.Python v1 test and example targets. The tests are relatively quiet by default. To get more-verbose output, you might try

        bjam -sTOOLS=toolset -sPYTHON_TEST_ARGS=-v test

which will print each test's Python code with the expected output as it passes.

## Building your Extension Module

Though there are other approaches, the easiest way to build an extension module using Boost.Python is with Boost.Build. Until Boost.Build v2 is released, cross-project build dependencies are not supported, so it works most smoothly if you add a new subproject to your boost installation. The `libs/python/example` subdirectory of your boost installation contains a minimal example (along with many extra sources). To copy the example subproject:

1. Create a new subdirectory in,`libs/python`, say `libs/python/my_project`.
2. Copy `libs/python/example/Jamfile` to your new directory.
3. Edit the Jamfile as appropriate for your project. You'll want to change the `subproject` rule invocation at the top, and the names of some of the source files and/or targets.

If you can't modify or copy your boost installation, the alternative is to create your own Boost.Build project. A similar example you can use as a starting point is available in this archive. You'll need to edit the Jamfile and Jamrules files, depending on the relative location of your Boost installation and the new project. Note that automatic testing of extension modules is not available in this configuration.

## Build Variants

Three variant configurations of all python-related targets are supported, and can be selected by setting the BUILD variable:

* `release` (optimization, `-DNDEBUG`)
* `debug` (no optimization `-D_DEBUG`)
* `debug-python` (no optimization, `-D_DEBUG -DBOOST_DEBUG_PYTHON`)

The first two variants of the boost_python library are built by default, and are compatible with the default Python distribution. The debug-python variant corresponds to a specially-built debugging version of Python. On Unix platforms, this python is built by adding `--with-pydebug` when configuring the Python build. On Windows, the debugging version of Python is generated by the "Win32 Debug" target of the PCBuild.dsw Visual C++ 6.0 project in the PCBuild subdirectory of your Python distribution. Extension modules built with Python debugging enabled are not link-compatible with a non-debug build of Python. Since few people actually have a debug build of Python (it doesn't come with the standard distribution), the normal debug variant builds modules which are compatible with ordinary Python.

On many windows compilers, when extension modules are built with `-D_DEBUG`, Python defaults to force linking with a special debugging version of the Python DLL. Since this debug DLL isn't supplied with the default Python installation for Windows, Boost.Python uses `boost/python/detail/wrap_python.hpp` to temporarily undefine `_DEBUG` when `Python.h` is #included - unless `BOOST_DEBUG_PYTHON` is defined.

If you want the extra runtime checks available with the debugging version of the library, #define `BOOST_DEBUG_PYTHON` to re-enable python debuggin, and link with the debug-python variant of boost_python.

If you do not #define `BOOST_DEBUG_PYTHON`, be sure that any source files in your extension module #include `<boost/python/detail/wrap_python.hpp>` instead of the usual `Python.h`, or you will have link incompatibilities.

``

Copyright © 2002 David Abrahams
Copyright © 2002 Joel de Guzman
Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This document is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.