boost/python
2
0
Fork 0
mirror of https://github.com/boostorg/python.git synced 2026-01-29 19:52:16 +00:00
Code Issues Projects Releases Wiki Activity

Some progress on new build/test guide.

Browse Source 
[SVN r37333]
This commit is contained in:
Dave Abrahams
2007-04-02 05:24:25 +00:00
parent 1b5cd10f7c
commit 4fc5cafd40
3 changed files with 636 additions and 483 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
doc/Jamfile Normal file
View File

@@ -0,0 +1,23 @@
# 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)
import docutils ;
import path ;
sources = building.rst ;
bases = $(sources:S=) ;
# This is a path relative to the html/ subdirectory where the
# generated output will eventually be moved.
stylesheet = "--stylesheet=../../../rst.css" ;
for local b in $(bases)
{
html $(b) : $(b).rst :
<docutils-html>"-gdt --source-url="./$(b).rst" --link-stylesheet --traceback --trim-footnote-reference-space --footnote-references=superscript "$(stylesheet)
;
}
alias htmls : $(bases) ;
stage . : $(bases) ;

797
doc/building.html
View File

@@ -1,463 +1,358 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<?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" href="../index.htm"><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) -->
<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
<!-- file LICENSE_1_0.txt or copy at -->
<!-- http://www.boost.org/LICENSE_1_0.txt) -->
<div class="contents sidebar small topic">
<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
<ul class="auto-toc simple">
<li><a class="reference" href="#requirements" id="id17" name="id17">1&nbsp;&nbsp;&nbsp;Requirements</a></li>
<li><a class="reference" href="#background" id="id18" name="id18">2&nbsp;&nbsp;&nbsp;Background</a></li>
<li><a class="reference" href="#getting-boost-python-binaries" id="id19" name="id19">3&nbsp;&nbsp;&nbsp;Getting Boost.Python Binaries</a></li>
<li><a class="reference" href="#choosing-a-boost-python-library-binary" id="id20" name="id20">4&nbsp;&nbsp;&nbsp;Choosing a Boost.Python Library Binary</a><ul class="auto-toc">
<li><a class="reference" href="#the-dynamic-binary" id="id21" name="id21">4.1&nbsp;&nbsp;&nbsp;The Dynamic Binary</a></li>
<li><a class="reference" href="#the-static-binary" id="id22" name="id22">4.2&nbsp;&nbsp;&nbsp;The Static Binary</a></li>
</ul>
</li>
<li><a class="reference" href="#configuring-boost-build" id="id23" name="id23">5&nbsp;&nbsp;&nbsp;Configuring Boost.Build</a><ul class="auto-toc">
<li><a class="reference" href="#the-basics" id="id24" name="id24">5.1&nbsp;&nbsp;&nbsp;The Basics</a></li>
<li><a class="reference" href="#advanced-configuration" id="id25" name="id25">5.2&nbsp;&nbsp;&nbsp;Advanced Configuration</a></li>
<li><a class="reference" href="#advanced-configuration-examples" id="id26" name="id26">5.3&nbsp;&nbsp;&nbsp;Advanced Configuration Examples</a></li>
</ul>
</li>
</ul>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id17" id="requirements" name="requirements">1&nbsp;&nbsp;&nbsp;Requirements</a></h1>
<p>Boost.Python requires <a class="reference" href="http://www.python.org/2.2">Python 2.2</a><a class="footnote-reference" href="#id13" id="id2" name="id2"><sup>1</sup></a> <em>or</em> <a class="reference" href="http://www.python.org"><em>newer</em></a>.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id18" id="background" name="background">2&nbsp;&nbsp;&nbsp;Background</a></h1>
<p>There are two basic models for combining C++ and Python:</p>
<ul class="simple">
<li><a class="reference" 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" 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 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" 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">
<h1><a class="toc-backref" href="#id19" id="getting-boost-python-binaries" name="getting-boost-python-binaries">3&nbsp;&nbsp;&nbsp;Getting Boost.Python Binaries</a></h1>
<p>Since Boost.Python is a separately-compiled (as opposed to
<a class="reference" 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. The Boost <a class="reference" href="../../../more/getting_started/index.html">Getting Started Guide</a>
will walk you through the steps of installing 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 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 and <strong>99% of all “I can't build
Boost.Python” problems come from trying to use another build
system</strong>.</p>
<p class="last">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
<tt class="docutils literal"><span class="pre">-o</span></tt><em>filename</em> option to dump the build commands it executes
to a file, so you can see what your build system needs to do.</p>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id20" id="choosing-a-boost-python-library-binary" name="choosing-a-boost-python-library-binary">4&nbsp;&nbsp;&nbsp;Choosing a Boost.Python Library Binary</a></h1>
<p>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="id5" name="id5"><sup>2</sup></a></p>
<div class="section">
<h2><a class="toc-backref" href="#id21" id="the-dynamic-binary" name="the-dynamic-binary">4.1&nbsp;&nbsp;&nbsp;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="id6" name="id6"><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">
<h2><a class="toc-backref" href="#id22" id="the-static-binary" name="the-static-binary">4.2&nbsp;&nbsp;&nbsp;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" 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" 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">
<h1><a class="toc-backref" href="#id23" id="configuring-boost-build" name="configuring-boost-build">5&nbsp;&nbsp;&nbsp;Configuring Boost.Build</a></h1>
<p>As described in the <a class="reference" 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 (<tt class="docutils literal"><span class="pre">%HOMEDRIVE%%HOMEPATH%</span></tt> on Windows) is used to
describe the build resources available to the build system. You'll
need to tell it about your Python installation.</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="id8" name="id8"><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>
<div class="section">
<h2><a class="toc-backref" href="#id24" id="the-basics" name="the-basics">5.1&nbsp;&nbsp;&nbsp;The Basics</a></h2>
<p>If you have a fairly “standard” python installation for your
platform, there's very little you need to do to describe it.
Simply adding</p>
<pre class="literal-block">
import toolset : using ;
using python ;
</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
<p>to a <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> file in your home directory<a class="footnote-reference" href="#home-dir" id="id9" name="id9"><sup>6</sup></a>
should be enough.</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id25" id="advanced-configuration" name="advanced-configuration">5.2&nbsp;&nbsp;&nbsp;Advanced Configuration</a></h2>
<p>On the other hand, 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
additional 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. 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> path for Python headers.</dd>
<dt>libraries</dt>
<dd>the path to Python library binaries. On MacOS/Darwin,
you can also pass the path of the Python framework.</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.</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
<tt class="docutils literal"><span class="pre">&lt;python-debugging&gt;</span></tt> feature. However, at least one Linux
distribution (Ubuntu Feisty Fawn) has a specially configured
<a class="reference" href="https://wiki.ubuntu.com/PyDbgBuilds">python-dbg</a> package that claims to use such a suffix.</dd>
</dl>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id26" id="advanced-configuration-examples" name="advanced-configuration-examples">5.3&nbsp;&nbsp;&nbsp;Advanced Configuration 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
<blockquote>
<pre>
bjam -sTOOLS=<i><a href=
"../../../more/getting_started.html#Tools">toolset</a></i> -sPYTHON_TEST_ARGS= test
using python : 2.4 ; # To build with python 2.4, add python=2.4
# to your command line.
</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 ;
<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>
</blockquote>
so that the path refers to the <code>tools/build/v1</code>
subdirectory of your Boost installation.
</li>
</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
<li>
<code><a href="../example/Jamrules"><b>Jamrules</b></a></code> - edit
the line which reads
<blockquote>
<pre>
path-global BOOST_ROOT : ../../.. ;
# Use with Intel C++ toolset
using python
: # version
: c:\\Devel\\Python-2.5-IntelBuild\\PCBuild\\python # cmd-or-prefix
: # includes
: # libraries
: &lt;toolset&gt;intel # condition
;
</pre>
</blockquote>
so that the path refers to the root directory of your Boost
installation.
</li>
</ol>
</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 cygwin python extensions. Just pass
<tt class="docutils literal"><span class="pre">&lt;target-os&gt;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 ;
<p>The instructions <a href="#testing">above</a> for testing Boost.Python
apply equally to your new extension modules in this subproject.</p>
# cygwin installation
using python : : c:\\cygwin\\bin\\python2.5 : : : &lt;target-os&gt;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="id11" name="id11"><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 cygwin 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" 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 : : : : &lt;target-os&gt;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>
<hr class="docutils" />
<table class="docutils footnote" frame="void" id="id13" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id2" name="id13">[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="#id5" name="naming">[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" href="../../../more/getting_started/windows.html#library-naming">on Windows</a></li>
<li><a class="reference" href="../../../more/getting_started/unix-variants.html#library-naming">on Unix variants</a></li>
</ul>
<p class="last">Be sure to read this section even if your compiler supports
auto-linking, as Boost.Python does not yet take advantage of
that feature.</p>
</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="#id6" name="toolset-specific">[3]</a></td><td>Because of the way most *nix platforms
share symbols among dynamically-loaded objects, I'm not
certainextension 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="#id8" name="overwrite">[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="#id11" name="flavor">[5]</a></td><td>Note that the <tt class="docutils literal"><span class="pre">&lt;target-os&gt;cygwin</span></tt> feature is
different from the <tt class="docutils literal"><span class="pre">&lt;flavor&gt;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="#id9" name="home-dir">[6]</a></td><td><p class="first">Create the <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> file if you don't
already have one. For Windows users, the home directory can
be found by typing:</p>
<pre class="literal-block">
ECHO %HOMEDRIVE%%HOMEPATH%
</pre>
<p class="last">into a <a class="reference" href="../../../more/getting_started/windows.html#or-build-from-the-command-prompt">Windows command prompt</a></p>
</td></tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="footer">
<hr class="footer" />
<a class="reference" href="./building.rst">View document source</a>.
Generated on: 2007-04-02 05:13 UTC.
Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
<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>
</div>
</body>
</html>

299
doc/building.rst
View File

@@ -26,7 +26,7 @@ __ ../index.htm
Requirements
============
Boost.Python requires `Python 2.2`_ *or* |newer|__.
Boost.Python requires `Python 2.2`_ [#2.2]_ *or* |newer|__.
.. _Python 2.2: http://www.python.org/2.2
__ http://www.python.org
@@ -36,11 +36,11 @@ Background
There are two basic models for combining C++ and Python:
- extending_, in which the end-user launches the Python
interpreter executable and imports Python “extension modules”
written in C++. Think of providing libraries written in C++ for
Python programmers to use. From Python, these modules look just
like regular Python modules.
- extending_, 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.
- embedding_, in which the end-user launches a program written
in C++ that in turn invokes the Python interpreter as a library
@@ -53,37 +53,69 @@ There are two basic models for combining C++ and Python:
The key distinction between extending and embedding is the location
of C++' ``main()`` function: in the Python interpreter executable,
or in some other program, respectively. Note that even when
embedding Python in another program, `extension modules are often the best
way to give Python code access to C/C++ functionality`__, so the use
of extension modules is really at the heart of both models.
embedding Python in another program, `extension modules are often
the best way to make C/C++ functionality accessible to Python
code`__, so the use of extension modules is really at the heart of
both models.
__ http://www.python.org/doc/current/ext/extending-with-embedding.html
Except in rare cases, extension modules are built as
dynamically-loaded libraries with a single entry point, which means
you can change them without recompiling either the other extension
you can change them without rebuilding either the other extension
modules or the executable containing ``main()``.
Getting Boost.Python Binaries
=============================
Since Boost.Python is a separately-compiled (as opposed to
`header-only`_) library, its user relies on the services of a
Boost.Python library binary. The Boost `Getting Started Guide`_
will walk you through the steps of installing one. If building
binaries from source, you might want to supply the
``--with-python`` argument to ``bjam`` (or the
``--with-libraries=python`` argument to ``configure``), so only the
Boost.Python binary will be built, rather than all the Boost
binaries.
.. _`Getting Started Guide`: ../../../more/getting_started/index.html
.. Note:: 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 and **99% of all “I can't build
Boost.Python” problems come from trying to use another build
system**.
If you want to use another system anyway, we suggest that you
follow these instructions, and then invoke ``bjam`` with the
``-o``\ *filename* option to dump the build commands it executes
to a file, so you can see what your build system needs to do.
Choosing a Boost.Python Library Binary
======================================
Boost.Python extension modules draw on the services of the
Boost.Python library binary. Since Boost.Python is a
separately-compiled (as opposed to `header-only`_) library, it
comes in both static and dynamic flavors. Take care to choose the
right flavor for your application. The dynamic library is the
safest and most-versatile choice:
The Boost.Python binary comes in both static and dynamic flavors.
Take care to choose the right flavor for your
application. [#naming]_
The Dynamic Binary
------------------
The dynamic library is the safest and most-versatile choice:
- A single copy of the library code is used by all extension
modules built with a given toolset.
modules built with a given toolset. [#toolset-specific]_
- The library contains a type conversion registry. Because one
registry is shared among all extension modules, a instances of a
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.
It is appropriate to use the static Boost.Python library in any of
the following cases:
The Static Binary
-----------------
It might be appropriate to use the static Boost.Python library in
any of the following cases:
- You are extending_ python and the types exposed in your
dynamically-loaded extension module don't need to be used by any
@@ -92,20 +124,223 @@ the following cases:
- You are embedding_ python in your application and either:
- You are targeting a Unix variant OS, where the
dynamically-loaded extension modules can “see” the Boost.Python
library symbols that are part of the executable.
- 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.
- 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 can use the
types exposed by your statically-linked extension modules (and
vice-versa).
- 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).
.. _header-only: ../../../more/getting_started.html#header-only-libraries
.. _header-only: ../../../more/getting_started/windows.html#header-only-libraries
Although they are supported under Boost.Python, we're not going to
cover the esoteric case of statically-linked extension modules here
in detail.
Configuring Boost.Build
=======================
As described in the `Boost.Build reference manual`__, a file called
``user-config.jam`` in your home
directory (``%HOMEDRIVE%%HOMEPATH%`` on Windows) is used to
describe the build resources available to the build system. You'll
need to tell it about your Python installation.
__ http://www.boost.orgdoc/html/bbv2/advanced.html#bbv2.advanced.configuration
.. Admonition:: Users of Unix-Variant OSes
If you are using a unix-variant OS and you ran Boost's
``configure`` script, it may have generated a
``user-config.jam`` for you. [#overwrite]_ If your ``configure``\
/\ ``make`` sequence was successful and Boost.Python binaries
were built, your ``user-config.jam`` file is probably already
correct.
The Basics
----------
If you have a fairly “standard” python installation for your
platform, there's very little you need to do to describe it.
Simply adding ::
import toolset : using ;
using python ;
to a ``user-config.jam`` file in your home directory [#home-dir]_
should be enough.
Advanced Configuration
----------------------
On the other hand, 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
``using python``:
version
the version of Python to use. Should be in Major.Minor
format, for example, ``2.3``. Do not include the subminor
version (i.e. *not* ``2.5.1``). If you have multiple Python
versions installed, the version will usually be the only
additional argument required.
cmd-or-prefix
preferably, a command that invokes a Python
interpreter. Alternatively, the installation prefix for Python
libraries and header files. Use the alternative formulation if
there is no appropriate Python executable available.
includes
the ``#include`` path for Python headers.
libraries
the path to Python library binaries. On MacOS/Darwin,
you can also pass the path of the Python framework.
condition
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.
extension-suffix
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
``<python-debugging>`` feature. However, at least one Linux
distribution (Ubuntu Feisty Fawn) has a specially configured
`python-dbg`__ package that claims to use such a suffix.
__ https://wiki.ubuntu.com/PyDbgBuilds
Advanced Configuration Examples
-------------------------------
Note that in the examples below, case and *especially whitespace* are
significant.
- If you have both python 2.5 and python 2.4 installed,
``user-config.jam`` might contain::
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.
The first version configured (2.5) becomes the default. To build
against python 2.4, add ``python=2.4`` to the ``bjam`` command line.
- If you have python installed in an unusual location, you might
supply the path to the interpreter in the ``cmd-or-prefix``
parameter::
using python : : /usr/local/python-2.6-beta/bin/python ;
- If you have a separate build of Python for use with a particular
toolset, you might supply that toolset in the ``condition``
parameter::
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
;
- You can set up your user-config.jam so a bjam built under Windows
can build/test both windows and cygwin python extensions. Just pass
``<target-os>cygwin`` in the ``condition`` parameter
for the cygwin python installation::
# windows installation
using python ;
# cygwin installation
using python : : c:\\cygwin\\bin\\python2.5 : : : <target-os>cygwin ;
when you put target-os=cygwin in your build request, it should build
with the cygwin version of python: [#flavor]_
bjam target-os=cygwin toolset=gcc
This is supposed to work the other way, too (targeting windows
python with a cygwin 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.
- Note that because of `the way Boost.Build currently selects target
alternatives`__, you might have be very explicit in your build
requests. For example, given::
using python : 2.5 ; # a regular windows build
using python : 2.4 : : : : <target-os>cygwin ;
building with ::
bjam target-os=cygwin
will yield an error. Instead, you'll need to write::
bjam target-os=cygwin/python=2.4
__ http://zigzag.cs.msu.su/boost.build/wiki/AlternativeSelection
-----------------------------
.. [#2.2] Note that although we tested earlier versions of
Boost.Python with Python 2.2, and we don't *think* 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.
.. [#naming] Information about how to identify the
static and dynamic builds of Boost.Python:
* `on Windows`__
* `on Unix variants`__
__ ../../../more/getting_started/windows.html#library-naming
__ ../../../more/getting_started/unix-variants.html#library-naming
Be sure to read this section even if your compiler supports
auto-linking, as Boost.Python does not yet take advantage of
that feature.
.. [#toolset-specific] Because of the way most \*nix platforms
share symbols among dynamically-loaded objects, I'm not
certainextension 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.
.. [#overwrite] ``configure`` overwrites the existing
``user-config.jam`` in your home directory
(if any) after making a backup of the old version.
.. [#flavor] Note that the ``<target-os>cygwin`` feature is
different from the ``<flavor>cygwin`` subfeature of the ``gcc``
toolset, and you might need handle both explicitly if you also
have a MinGW GCC installed.
.. [#home-dir] Create the ``user-config.jam`` file if you don't
already have one. Windows users, your home directory can be
found by typing::
ECHO %HOMEDRIVE%%HOMEPATH%
into a `Windows command prompt`__
__ ../../../more/getting_started/windows.html#or-build-from-the-command-prompt