diff --git a/doc/Jamfile b/doc/Jamfile new file mode 100644 index 00000000..9b7c8841 --- /dev/null +++ b/doc/Jamfile @@ -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 : + + "-gdt --source-url="./$(b).rst" --link-stylesheet --traceback --trim-footnote-reference-space --footnote-references=superscript "$(stylesheet) + ; +} + +alias htmls : $(bases) ; +stage . : $(bases) ; diff --git a/doc/building.html b/doc/building.html index 51562b8a..815c66d1 100644 --- a/doc/building.html +++ b/doc/building.html @@ -1,463 +1,358 @@ - + + + + + + +Boost C++ Libraries: Boost.Python Build and Test HOWTO + + + +
+

Boost.Python Build and Test HOWTO

- - - - - - - - Boost.Python - Building and Testing - - - - - - - - - -
-

-

- 		-

Boost.Python

- -

Building and Testing

-
-
- -

Contents

- -
-
Requirements
- -
Building Boost.Python
- -
-
-
Configuration
- -
Configuration for Cygwin GCC - from a Windows prompt
- -
Results
- -
Notes for Cygwin GCC Users
- -
Notes for MinGW (and Cygwin with -mno-cygwin) - GCC Users
- -
Testing
-
-
- -
Building your Extension Module
- -
Build Variants
- -
Building Using the Microsoft Visual Studio - IDE
-
-
- -

Requirements

- Boost.Python version 2 requires Python 2.2 or newer. An unsupported archive of - Boost.Python version 1, which works with versions of Python since 1.5.2, - is available here. - -

Building Boost.Python

- -

Normally, Boost.Python extension modules must be linked with the - boost_python shared library. In special circumstances you - may want to link to a static version of the boost_python - 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 boost_python, use Boost.Build in the - usual way from the libs/python/build 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).

- -

Basic Configuration

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 bjam command-line - as -sname=value. Variable - names are case-sensitive. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Variable NameSemanticsDefaultNotes
PYTHON_VERSIONThe The 2-part python Major.Minor version number2.4Be sure not to include a third number, e.g. not - "2.2.1", even if that's the version you have.
PYTHON_ROOTThe root directory of your Python installationWindows: c:/Python(10*Version), e.g. c:/Python24 -
- *nix/Cygwin: /usr		On *nix, this should be the --prefix= directory used - to configure Python when it was built and installed.
PYTHON_INCLUDESpath to Python #include directoriesAutoconfigured from PYTHON_ROOT. Try the default - before attempting to set it yourself.
PYTHON_LIB_PATHpath to Python library object.Autoconfigured from PYTHON_ROOT. Try the default - before attempting to set it yourself.
- -

Configuration for Cygwin GCC from a - Windows prompt

- The following settings may be useful when building with Cygwin GCC (not MinGW) from a Windows command - shell using a Windows build of bjam. If - "bjam -v" does not report "OS=NT", these - settings do not apply to you; you should use the normal configuration 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. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Variable NameSemanticsDefault
CYGWIN_PYTHON_[DEBUG_]VERSIONThe version of python being used under Cygwin.$(PYTHON_VERSION)
CYGWIN_PYTHON_[DEBUG_]ROOT*nix-style path containing the include/ directory - containing - python$(CYGWIN_PYTHON_[DEBUG_]VERSION)/python.h.$(PYTHON_ROOT)
CYGWIN_PYTHON_[DEBUG_]LIB_PATHpath containing the user's Cygwin Python import lib - libpython$(CYGWIN_PYTHON_[DEBUG_]VERSION).dll.aAutoconfigured from CYGWIN_PYTHON_ROOT
CYGWIN_PYTHON_[DEBUG_]DLL_PATHpath containing the user's Cygwin Python dll - (libpython$(CYGWIN_PYTHON_[DEBUG_]VERSION).dll)/bin
- -

Notes for Cygwin GCC Users

