diff --git a/doc/building.html b/doc/building.html index cdca6b97..d76a708c 100644 --- a/doc/building.html +++ b/doc/building.html @@ -1,222 +1,294 @@ - + +
+ + + -|
+ |
-
+ Boost.Python-Every Boost.Python extension module must be linked with the
- Building and Testing+ |
+
Every Boost.Python extension module must be linked with the
+ boost_python shared library. 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).
| Variable Name | + +Semantics | + +Default | + +Notes | +|||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
PYTHON_ROOT |
+
+ The root directory of your Python installation | -
| Variable Name | Semantics | Default | Notes - | |
|---|---|---|---|---|
PYTHON_ROOT
- | The root directory of your Python installation | Windows: c:/tools/python
- Unix: /usr/local
- | On Unix, this is the --with-prefix= directory
- used to configure Python
+ Unix: /usr/local |
+
+ On Unix, this is the --with-prefix= directory used
+ to configure Python |
+
PYTHON_VERSION |
+
+ The The 2-part python Major.Minor version number | + +2.2 |
- ||
PYTHON_VERSION
- | The The 2-part python Major.Minor version number - | Windows: 2.1
- Unix: 1.5
| Be sure not to include a third number, e.g. not
- "2.2.1", even if that's the version you
- have.
+ "2.2.1", even if that's the version you have. |
+ |
PYTHON_INCLUDES
- | path to Python #include directories
- | Autoconfigured from PYTHON_ROOT
+ | ||
PYTHON_INCLUDES |
- ||||
PYTHON_LIB_PATH
- | path to Python library object. - | Autoconfigured from PYTHON_ROOT
+ | path to Python #include directories |
- |
PYTHON_STDLIB_PATH
- | path to Python standard library modules - | Autoconfigured from PYTHON_ROOT
+ | Autoconfigured from PYTHON_ROOT |
+ |
PYTHON_LIB_PATH |
+
+ path to Python library object. | + +Autoconfigured from PYTHON_ROOT |
+ ||
PYTHON_STDLIB_PATH |
+
+ path to Python standard library modules | + +Autoconfigured from PYTHON_ROOT |
+ ||
CYGWIN_ROOT |
+
+ path to the user's Cygwin installation | -|||
CYGWIN_ROOT
- | path to the user's Cygwin installation | - | Cygwin only. This and the following two settings are - useful when building with multiple toolsets on Windows, since - Cygwin requires a different build of Python. + | -|
GCC_PYTHON_ROOT
- | path to the user's Cygwin Python installation - | $(CYGWIN_ROOT)/usr/local
- | Cygwin only + | Cygwin only. This and the + following two settings are useful when building with multiple + toolsets on Windows, since Cygwin requires a different build of + Python. | +
GCC_DEBUG_PYTHON_ROOT
- | path to the user's Cygwin pydebug build
- | $(CYGWIN_ROOT)/usr/local/pydebug
- | Cygwin only + | |
GCC_PYTHON_ROOT |
-
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.
+
$(CYGWIN_ROOT)/usr/localTo build and test Boost.Python from within the
- libs/python/build directory, invoke
-
+Cygwin only +
GCC_DEBUG_PYTHON_ROOTpydebug build$(CYGWIN_ROOT)/usr/local/pydebugThe 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.
To build and test Boost.Python, start from the
+ libs/python/test directory and invoke
-This will -update all of the Boost.Python v1 test and example targets. The tests -are relatively quiet by default. To get more-verbose output, you might try --bjam -sTOOLS=toolset test +bjam -sTOOLS=toolset test-
++ This will update all of the Boost.Python v1 test and example targets. The + tests are relatively quiet by default. To get more-verbose output, you + might try + +
-which will print each test's Python code with the expected output as -it passes. + + which will print each test's Python code with the expected output as it + passes. --bjam -sTOOLS=toolset -sPYTHON_TEST_ARGS=-v test +bjam -sTOOLS=toolset -sPYTHON_TEST_ARGS=-v test-
libs/python/example subdirectory of your boost installation
+ contains a minimal example (along with many extra sources). To copy the
+ example subproject:
- Though there are other approaches, the easiest way to build an
- extension module using Boost.Python is with Boost.Build. Until
- Boost.Build v2 is released, cross-project build dependencies are
- not supported, so it works most smoothly if you add a new
- subproject to your boost installation. The
- libs/python/example subdirectory of your boost
- installation contains a minimal example (along with many extra
- sources). To copy the example subproject:
-
- libs/python, say
- libs/python/my_project.
+ libs/python/my_project.libs/python/example/Jamfile
- to your new directory.
+ libs/python/example/Jamfile to your new
+ directory.subproject" rule
- invocation at the top, and the names of some of the source files
- and/or targets.
+ subproject" rule invocation at the top, and
+ the names of some of the source files and/or targets.this archive. You'll need to edit the
+ Jamfile and Jamrules files, depending on the relative location of your
+ Boost installation and the new project. Note that automatic testing of
+ extension modules is not available in this configuration.
- BUILD
+ variable:
- If you can't modify or copy your boost installation, the
- alternative is to create your own Boost.Build project. A similar
- example you can use as a starting point is available in this archive. You'll
- need to edit the Jamfile and Jamrules files, depending on the
- relative location of your Boost installation and the new
- project. Note that automatic testing of extension modules is not
- available in this configuration.
+ release (optimization, -DNDEBUG)debug (no optimization -D_DEBUG)BUILD
- variable:
+ debug-python (no optimization, -D_DEBUG
+ -DBOOST_DEBUG_PYTHON)release (optimization, -DNDEBUG)
+ 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 Unix 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.
debug (no optimization -D_DEBUG)
+ 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.
debug-python (no optimization, -D_DEBUG
- -DBOOST_DEBUG_PYTHON)
- 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.
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 Unix 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.
+
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.
+
debug variant builds modules which are compatible
- with ordinary Python.
+ © Copyright David Abrahams 2002. 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: O8 October, 2002 (David Abrahams)
+ + -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.
-
-
© Copyright David Abrahams 2002. 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: May 15, 2002 (David Abrahams) -

