- |
- |
- Building - an Extension Module | -
 |
-  |
-  |
-
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).
-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 | -
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.
-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.
-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:
-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.
-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.