- -

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 python.org will not - work with your compiler because the dynamic linking conventions are - different (you can use MinGW 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 Unix installation - process to build Python from source.

- -

The special build configuration variables listed above 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.

- -

Notes for MinGW (and Cygwin with -mno-cygwin) GCC - Users

- -

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 Installing Python - Modules to create libpythonXX.a, where XX - corresponds to the major and minor version numbers of your Python - installation.

- -

Results

- -

The build process will create a - libs/python/build/bin-stage subdirectory of the boost root - (or of $(ALL_LOCATE_TARGET), 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 bin-stage 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 - bin-stage.

- -

Testing

- -

To build and test Boost.Python, start from the - libs/python/test directory and invoke

- -
-
-bjam -sTOOLS=toolset test
+
+
+

+
Contents

+
+

+

+
1   Requirements

+
Boost.Python requires Python 2.21 or newer.

+

+

+
2   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 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
+subroutine.  Think of adding scriptability to an existing
+application.
    • 
+

+
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 make C/C++ functionality accessible to Python
+code, so the use of extension modules is really at the heart of
+both models.

+
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 main().

+

+

+
3   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.

+

+
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
+-ofilename option to dump the build commands it executes
+to a file, so you can see what your build system needs to do.

+

+

+

+
4   Choosing a Boost.Python Library Binary

+
The Boost.Python binary comes in both static and dynamic flavors.
+Take care to choose the right flavor for your
+application.2

+

+
4.1   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.3
    • 
+
  • 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.
    • 
+

+

+

+
4.2   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
+other Boost.Python extension modules, and you don't care if the
+core library code is duplicated among them.
    • 
+
  • You are embedding python in your application and either:
      
+
    • 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.
      • 
+
    • 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).
      • 
+
    
+
    • 
+

+

+

+

+
5   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.

+

+
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.4 If your configure/make sequence was successful and Boost.Python binaries
+were built, your user-config.jam file is probably already
+correct.

+

+

+
5.1   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 ;
 

-
- 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 +

to a user-config.jam file in your home directory6 +should be enough.

+
+
+

5.2   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.
+
+
+
+

5.3   Advanced Configuration Examples

+

Note that in the examples below, case and especially whitespace are +significant.

+ +
+ + + + + +
[1]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.
+ + + + + +
[2]

Information about how to identify the +static and dynamic builds of Boost.Python:

+ +

Be sure to read this section even if your compiler supports +auto-linking, as Boost.Python does not yet take advantage of +that feature.

+
+ + + + + +
[3]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.
+ + + + + +
[4]configure overwrites the existing +user-config.jam in your home directory +(if any) after making a backup of the old version.
+ + + + + +
[5]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.
+ + + + + +
[6]

Create the user-config.jam file if you don't +already have one. For Windows users, the home directory can +be found by typing:

+
+ECHO %HOMEDRIVE%%HOMEPATH%
+
+

into a Windows command prompt

+
+
+ + +
+
+View document source. +Generated on: 2007-04-02 05:13 UTC. +Generated by Docutils from reStructuredText source. -

Build Variants

- Three variant - configurations of all python-related targets are supported, and can be - selected by setting the BUILD - variable: - - - -

The first two variants of the boost_python library are - built by default, and are compatible with the default Python - distribution. The debug-python variant corresponds to a - specially-built debugging version of Python. On *nix platforms, this - python is built by adding --with-pydebug when configuring - the Python build. On Windows, the debugging version of Python is - generated by the "Win32 Debug" target of the PCBuild.dsw - Visual C++ 6.0 project in the PCBuild subdirectory of your - Python distribution. Extension modules built with Python debugging - enabled are not link-compatible 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 debug variant - builds modules which are compatible with ordinary Python.

- -

On many windows compilers, when extension modules are built with - -D_DEBUG, Python defaults to force 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 - boost/python/detail/wrap_python.hpp - to temporarily undefine _DEBUG when Python.h is - #included - unless BOOST_DEBUG_PYTHON is - defined.

- -

If you want the extra runtime checks available with the debugging - version of the library, #define BOOST_DEBUG_PYTHON to re-enable - python debuggin, and link with the debug-python variant of - boost_python.

- -

If you do not #define BOOST_DEBUG_PYTHON, be sure that any - source files in your extension module #include <boost/python/detail/wrap_python.hpp> - instead of the usual Python.h, or you will have link - incompatibilities.
-

- -

Building Using the Microsoft Visual Studio - IDE

- -

For the those of you who feel more comfortable in the IDE world, a - workspace and project file have been included in the - libs/python/build/VisualStudio 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 Include/ and Libs/ directories. - Under Tools>Options>Directories, add an entry for the Python - include dir (i.e. c:/Python22/Include), and one for the Lib - (i.e. c:/Python/Libs. Make sure it is Libs with - an "s" and not just Lib).

- -

Using the IDE for your own projects

- -

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.

- -

You'll need to add the Boost root directory under - Tools>Options>Directories to get your code compiling. To - make it link, add the above boost_python.dsp file to your - workspace, and make your project depend upon it (under - Project>Dependencies). You should be able to build now.

- -

Lastly, go to the Project Settings>Debug Page and add the - Python.exe as the executable for the project. Set a startup - directory, and make sure that your current project's output dll, the - boost_python.dll and the python22.dll are on - the current PATH. 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.

- -
- The Visual Studio project files are graciously contributed and - maintained by Brett - Calcott. -
-
- -

© 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.

- -

Updated: 13 April 2004 (David Abrahams)

- +
+ - diff --git a/doc/building.rst b/doc/building.rst index 953904fe..1d31d2f7 100644 --- a/doc/building.rst +++ b/doc/building.rst @@ -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 + ```` 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 + : 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 + ``cygwin`` in the ``condition`` parameter + for the cygwin python installation:: + + # windows installation + using python ; + + # cygwin installation + using python : : c:\\cygwin\\bin\\python2.5 : : : 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 : : : : 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 ``cygwin`` feature is + different from the ``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