boost/python
2
0
Fork 0
mirror of https://github.com/boostorg/python.git synced 2026-01-23 17:52:17 +00:00
Code Issues Projects Releases Wiki Activity
Files
83c38876fe51a661ffd30b2cde1002af170ed833
python/doc/tutorial/doc/building_an_extension_module.html
Joel de Guzman e49e0d2705 tutorial added 
[SVN r15817]
2002-10-09 05:03:22 +00:00

187 lines
9.3 KiB
HTML
Raw Blame History

<html>
<head>
<!-- Generated by the Spirit (http://spirit.sf.net) QuickDoc -->
<title>Building an Extension Module </title>
<link rel="stylesheet" href="theme/style.css" type="text/css">
<link rel="prev" href="class_data_members.html">
<link rel="next" href="inheritance.html">
</head>
<body>
<table width="100%" height="48" border="0" cellspacing="2">
<tr>
<td><img src="theme/c%2B%2Bboost.gif">
</td>
<td width="85%"> <font size="6" face="Verdana, Arial, Helvetica, sans-serif"><strong>Building
an Extension Module</strong></font> </td>
</tr>
</table>
<br>
<table border="0">
<tr>
<td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
<td width="30"><img src="theme/l_arr.gif" border="0"></td>
<td width="20"><img src="theme/r_arr.gif" border="0"></td>
</tr>
</table>
<h2>Building Boost.Python</h2>
<p>Every Boost.Python extension module must be linked with the boost_python shared
library. To build boost_python, use <a href="file:///C:/dev/boost/tools/build/index.html">Boost.Build</a>
in the usual way from the <tt>libs/python/build</tt> 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>
<h2>Configuration</h2>
<p>You may need to configure the following variables to point Boost.Build at your
Python installation:</p>
<table width="95%" border="0" align="center">
<tr class="table_title">
<td width="24%">Variable Name</td>
<td width="20%">Semantics</td>
<td width="21%">Default</td>
<td width="35%">Notes</td>
</tr>
<tr class="table_cells">
<td><tt>PYTHON_ROOT</tt></td>
<td> The root directory of your Python installation</td>
<td>Windows: <tt><br>
c:/tools/python <br>
Unix: /usr/local</tt></td>
<td>On Unix, this is the <tt>--with-prefix=</tt> directory used to configure
Python</td>
</tr>
<tr class="table_cells">
<td><tt>PYTHON_VERSION</tt></td>
<td> The The 2-part python Major.Minor version number</td>
<td>Windows: 2.1 Unix: 1.5</td>
<td>Be sure not to include a third number, e.g. not &quot;2.2.1&quot;, even
if that's the version you have.</td>
</tr>
<tr class="table_cells">
<td><tt>PYTHON_INCLUDES</tt></td>
<td> path to Python <span class="preprocessor">#include</span> directories</td>
<td>Autoconfigured from <tt><br>
PYTHON_ROOT</tt></td>
<td>&nbsp;</td>
</tr>
<tr class="table_cells">
<td><tt>PYTHON_LIB_PATH</tt></td>
<td>path to Python library object.</td>
<td>Autoconfigured from <tt><br>
PYTHON_ROOT</tt></td>
<td>&nbsp;</td>
</tr>
<tr class="table_cells">
<td><tt>PYTHON_STDLIB_PATH</tt></td>
<td>path to Python standard library modules</td>
<td>Autoconfigured from <tt><br>
PYTHON_ROOT</tt></td>
<td>&nbsp;</td>
</tr>
<tr class="table_cells">
<td height="129"><tt>CYGWIN_ROOT</tt></td>
<td> path to the user's Cygwin installation</td>
<td>Autoconfigured from <tt><br>
PYTHON_ROOT</tt></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 class="table_cells">
<td height="21"><tt>GCC_PYTHON_ROOT</tt></td>
<td>path to the user's Cygwin Python installation</td>
<td><tt>$(CYGWIN_ROOT)<br>
/usr/local</tt></td>
<td> <a href="http://www.cygwin.com">Cygwin</a> only</td>
</tr>
<tr class="table_cells">
<td><tt>GCC_DEBUG_PYTHON_ROOT</tt></td>
<td> path to the user's Cygwin <a href="#variants">pydebug</a>
build</td>
<td><tt>$(CYGWIN_ROOT)<br>
/usr/local/pydebug</tt></td>
<td> <a href="http://www.cygwin.com">Cygwin</a> only</td>
</tr>
</table>
<h2>Results</h2>
<p>The build process will create a <tt>libs/python/build/bin-stage</tt> subdirectory
of the boost root (or of <tt>$(ALL_LOCATE_TARGET)</tt>, 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.</p>
<h2>Testing</h2>
<p>To build and test Boost.Python from within the <tt>libs/python/build directory</tt>,
invoke</p>
<pre> bjam -sTOOLS=<a href="../../../tools/build/index.html">toolset</a> test</pre>
<p>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</p>
<pre> bjam -sTOOLS=<a href="../../../tools/build/index.html">toolset</a> -sPYTHON_TEST_ARGS=-v test</pre>
<p>which will print each test's Python code with the expected output as it passes.</p>
<h2>Building your Extension Module</h2>
<p>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 <tt>libs/python/example</tt>
subdirectory of your boost installation contains a minimal example (along with
many extra sources). To copy the example subproject:</p>
<ol>
<li> Create a new subdirectory in,<tt> libs/python</tt>, say <tt>libs/python/my_project</tt>.</li>
<li> Copy <a href="../example/Jamfile"><tt>libs/python/example/Jamfile</tt></a>
to your new directory.</li>
<li> Edit the Jamfile as appropriate for your project. You'll want to change
the <tt>subproject</tt> rule invocation at the top, and the names of some
of the source files and/or targets.</li>
</ol>
<p>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 <a href="../example/project.zip">this archive</a>. 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.</p>
<h2>Build Variants</h2>
<p>Three variant configurations of all python-related targets are supported, and
can be selected by setting the BUILD variable:</p>
<p> * <tt>release</tt> (optimization, <tt>-DNDEBUG</tt>)<br>
* <tt>debug</tt> (no optimization <tt>-D_DEBUG</tt>)<br>
* <tt>debug-python</tt> (no optimization, <tt>-D_DEBUG -DBOOST_DEBUG_PYTHON</tt>)</p>
<p>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 <tt>--with-pydebug</tt> when configuring the
Python build. On Windows, the debugging version of Python is generated by the
&quot;Win32 Debug&quot; 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.</p>
<p>On many windows compilers, when extension modules are built with <tt>-D_DEBUG</tt>,
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 <a href="../../../boost/python/detail/wrap_python.hpp"><tt>boost/python/detail/wrap_python.hpp</tt></a>
to temporarily undefine <tt>_DEBUG</tt> when <tt>Python.h</tt> is <span class="preprocessor">#included</span>
- unless <tt>BOOST_DEBUG_PYTHON</tt> is defined.</p>
<p>If you want the extra runtime checks available with the debugging version of
the library, <span class="preprocessor">#define</span> <tt>BOOST_DEBUG_PYTHON</tt>
to re-enable python debuggin, and link with the debug-python variant of boost_python.</p>
<p>If you do not <span class="preprocessor">#define</span> <tt>BOOST_DEBUG_PYTHON</tt>,
be sure that any source files in your extension module <span class="preprocessor">#include</span>
<tt>&lt;boost/python/detail/wrap_python.hpp&gt;</tt> instead of the usual <tt>Python.h</tt>,
or you will have link incompatibilities.</p>
<code></code>
<table border="0">
<tr>
<td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
<td width="30"><img src="theme/l_arr.gif" border="0"></td>
<td width="20"><img src="theme/r_arr.gif" border="0"></td>
</tr>
</table>
<br>
<hr size="1"><p class="copyright">Copyright &copy; 2002 David Abrahams<br>Copyright &copy; 2002 Joel de Guzman<br><br>
<font size="2">Permission to copy, use, modify, sell and distribute this document
is granted provided this copyright notice appears in all copies. This document
is provided &quot;as is&quot; without express or implied warranty, and with
no claim as to its suitability for any purpose. </font> </p>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink