boost/python
2
0
Fork 0
mirror of https://github.com/boostorg/python.git synced 2026-01-20 16:52:15 +00:00
Code Issues Projects Releases Wiki Activity
Files
49d4aac8ec00a0eee4232402a97c1da5cf5560e8
python/doc/building.html
Dave Abrahams 1d65b74273 Add missing license/copyright 
[SVN r35070]
2006-09-11 22:27:29 +00:00

464 lines
19 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
<!-- Software License, Version 1.0. (See accompanying -->
<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
<html>
<head>
<meta name="generator" content=
"HTML Tidy for Cygwin (vers 1st April 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="../../../boost.png" border="0"></a></h3>
</td>
<td valign="top">
<h1 align="center"><a href="index.html">Boost.Python</a></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="#cygwin_configuration">Configuration for Cygwin GCC
from a Windows prompt</a></dt>
<dt><a href="#results">Results</a></dt>
<dt><a href="#cygwin">Notes for Cygwin GCC Users</a></dt>
<dt><a href="#mingw">Notes for MinGW (and Cygwin with -mno-cygwin)
GCC Users</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>
<dt><a href="#VisualStudio">Building Using the Microsoft Visual Studio
IDE</a></dt>
</dl>
<hr>
<h2><a name="requirements">Requirements</a></h2>
<b>Boost.Python</b> version 2 requires <a href=
"http://www.python.org/2.2">Python 2.2</a> <i>or <a href=
"http://www.python.org">newer</a></i>. An unsupported archive of
Boost.Python version 1, which works with versions of Python since 1.5.2,
is available <a href="../build/python_v1.zip">here</a>.
<h2><a name="building">Building Boost.Python</a></h2>
<p>Normally, Boost.Python extension modules must be linked with the
<code>boost_python</code> shared library. In special circumstances you
may want to link to a static version of the <code>boost_python</code>
library, but if multiple Boost.Python extension modules are used
together, it will prevent sharing of types across extension modules, and
consume extra code space. To build <code>boost_python</code>, use <a
href="../../../tools/build/v1/build_system.htm">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">Basic Configuration</a></h3> You may
need to configure the following variables to point Boost.Build at
your Python installation. Variables can be either set in the
environment or passed on the <code>bjam</code> command-line
as <code>-s</code><i>name</i><code>=</code><i>value</i>. Variable
names are case-sensitive.
<table border="1" summary="build configuration variables">
<tr>
<th>Variable Name</th>
<th>Semantics</th>
<th>Default</th>
<th>Notes</th>
</tr>
<tr>
<tr>
<td><code>PYTHON_VERSION</code></td>
<td>The The 2-part python Major.Minor version number</td>
<td><code>2.4</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>
<td><code>PYTHON_ROOT</code></td>
<td>The root directory of your Python installation</td>
<td>Windows:&nbsp;<code>c:/Python</code><i>(10*Version)</i>, e.g. <code>c:/Python24</code>
<br>
*nix/Cygwin:&nbsp;<code>/usr</code></td>
<td>On *nix, this should be the <code>--prefix=</code> directory used
to configure Python when it was built and installed.</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>. Try the default
before attempting to set it yourself.</td>
</tr>
<tr>
<td><code>PYTHON_LIB_PATH</code></td>
<td>path to Python library object.</td>
<td>Autoconfigured from <code>PYTHON_ROOT</code>. Try the default
before attempting to set it yourself.</td>
</tr>
</table>
<h3><a name="cygwin_configuration">Configuration for Cygwin GCC from a
Windows prompt</a></h3>
The following settings may be useful when building with <a href=
"http://www.cygwin.com">Cygwin</a> GCC (not MinGW) from a Windows command
shell using a Windows build of <code>bjam</code>. <b>If
"<code>bjam&nbsp;-v</code>" does not report "<code>OS=NT</code>", these
settings do not apply to you</b>; you should use the <a href=
"#configuration">normal configuration</a> variables instead. They are
only useful when building and testing with multiple toolsets on Windows
using a single build command, since Cygwin GCC requires a different build
of Python.
<table border="1" summary=
"Cygwin GCC under NT build configuration variables">
<tr>
<th>Variable Name</th>
<th>Semantics</th>
<th>Default</th>
</tr>
<tr>
<td><code>CYGWIN_PYTHON_[DEBUG_]VERSION</code></td>
<td>The version of python being used under Cygwin.</td>
<td>$(PYTHON_VERSION)</td>
</tr>
<tr>
<td><code>CYGWIN_PYTHON_[DEBUG_]ROOT</code></td>
<td>*nix-style path containing the <code>include/</code> directory
containing
<code>python$(CYGWIN_PYTHON_[DEBUG_]VERSION)/python.h</code>.</td>
<td>$(PYTHON_ROOT)</td>
</tr>
<tr>
<td><code>CYGWIN_PYTHON_[DEBUG_]LIB_PATH</code></td>
<td>path containing the user's Cygwin Python import lib
<code>libpython$(CYGWIN_PYTHON_[DEBUG_]VERSION).dll.a</code></td>
<td>Autoconfigured from <code>CYGWIN_PYTHON_ROOT</code></td>
</tr>
<tr>
<td><code>CYGWIN_PYTHON_[DEBUG_]DLL_PATH</code></td>
<td>path containing the user's Cygwin Python dll
(<code>libpython$(CYGWIN_PYTHON_[DEBUG_]VERSION).dll</code>)</td>
<td><code>/bin</code></td>
</tr>
</table>
<h3><a name="cygwin">Notes for Cygwin GCC Users</a></h3>
<p>If you are using Cygwin GCC to build extension modules, you must use a
Cygwin build of Python. The regular Win32 Python installation that you
can download from <a href="http://www.python.org">python.org</a> will not
work with your compiler because the dynamic linking conventions are
different (you can use <a href="http://www.mingw.org/">MinGW</a> GCC if
you want to build extension modules which are compatible with a stock
Win32 Python). The Cygwin installer may be able to install an appropriate
version of Python, or you can follow the traditional <a href=
"http://www.python.org/download/download_source.html">Unix installation
process</a> to build Python from source.</p>
<p>The special build configuration variables listed <a href=
"#cygwin_configuration">above</a> make it possible to use a regular Win32
build of bjam to build and test Boost.Python and Boost.Python extensions
using Cygwin GCC and targeting a Cygwin build of Python.</p>
<h3><a name="mingw">Notes for MinGW (and Cygwin with -mno-cygwin) GCC
Users</a></h3>
<p>If you are using a version of Python prior to 2.4.1 with a
MinGW prior to 3.0.0 (with binutils-2.13.90-20030111-1), you will
need to create a MinGW-compatible version of the Python library;
the one shipped with Python will only work with a
Microsoft-compatible linker. Follow the instructions in the
"Non-Microsoft" section of the "Building Extensions: Tips And Tricks"
chapter in <a href=
"http://www.python.org/doc/current/inst/index.html">Installing Python
Modules</a> to create <code>libpythonXX.a</code>, where <code>XX</code>
corresponds to the major and minor version numbers of your Python
installation.</p>
<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=
"../../../more/getting_started.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 verbose by default. To get less-verbose output, you
might try
<blockquote>
<pre>
bjam -sTOOLS=<i><a href=
"../../../more/getting_started.html#Tools">toolset</a></i> -sPYTHON_TEST_ARGS= test
</pre>
</blockquote>
By default, <code>PYTHON_TEST_ARGS</code> is set to <code>-v</code>.
<h2><a name="building_ext">Building your Extension Module</a></h2>
Though there are other approaches, the smoothest and most reliable way to
build an extension module using Boost.Python is with Boost.Build. If you
have to use another build system, you should use Boost.Build at least
once with the "<code><b>-n</b></code>" option so you can see the
command-lines it uses, and replicate them. You are likely to run into
compilation or linking problems otherwise.
<p>The files required to build a Boost.Python extension module using bjam
are the "local" files <tt>Jamfile</tt>, <tt>Jamrules</tt>, and
<tt>boost_build.jam</tt>, and the <tt>boost/</tt>
and <tt>tools/build/v1/</tt> subdirectories of your Boost
tree. The latter directory contains the source code of the
Boost.Build system, which is used to generate the correct build
commands for your extension module. The '<tt>v1</tt>' refers to
Boost.Build version 1. Version 2 is pre-release and currently not
ready for general use.
<p>
The <tt>libs/python/example/</tt> project we're going to build is
set up to automatically rebuild the Boost.Python library in place
whenever it's out-of-date rather than just reusing an existing
library, so you'll also need the Boost.Python library sources in
<tt>boost/python/src/</tt>.
</p>
<blockquote>
<b>Note:</b> Third-party package and distribution maintainers
for various operating systems sometimes split up Boost's
structure or omit parts of it, so if you didn't download an
official <a href=
"http://sourceforge.net/project/showfiles.php?group_id=7586">Boost
release</a> you might want to <a href=
"http://cvs.sourceforge.net/viewcvs.py/boost/boost/">browse our CVS
structure</a> to make sure you have everything you need, and in the
right places.
</blockquote>
<p>The <code>libs/python/example</code>
subdirectory of your boost installation contains a small example which
builds and tests two extensions. To build your own extensions copy the
example subproject and make the following two edits:</p>
<ol>
<li>
<code><a href=
"../example/boost-build.jam"><b>boost-build.jam</b></a></code> - edit
the line which reads
<blockquote>
<pre>
boost-build ../../../tools/build/v1 ;
</pre>
</blockquote>
so that the path refers to the <code>tools/build/v1</code>
subdirectory of your Boost installation.
</li>
<li>
<code><a href="../example/Jamrules"><b>Jamrules</b></a></code> - edit
the line which reads
<blockquote>
<pre>
path-global BOOST_ROOT : ../../.. ;
</pre>
</blockquote>
so that the path refers to the root directory of your Boost
installation.
</li>
</ol>
<p>The instructions <a href="#testing">above</a> for testing Boost.Python
apply equally to your new extension modules in this subproject.</p>
<h2><a name="variants">Build Variants</a></h2>
Three <a href=
"../../../tools/build/v1/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/v1/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 *nix 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&nbsp;&lt;<a href=
"../../../boost/python/detail/wrap_python.hpp">boost/python/detail/wrap_python.hpp</a>&gt;</tt>
instead of the usual <tt>Python.h</tt>, or you will have link
incompatibilities.<br>
</p>
<h2><a name="VisualStudio">Building Using the Microsoft Visual Studio
IDE</a></h2>
<p>For the those of you who feel more comfortable in the IDE world, a
workspace and project file have been included in the <code>
libs/python/build/VisualStudio</code> subdirectory.
It builds release and debug versions of the Boost.Python libraries and
places them and the same directory as Jamfile build does, though the
intermediate object files are placed in a different directory. The files
have been created using Microsoft Visual C++ version 6, but they should
work for later versions as well. You will need to tell the IDE where to
find the Python <code>Include/</code> and <code>Libs/</code> directories.
Under <b>Tools&gt;Options&gt;Directories</b>, add an entry for the Python
include dir (i.e. <code>c:/Python22/Include</code>), and one for the Lib
(i.e. <code>c:/Python/Libs</code>. Make sure it is <code>Libs</code> with
an "<code>s</code>" and not just <code>Lib</code>).</p>
<h3>Using the IDE for your own projects</h3>
<p>Building your own projects using the IDE is slightly more complicated.
Firstly, you need to make sure that the project you create as the right
kind. It should be a "Win32 Dynamic-Link Library". The default one that
Visual Studio 6 creates needs some modifications: turn on RTTI, and
change the debug and release builds to use the respective debug and
release Multithreaded DLL versions. You should probably turn off
incremental linking too -- I believe it a bit flaky. If you do this, then
change the "Debug Info" to "Program Database" to get rid of the Edit and
Continue warning.</p>
<p>You'll need to add the Boost root directory under
<b>Tools&gt;Options&gt;Directories</b> to get your code compiling. To
make it link, add the above <code>boost_python.dsp</code> file to your
workspace, and make your project depend upon it (under
<b>Project&gt;Dependencies</b>). You should be able to build now.</p>
<p>Lastly, go to the <b>Project Settings&gt;Debug</b> Page and add the
<code>Python.exe</code> as the executable for the project. Set a startup
directory, and make sure that your current project's output dll, the
<code>boost_python.dll</code> and the <code>python22.dll</code> are on
the current <code>PATH</code>. If you have a python script that tests
your dll, then add it in the "Program Arguments". Now, if all went well,
you should be able to hit the Run (F5) button, and debug your code.</p>
<blockquote>
<em>The Visual Studio project files are graciously contributed and
maintained by <a href="mailto:brett.calcott@gmail.com">Brett
Calcott</a></em>.
</blockquote>
<hr>
<p>&copy; Copyright David Abrahams 2002-2004. 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: 13 April 2004 (David Abrahams)</p>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink