GeezerVison

[section No-Install Quickstart]

There is no need to “install Boost” in order to get started using

Boost.Python. These instructions use [@http://boost.org/build] projects,

Boost.Python. These instructions use _bb_ projects,

which will build those binaries as soon as they're needed. Your

first tests may take a little longer while you wait for

Boost.Python to build, but doing things this way will save you from

build system* without first following these instructions.

If you want to use another system anyway, we suggest that you

follow these instructions, and then invoke ``bjam`` with the

follow these instructions, and then invoke `bjam` with the

`-a -o`\ *filename*

`-a -o`\ /filename/

options to dump the build commands it executes to a file, so

you can see what your alternate build system needs to do.]

to see the output generated by the tests when they are run.

On Windows, your `bjam` invocation might look something like:

``

C:\\boost_1_34_0\\...\\quickstart> bjam toolset=msvc --verbose-test test

C:\\...\\quickstart> bjam toolset=msvc --verbose-test test

``

and on Unix variants, perhaps,

``

~/boost_1_34_0/.../quickstart$ bjam toolset=gcc --verbose-test test

.../quickstart$ bjam toolset=gcc --verbose-test test

``

[note For the sake of concision, the rest of this guide will use

unix-style forward slashes in pathnames instead of the

backslashes with which Windows users may be more familiar. The forward

slashes should work everywhere except in

[@http://www.boost.org/more/getting_started/windows.html#command-prompt Command Prompt windows],

where you should use backslashes.]

[@http://www.boost.org/more/getting_started/windows.html#command-prompt

Command Prompt] windows, where you should use backslashes.]

If you followed this procedure successfully, you will have built an

extension module called `extending` and tested it by running a

`/home/dave/my-project`, you could change the first path in

`boost-build.jam` from

``

../../../../tools/build/v2

../../../../tools/build/src

``

to

``

/home/dave/boost_1_34_0/tools/build/v2

/home/dave/boost_1_34_0/tools/build/src

``

and change the first path in `Jamroot` from

``

The name of the extension module is determined by two things:

1. the name in `Jamroot` immediately following `python-extension`, and

2. the name passed to ``BOOST_PYTHON_MODULE`` in `extending.cpp`.

# the name in `Jamroot` immediately following `python-extension`, and

# the name passed to `BOOST_PYTHON_MODULE` in `extending.cpp`.

To change the name of the extension module from `extending` to

`hello`, you'd edit `Jamroot`, changing

``

[endsect]

[endsect]

[endsect]

[section Installing Boost.Python on your System]

