|
| 1 | +<html> |
| 2 | +<head> |
| 3 | +<!-- Generated by the Spirit (http://spirit.sf.net) QuickDoc --> |
| 4 | +<title>Building an Extension Module </title> |
| 5 | +<link rel="stylesheet" href="theme/style.css" type="text/css"> |
| 6 | +<link rel="prev" href="class_data_members.html"> |
| 7 | +<link rel="next" href="inheritance.html"> |
| 8 | +</head> |
| 9 | +<body> |
| 10 | +<table width="100%" height="48" border="0" cellspacing="2"> |
| 11 | + <tr> |
| 12 | + <td><img src="theme/c%2B%2Bboost.gif"> |
| 13 | + </td> |
| 14 | + <td width="85%"> <font size="6" face="Verdana, Arial, Helvetica, sans-serif"><strong>Building |
| 15 | + an Extension Module</strong></font> </td> |
| 16 | + </tr> |
| 17 | +</table> |
| 18 | +<br> |
| 19 | +<table border="0"> |
| 20 | + <tr> |
| 21 | + <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td> |
| 22 | + <td width="30"><img src="theme/l_arr.gif" border="0"></td> |
| 23 | + <td width="20"><img src="theme/r_arr.gif" border="0"></td> |
| 24 | + </tr> |
| 25 | +</table> |
| 26 | +<h2>Building Boost.Python</h2> |
| 27 | +<p>Every Boost.Python extension module must be linked with the boost_python shared |
| 28 | + library. To build boost_python, use <a href="file:///C:/dev/boost/tools/build/index.html">Boost.Build</a> |
| 29 | + in the usual way from the <tt>libs/python/build</tt> subdirectory of your boost |
| 30 | + installation (if you have already built boost from the top level this may have |
| 31 | + no effect, since the work is already done).</p> |
| 32 | +<h2>Configuration</h2> |
| 33 | +<p>You may need to configure the following variables to point Boost.Build at your |
| 34 | + Python installation:</p> |
| 35 | +<table width="95%" border="0" align="center"> |
| 36 | + <tr class="table_title"> |
| 37 | + <td width="24%">Variable Name</td> |
| 38 | + <td width="20%">Semantics</td> |
| 39 | + <td width="21%">Default</td> |
| 40 | + <td width="35%">Notes</td> |
| 41 | + </tr> |
| 42 | + <tr class="table_cells"> |
| 43 | + <td><tt>PYTHON_ROOT</tt></td> |
| 44 | + <td> The root directory of your Python installation</td> |
| 45 | + <td>Windows: <tt><br> |
| 46 | + c:/tools/python <br> |
| 47 | + Unix: /usr/local</tt></td> |
| 48 | + <td>On Unix, this is the <tt>--with-prefix=</tt> directory used to configure |
| 49 | + Python</td> |
| 50 | + </tr> |
| 51 | + <tr class="table_cells"> |
| 52 | + <td><tt>PYTHON_VERSION</tt></td> |
| 53 | + <td> The The 2-part python Major.Minor version number</td> |
| 54 | + <td>Windows: 2.1 Unix: 1.5</td> |
| 55 | + <td>Be sure not to include a third number, e.g. not "2.2.1", even |
| 56 | + if that's the version you have.</td> |
| 57 | + </tr> |
| 58 | + <tr class="table_cells"> |
| 59 | + <td><tt>PYTHON_INCLUDES</tt></td> |
| 60 | + <td> path to Python <span class="preprocessor">#include</span> directories</td> |
| 61 | + <td>Autoconfigured from <tt><br> |
| 62 | + PYTHON_ROOT</tt></td> |
| 63 | + <td> </td> |
| 64 | + </tr> |
| 65 | + <tr class="table_cells"> |
| 66 | + <td><tt>PYTHON_LIB_PATH</tt></td> |
| 67 | + <td>path to Python library object.</td> |
| 68 | + <td>Autoconfigured from <tt><br> |
| 69 | + PYTHON_ROOT</tt></td> |
| 70 | + <td> </td> |
| 71 | + </tr> |
| 72 | + <tr class="table_cells"> |
| 73 | + <td><tt>PYTHON_STDLIB_PATH</tt></td> |
| 74 | + <td>path to Python standard library modules</td> |
| 75 | + <td>Autoconfigured from <tt><br> |
| 76 | + PYTHON_ROOT</tt></td> |
| 77 | + <td> </td> |
| 78 | + </tr> |
| 79 | + <tr class="table_cells"> |
| 80 | + <td height="129"><tt>CYGWIN_ROOT</tt></td> |
| 81 | + <td> path to the user's Cygwin installation</td> |
| 82 | + <td>Autoconfigured from <tt><br> |
| 83 | + PYTHON_ROOT</tt></td> |
| 84 | + <td><a href="http://www.cygwin.com">Cygwin</a> only. This and the following |
| 85 | + two settings are useful when building with multiple toolsets on Windows, |
| 86 | + since Cygwin requires a different build of Python.</td> |
| 87 | + </tr> |
| 88 | + <tr class="table_cells"> |
| 89 | + <td height="21"><tt>GCC_PYTHON_ROOT</tt></td> |
| 90 | + <td>path to the user's Cygwin Python installation</td> |
| 91 | + <td><tt>$(CYGWIN_ROOT)<br> |
| 92 | + /usr/local</tt></td> |
| 93 | + <td> <a href="http://www.cygwin.com">Cygwin</a> only</td> |
| 94 | + </tr> |
| 95 | + <tr class="table_cells"> |
| 96 | + <td><tt>GCC_DEBUG_PYTHON_ROOT</tt></td> |
| 97 | + <td> path to the user's Cygwin <a href="#variants">pydebug</a> |
| 98 | + build</td> |
| 99 | + <td><tt>$(CYGWIN_ROOT)<br> |
| 100 | + /usr/local/pydebug</tt></td> |
| 101 | + <td> <a href="http://www.cygwin.com">Cygwin</a> only</td> |
| 102 | + </tr> |
| 103 | +</table> |
| 104 | +<h2>Results</h2> |
| 105 | +<p>The build process will create a <tt>libs/python/build/bin-stage</tt> subdirectory |
| 106 | + of the boost root (or of <tt>$(ALL_LOCATE_TARGET)</tt>, if you have set that |
| 107 | + variable), containing the built libraries. The libraries are actually built |
| 108 | + to unique directories for each toolset and variant elsewhere in the filesystem, |
| 109 | + and copied to the bin-stage directory as a convenience, so if you build with |
| 110 | + multiple toolsets at once, the product of later toolsets will overwrite that |
| 111 | + of earlier toolsets in bin-stage.</p> |
| 112 | +<h2>Testing</h2> |
| 113 | +<p>To build and test Boost.Python from within the <tt>libs/python/build directory</tt>, |
| 114 | + invoke</p> |
| 115 | +<pre> bjam -sTOOLS=<a href="../../../tools/build/index.html">toolset</a> test</pre> |
| 116 | +<p>This will update all of the Boost.Python v1 test and example targets. The tests |
| 117 | + are relatively quiet by default. To get more-verbose output, you might try</p> |
| 118 | +<pre> bjam -sTOOLS=<a href="../../../tools/build/index.html">toolset</a> -sPYTHON_TEST_ARGS=-v test</pre> |
| 119 | +<p>which will print each test's Python code with the expected output as it passes.</p> |
| 120 | +<h2>Building your Extension Module</h2> |
| 121 | +<p>Though there are other approaches, the easiest way to build an extension module |
| 122 | + using Boost.Python is with Boost.Build. Until Boost.Build v2 is released, cross-project |
| 123 | + build dependencies are not supported, so it works most smoothly if you add a |
| 124 | + new subproject to your boost installation. The <tt>libs/python/example</tt> |
| 125 | + subdirectory of your boost installation contains a minimal example (along with |
| 126 | + many extra sources). To copy the example subproject:</p> |
| 127 | +<ol> |
| 128 | + <li> Create a new subdirectory in,<tt> libs/python</tt>, say <tt>libs/python/my_project</tt>.</li> |
| 129 | + <li> Copy <a href="../example/Jamfile"><tt>libs/python/example/Jamfile</tt></a> |
| 130 | + to your new directory.</li> |
| 131 | + <li> Edit the Jamfile as appropriate for your project. You'll want to change |
| 132 | + the <tt>subproject</tt> rule invocation at the top, and the names of some |
| 133 | + of the source files and/or targets.</li> |
| 134 | +</ol> |
| 135 | +<p>If you can't modify or copy your boost installation, the alternative is to |
| 136 | + create your own Boost.Build project. A similar example you can use as a starting |
| 137 | + point is available in <a href="../example/project.zip">this archive</a>. You'll |
| 138 | + need to edit the Jamfile and Jamrules files, depending on the relative location |
| 139 | + of your Boost installation and the new project. Note that automatic testing |
| 140 | + of extension modules is not available in this configuration.</p> |
| 141 | +<h2>Build Variants</h2> |
| 142 | +<p>Three variant configurations of all python-related targets are supported, and |
| 143 | + can be selected by setting the BUILD variable:</p> |
| 144 | +<p> * <tt>release</tt> (optimization, <tt>-DNDEBUG</tt>)<br> |
| 145 | + * <tt>debug</tt> (no optimization <tt>-D_DEBUG</tt>)<br> |
| 146 | + * <tt>debug-python</tt> (no optimization, <tt>-D_DEBUG -DBOOST_DEBUG_PYTHON</tt>)</p> |
| 147 | +<p>The first two variants of the boost_python library are built by default, and |
| 148 | + are compatible with the default Python distribution. The debug-python variant |
| 149 | + corresponds to a specially-built debugging version of Python. On Unix platforms, |
| 150 | + this python is built by adding <tt>--with-pydebug</tt> when configuring the |
| 151 | + Python build. On Windows, the debugging version of Python is generated by the |
| 152 | + "Win32 Debug" target of the PCBuild.dsw Visual C++ 6.0 project in |
| 153 | + the PCBuild subdirectory of your Python distribution. Extension modules built |
| 154 | + with Python debugging enabled are not link-compatible with a non-debug build |
| 155 | + of Python. Since few people actually have a debug build of Python (it doesn't |
| 156 | + come with the standard distribution), the normal debug variant builds modules |
| 157 | + which are compatible with ordinary Python.</p> |
| 158 | +<p>On many windows compilers, when extension modules are built with <tt>-D_DEBUG</tt>, |
| 159 | + Python defaults to force linking with a special debugging version of the Python |
| 160 | + DLL. Since this debug DLL isn't supplied with the default Python installation |
| 161 | + for Windows, Boost.Python uses <a href="../../../boost/python/detail/wrap_python.hpp"><tt>boost/python/detail/wrap_python.hpp</tt></a> |
| 162 | + to temporarily undefine <tt>_DEBUG</tt> when <tt>Python.h</tt> is <span class="preprocessor">#included</span> |
| 163 | + - unless <tt>BOOST_DEBUG_PYTHON</tt> is defined.</p> |
| 164 | +<p>If you want the extra runtime checks available with the debugging version of |
| 165 | + the library, <span class="preprocessor">#define</span> <tt>BOOST_DEBUG_PYTHON</tt> |
| 166 | + to re-enable python debuggin, and link with the debug-python variant of boost_python.</p> |
| 167 | +<p>If you do not <span class="preprocessor">#define</span> <tt>BOOST_DEBUG_PYTHON</tt>, |
| 168 | + be sure that any source files in your extension module <span class="preprocessor">#include</span> |
| 169 | + <tt><boost/python/detail/wrap_python.hpp></tt> instead of the usual <tt>Python.h</tt>, |
| 170 | + or you will have link incompatibilities.</p> |
| 171 | +<code></code> |
| 172 | +<table border="0"> |
| 173 | + <tr> |
| 174 | + <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td> |
| 175 | + <td width="30"><img src="theme/l_arr.gif" border="0"></td> |
| 176 | + <td width="20"><img src="theme/r_arr.gif" border="0"></td> |
| 177 | + </tr> |
| 178 | +</table> |
| 179 | +<br> |
| 180 | +<hr size="1"><p class="copyright">Copyright © 2002 David Abrahams<br>Copyright © 2002 Joel de Guzman<br><br> |
| 181 | +<font size="2">Permission to copy, use, modify, sell and distribute this document |
| 182 | + is granted provided this copyright notice appears in all copies. This document |
| 183 | + is provided "as is" without express or implied warranty, and with |
| 184 | + no claim as to its suitability for any purpose. </font> </p> |
| 185 | +</body> |
| 186 | +</html> |
0 commit comments