diff --git a/doc/building.html b/doc/building.html index f9458c42..71c5cc4b 100644 --- a/doc/building.html +++ b/doc/building.html @@ -9,172 +9,193 @@ "../../../c++boost.gif" alt="c++boost.gif (8819 bytes)">Building an Extension Module -

The build process for Boost is currently undergoing some evolution, - and, it is to be hoped, improvement. The following facts may help: +

Building Boost.Python

-
- Makefiles for various platforms and a Visual Studio project - reside in the Boost subdirectory libs/python/build. - Build targets include: +

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 + +
+ +

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: - -
- There is a group of makefiles with support for simultaneous - compilation on multiple platforms and a consistent set of - features that build the boost_python library for static - linking, the comprehensive test, and all examples in - libs/python/example: - - - Usage of these makefiles is described here. - -
- There is another group of makefiles for GNU make. - These makefiles are less redundant than the makefiles - in the group above, - but the list of compilation targets is not as complete - and there is no support for simultaneous compilation - on multiple platforms. - - - -
- A project workspace for Microsoft Visual Studio is provided at libs/python/build/build.dsw. The - include paths for this project may need to be changed for your - installation. They currently assume that python has been installed at - c:\tools\python. Three configurations of all targets are - supported: - - -

When extension modules are built with Visual C++ using +

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. + #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 library forcing, and link with the DebugPython version of - boost_python.lib. You'll need to get the debugging version - of the Python executable (python_d.exe) and DLL - (python20_d.dll or python15_d.dll). The Python - sources include project files for building these. If you download them, change the name of the - top-level directory to src, and install it under - c:\tools\python, the workspace supplied by Boost.Python will - be able to use it without modification. Just open - c:\tools\python\src\pcbuild\pcbuild.dsw and invoke "build - all" to generate all the debugging targets. +

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 #include <#include <boost/python/detail/wrap_python.hpp> instead of the usual Python.h, or you will have link incompatibilities.
-

- If your platform isn't directly supported, you can build a static - library from the following source files (in the Boost subdirectory - libs/python/src), or compile them directly and link the - resulting objects into your extension module: - - -
Next: Wrapping Enums Previous: A Peek Under the Hood Up: Top
-

© Copyright David Abrahams 2000. Permission to copy, use, modify, +

© Copyright David Abrahams 2002. 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. -

Updated: Apr 17, 2001 (R.W. Grosse-Kunstleve) +

Updated: May 15, 2002 (David Abrahams)