mirror of
https://github.com/boostorg/python.git
synced 2026-01-20 16:52:15 +00:00
223 lines
9.0 KiB
HTML
223 lines
9.0 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
||
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
||
|
||
<title>Building an Extension Module</title>
|
||
|
||
<div>
|
||
<h1><img width="277" height="86" align="center" src=
|
||
"../../../c++boost.gif" alt="c++boost.gif (8819 bytes)">Building an
|
||
Extension Module</h1>
|
||
|
||
<h2>Building Boost.Python</h2>
|
||
|
||
<p>Every Boost.Python extension module must be linked with the
|
||
<code>boost_python</code> shared library. To build
|
||
<code>boost_python</code>, use <a
|
||
href="../../../tools/build/index.html">Boost.Build</a> in the
|
||
usual way from the <code>libs/python/build</code> 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).
|
||
|
||
<h3>Configuration</h3>
|
||
You may need to configure the following variables to point Boost.Build at your Python installation:
|
||
|
||
<table border="1">
|
||
<tr><th>Variable Name <th>Semantics <th>Default <th>Notes
|
||
<tr>
|
||
<td><code>PYTHON_ROOT</code>
|
||
<td>The root directory of your Python installation
|
||
<td>Windows: <code>c:/tools/python</code>
|
||
Unix: <code>/usr/local</code>
|
||
<td>On Unix, this is the <code>--with-prefix=</code> directory
|
||
used to configure Python
|
||
|
||
<tr>
|
||
<td><code>PYTHON_VERSION</code>
|
||
<td>The The 2-part python Major.Minor version number
|
||
<td>Windows: <code>2.1</code>
|
||
Unix: <code>1.5</code>
|
||
<td>Be sure not to include a third number, e.g. <b>not</b>
|
||
"<code>2.2.1</code>", even if that's the version you
|
||
have.
|
||
|
||
<tr>
|
||
<td><code>PYTHON_INCLUDES</code>
|
||
<td>path to Python <code>#include</code> directories
|
||
<td>Autoconfigured from <code>PYTHON_ROOT</code>
|
||
|
||
<tr>
|
||
<td><code>PYTHON_LIB_PATH</code>
|
||
<td>path to Python library object.
|
||
<td>Autoconfigured from <code>PYTHON_ROOT</code>
|
||
|
||
<tr>
|
||
<td><code>PYTHON_STDLIB_PATH</code>
|
||
<td>path to Python standard library modules
|
||
<td>Autoconfigured from <code>PYTHON_ROOT</code>
|
||
|
||
<tr>
|
||
<td><code>CYGWIN_ROOT</code>
|
||
<td>path to the user's Cygwin installation
|
||
<td>
|
||
<td><a href="http://www.cygwin.com">Cygwin</a> only. This and the following two settings are
|
||
useful when building with multiple toolsets on Windows, since
|
||
Cygwin requires a different build of Python.
|
||
|
||
<tr>
|
||
<td><code>GCC_PYTHON_ROOT</code>
|
||
<td>path to the user's Cygwin Python installation
|
||
<td><code>$(CYGWIN_ROOT)/usr/local</code>
|
||
<td><a href="http://www.cygwin.com">Cygwin</a> only
|
||
|
||
<tr>
|
||
<td><code>GCC_DEBUG_PYTHON_ROOT</code>
|
||
<td>path to the user's Cygwin <code><a
|
||
href="#variants">pydebug</a></code> build
|
||
<td><code>$(CYGWIN_ROOT)/usr/local/pydebug</code>
|
||
<td><a href="http://www.cygwin.com">Cygwin</a> only
|
||
|
||
</table>
|
||
|
||
<h3>Results</h3>
|
||
<p>The build process will create a
|
||
<code>libs/python/build/bin-stage</code> subdirectory of the
|
||
boost root (or of <code>$(ALL_LOCATE_TARGET)</code>,
|
||
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
|
||
<code>bin-stage</code> 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
|
||
<code>bin-stage</code>.
|
||
|
||
<h3>Testing</h3>
|
||
<p>To build and test Boost.Python from within the
|
||
<code>libs/python/build</code> directory, invoke
|
||
<blockquote>
|
||
<pre>
|
||
bjam -sTOOLS=<i><a href="../../../tools/build/index.html#Tools">toolset</a></i> test
|
||
</pre>
|
||
</blockquote>
|
||
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
|
||
<blockquote>
|
||
<pre>
|
||
bjam -sTOOLS=<i><a href="../../../tools/build/index.html#Tools">toolset</a></i> -sPYTHON_TEST_ARGS=-v test
|
||
</pre>
|
||
</blockquote>
|
||
which will print each test's Python code with the expected output as
|
||
it passes.
|
||
|
||
<h2>Building your Extension Module</h2>
|
||
|
||
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
|
||
<code>libs/python/example</code> subdirectory of your boost
|
||
installation contains a minimal example (along with many extra
|
||
sources). To copy the example subproject:
|
||
|
||
<ol>
|
||
<li>Create a new subdirectory in, <code>libs/python</code>, say
|
||
<code>libs/python/my_project</code>.
|
||
|
||
<li>Copy <code><a
|
||
href="../example/Jamfile">libs/python/example/Jamfile</a></code>
|
||
to your new directory.
|
||
|
||
<li>Edit the Jamfile as appropriate for your project. You'll
|
||
want to change the "<code>subproject</code>" rule
|
||
invocation at the top, and the names of some of the source files
|
||
and/or targets.
|
||
|
||
</ol>
|
||
|
||
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 <code><a
|
||
href="../example/project.zip">this archive</a></code>. 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.
|
||
|
||
<h2><a name="variants">Build Variants</a></h2>
|
||
|
||
Three <a
|
||
href="../../../tools/build/build_system.htm#variants">variant</a>
|
||
configurations of all python-related targets are supported, and
|
||
can be selected by setting the <code><a
|
||
href="../../../tools/build/build_system.htm#user_globals">BUILD</a></code>
|
||
variable:
|
||
|
||
<ul>
|
||
<li><code>release</code> (optimization, <tt>-DNDEBUG</tt>)
|
||
|
||
<li><code>debug</code> (no optimization <tt>-D_DEBUG</tt>)
|
||
|
||
<li><code>debug-python</code> (no optimization, <tt>-D_DEBUG
|
||
-DBOOST_DEBUG_PYTHON</tt>)
|
||
</ul>
|
||
|
||
<p>The first two variants of the <code>boost_python</code>
|
||
library are built by default, and are compatible with the
|
||
default Python distribution. The <code>debug-python</code>
|
||
variant corresponds to a specially-built debugging version of
|
||
Python. On Unix platforms, this python is built by adding
|
||
<code>--with-pydebug</code> when configuring the Python
|
||
build. On Windows, the debugging version of Python is generated
|
||
by the "Win32 Debug" target of the
|
||
<code>PCBuild.dsw</code> Visual C++ 6.0 project in the
|
||
<code>PCBuild</code> subdirectory of your Python distribution.
|
||
|
||
Extension modules built with Python debugging enabled are <b>not
|
||
link-compatible</b> 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
|
||
<code>debug</code> variant builds modules which are compatible
|
||
with ordinary Python.
|
||
|
||
|
||
<p>On many windows compilers, when extension modules are built
|
||
with
|
||
<tt>-D_DEBUG</tt>, Python defaults to <i>force</i> 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 <tt><a href=
|
||
"../../../boost/python/detail/wrap_python.hpp">boost/python/detail/wrap_python.hpp</a></tt>
|
||
to temporarily undefine <tt>_DEBUG</tt> when <tt>Python.h</tt> is
|
||
<tt>#include</tt>d - unless <code>BOOST_DEBUG_PYTHON</code> is defined.
|
||
|
||
<p>If you want the extra runtime checks available with the
|
||
debugging version of the library, <tt>#define
|
||
BOOST_DEBUG_PYTHON</tt> to re-enable python debuggin, and link
|
||
with the <code>debug-python</code> variant of
|
||
<tt>boost_python</tt>.
|
||
|
||
<p>If you do not <tt>#define BOOST_DEBUG_PYTHON</tt>, be sure that
|
||
any source files in your extension module <tt>#include <<a href=
|
||
"../../../boost/python/detail/wrap_python.hpp">boost/python/detail/wrap_python.hpp</a>></tt>
|
||
instead of the usual <tt>Python.h</tt>, or you will have link
|
||
incompatibilities.<br>
|
||
|
||
<hr>
|
||
Next: <a href="enums.html">Wrapping Enums</a> Previous: <a href=
|
||
"under-the-hood.html">A Peek Under the Hood</a> Up: <a href=
|
||
"index.html">Top</a>
|
||
|
||
<hr>
|
||
<p>© 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.
|
||
|
||
<p>Updated: May 15, 2002 (David Abrahams)
|
||
</div>
|