mirror of
https://github.com/boostorg/python.git
synced 2026-01-23 05:42:30 +00:00
Updated instructions
[SVN r13928]
This commit is contained in:
Dave Abrahams
@@ -9,172 +9,193 @@
|
||||
"../../../c++boost.gif" alt="c++boost.gif (8819 bytes)">Building an
|
||||
Extension Module</h1>
|
||||
|
||||
<p>The build process for Boost is currently undergoing some evolution,
|
||||
and, it is to be hoped, improvement. The following facts may help:
|
||||
<h2>Building Boost.Python</h2>
|
||||
|
||||
<hr>
|
||||
Makefiles for various platforms and a Visual Studio project
|
||||
reside in the Boost subdirectory <tt>libs/python/build</tt>.
|
||||
Build targets include:
|
||||
<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>
|
||||
|
||||
</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>Build Variants</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>The <tt>boost_python</tt> library for static linking with your
|
||||
extension module. On the various Unices, this library will be
|
||||
called <tt>libboost_python.a</tt>. When using Visual C++, the
|
||||
library will be called <tt>boost_python.lib</tt>.
|
||||
<li><code>release</code> (optimization, <tt>-DNDEBUG</tt>)
|
||||
|
||||
<p>
|
||||
<li>A comprehensive test of Boost.Python features. This test builds
|
||||
a Boost.Python extension module, then runs Python to import the
|
||||
module, and runs a series of tests on it using <tt><a href=
|
||||
"../test/doctest.py">doctest</a></tt>. Source code for the module
|
||||
and tests is available in the Boost subdirectory
|
||||
<tt>libs/python/test</tt>.
|
||||
<li><code>debug</code> (no optimization <tt>-D_DEBUG</tt>)
|
||||
|
||||
<p>
|
||||
<li>Various examples from the Boost subdirectory
|
||||
<tt>libs/python/example</tt>.
|
||||
All these examples include a doctest modeled
|
||||
on the comprehensive test above.
|
||||
|
||||
</ul>
|
||||
|
||||
<hr>
|
||||
There is a group of makefiles with support for simultaneous
|
||||
compilation on multiple platforms and a consistent set of
|
||||
features that build the <tt>boost_python</tt> library for static
|
||||
linking, the comprehensive test, and all examples in
|
||||
<tt>libs/python/example</tt>:
|
||||
|
||||
<ul>
|
||||
<li><a href="../build/vc60.mak">vc60.mak</a>:
|
||||
Visual C++ 6.0 Service Pack 4
|
||||
|
||||
<li><a href="../build/mingw32.mak">mingw32.mak</a>:
|
||||
mingw32 (Win32-targeted) gcc 2.95.2
|
||||
|
||||
<li><a href="../build/linux_gcc.mak">linux_gcc.mak</a>:
|
||||
gcc 2.95.2 on Linux/Unix
|
||||
|
||||
<li><a href="../build/tru64_cxx.mak">tru64_cxx.mak</a>:
|
||||
Compaq Alpha using the Compaq cxx compiler
|
||||
|
||||
<li><a href="../build/irix_CC.mak">irix_CC.mak</a>:
|
||||
Silicon Graphics IRIX 6.5 CC compiler
|
||||
|
||||
</ul>
|
||||
<a href="http://cctbx.sourceforge.net/page_installation_adv.html#installation_boost_python"
|
||||
>Usage of these makefiles is described here.</a>
|
||||
|
||||
<hr>
|
||||
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.
|
||||
|
||||
<ul>
|
||||
<li><a href="../build/como.mak">como.mak</a>:
|
||||
Comeau C++ on Linux
|
||||
|
||||
<li><a href="../build/gcc.mak">gcc.mak</a>:
|
||||
GCC on Linux/Unix.
|
||||
|
||||
</ul>
|
||||
|
||||
<hr>
|
||||
A project workspace for Microsoft Visual Studio is provided at <tt><a
|
||||
href="../build/build.dsw">libs/python/build/build.dsw</a></tt>. The
|
||||
include paths for this project may need to be changed for your
|
||||
installation. They currently assume that python has been installed at
|
||||
<tt>c:\tools\python</tt>. Three configurations of all targets are
|
||||
supported:
|
||||
|
||||
<ul>
|
||||
<li>Release (optimization, <tt>-DNDEBUG</tt>)
|
||||
|
||||
<li>Debug (no optimization <tt>-D_DEBUG</tt>)
|
||||
|
||||
<li>DebugPython (no optimization, <tt>-D_DEBUG
|
||||
<li><code>debug-python</code> (no optimization, <tt>-D_DEBUG
|
||||
-DBOOST_DEBUG_PYTHON</tt>)
|
||||
</ul>
|
||||
|
||||
<p>When extension modules are built with Visual C++ using
|
||||
<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.
|
||||
<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 library forcing, and link with the DebugPython version of
|
||||
<tt>boost_python.lib</tt>. You'll need to get the debugging version
|
||||
of the Python executable (<tt>python_d.exe</tt>) and DLL
|
||||
(<tt>python20_d.dll</tt> or <tt>python15_d.dll</tt>). The Python
|
||||
sources include project files for building these. If you <a href=
|
||||
"http://www.python.org">download</a> them, change the name of the
|
||||
top-level directory to <tt>src</tt>, and install it under
|
||||
<tt>c:\tools\python</tt>, the workspace supplied by Boost.Python will
|
||||
be able to use it without modification. Just open
|
||||
<tt>c:\tools\python\src\pcbuild\pcbuild.dsw</tt> and invoke "build
|
||||
all" to generate all the debugging targets.
|
||||
<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 <tt>#include <<a href=
|
||||
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>
|
||||
If your platform isn't directly supported, you can build a static
|
||||
library from the following source files (in the Boost subdirectory
|
||||
<tt>libs/python/src</tt>), or compile them directly and link the
|
||||
resulting objects into your extension module:
|
||||
|
||||
<ul>
|
||||
<li><a href=
|
||||
"../../../libs/python/src/classes.cpp">classes.cpp</a>
|
||||
|
||||
<li><a href=
|
||||
"../../../libs/python/src/conversions.cpp">conversions.cpp</a>
|
||||
|
||||
<li><a href=
|
||||
"../../../libs/python/src/cross_module.cpp">cross_module.cpp</a>
|
||||
|
||||
<li><a href=
|
||||
"../../../libs/python/src/extension_class.cpp">extension_class.cpp</a>
|
||||
|
||||
<li><a href=
|
||||
"../../../libs/python/src/functions.cpp">functions.cpp</a>
|
||||
|
||||
<li><a href=
|
||||
"../../../libs/python/src/init_function.cpp">init_function.cpp</a>
|
||||
|
||||
<li><a href=
|
||||
"../../../libs/python/src/module_builder.cpp">module_builder.cpp</a>
|
||||
|
||||
<li><a href=
|
||||
"../../../libs/python/src/objects.cpp">objects.cpp</a>
|
||||
|
||||
<li><a href=
|
||||
"../../../libs/python/src/types.cpp">types.cpp</a>
|
||||
</ul>
|
||||
|
||||
<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 2000. Permission to copy, use, modify,
|
||||
<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: Apr 17, 2001 (R.W. Grosse-Kunstleve)
|
||||
<p>Updated: May 15, 2002 (David Abrahams)
|
||||
</div>
|
||||
|
||||
Reference in New Issue
Block a user