1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>No-Install Quickstart</title> 5<link rel="stylesheet" href="../boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../index.html" title="Boost.Python"> 8<link rel="up" href="../building.html" title="Chapter 2. Building and Testing"> 9<link rel="prev" href="background.html" title="Background"> 10<link rel="next" href="installing_boost_python_on_your_.html" title="Installing Boost.Python on your System"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../images/boost.png"></td></tr></table> 14<hr> 15<div class="spirit-nav"> 16<a accesskey="p" href="background.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../building.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="installing_boost_python_on_your_.html"><img src="../images/next.png" alt="Next"></a> 17</div> 18<div class="section"> 19<div class="titlepage"><div><div><h3 class="title"> 20<a name="building.no_install_quickstart"></a><a class="link" href="no_install_quickstart.html" title="No-Install Quickstart">No-Install Quickstart</a> 21</h3></div></div></div> 22<div class="toc"><dl class="toc"> 23<dt><span class="section"><a href="no_install_quickstart.html#building.no_install_quickstart.basic_procedure">Basic 24 Procedure</a></span></dt> 25<dt><span class="section"><a href="no_install_quickstart.html#building.no_install_quickstart.in_case_of_trouble">In 26 Case of Trouble</a></span></dt> 27<dt><span class="section"><a href="no_install_quickstart.html#building.no_install_quickstart.in_case_everything_seemed_to_wor">In 28 Case Everything Seemed to Work</a></span></dt> 29<dt><span class="section"><a href="no_install_quickstart.html#building.no_install_quickstart.modifying_the_example_project">Modifying 30 the Example Project</a></span></dt> 31</dl></div> 32<p> 33 There is no need to “install Boost” in order to get started using Boost.Python. 34 These instructions use <a href="http://www.boost.org/build" target="_top">Boost.Build</a> 35 projects, which will build those binaries as soon as they're needed. Your 36 first tests may take a little longer while you wait for Boost.Python to build, 37 but doing things this way will save you from worrying about build intricacies 38 like which library binaries to use for a specific compiler configuration 39 and figuring out the right compiler options to use yourself. 40 </p> 41<div class="note"><table border="0" summary="Note"> 42<tr> 43<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td> 44<th align="left">Note</th> 45</tr> 46<tr><td align="left" valign="top"> 47<p> 48 Of course it's possible to use other build systems to build Boost.Python 49 and its extensions, but they are not officially supported by Boost. Moreover 50 <span class="bold"><strong>99% of all “I can't build Boost.Python” problems 51 come from trying to use another build system</strong></span> without first following 52 these instructions. 53 </p> 54<p> 55 If you want to use another system anyway, we suggest that you follow these 56 instructions, and then invoke <code class="computeroutput"><span class="identifier">bjam</span></code> 57 with the 58 </p> 59<p> 60 <code class="computeroutput"><span class="special">-</span><span class="identifier">a</span> 61 <span class="special">-</span><span class="identifier">o</span></code><span class="emphasis"><em>filename</em></span> 62 </p> 63<p> 64 options to dump the build commands it executes to a file, so you can see 65 what your alternate build system needs to do. 66 </p> 67</td></tr> 68</table></div> 69<div class="section"> 70<div class="titlepage"><div><div><h4 class="title"> 71<a name="building.no_install_quickstart.basic_procedure"></a><a class="link" href="no_install_quickstart.html#building.no_install_quickstart.basic_procedure" title="Basic Procedure">Basic 72 Procedure</a> 73</h4></div></div></div> 74<p> 75 1. Get Boost; see sections 1 and 2 of the Boost <a href="http://www.boost.org/more/getting_started/" target="_top">Getting 76 Started Guide</a>. 77 </p> 78<p> 79 2. Get the <code class="computeroutput"><span class="identifier">bjam</span></code> build driver. 80 See section 5 of the Boost <a href="http://www.boost.org/more/getting_started/" target="_top">Getting 81 Started Guide</a>. 82 </p> 83<p> 84 3. cd into the <code class="computeroutput"><span class="identifier">example</span><span class="special">/</span><span class="identifier">quickstart</span><span class="special">/</span></code> directory of your Boost.Python installation, 85 which contains a small example project. 86 </p> 87<p> 88 4. Invoke <code class="computeroutput"><span class="identifier">bjam</span></code>. Replace 89 the “<code class="computeroutput"><span class="identifier">stage</span></code>“ argument 90 from the example invocation from section 5 of the Boost <a href="http://www.boost.org/more/getting_started/" target="_top">Getting 91 Started Guide</a> with “<code class="computeroutput"><span class="identifier">test</span></code>,“ 92 to build all the test targets. Also add the argument “<code class="computeroutput"><span class="special">--</span><span class="identifier">verbose</span><span class="special">-</span><span class="identifier">test</span></code>” to see the output generated by 93 the tests when they are run. On Windows, your <code class="computeroutput"><span class="identifier">bjam</span></code> 94 invocation might look something like: 95 </p> 96<pre class="programlisting"><span class="identifier">C</span><span class="special">:\\...\\</span><span class="identifier">quickstart</span><span class="special">></span> <span class="identifier">bjam</span> <span class="identifier">toolset</span><span class="special">=</span><span class="identifier">msvc</span> <span class="special">--</span><span class="identifier">verbose</span><span class="special">-</span><span class="identifier">test</span> <span class="identifier">test</span> 97</pre> 98<p> 99 and on Unix variants, perhaps, 100 </p> 101<pre class="programlisting"><span class="special">.../</span><span class="identifier">quickstart</span><span class="error">$</span> <span class="identifier">bjam</span> <span class="identifier">toolset</span><span class="special">=</span><span class="identifier">gcc</span> <span class="special">--</span><span class="identifier">verbose</span><span class="special">-</span><span class="identifier">test</span> <span class="identifier">test</span> 102</pre> 103<div class="note"><table border="0" summary="Note"> 104<tr> 105<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td> 106<th align="left">Note</th> 107</tr> 108<tr><td align="left" valign="top"><p> 109 For the sake of concision, the rest of this guide will use unix-style 110 forward slashes in pathnames instead of the backslashes with which Windows 111 users may be more familiar. The forward slashes should work everywhere 112 except in <a href="http://www.boost.org/more/getting_started/windows.html#command-prompt" target="_top">Command 113 Prompt</a> windows, where you should use backslashes. 114 </p></td></tr> 115</table></div> 116<p> 117 If you followed this procedure successfully, you will have built an extension 118 module called <code class="computeroutput"><span class="identifier">extending</span></code> 119 and tested it by running a Python script called <code class="computeroutput"><span class="identifier">test_extending</span><span class="special">.</span><span class="identifier">py</span></code>. 120 You will also have built and run a simple application called <code class="computeroutput"><span class="identifier">embedding</span></code> that embeds python. 121 </p> 122</div> 123<div class="section"> 124<div class="titlepage"><div><div><h4 class="title"> 125<a name="building.no_install_quickstart.in_case_of_trouble"></a><a class="link" href="no_install_quickstart.html#building.no_install_quickstart.in_case_of_trouble" title="In Case of Trouble">In 126 Case of Trouble</a> 127</h4></div></div></div> 128<p> 129 If you're seeing lots of compiler and/or linker error messages, it's probably 130 because Boost.Build is having trouble finding your Python installation. 131 You might want to pass the <code class="computeroutput"><span class="special">--</span><span class="identifier">debug</span><span class="special">-</span><span class="identifier">configuration</span></code> option to <code class="computeroutput"><span class="identifier">bjam</span></code> the first few times you invoke it, 132 to make sure that Boost.Build is correctly locating all the parts of your 133 Python installation. If it isn't, consider <a class="link" href="configuring_boost_build.html" title="Configuring Boost.Build">Configuring 134 Boost.Build</a> as detailed below. 135 </p> 136<p> 137 If you're still having trouble, Someone on one of the following mailing 138 lists may be able to help: 139 </p> 140<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 141<li class="listitem"> 142 The <a href="http://www.boost.org/more/mailing_lists.htm#jamboost" target="_top">Boost.Build 143 mailing list</a> for issues related to Boost.Build 144 </li> 145<li class="listitem"> 146 The <a href="http://www.boost.org/more/mailing_lists.htm#cplussig" target="_top">Boost.Python 147 mailing list</a> for issues specifically related to Boost.Python 148 </li> 149</ul></div> 150</div> 151<div class="section"> 152<div class="titlepage"><div><div><h4 class="title"> 153<a name="building.no_install_quickstart.in_case_everything_seemed_to_wor"></a><a class="link" href="no_install_quickstart.html#building.no_install_quickstart.in_case_everything_seemed_to_wor" title="In Case Everything Seemed to Work">In 154 Case Everything Seemed to Work</a> 155</h4></div></div></div> 156<p> 157 Rejoice! If you're new to Boost.Python, at this point it might be a good 158 idea to ignore build issues for a while and concentrate on learning the 159 library by going through the <a href="../tutorial/index.html" target="_top">Tutorial</a> 160 and perhaps some of the <a href="../reference/index.html" target="_top">Reference Manual</a>, 161 trying out what you've learned about the API by modifying the quickstart 162 project. 163 </p> 164</div> 165<div class="section"> 166<div class="titlepage"><div><div><h4 class="title"> 167<a name="building.no_install_quickstart.modifying_the_example_project"></a><a class="link" href="no_install_quickstart.html#building.no_install_quickstart.modifying_the_example_project" title="Modifying the Example Project">Modifying 168 the Example Project</a> 169</h4></div></div></div> 170<div class="toc"><dl class="toc"> 171<dt><span class="section"><a href="no_install_quickstart.html#building.no_install_quickstart.modifying_the_example_project.relocate_the_project">Relocate 172 the Project</a></span></dt> 173<dt><span class="section"><a href="no_install_quickstart.html#building.no_install_quickstart.modifying_the_example_project.add_new_or_change_names_of_exist">Add 174 New or Change Names of Existing Source Files</a></span></dt> 175<dt><span class="section"><a href="no_install_quickstart.html#building.no_install_quickstart.modifying_the_example_project.change_the_name_of_your_extensio">Change 176 the Name of your Extension Module</a></span></dt> 177</dl></div> 178<p> 179 If you're content to keep your extension module forever in one source file 180 called <code class="computeroutput"><span class="identifier">extending</span><span class="special">.</span><span class="identifier">cpp</span></code>, inside your Boost.Python distribution, 181 and import it forever as <code class="computeroutput"><span class="identifier">extending</span></code>, 182 then you can stop here. However, it's likely that you will want to make 183 a few changes. There are a few things you can do without having to learn 184 <a href="http://www.boost.org/build" target="_top">Boost.Build</a> in depth. 185 </p> 186<p> 187 The project you just built is specified in two files in the current directory: 188 <code class="computeroutput"><span class="identifier">boost</span><span class="special">-</span><span class="identifier">build</span><span class="special">.</span><span class="identifier">jam</span></code>, which tells <code class="computeroutput"><span class="identifier">bjam</span></code> 189 where it can find the interpreted code of the Boost build system, and 190 <code class="computeroutput"><span class="identifier">Jamroot</span></code>, which describes 191 the targets you just built. These files are heavily commented, so they 192 should be easy to modify. Take care, however, to preserve whitespace. Punctuation 193 such as <code class="computeroutput"><span class="special">;</span></code> will not be recognized 194 as intended by <code class="computeroutput"><span class="identifier">bjam</span></code> if 195 it is not surrounded by whitespace. 196 </p> 197<div class="section"> 198<div class="titlepage"><div><div><h5 class="title"> 199<a name="building.no_install_quickstart.modifying_the_example_project.relocate_the_project"></a><a class="link" href="no_install_quickstart.html#building.no_install_quickstart.modifying_the_example_project.relocate_the_project" title="Relocate the Project">Relocate 200 the Project</a> 201</h5></div></div></div> 202<p> 203 You'll probably want to copy this project elsewhere so you can change 204 it without modifying your Boost distribution. To do that, simply 205 </p> 206<p> 207 a. copy the entire <code class="computeroutput"><span class="identifier">example</span><span class="special">/</span><span class="identifier">quickstart</span><span class="special">/</span></code> directory into a new directory. 208 </p> 209<p> 210 b. In the new copies of <code class="computeroutput"><span class="identifier">boost</span><span class="special">-</span><span class="identifier">build</span><span class="special">.</span><span class="identifier">jam</span></code> 211 and <code class="computeroutput"><span class="identifier">Jamroot</span></code>, locate the 212 relative path near the top of the file that is clearly marked by a comment, 213 and edit that path so that it refers to the same directory your Boost 214 distribution as it referred to when the file was in its original location 215 in the <code class="computeroutput"><span class="identifier">example</span><span class="special">/</span><span class="identifier">quickstart</span><span class="special">/</span></code> 216 directory. 217 </p> 218<p> 219 For example, if you moved the project from <code class="computeroutput"><span class="special">/</span><span class="identifier">home</span><span class="special">/</span><span class="identifier">dave</span><span class="special">/</span><span class="identifier">boost_1_34_0</span><span class="special">/</span><span class="identifier">libs</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">example</span><span class="special">/</span><span class="identifier">quickstart</span></code> to <code class="computeroutput"><span class="special">/</span><span class="identifier">home</span><span class="special">/</span><span class="identifier">dave</span><span class="special">/</span><span class="identifier">my</span><span class="special">-</span><span class="identifier">project</span></code>, you could change the first 220 path in <code class="computeroutput"><span class="identifier">boost</span><span class="special">-</span><span class="identifier">build</span><span class="special">.</span><span class="identifier">jam</span></code> from 221 </p> 222<pre class="programlisting"><span class="special">../../../../</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">build</span><span class="special">/</span><span class="identifier">src</span> 223</pre> 224<p> 225 to 226 </p> 227<pre class="programlisting"><span class="special">/</span><span class="identifier">home</span><span class="special">/</span><span class="identifier">dave</span><span class="special">/</span><span class="identifier">boost_1_34_0</span><span class="special">/</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">build</span><span class="special">/</span><span class="identifier">src</span> 228</pre> 229<p> 230 and change the first path in <code class="computeroutput"><span class="identifier">Jamroot</span></code> 231 from 232 </p> 233<pre class="programlisting"><span class="special">../../../..</span> 234</pre> 235<p> 236 to 237 </p> 238<pre class="programlisting"><span class="special">/</span><span class="identifier">home</span><span class="special">/</span><span class="identifier">dave</span><span class="special">/</span><span class="identifier">boost_1_34_0</span> 239</pre> 240</div> 241<div class="section"> 242<div class="titlepage"><div><div><h5 class="title"> 243<a name="building.no_install_quickstart.modifying_the_example_project.add_new_or_change_names_of_exist"></a><a class="link" href="no_install_quickstart.html#building.no_install_quickstart.modifying_the_example_project.add_new_or_change_names_of_exist" title="Add New or Change Names of Existing Source Files">Add 244 New or Change Names of Existing Source Files</a> 245</h5></div></div></div> 246<p> 247 The names of additional source files involved in building your extension 248 module or embedding application can be listed in <code class="computeroutput"><span class="identifier">Jamroot</span></code> 249 right alongside <code class="computeroutput"><span class="identifier">extending</span><span class="special">.</span><span class="identifier">cpp</span></code> 250 or <code class="computeroutput"><span class="identifier">embedding</span><span class="special">.</span><span class="identifier">cpp</span></code> respectively. Just be sure to leave 251 whitespace around each filename: 252 </p> 253<pre class="programlisting"><span class="error">…</span> <span class="identifier">file1</span><span class="special">.</span><span class="identifier">cpp</span> <span class="identifier">file2</span><span class="special">.</span><span class="identifier">cpp</span> <span class="identifier">file3</span><span class="special">.</span><span class="identifier">cpp</span> <span class="error">…</span> 254</pre> 255<p> 256 Naturally, if you want to change the name of a source file you can tell 257 Boost.Build about it by editing the name in <code class="computeroutput"><span class="identifier">Jamroot</span></code>. 258 </p> 259</div> 260<div class="section"> 261<div class="titlepage"><div><div><h5 class="title"> 262<a name="building.no_install_quickstart.modifying_the_example_project.change_the_name_of_your_extensio"></a><a class="link" href="no_install_quickstart.html#building.no_install_quickstart.modifying_the_example_project.change_the_name_of_your_extensio" title="Change the Name of your Extension Module">Change 263 the Name of your Extension Module</a> 264</h5></div></div></div> 265<p> 266 The name of the extension module is determined by two things: 267 </p> 268<div class="orderedlist"><ol class="orderedlist" type="1"> 269<li class="listitem"> 270 the name in <code class="computeroutput"><span class="identifier">Jamroot</span></code> 271 immediately following <code class="computeroutput"><span class="identifier">python</span><span class="special">-</span><span class="identifier">extension</span></code>, 272 and 273 </li> 274<li class="listitem"> 275 the name passed to <code class="computeroutput"><span class="identifier">BOOST_PYTHON_MODULE</span></code> 276 in <code class="computeroutput"><span class="identifier">extending</span><span class="special">.</span><span class="identifier">cpp</span></code>. 277 </li> 278</ol></div> 279<p> 280 To change the name of the extension module from <code class="computeroutput"><span class="identifier">extending</span></code> 281 to <code class="computeroutput"><span class="identifier">hello</span></code>, you'd edit 282 <code class="computeroutput"><span class="identifier">Jamroot</span></code>, changing 283 </p> 284<pre class="programlisting"><span class="identifier">python</span><span class="special">-</span><span class="identifier">extension</span> <span class="identifier">extending</span> <span class="special">:</span> <span class="identifier">extending</span><span class="special">.</span><span class="identifier">cpp</span> <span class="special">;</span> 285</pre> 286<p> 287 to 288 </p> 289<pre class="programlisting"><span class="identifier">python</span><span class="special">-</span><span class="identifier">extension</span> <span class="identifier">hello</span> <span class="special">:</span> <span class="identifier">extending</span><span class="special">.</span><span class="identifier">cpp</span> <span class="special">;</span> 290</pre> 291<p> 292 and you'd edit extending.cpp, changing 293 </p> 294<pre class="programlisting"><span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">extending</span><span class="special">)</span> 295</pre> 296<p> 297 to 298 </p> 299<pre class="programlisting"><span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">hello</span><span class="special">)</span> 300</pre> 301</div> 302</div> 303</div> 304<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 305<td align="left"></td> 306<td align="right"><div class="copyright-footer">Copyright © 2002-2015 David 307 Abrahams, Stefan Seefeld<br>Copyright © 2002-2015 David Abrahams, Stefan Seefeld<p> 308 Distributed under the Boost Software License, Version 1.0. (See accompanying 309 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) 310 </p> 311</div></td> 312</tr></table> 313<hr> 314<div class="spirit-nav"> 315<a accesskey="p" href="background.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../building.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="installing_boost_python_on_your_.html"><img src="../images/next.png" alt="Next"></a> 316</div> 317</body> 318</html> 319
