### Configuring Boost.Build

As described in the Boost.Build Reference Manual, a file called `user-config.jam` in your home directory is used to specify the tools and libraries available to the build system. You may need to create or edit `user-config.jam` to tell Boost.Build how to invoke Python, `#include` its headers, and link with its libraries.

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

If you have one fairly “standard” python installation for your platform, you might not need to do anything special to describe it. If you haven't configured python in `user-config.jam` (and you don't specify `--without-python` on the Boost.Build command line), Boost.Build will automatically execute the equivalent of

    import toolset : using ;
    using python ;

which automatically looks for Python in the most likely places. However, that only happens when using the Boost.Python project file (e.g. when referred to by another project as in the quickstart method). If instead you are linking against separately-compiled Boost.Python binaries, you should set up a `user-config.jam` file with at least the minimal incantation above.

#### Python Configuration Parameters

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 configuration argument required.

cmd-or-prefix

  preferably, a command that invokes a Python interpreter. Alternatively, the installation prefix for Python libraries and header files. Only use the alternative formulation if there is no appropriate Python executable available.

includes

  the `#include` paths for Python headers. Normally the correct path(s) will be automatically deduced from `version` and/or `cmd-or-prefix`.

libraries

  the path to Python library binaries. On MacOS/Darwin, you can also pass the path of the Python framework. Normally the correct path(s) will be automatically deduced from `version` and/or `cmd-or-prefix`.

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. See examples below for details.

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.

#### 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
           ;

- If you have downloaded the Python sources and built both the normal and the "python debugging" builds from source on Windows, you might see:

      using python : 2.5 : C:\\src\\Python-2.5\\PCBuild\\python ;
      using python : 2.5 : C:\\src\\Python-2.5\\PCBuild\\python_d
        : # includes
        : # libs
        : <python-debugging>on ;

- 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: _

      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

[2] `configure` overwrites the existing `user-config.jam` in your home directory (if any) after making a backup of the old version.