mirror of
https://github.com/boostorg/python.git
synced 2026-01-21 17:12:22 +00:00
295 lines
10 KiB
HTML
295 lines
10 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content=
|
|
"HTML Tidy for Windows (vers 1st August 2002), see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link rel="stylesheet" type="text/css" href="boost.css">
|
|
|
|
<title>Boost.Python - Building and Testing</title>
|
|
</head>
|
|
|
|
<body link="#0000ff" vlink="#800080">
|
|
<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
|
|
"header">
|
|
<tr>
|
|
<td valign="top" width="300">
|
|
<h3><a href="../../../index.htm"><img height="86" width="277" alt=
|
|
"C++ Boost" src="../../../c++boost.gif" border="0"></a></h3>
|
|
</td>
|
|
|
|
<td valign="top">
|
|
<h1 align="center">Boost.Python</h1>
|
|
|
|
<h2 align="center">Building and Testing</h2>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<hr>
|
|
|
|
<h2>Contents</h2>
|
|
|
|
<dl class="Reference">
|
|
<dt><a href="#requirements">Requirements</a></dt>
|
|
|
|
<dt><a href="#building">Building Boost.Python</a></dt>
|
|
|
|
<dd>
|
|
<dl class="index">
|
|
<dt><a href="#configuration">Configuration</a></dt>
|
|
|
|
<dt><a href="#results">Results</a></dt>
|
|
|
|
<dt><a href="#testing">Testing</a></dt>
|
|
</dl>
|
|
</dd>
|
|
|
|
<dt><a href="#building_ext">Building your Extension Module</a></dt>
|
|
|
|
<dt><a href="#variants">Build Variants</a></dt>
|
|
</dl>
|
|
<hr>
|
|
|
|
<h2><a name="requirements">Requirements</a></h2>
|
|
Boost.Python requires <a href="http://www.python.org">Python</a> 2.2 or
|
|
later.
|
|
|
|
<h2><a name="building">Building Boost.Python</a></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).</p>
|
|
|
|
<h3><a name="configuration">Configuration</a></h3>
|
|
You may need to configure the following variables to point Boost.Build at
|
|
your Python installation:
|
|
|
|
<table border="1" summary="build configuration variables">
|
|
<tr>
|
|
<th>Variable Name</th>
|
|
|
|
<th>Semantics</th>
|
|
|
|
<th>Default</th>
|
|
|
|
<th>Notes</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>PYTHON_ROOT</code></td>
|
|
|
|
<td>The root directory of your Python installation</td>
|
|
|
|
<td>Windows: <code>c:/tools/python</code>
|
|
Unix: <code>/usr/local</code></td>
|
|
|
|
<td>On Unix, this is the <code>--with-prefix=</code> directory used
|
|
to configure Python</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>PYTHON_VERSION</code></td>
|
|
|
|
<td>The The 2-part python Major.Minor version number</td>
|
|
|
|
<td><code>2.2</code></td>
|
|
|
|
<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.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>PYTHON_INCLUDES</code></td>
|
|
|
|
<td>path to Python <code>#include</code> directories</td>
|
|
|
|
<td>Autoconfigured from <code>PYTHON_ROOT</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>PYTHON_LIB_PATH</code></td>
|
|
|
|
<td>path to Python library object.</td>
|
|
|
|
<td>Autoconfigured from <code>PYTHON_ROOT</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>PYTHON_STDLIB_PATH</code></td>
|
|
|
|
<td>path to Python standard library modules</td>
|
|
|
|
<td>Autoconfigured from <code>PYTHON_ROOT</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>CYGWIN_ROOT</code></td>
|
|
|
|
<td>path to the user's Cygwin installation</td>
|
|
|
|
<td>
|
|
</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.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>GCC_PYTHON_ROOT</code></td>
|
|
|
|
<td>path to the user's Cygwin Python installation</td>
|
|
|
|
<td><code>$(CYGWIN_ROOT)/usr/local</code></td>
|
|
|
|
<td><a href="http://www.cygwin.com">Cygwin</a> only</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>GCC_DEBUG_PYTHON_ROOT</code></td>
|
|
|
|
<td>path to the user's Cygwin <code><a href=
|
|
"#variants">pydebug</a></code> build</td>
|
|
|
|
<td><code>$(CYGWIN_ROOT)/usr/local/pydebug</code></td>
|
|
|
|
<td><a href="http://www.cygwin.com">Cygwin</a> only</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h3><a name="results">Results</a></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>.</p>
|
|
|
|
<h3><a name="testing">Testing</a></h3>
|
|
|
|
<p>To build and test Boost.Python, start from the
|
|
<code>libs/python/test</code> directory and invoke</p>
|
|
|
|
<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><a name="building_ext">Building your Extension Module</a></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>
|
|
|
|
<li>Copy <code><a href=
|
|
"../example/Jamfile">libs/python/example/Jamfile</a></code> to your new
|
|
directory.</li>
|
|
|
|
<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.</li>
|
|
</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>
|
|
|
|
<li><code>debug</code> (no optimization <tt>-D_DEBUG</tt>)</li>
|
|
|
|
<li><code>debug-python</code> (no optimization, <tt>-D_DEBUG
|
|
-DBOOST_DEBUG_PYTHON</tt>)</li>
|
|
</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>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
</p>
|
|
<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>
|
|
|
|
<p>Updated: O8 October, 2002 (David Abrahams)</p>
|
|
</body>
|
|
</html>
|
|
|