Since Boost.Python is a separately-compiled (as opposed to

[endsect]

[section Configuring Boost.Build]

As described in the _reference_, a file called

As described in the [@http://www.boost.org/build/doc/html/bbv2/overview/configuration.html 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

Boost.Python binaries, you should set up a `user-config.jam` file

with at least the minimal incantation above.

[endsect]

[section 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*

[variablelist

[[version]

the version of Python to use. Should be in Major.Minor

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

configuration argument required.]]

* *cmd-or-prefix*

[[cmd-or-prefix]

preferably, a command that invokes a Python interpreter.

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

no appropriate Python executable available.]]

* *includes*

[[*includes*]

the `#include` paths for Python headers. Normally the correct

[the `#include` paths for Python headers. Normally the correct

path(s) will be automatically deduced from `version` and/or

`cmd-or-prefix`.

`cmd-or-prefix`.]]

* *libraries*

[[*libraries*]

the path to Python library binaries. On MacOS/Darwin,

[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`.

and/or `cmd-or-prefix`.]]

* *condition*

[[*condition*]

if specified, should be a set of Boost.Build

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

below for details.]]

* *extension-suffix*

[[*extension-suffix*]

A string to append to the name of extension

[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

[@https://wiki.ubuntu.com/PyDbgBuilds <python-debugging>] package

that claims to use such a suffix.

[link building.python_debugging_builds <python-debugging>] feature.

However, at least one Linux distribution (Ubuntu Feisty Fawn) has

a specially configured [@https://wiki.ubuntu.com/PyDbgBuilds <python-dbg>]

package that claims to use such a suffix.]]

]

[endsect]

[section Examples]

``

* If you have downloaded the Python sources and built both the

normal and the “\ `python debugging`_\ ” builds from source on

Windows, you might see:

normal and the [link building.python_debugging_builds "python debugging"]

builds from source on Windows, you might see:

``

using python : 2.5 : C:\\src\\Python-2.5\\PCBuild\\python ;

Boost.Python binary comes in both static and dynamic flavors. Take

care to choose the right flavor for your application. [footnote

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

[@http://boost.org/getting_started/windows.html#library-naming Windows] /

[@http://boost.org/getting_started/unix-variants.html#library-naming Unix variants]]

[@http://boost.org/more/getting_started/windows.html#library-naming Windows] /

[@http://boost.org/more/getting_started/unix-variants.html#library-naming Unix variants]]

[section The Dynamic 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

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

`wrap_python.hpp`. This restriction is actually imposed by

Python, or more properly, by Python's interaction with your

operating system. See

http://docs.python.org/ext/simpleExample.html for details.

[@http://docs.python.org/ext/simpleExample.html] for details.

[endsect]

[section Python Debugging Builds]

Since pre-built “python debugging” versions of the Python

executable and libraries are not supplied with most distributions

of Python, [#get-debug-build]_ and we didn't want to force our users

of Python, [footnote On Unix and similar platforms, a debugging python and associated libraries are 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 Visual Studio project in the PCBuild subdirectory of a full Python source code distribution.] and we didn't want to force our users

to build them, Boost.Build does not automatically enable python

debugging in its `debug` build variant (which is the default).

Instead there is a special build property called

the preprocessor symbol `_DEBUG`, Python defaults to force

linking with a special debugging version of the Python DLL. Since

that symbol is very commonly used even when Python is not present,

Boost.Python temporarily undefines _DEBUG when Python.h

Boost.Python temporarily undefines `_DEBUG` when `Python.h`

is #included from `boost/python/detail/wrap_python.hpp` - unless

`BOOST_DEBUG_PYTHON` is defined. The upshot is that if you want

“python debugging”and you aren't using Boost.Build, you should make

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 [@http://www.python.org/doc/current/inst/index.html Installing Python Modules] to create `libpythonXX.a`, where `XX`

corresponds to the major and minor version numbers of your Python

installation.

the “Building Extensions: Tips And Tricks” chapter in

[@https://docs.python.org/2/install/index.html Installing Python Modules]

to create `libpythonXX.a`, where `XX` corresponds to the major and minor

version numbers of your Python installation.

[endsect]

[section Configuration]

[section Introduction]

*Boost.Python* uses several configuration macros in `<boost/config.hpp>`, as well as configuration macros meant to be supplied by the application. These macros are documented here.

[*Boost.Python] uses several configuration macros in `<boost/config.hpp>`, as well as configuration macros meant to be supplied by the application. These macros are documented here.

[endsect]

[section Application Defined Macros]

These are the macros that may be defined by an application using Boost.Python. Note that if you extend a strict interpretation of the C++ standard to cover dynamic libraries, using different values of these macros when compiling different libraries (including extension modules and the Boost.Python library itself) is a violation of the ODR. However, we know of no C++ implementations on which this particular violation is detectable or causes any problems.

These are the macros that may be defined by an application using Boost.Python. Note that if you extend a strict interpretation of the C++ standard to cover dynamic libraries, using different values of these macros when compiling different libraries (including extension modules and the Boost.Python library itself) is a violation of the [link odr ODR]. However, we know of no C++ implementations on which this particular violation is detectable or causes any problems.

[table

[[Macro][Default][Meaning]]

]

[endsect]

[section Library Defined Defined Macros]

[table

[[Macro][Default][Meaning]]

[[BOOST_PYTHON_TYPE_ID_NAME][ /not defined/ ]

[chapter FAQ

[chapter Frequently Asked Questions (FAQs)

[quickbook 1.7]

[id faq]

]

you do that.

[endsect]

[section Is return_internal_reference efficient?]

[section Is `return_internal_reference` efficient?]

[*Q:] /I have an object composed of 12 doubles. A const& to

[*Q:] /I have an object composed of 12 doubles. A `const&` to

this object is returned by a member function of another class. From the

viewpoint of using the returned object in Python I do not care if I get

a copy or a reference to the returned object. In Boost.Python Version 2

I have the choice of using copy_const_reference or

return_internal_reference. Are there considerations that would lead me

to prefer one over the other, such as size of generated code or memory

overhead?/

a copy or a reference to the returned object. In Boost.Python I have the

choice of using `copy_const_reference` or `return_internal_reference`.

Are there considerations that would lead me to prefer one over the other,

such as size of generated code or memory overhead?/

[*A:] `copy_const_reference` will make an instance with storage

for one of your objects, size = base_size + 12 * sizeof(double).

return_internal_reference will make an instance with storage for a

pointer to one of your objects, size = base_size + sizeof(void*).

for one of your objects, `size = base_size + 12 * sizeof(double)`.

`return_internal_reference` will make an instance with storage for a

pointer to one of your objects, `size = base_size + sizeof(void*)`.

However, it will also create a weak reference object which goes in the

source object's weakreflist and a special callback object to manage the

lifetime of the internally-referenced object. My guess?

copy_const_reference is your friend here, resulting in less overall

`copy_const_reference` is your friend here, resulting in less overall

memory use and less fragmentation, also probably fewer total

cycles.

...

;

``

This can be moved to a template so that several types (double, int,

long, etc.) can be wrapped with the same code. This technique is used

This can be moved to a template so that several types (`double`, `int`,

`long`, etc.) can be wrapped with the same code. This technique is used

in the file `scitbx/include/scitbx/array_family/boost_python/flex_wrapper.h`

in the "scitbx" package. The file could easily be modified for

wrapping `std::vector<>` instantiations.

}

}

``

Python:

Python: [python]

``

>>> l = [1, 2, 3]

>>> foo(l)

# Break your source file up into multiple translation units.

`my_module.cpp`:

`my_module.cpp`: [c++]

``

...

...

}

``

If you find that a [link reference.class-spec class_]<...> declaration

If you find that a `class_<...>` declaration

can't fit in a single source file without triggering the error, you

can always pass a reference to the `class_` object to a

function in another source file, and call some of its member

a.release();

}

``

Wrap that as B.add. Note that pointers returned via [link reference.manage_new_object manage_new_object]

Wrap that as B.add. Note that pointers returned via `manage_new_object`

will also be held by `auto_ptr`, so this transfer-of-ownership

will also work correctly.

[endsect]

[section Compilation takes too much time and eats too much memory!

What can I do to make it faster?]

Please refer to the [link tutorial.python.reducing_compiling_time Reducing Compiling Time] section in the tutorial.

Please refer to the `Reducing Compiling Time` section in the _tutorial_.

[endsect]

[section How do I create sub-packages using Boost.Python?]

Please refer to the [link tutorial.python.creating_packages Creating Packages] section in the tutorial.

Please refer to the `Creating Packages` section in the _tutorial_.

[endsect]

[section error C2064: term does not evaluate to a function taking 2 arguments]