- Use the Boost Python Library to quickly and easily export a C++ library to Python such that the Python interface is - very similar to the C++ interface. It is designed to be minimally - intrusive on your C++ design. In most cases, you should not have to alter - your C++ classes in any way in order to use them with Boost.Python. The system - should simply ``reflect'' your C++ classes and functions into - Python. + +
+ + + -+
| Note: this is the last official release of -Boost.Python v1. Development of this version of the library has -stopped; it will be retired soon in favor of the redesigned and -improved version 2. A summary of the development goals is available on -the Python C++-sig -page, which also serves as a mailing list for users of both versions -of the library. A preview of the v2 documentation is available here, -and instructions for getting started with a prerelease are available -upon request. - |
|
+ |
-
+ Boost.Python-
|
+
-
-
-
-
-
-
-
-
-Note that pickling doesn't work with Python 2.2 -due to a core language bug. This is fixed in -2.2.1. +
Revised + + 08 October, 2002 + +
--Boost.Python has also been used with other versions of Python back to -Python 1.5.2. It is expected that the older Python releases still work, -but we are not regularly testing for backward compatibility. - -
- Documentation is a major ongoing project; assistance is greatly
- appreciated! In the meantime, useful examples of every Boost.Python feature should
- be evident in the regression test files test/comprehensive.[py/hpp/cpp]
-
-
- Questions should be directed to the Python C++ SIG. - -
- © Copyright David Abrahams 2001. 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: Apr 2002 +
© Copyright Dave + Abrahams 2002. All Rights Reserved.
+ + diff --git a/doc/tutorial/doc/building_hello_world.html b/doc/tutorial/doc/building_hello_world.html index 8595ea56..68094b60 100644 --- a/doc/tutorial/doc/building_hello_world.html +++ b/doc/tutorial/doc/building_hello_world.html @@ -36,26 +36,22 @@ building Boost.Python, check out: building.html. After this brief bjam tutorial, we should have built two DLLs:-if you are on Windows, and
--if you are on Unix.
+This assumes of course that we are running on Windows.The tutorial example can be found in the directory: -libs/python/example/tutorial. There, you can find:
+/libs/python/example/tutorial. There, you can find:The hello.cpp file is our C++ hello world example. The Jamfile is a minimalist bjam script that builds the DLLs for us.
Before anything else, you should have the bjam executable in your boost -directory. Pre-built Boost.Jam executables are available for most +directory. Pre-built Boost.Jam executables are available for some platforms. For example, a pre-built Microsoft Windows bjam executable can be downloaded here. The complete list of bjam pre-built executables can be found here.
-
Here is our minimalist Jamfile:
subproject libs/python/example/tutorial ;
@@ -103,9 +99,8 @@ Python modules. Example:
The above assumes that the Python installation is in c:/dev/tools/python
-and that we are using Python version 2.2. You'll have to tweak this path
-appropriately.
Be sure not to include a third number, e.g. not "2.2.1",
-even if that's the version you have.
Now we are ready... Be sure to cd to libs/python/example/tutorial where the tutorial "hello.cpp" and the "Jamfile" is situated.
@@ -144,10 +139,6 @@ And so on... Finally:If all is well, you should now have:
-if you are on Windows, and
--if you are on Unix.
-boost_python.dll can be found somewhere in libs\python\build\bin while hello.pyd can be found somewhere in libs\python\example\tutorial\bin. After a successful build, you can just diff --git a/doc/tutorial/doc/call_policies.html b/doc/tutorial/doc/call_policies.html index 194097df..f0decf84 100644 --- a/doc/tutorial/doc/call_policies.html +++ b/doc/tutorial/doc/call_policies.html @@ -142,7 +142,7 @@ or more policies can be composed by chaining. Here's the general syntax:
Here is the list of predefined call policies. A complete reference detailing -these can be found +these can be found here.
![]() |
![]() |
diff --git a/doc/tutorial/doc/class_virtual_functions.html b/doc/tutorial/doc/class_virtual_functions.html
index 72c3fe3d..dea828c4 100644
--- a/doc/tutorial/doc/class_virtual_functions.html
+++ b/doc/tutorial/doc/class_virtual_functions.html
@@ -92,16 +92,15 @@ polymorphically from C++.
+ Beware the common pitfall of
+forgetting that the constructors of most of Python's mutable types
+make copies, just as in Python.+ + dict d(x.attr("__dict__")); # makes a copy of x's dict + d['whatever'] = 3; # modifies a copy of x.__dict__ (not the original) + |
+
Due to the dynamic nature of Boost.Python objects, any class_<T> may
also be one of these types! The following code snippet wraps the class
diff --git a/doc/tutorial/doc/quickstart.txt b/doc/tutorial/doc/quickstart.txt
index a8176ec1..ecf3b87d 100644
--- a/doc/tutorial/doc/quickstart.txt
+++ b/doc/tutorial/doc/quickstart.txt
@@ -65,15 +65,10 @@ After this brief ['bjam] tutorial, we should have built two DLLs:
* boost_python.dll
* hello.pyd
-if you are on Windows, and
-
-* libboost_python.so
-* hello.so
-
-if you are on Unix.
+This assumes of course that we are running on Windows.
The tutorial example can be found in the directory:
-[^libs/python/example/tutorial]. There, you can find:
+[^/libs/python/example/tutorial]. There, you can find:
* hello.cpp
* Jamfile
@@ -82,13 +77,12 @@ The [^hello.cpp] file is our C++ hello world example. The [^Jamfile] is a
minimalist ['bjam] script that builds the DLLs for us.
Before anything else, you should have the bjam executable in your boost
-directory. Pre-built Boost.Jam executables are available for most
+directory. Pre-built Boost.Jam executables are available for some
platforms. For example, a pre-built Microsoft Windows bjam executable can
be downloaded [@http://boost.sourceforge.net/jam-executables/bin.ntx86/bjam.zip here].
The complete list of bjam pre-built executables can be found [@../../../../../tools/build/index.html#Jam here].
[h2 Lets Jam!]
-[$theme/jam.png]
Here is our minimalist Jamfile:
@@ -147,9 +141,8 @@ Python modules. Example:
set PYTHON_VERSION=2.2
The above assumes that the Python installation is in [^c:/dev/tools/python]
-and that we are using Python version 2.2. You'll have to tweak this path
-appropriately. __note__ Be sure not to include a third number, e.g. [*not] "2.2.1",
-even if that's the version you have.
+and that we are using Python version 2.2. Be sure not to include a third
+number, e.g. [*not] "2.2.1", even if that's the version you have.
Now we are ready... Be sure to [^cd] to [^libs/python/example/tutorial]
where the tutorial [^"hello.cpp"] and the [^"Jamfile"] is situated.
@@ -193,13 +186,6 @@ If all is well, you should now have:
* boost_python.dll
* hello.pyd
-if you are on Windows, and
-
-* libboost_python.so
-* hello.so
-
-if you are on Unix.
-
[^boost_python.dll] can be found somewhere in [^libs\python\build\bin]
while [^hello.pyd] can be found somewhere in
[^libs\python\example\tutorial\bin]. After a successful build, you can just
@@ -290,7 +276,7 @@ expose instead.
[^init Revised
-
- 05 November, 2002
-
- © Copyright Dave Abrahams
- 2002. All Rights Reserved. Dave Abrahams is
+ the architect, designer, and implementor of Boost.Python. Joel de Guzman implemented the default
+ argument support and wrote the excellent tutorial documentation. Ralf W.
+ Grosse-Kunstleve implemented the pickle
+ support, and has enthusiastically supported the library since its
+ birth, contributing to design decisions and providing invaluable
+ real-world insight into user requirements. Ralf has written some
+ extensions for converting C++ containers that I hope will be incorporated
+ into the library soon. He also implemented the cross-module support in
+ the first version of Boost.Python. More importantly, Ralf makes sure
+ nobody forgets the near-perfect synergy of C++ and Python for solving the
+ problems of large-scale software construction. Achim Domma contributed some
+ of the Object Wrappers and
+ HTML templates for this documentation. Dave Hawkes contributed
+ inspiration for the use of the Martin Casado solved some sticky problems which allow us to build the
+ Boost.Python shared library for AIX's crazy dynamic linking model. The development of this version of Boost.Python was funded in part by
+ the Lawrence Livermore National
+ Laboratories and by the Computational
+ Crystallography Initiative at Lawrence Berkeley National
+ Laboratories. Ullrich
+ Koethe provided the implementation of inheritance and special
+ method/operator support in the first version of Boost.Python. The first version of Boost.Python would not have been possible without
+ the support of Dragon Systems, which supported its development and
+ release as a Boost library. Revised
+
+ 08 October, 2002
+
+ © Copyright Dave Abrahams 2002. All Rights
+ Reserved.
+
+
+
+
+
+
-
-
-
-
-
-
- 
-
- Boost.Python
- Acknowledgments
-
-{{text}}
-
-
+
+
+
+
+
+ 
+
+ Boost.Python
+
+ Acknowledgments
+
+
+ scope class to simplify module
+ definition syntax. Pearu Pearson wrote some of the test cases that are in
+ the current test suite.
+
+