| <?xml version="1.0" encoding="utf-8" ?> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
| <meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" /> |
| <title>Boost C++ Libraries: Boost.Python Build and Test HOWTO</title> |
| <link rel="stylesheet" href="../../../rst.css" type="text/css" /> |
| </head> |
| <body> |
| <div class="document" id="logo-boost-python-build-and-test-howto"> |
| <h1 class="title"><a class="reference external" href="../index.html"><img alt="Boost C++ Libraries:" class="boost-logo" src="../../../boost.png" /></a> Boost.Python Build and Test HOWTO</h1> |
| |
| <!-- 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) --> |
| <div class="contents sidebar small topic" id="contents"> |
| <p class="topic-title first">Contents</p> |
| <ul class="auto-toc simple"> |
| <li><a class="reference internal" href="#requirements" id="id25">1 Requirements</a></li> |
| <li><a class="reference internal" href="#background" id="id26">2 Background</a></li> |
| <li><a class="reference internal" href="#no-install-quickstart" id="id27">3 No-Install Quickstart</a><ul class="auto-toc"> |
| <li><a class="reference internal" href="#basic-procedure" id="id28">3.1 Basic Procedure</a></li> |
| <li><a class="reference internal" href="#in-case-of-trouble" id="id29">3.2 In Case of Trouble</a></li> |
| <li><a class="reference internal" href="#in-case-everything-seemed-to-work" id="id30">3.3 In Case Everything Seemed to Work</a></li> |
| <li><a class="reference internal" href="#modifying-the-example-project" id="id31">3.4 Modifying the Example Project</a></li> |
| </ul> |
| </li> |
| <li><a class="reference internal" href="#installing-boost-python-on-your-system" id="id32">4 Installing Boost.Python on your System</a></li> |
| <li><a class="reference internal" href="#configuring-boost-build" id="id33">5 Configuring Boost.Build</a><ul class="auto-toc"> |
| <li><a class="reference internal" href="#python-configuration-parameters" id="id34">5.1 Python Configuration Parameters</a></li> |
| <li><a class="reference internal" href="#examples" id="id35">5.2 Examples</a></li> |
| </ul> |
| </li> |
| <li><a class="reference internal" href="#choosing-a-boost-python-library-binary" id="id36">6 Choosing a Boost.Python Library Binary</a><ul class="auto-toc"> |
| <li><a class="reference internal" href="#the-dynamic-binary" id="id37">6.1 The Dynamic Binary</a></li> |
| <li><a class="reference internal" href="#the-static-binary" id="id38">6.2 The Static Binary</a></li> |
| </ul> |
| </li> |
| <li><a class="reference internal" href="#include-issues" id="id39">7 <tt class="docutils literal"><span class="pre">#include</span></tt> Issues</a></li> |
| <li><a class="reference internal" href="#python-debugging-builds" id="id40">8 Python Debugging Builds</a></li> |
| <li><a class="reference internal" href="#testing-boost-python" id="id41">9 Testing Boost.Python</a></li> |
| <li><a class="reference internal" href="#notes-for-mingw-and-cygwin-with-mno-cygwin-gcc-users" id="id42">10 Notes for MinGW (and Cygwin with -mno-cygwin) GCC Users</a></li> |
| </ul> |
| </div> |
| <div class="section" id="requirements"> |
| <h1><a class="toc-backref" href="#id25">1 Requirements</a></h1> |
| <p>Boost.Python requires <a class="reference external" href="http://www.python.org/2.2">Python 2.2</a><a class="footnote-reference" href="#id22" id="id2"><sup>1</sup></a> <em>or</em> <a class="reference external" href="http://www.python.org"><em>newer</em></a>.</p> |
| </div> |
| <div class="section" id="background"> |
| <h1><a class="toc-backref" href="#id26">2 Background</a></h1> |
| <p>There are two basic models for combining C++ and Python:</p> |
| <ul class="simple"> |
| <li><a class="reference external" href="http://www.python.org/doc/current/ext/intro.html">extending</a>, in which the end-user launches the Python interpreter |
| executable and imports Python “extension modules” written in C++. |
| Think of taking a library written in C++ and giving it a Python |
| interface so Python programmers can use it. From Python, these |
| modules look just like regular Python modules.</li> |
| <li><a class="reference external" href="http://www.python.org/doc/current/ext/embedding.html">embedding</a>, in which the end-user launches a program written |
| in C++ that in turn invokes the Python interpreter as a library |
| subroutine. Think of adding scriptability to an existing |
| application.</li> |
| </ul> |
| <p>The key distinction between extending and embedding is the location |
| of the C++ <tt class="docutils literal"><span class="pre">main()</span></tt> function: in the Python interpreter executable, |
| or in some other program, respectively. Note that even when |
| embedding Python in another program, <a class="reference external" href="http://www.python.org/doc/current/ext/extending-with-embedding.html">extension modules are often |
| the best way to make C/C++ functionality accessible to Python |
| code</a>, so the use of extension modules is really at the heart of |
| both models.</p> |
| <p>Except in rare cases, extension modules are built as |
| dynamically-loaded libraries with a single entry point, which means |
| you can change them without rebuilding either the other extension |
| modules or the executable containing <tt class="docutils literal"><span class="pre">main()</span></tt>.</p> |
| </div> |
| <div class="section" id="no-install-quickstart"> |
| <span id="quickstart"></span><h1><a class="toc-backref" href="#id27">3 No-Install Quickstart</a></h1> |
| <p>There is no need to “install Boost” in order to get started using |
| Boost.Python. These instructions use <a class="reference external" href="../../../tools/build/index.html">Boost.Build</a> projects, |
| which will build those binaries as soon as they're needed. Your |
| first tests may take a little longer while you wait for |
| Boost.Python to build, but doing things this way will save you from |
| worrying about build intricacies like which library binaries to use |
| for a specific compiler configuration and figuring out the right |
| compiler options to use yourself.</p> |
| <!-- .. raw:: html |
| |
| <div style="width:50%"> --> |
| <div class="note"> |
| <p class="first admonition-title">Note</p> |
| <p>Of course it's possible to use other build systems to |
| build Boost.Python and its extensions, but they are not |
| officially supported by Boost. Moreover <strong>99% of all “I can't |
| build Boost.Python” problems come from trying to use another |
| build system</strong> without first following these instructions.</p> |
| <p>If you want to use another system anyway, we suggest that you |
| follow these instructions, and then invoke <tt class="docutils literal"><span class="pre">bjam</span></tt> with the</p> |
| <pre class="literal-block"> |
| <tt class="docutils literal"><span class="pre">-a</span> <span class="pre">-o</span></tt><em>filename</em> |
| </pre> |
| <p class="last">options to dump the build commands it executes to a file, so |
| you can see what your alternate build system needs to do.</p> |
| </div> |
| <!-- .. raw:: html |
| |
| </div> --> |
| <div class="section" id="basic-procedure"> |
| <h2><a class="toc-backref" href="#id28">3.1 Basic Procedure</a></h2> |
| <ol class="arabic"> |
| <li><p class="first">Get Boost; see sections 1 and 2 [<a class="reference external" href="../../../more/getting_started/unix-variants.html#get-boost">Unix/Linux</a>, <a class="reference external" href="../../../more/getting_started/windows.html#get-boost">Windows</a>] of the |
| Boost <a class="reference external" href="../../../more/getting_started/index.html">Getting Started Guide</a>.</p> |
| </li> |
| <li><p class="first">Get the <tt class="docutils literal"><span class="pre">bjam</span></tt> build driver. See section 5 [<a class="reference external" href="../../../more/getting_started/unix-variants.html#prepare-to-use-a-boost-library-binary">Unix/Linux</a>, |
| <a class="reference external" href="../../../more/getting_started/windows.html#prepare-to-use-a-boost-library-binary">Windows</a>] of the Boost <a class="reference external" href="../../../more/getting_started/index.html">Getting Started Guide</a>.</p> |
| </li> |
| <li><p class="first">cd into the <tt class="docutils literal"><span class="pre">libs/python/example/quickstart/</span></tt> directory of your |
| Boost installation, which contains a small example project.</p> |
| </li> |
| <li><p class="first">Invoke <tt class="docutils literal"><span class="pre">bjam</span></tt>. Replace the “<tt class="docutils literal"><span class="pre">stage</span></tt>“ argument from the |
| example invocation from section 5 of the <a class="reference external" href="../../../more/getting_started/index.html">Getting Started |
| Guide</a> with “<tt class="docutils literal"><span class="pre">test</span></tt>,“ to build all the test targets. Also add |
| the argument “<tt class="docutils literal"><span class="pre">--verbose-test</span></tt>” to see the output generated by |
| the tests when they are run.</p> |
| <p>On Windows, your <tt class="docutils literal"><span class="pre">bjam</span></tt> invocation might look something like:</p> |
| <pre class="literal-block"> |
| C:\boost_1_34_0\…\quickstart> <strong>bjam toolset=msvc --verbose-test test</strong> |
| </pre> |
| <p>and on Unix variants, perhaps,</p> |
| <pre class="literal-block"> |
| ~/boost_1_34_0/…/quickstart$ <strong>bjam toolset=gcc --verbose-test test</strong> |
| </pre> |
| </li> |
| </ol> |
| <div class="admonition-note-to-windows-users admonition"> |
| <p class="first admonition-title">Note to Windows Users</p> |
| <p class="last">For the sake of concision, the rest of this guide will use |
| unix-style forward slashes in pathnames instead of the |
| backslashes with which you may be more familiar. The forward |
| slashes should work everywhere except in <a class="reference external" href="../../../more/getting_started/windows.html#command-prompt">Command Prompt</a> |
| windows, where you should use backslashes.</p> |
| </div> |
| <p>If you followed this procedure successfully, you will have built an |
| extension module called <tt class="docutils literal"><span class="pre">extending</span></tt> and tested it by running a |
| Python script called <tt class="docutils literal"><span class="pre">test_extending.py</span></tt>. You will also have |
| built and run a simple application called <tt class="docutils literal"><span class="pre">embedding</span></tt> that embeds |
| python.</p> |
| </div> |
| <div class="section" id="in-case-of-trouble"> |
| <h2><a class="toc-backref" href="#id29">3.2 In Case of Trouble</a></h2> |
| <p>If you're seeing lots of compiler and/or linker error messages, |
| it's probably because Boost.Build is having trouble finding your |
| Python installation. You might want to pass the |
| <tt class="docutils literal"><span class="pre">--debug-configuration</span></tt> option to <tt class="docutils literal"><span class="pre">bjam</span></tt> the first few times |
| you invoke it, to make sure that Boost.Build is correctly locating |
| all the parts of your Python installation. If it isn't, consider |
| <a class="reference internal" href="#configuring-boost-build">Configuring Boost.Build</a> as detailed below.</p> |
| <p>If you're still having trouble, Someone on one of the following |
| mailing lists may be able to help:</p> |
| <ul class="simple"> |
| <li>The <a class="reference external" href="http://www.boost.org/more/mailing_lists.htm#jamboost">Boost.Build mailing list</a> for issues related to Boost.Build</li> |
| <li>The Python <a class="reference external" href="http://www.boost.org/more/mailing_lists.htm#cplussig">C++ Sig</a> for issues specifically related to Boost.Python</li> |
| </ul> |
| </div> |
| <div class="section" id="in-case-everything-seemed-to-work"> |
| <h2><a class="toc-backref" href="#id30">3.3 In Case Everything Seemed to Work</a></h2> |
| <p>Rejoice! If you're new to Boost.Python, at this point it might be |
| a good idea to ignore build issues for a while and concentrate on |
| learning the library by going through the <a class="reference external" href="tutorial/index.html">tutorial</a> and perhaps |
| some of the <a class="reference external" href="v2/reference.html">reference documentation</a>, trying out what you've |
| learned about the API by modifying the quickstart project.</p> |
| </div> |
| <div class="section" id="modifying-the-example-project"> |
| <h2><a class="toc-backref" href="#id31">3.4 Modifying the Example Project</a></h2> |
| <p>If you're content to keep your extension module forever in one |
| source file called <a class="reference external" href="../example/quickstart/extending.cpp"><tt class="docutils literal"><span class="pre">extending.cpp</span></tt></a>, inside your Boost |
| distribution, and import it forever as <tt class="docutils literal"><span class="pre">extending</span></tt>, then you can |
| stop here. However, it's likely that you will want to make a few |
| changes. There are a few things you can do without having to learn |
| <a class="reference external" href="../../../tools/build/index.html">Boost.Build</a> in depth.</p> |
| <p>The project you just built is specified in two files in the current |
| directory: <a class="reference external" href="../example/quickstart/boost-build.jam"><tt class="docutils literal"><span class="pre">boost-build.jam</span></tt></a>, which tells <tt class="docutils literal"><span class="pre">bjam</span></tt> where it can |
| find the interpreted code of the Boost build system, and |
| <a class="reference external" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a>, which describes the targets you just built. These |
| files are heavily commented, so they should be easy to modify. |
| Take care, however, to preserve whitespace. Punctuation such as |
| <tt class="docutils literal"><span class="pre">;</span></tt> will not be recognized as intended by <tt class="docutils literal"><span class="pre">bjam</span></tt> if it is not |
| surrounded by whitespace.</p> |
| <div class="section" id="relocate-the-project"> |
| <h3>Relocate the Project</h3> |
| <p>You'll probably want to copy this project elsewhere so you can |
| change it without modifying your Boost distribution. To do that, |
| simply</p> |
| <ol class="loweralpha simple"> |
| <li>copy the entire <tt class="docutils literal"><span class="pre">libs/python/example/quickstart/</span></tt> directory |
| into a new directory.</li> |
| <li>In the new copies of <a class="reference external" href="../example/quickstart/boost-build.jam"><tt class="docutils literal"><span class="pre">boost-build.jam</span></tt></a> and <a class="reference external" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a>, locate |
| the relative path near the top of the file that is clearly |
| marked by a comment, and edit that path so that it refers to the |
| same directory your Boost distribution as it referred to when |
| the file was in its original location in the |
| <tt class="docutils literal"><span class="pre">libs/python/example/quickstart/</span></tt> directory.</li> |
| </ol> |
| <p>For example, if you moved the project from |
| <tt class="docutils literal"><span class="pre">/home/dave/boost_1_34_0/libs/python/example/quickstart</span></tt> to |
| <tt class="docutils literal"><span class="pre">/home/dave/my-project</span></tt>, you could change the first path in |
| <a class="reference external" href="../example/quickstart/boost-build.jam"><tt class="docutils literal"><span class="pre">boost-build.jam</span></tt></a> from</p> |
| <pre class="literal-block"> |
| <strong>../../../..</strong>/tools/build/v2 |
| </pre> |
| <p>to</p> |
| <pre class="literal-block"> |
| <strong>/home/dave/boost_1_34_0</strong>/tools/build/v2 |
| </pre> |
| <p>and change the first path in <a class="reference external" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a> from</p> |
| <pre class="literal-block"> |
| <strong>../../../..</strong> |
| </pre> |
| <p>to</p> |
| <pre class="literal-block"> |
| <strong>/home/dave/boost_1_34_0</strong> |
| </pre> |
| </div> |
| <div class="section" id="add-new-or-change-names-of-existing-source-files"> |
| <h3>Add New or Change Names of Existing Source Files</h3> |
| <p>The names of additional source files involved in building your |
| extension module or embedding application can be listed in |
| <a class="reference external" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a> right alongside <tt class="docutils literal"><span class="pre">extending.cpp</span></tt> or <tt class="docutils literal"><span class="pre">embedding.cpp</span></tt> |
| respectively. Just be sure to leave whitespace around each |
| filename:</p> |
| <pre class="literal-block"> |
| … file1.cpp file2.cpp file3.cpp … |
| </pre> |
| <p>Naturally, if you want to change the name of a source file you can |
| tell Boost.Build about it by editing the name in <a class="reference external" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a>.</p> |
| </div> |
| <div class="section" id="change-the-name-of-your-extension-module"> |
| <h3>Change the Name of your Extension Module</h3> |
| <p>The name of the extension module is determined by two things:</p> |
| <ol class="arabic simple"> |
| <li>the name in <a class="reference external" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a> immediately following <tt class="docutils literal"><span class="pre">python-extension</span></tt>, and</li> |
| <li>the name passed to <tt class="docutils literal"><span class="pre">BOOST_PYTHON_MODULE</span></tt> in <a class="reference external" href="../example/quickstart/extending.cpp"><tt class="docutils literal"><span class="pre">extending.cpp</span></tt></a>.</li> |
| </ol> |
| <p>To change the name of the extension module from <tt class="docutils literal"><span class="pre">extending</span></tt> to |
| <tt class="docutils literal"><span class="pre">hello</span></tt>, you'd edit <a class="reference external" href="../example/quickstart/Jamroot"><tt class="docutils literal"><span class="pre">Jamroot</span></tt></a>, changing</p> |
| <pre class="literal-block"> |
| python-extension <strong>extending</strong> : extending.cpp ; |
| </pre> |
| <p>to</p> |
| <pre class="literal-block"> |
| python-extension <strong>hello</strong> : extending.cpp ; |
| </pre> |
| <p>and you'd edit extending.cpp, changing</p> |
| <pre class="literal-block"> |
| BOOST_PYTHON_MODULE(<strong>extending</strong>) |
| </pre> |
| <p>to</p> |
| <pre class="literal-block"> |
| BOOST_PYTHON_MODULE(<strong>hello</strong>) |
| </pre> |
| </div> |
| </div> |
| </div> |
| <div class="section" id="installing-boost-python-on-your-system"> |
| <h1><a class="toc-backref" href="#id32">4 Installing Boost.Python on your System</a></h1> |
| <p>Since Boost.Python is a separately-compiled (as opposed to |
| <a class="reference external" href="../../../more/getting_started/windows.html#header-only-libraries">header-only</a>) library, its user relies on the services of a |
| Boost.Python library binary.</p> |
| <p>If you need a regular installation of the Boost.Python library |
| binaries on your system, the Boost <a class="reference external" href="../../../more/getting_started/index.html">Getting Started Guide</a> will |
| walk you through the steps of creating one. If building binaries |
| from source, you might want to supply the <tt class="docutils literal"><span class="pre">--with-python</span></tt> |
| argument to <tt class="docutils literal"><span class="pre">bjam</span></tt> (or the <tt class="docutils literal"><span class="pre">--with-libraries=python</span></tt> argument |
| to <tt class="docutils literal"><span class="pre">configure</span></tt>), so only the Boost.Python binary will be built, |
| rather than all the Boost binaries.</p> |
| </div> |
| <div class="section" id="configuring-boost-build"> |
| <h1><a class="toc-backref" href="#id33">5 Configuring Boost.Build</a></h1> |
| <p>As described in the <a class="reference external" href="http://www.boost.orgdoc/html/bbv2/advanced.html#bbv2.advanced.configuration">Boost.Build reference manual</a>, a file called |
| <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> in your home directory<a class="footnote-reference" href="#home-dir" id="id11"><sup>6</sup></a> is used to |
| specify the tools and libraries available to the build system. You |
| may need to create or edit <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> to tell Boost.Build |
| how to invoke Python, <tt class="docutils literal"><span class="pre">#include</span></tt> its headers, and link with its |
| libraries.</p> |
| <div class="admonition-users-of-unix-variant-oses admonition"> |
| <p class="first admonition-title">Users of Unix-Variant OSes</p> |
| <p class="last">If you are using a unix-variant OS and you ran Boost's |
| <tt class="docutils literal"><span class="pre">configure</span></tt> script, it may have generated a |
| <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> for you.<a class="footnote-reference" href="#overwrite" id="id13"><sup>4</sup></a> If your <tt class="docutils literal"><span class="pre">configure</span></tt>/<tt class="docutils literal"><span class="pre">make</span></tt> sequence was successful and Boost.Python binaries |
| were built, your <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> file is probably already |
| correct.</p> |
| </div> |
| <p>If you have one fairly “standard” python installation for your |
| platform, you might not need to do anything special to describe it. If |
| you haven't configured python in <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> (and you don't |
| specify <tt class="docutils literal"><span class="pre">--without-python</span></tt> on the Boost.Build command line), |
| Boost.Build will automatically execute the equivalent of</p> |
| <pre class="literal-block"> |
| import toolset : using ; |
| using python ; |
| </pre> |
| <p>which automatically looks for Python in the most likely places. |
| However, that only happens when using the Boost.Python project file |
| (e.g. when referred to by another project as in the <a class="reference internal" href="#quickstart">quickstart</a> |
| method). If instead you are linking against separately-compiled |
| Boost.Python binaries, you should set up a <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> file |
| with at least the minimal incantation above.</p> |
| <div class="section" id="python-configuration-parameters"> |
| <h2><a class="toc-backref" href="#id34">5.1 Python Configuration Parameters</a></h2> |
| <p>If you have several versions of Python installed, or Python is |
| installed in an unusual way, you may want to supply any or all of |
| the following optional parameters to <tt class="docutils literal"><span class="pre">using</span> <span class="pre">python</span></tt>.</p> |
| <dl class="docutils"> |
| <dt>version</dt> |
| <dd>the version of Python to use. Should be in Major.Minor |
| format, for example, <tt class="docutils literal"><span class="pre">2.3</span></tt>. Do not include the subminor |
| version (i.e. <em>not</em> <tt class="docutils literal"><span class="pre">2.5.1</span></tt>). If you have multiple Python |
| versions installed, the version will usually be the only |
| configuration argument required.</dd> |
| <dt>cmd-or-prefix</dt> |
| <dd>preferably, a command that invokes a Python interpreter. |
| Alternatively, the installation prefix for Python libraries and |
| header files. Only use the alternative formulation if there is |
| no appropriate Python executable available.</dd> |
| <dt>includes</dt> |
| <dd>the <tt class="docutils literal"><span class="pre">#include</span></tt> paths for Python headers. Normally the correct |
| path(s) will be automatically deduced from <tt class="docutils literal"><span class="pre">version</span></tt> and/or |
| <tt class="docutils literal"><span class="pre">cmd-or-prefix</span></tt>.</dd> |
| <dt>libraries</dt> |
| <dd>the path to Python library binaries. On MacOS/Darwin, |
| you can also pass the path of the Python framework. Normally the |
| correct path(s) will be automatically deduced from <tt class="docutils literal"><span class="pre">version</span></tt> |
| and/or <tt class="docutils literal"><span class="pre">cmd-or-prefix</span></tt>.</dd> |
| <dt>condition</dt> |
| <dd>if specified, should be a set of Boost.Build |
| properties that are matched against the build configuration when |
| Boost.Build selects a Python configuration to use. See examples |
| below for details.</dd> |
| <dt>extension-suffix</dt> |
| <dd>A string to append to the name of extension |
| modules before the true filename extension. You almost certainly |
| don't need to use this. Usually this suffix is only used when |
| targeting a Windows debug build of Python, and will be set |
| automatically for you based on the value of the |
| <a class="reference internal" href="#python-debugging"><tt class="docutils literal"><span class="pre"><python-debugging></span></tt></a> feature. However, at least one Linux |
| distribution (Ubuntu Feisty Fawn) has a specially configured |
| <a class="reference external" href="https://wiki.ubuntu.com/PyDbgBuilds">python-dbg</a> package that claims to use such a suffix.</dd> |
| </dl> |
| </div> |
| <div class="section" id="examples"> |
| <h2><a class="toc-backref" href="#id35">5.2 Examples</a></h2> |
| <p>Note that in the examples below, case and <em>especially whitespace</em> are |
| significant.</p> |
| <ul> |
| <li><p class="first">If you have both python 2.5 and python 2.4 installed, |
| <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> might contain:</p> |
| <pre class="literal-block"> |
| using python : 2.5 ; # Make both versions of Python available |
| |
| using python : 2.4 ; # To build with python 2.4, add python=2.4 |
| # to your command line. |
| </pre> |
| <p>The first version configured (2.5) becomes the default. To build |
| against python 2.4, add <tt class="docutils literal"><span class="pre">python=2.4</span></tt> to the <tt class="docutils literal"><span class="pre">bjam</span></tt> command line.</p> |
| </li> |
| <li><p class="first">If you have python installed in an unusual location, you might |
| supply the path to the interpreter in the <tt class="docutils literal"><span class="pre">cmd-or-prefix</span></tt> |
| parameter:</p> |
| <pre class="literal-block"> |
| using python : : /usr/local/python-2.6-beta/bin/python ; |
| </pre> |
| </li> |
| <li><p class="first">If you have a separate build of Python for use with a particular |
| toolset, you might supply that toolset in the <tt class="docutils literal"><span class="pre">condition</span></tt> |
| parameter:</p> |
| <pre class="literal-block"> |
| using python ; # use for most toolsets |
| |
| # Use with Intel C++ toolset |
| using python |
| : # version |
| : c:\\Devel\\Python-2.5-IntelBuild\\PCBuild\\python # cmd-or-prefix |
| : # includes |
| : # libraries |
| : <toolset>intel # condition |
| ; |
| </pre> |
| </li> |
| <li><p class="first">If you have downloaded the Python sources and built both the |
| normal and the “<a class="reference internal" href="#id19">python debugging</a>” builds from source on |
| Windows, you might see:</p> |
| <pre class="literal-block"> |
| using python : 2.5 : C:\\src\\Python-2.5\\PCBuild\\python ; |
| using python : 2.5 : C:\\src\\Python-2.5\\PCBuild\\python_d |
| : # includes |
| : # libs |
| : <python-debugging>on ; |
| </pre> |
| </li> |
| <li><p class="first">You can set up your user-config.jam so a bjam built under Windows |
| can build/test both Windows and <a class="reference external" href="http://cygwin.com">Cygwin</a> python extensions. Just pass |
| <tt class="docutils literal"><span class="pre"><target-os>cygwin</span></tt> in the <tt class="docutils literal"><span class="pre">condition</span></tt> parameter |
| for the cygwin python installation:</p> |
| <pre class="literal-block"> |
| # windows installation |
| using python ; |
| |
| # cygwin installation |
| using python : : c:\\cygwin\\bin\\python2.5 : : : <target-os>cygwin ; |
| </pre> |
| <p>when you put target-os=cygwin in your build request, it should build |
| with the cygwin version of python:<a class="footnote-reference" href="#flavor" id="id15"><sup>5</sup></a></p> |
| <blockquote> |
| <p>bjam target-os=cygwin toolset=gcc</p> |
| </blockquote> |
| <p>This is supposed to work the other way, too (targeting windows |
| python with a <a class="reference external" href="http://cygwin.com">Cygwin</a> bjam) but it seems as though the support in |
| Boost.Build's toolsets for building that way is broken at the |
| time of this writing.</p> |
| </li> |
| <li><p class="first">Note that because of <a class="reference external" href="http://zigzag.cs.msu.su/boost.build/wiki/AlternativeSelection">the way Boost.Build currently selects target |
| alternatives</a>, you might have be very explicit in your build |
| requests. For example, given:</p> |
| <pre class="literal-block"> |
| using python : 2.5 ; # a regular windows build |
| using python : 2.4 : : : : <target-os>cygwin ; |
| </pre> |
| <p>building with</p> |
| <pre class="literal-block"> |
| bjam target-os=cygwin |
| </pre> |
| <p>will yield an error. Instead, you'll need to write:</p> |
| <pre class="literal-block"> |
| bjam target-os=cygwin/python=2.4 |
| </pre> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="section" id="choosing-a-boost-python-library-binary"> |
| <h1><a class="toc-backref" href="#id36">6 Choosing a Boost.Python Library Binary</a></h1> |
| <p>If—instead of letting Boost.Build construct and link with the right |
| libraries automatically—you choose to use a pre-built Boost.Python |
| library, you'll need to think about which one to link with. The |
| Boost.Python binary comes in both static and dynamic flavors. Take |
| care to choose the right flavor for your application.<a class="footnote-reference" href="#naming" id="id17"><sup>2</sup></a></p> |
| <div class="section" id="the-dynamic-binary"> |
| <h2><a class="toc-backref" href="#id37">6.1 The Dynamic Binary</a></h2> |
| <p>The dynamic library is the safest and most-versatile choice:</p> |
| <ul class="simple"> |
| <li>A single copy of the library code is used by all extension |
| modules built with a given toolset.<a class="footnote-reference" href="#toolset-specific" id="id18"><sup>3</sup></a></li> |
| <li>The library contains a type conversion registry. Because one |
| registry is shared among all extension modules, instances of a |
| class exposed to Python in one dynamically-loaded extension |
| module can be passed to functions exposed in another such module.</li> |
| </ul> |
| </div> |
| <div class="section" id="the-static-binary"> |
| <h2><a class="toc-backref" href="#id38">6.2 The Static Binary</a></h2> |
| <p>It might be appropriate to use the static Boost.Python library in |
| any of the following cases:</p> |
| <ul class="simple"> |
| <li>You are <a class="reference external" href="http://www.python.org/doc/current/ext/intro.html">extending</a> python and the types exposed in your |
| dynamically-loaded extension module don't need to be used by any |
| other Boost.Python extension modules, and you don't care if the |
| core library code is duplicated among them.</li> |
| <li>You are <a class="reference external" href="http://www.python.org/doc/current/ext/embedding.html">embedding</a> python in your application and either:<ul> |
| <li>You are targeting a Unix variant OS other than MacOS or AIX, |
| where the dynamically-loaded extension modules can “see” the |
| Boost.Python library symbols that are part of the executable.</li> |
| <li>Or, you have statically linked some Boost.Python extension |
| modules into your application and you don't care if any |
| dynamically-loaded Boost.Python extension modules are able to |
| use the types exposed by your statically-linked extension |
| modules (and vice-versa).</li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="section" id="include-issues"> |
| <h1><a class="toc-backref" href="#id39">7 <tt class="docutils literal"><span class="pre">#include</span></tt> Issues</a></h1> |
| <ol class="arabic simple"> |
| <li>If you should ever have occasion to <tt class="docutils literal"><span class="pre">#include</span> <span class="pre">"python.h"</span></tt> |
| directly in a translation unit of a program using Boost.Python, |
| use <tt class="docutils literal"><span class="pre">#include</span> <span class="pre">"boost/python/detail/wrap_python.hpp"</span></tt> instead. |
| It handles several issues necessary for use with Boost.Python, |
| one of which is mentioned in the next section.</li> |
| <li>Be sure not to <tt class="docutils literal"><span class="pre">#include</span></tt> any system headers before |
| <tt class="docutils literal"><span class="pre">wrap_python.hpp</span></tt>. This restriction is actually imposed by |
| Python, or more properly, by Python's interaction with your |
| operating system. See |
| <a class="reference external" href="http://docs.python.org/ext/simpleExample.html">http://docs.python.org/ext/simpleExample.html</a> for details.</li> |
| </ol> |
| </div> |
| <div class="section" id="python-debugging-builds"> |
| <span id="id19"></span><span id="python-debugging"></span><h1><a class="toc-backref" href="#id40">8 Python Debugging Builds</a></h1> |
| <p>Python can be built in a special “python debugging” configuration |
| that adds extra checks and instrumentation that can be very useful |
| for developers of extension modules. The data structures used by |
| the debugging configuration contain additional members, so <strong>a |
| Python executable built with python debugging enabled cannot be |
| used with an extension module or library compiled without it, and |
| vice-versa.</strong></p> |
| <p>Since pre-built “python debugging” versions of the Python |
| executable and libraries are not supplied with most distributions |
| of Python,<a class="footnote-reference" href="#get-debug-build" id="id20"><sup>7</sup></a> and we didn't want to force our users |
| to build them, Boost.Build does not automatically enable python |
| debugging in its <tt class="docutils literal"><span class="pre">debug</span></tt> build variant (which is the default). |
| Instead there is a special build property called |
| <tt class="docutils literal"><span class="pre">python-debugging</span></tt> that, when used as a build property, will |
| define the right preprocessor symbols and select the right |
| libraries to link with.</p> |
| <p>On unix-variant platforms, the debugging versions of Python's data |
| structures will only be used if the symbol <tt class="docutils literal"><span class="pre">Py_DEBUG</span></tt> is defined. |
| On many windows compilers, when extension modules are built with |
| the preprocessor symbol <tt class="docutils literal"><span class="pre">_DEBUG</span></tt>, Python defaults to force |
| linking with a special debugging version of the Python DLL. Since |
| that symbol is very commonly used even when Python is not present, |
| Boost.Python temporarily undefines _DEBUG when Python.h |
| is #included from <tt class="docutils literal"><span class="pre">boost/python/detail/wrap_python.hpp</span></tt> - unless |
| <tt class="docutils literal"><span class="pre">BOOST_DEBUG_PYTHON</span></tt> is defined. The upshot is that if you want |
| “python debugging”and you aren't using Boost.Build, you should make |
| sure <tt class="docutils literal"><span class="pre">BOOST_DEBUG_PYTHON</span></tt> is defined, or python debugging will be |
| suppressed.</p> |
| </div> |
| <div class="section" id="testing-boost-python"> |
| <h1><a class="toc-backref" href="#id41">9 Testing Boost.Python</a></h1> |
| <p>To run the full test suite for Boost.Python, invoke <tt class="docutils literal"><span class="pre">bjam</span></tt> in the |
| <tt class="docutils literal"><span class="pre">libs/python/test</span></tt> subdirectory of your Boost distribution.</p> |
| </div> |
| <div class="section" id="notes-for-mingw-and-cygwin-with-mno-cygwin-gcc-users"> |
| <h1><a class="toc-backref" href="#id42">10 Notes for MinGW (and Cygwin with -mno-cygwin) GCC Users</a></h1> |
| <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 class="reference external" href="http://www.python.org/doc/current/inst/index.html">Installing |
| Python Modules</a> to create <tt class="docutils literal"><span class="pre">libpythonXX.a</span></tt>, where <tt class="docutils literal"><span class="pre">XX</span></tt> |
| corresponds to the major and minor version numbers of your Python |
| installation.</p> |
| <hr class="docutils" /> |
| <table class="docutils footnote" frame="void" id="id22" rules="none"> |
| <colgroup><col class="label" /><col /></colgroup> |
| <tbody valign="top"> |
| <tr><td class="label"><a class="fn-backref" href="#id2">[1]</a></td><td>Note that although we tested earlier versions of |
| Boost.Python with Python 2.2, and we don't <em>think</em> we've done |
| anything to break compatibility, this release of Boost.Python |
| may not have been tested with versions of Python earlier than |
| 2.4, so we're not 100% sure that python 2.2 and 2.3 are |
| supported.</td></tr> |
| </tbody> |
| </table> |
| <table class="docutils footnote" frame="void" id="naming" rules="none"> |
| <colgroup><col class="label" /><col /></colgroup> |
| <tbody valign="top"> |
| <tr><td class="label"><a class="fn-backref" href="#id17">[2]</a></td><td><p class="first">Information about how to identify the |
| static and dynamic builds of Boost.Python:</p> |
| <ul class="simple"> |
| <li><a class="reference external" href="../../../more/getting_started/windows.html#library-naming">on Windows</a></li> |
| <li><a class="reference external" href="../../../more/getting_started/unix-variants.html#library-naming">on Unix variants</a></li> |
| </ul> |
| </td></tr> |
| </tbody> |
| </table> |
| <table class="docutils footnote" frame="void" id="toolset-specific" rules="none"> |
| <colgroup><col class="label" /><col /></colgroup> |
| <tbody valign="top"> |
| <tr><td class="label"><a class="fn-backref" href="#id18">[3]</a></td><td>Because of the way most *nix platforms |
| share symbols among dynamically-loaded objects, I'm not certain |
| that extension modules built with different compiler toolsets |
| will always use different copies of the Boost.Python library |
| when loaded into the same Python instance. Not using different |
| libraries could be a good thing if the compilers have compatible |
| ABIs, because extension modules built with the two libraries |
| would be interoperable. Otherwise, it could spell disaster, |
| since an extension module and the Boost.Python library would |
| have different ideas of such things as class layout. I would |
| appreciate someone doing the experiment to find out what |
| happens.</td></tr> |
| </tbody> |
| </table> |
| <table class="docutils footnote" frame="void" id="overwrite" rules="none"> |
| <colgroup><col class="label" /><col /></colgroup> |
| <tbody valign="top"> |
| <tr><td class="label"><a class="fn-backref" href="#id13">[4]</a></td><td><tt class="docutils literal"><span class="pre">configure</span></tt> overwrites the existing |
| <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> in your home directory |
| (if any) after making a backup of the old version.</td></tr> |
| </tbody> |
| </table> |
| <table class="docutils footnote" frame="void" id="flavor" rules="none"> |
| <colgroup><col class="label" /><col /></colgroup> |
| <tbody valign="top"> |
| <tr><td class="label"><a class="fn-backref" href="#id15">[5]</a></td><td>Note that the <tt class="docutils literal"><span class="pre"><target-os>cygwin</span></tt> feature is |
| different from the <tt class="docutils literal"><span class="pre"><flavor>cygwin</span></tt> subfeature of the <tt class="docutils literal"><span class="pre">gcc</span></tt> |
| toolset, and you might need handle both explicitly if you also |
| have a MinGW GCC installed.</td></tr> |
| </tbody> |
| </table> |
| <table class="docutils footnote" frame="void" id="home-dir" rules="none"> |
| <colgroup><col class="label" /><col /></colgroup> |
| <tbody valign="top"> |
| <tr><td class="label"><a class="fn-backref" href="#id11">[6]</a></td><td><p class="first">Windows users, your home directory can be |
| found by typing:</p> |
| <pre class="literal-block"> |
| ECHO %HOMEDRIVE%%HOMEPATH% |
| </pre> |
| <p class="last">into a <a class="reference external" href="../../../more/getting_started/windows.html#command-prompt">command prompt</a> window.</p> |
| </td></tr> |
| </tbody> |
| </table> |
| <table class="docutils footnote" frame="void" id="get-debug-build" rules="none"> |
| <colgroup><col class="label" /><col /></colgroup> |
| <tbody valign="top"> |
| <tr><td class="label"><a class="fn-backref" href="#id20">[7]</a></td><td>On Unix and similar platforms, a debugging |
| python and associated libraries are built by adding |
| <tt class="docutils literal"><span class="pre">--with-pydebug</span></tt> when configuring the Python build. On |
| Windows, the debugging version of Python is generated by |
| the "Win32 Debug" target of the Visual Studio project in the |
| PCBuild subdirectory of a full Python source code distribution. |
| </td></tr> |
| </tbody> |
| </table> |
| </div> |
| </div> |
| <div class="footer"> |
| <hr class="footer" /> |
| <a class="reference external" href="./building.rst">View document source</a>. |
| Generated on: 2007-07-02 13:46 UTC. |
| Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source. |
| |
| </div> |
| </body> |
| </html> |