Skip to content

Commit 617bcda

Browse files
dabrahamsdabrahams
committed
Major doc updates
[SVN r9470]
1 parent 116b3db commit 617bcda

14 files changed

Lines changed: 552 additions & 294 deletions

‎doc/building.html‎

Lines changed: 154 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,157 @@
1-
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN"
2-
"http://www.w3.org/TR/REC-html40/strict.dtd">
3-
<title>
4-
Building an Extension Module
5-
</title>
1+
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2+
3+
<meta name="generator" content="HTML Tidy, see www.w3.org">
4+
5+
<title>Building an Extension Module</title>
6+
67
<div>
7-
<h1>
8-
<img width="277" height="86" id="_x0000_i1025" align="center"
9-
src="../../../c++boost.gif" alt= "c++boost.gif (8819 bytes)">Building an Extension Module
10-
</h1>
11-
<p>
12-
Right now, the only supported configuration is one in which the BPL
13-
source files are statically linked with the source for your extension
14-
module. You may first build them into a library and link it with your
15-
extension module source, but the effect is the same as compiling all
16-
the source files together. Some users have successfully built the
17-
sources into a shared library, and support for a shared library
18-
build is planned, but not yet implemented. The BPL source files are:
19-
<blockquote>
20-
<pre>
21-
<a href="../../../libs/python/src/extension_class.cpp">extclass.cpp</a>
22-
<a href="../../../libs/python/src/functions.cpp">functions.cpp</a>
23-
<a href="../../../libs/python/src/init_function.cpp">init_function.cpp</a>
24-
<a href="../../../libs/python/src/module_builder.cpp">module.cpp</a>
25-
<a href="../../../libs/python/src/types.cpp">newtypes.cpp</a>
26-
<a href="../../../libs/python/src/objects.cpp">objects.cpp</a>
27-
<a href="../../../libs/python/src/conversions.cpp">py.cpp</a>
28-
<a href="../../../libs/python/src/classes.cpp">subclass.cpp</a>
29-
</pre>
30-
</blockquote>
31-
<p>
32-
Next: <a href="enums.html">Enums</a>
33-
Previous: <a href="under-the-hood.html">A Peek Under the Hood</a>
34-
Up: <a href="index.html">Top</a>
35-
<p>
36-
&copy; Copyright David Abrahams 2000. Permission to copy, use, modify,
37-
sell and distribute this document is granted provided this copyright
38-
notice appears in all copies. This document is provided ``as
39-
is'' without express or implied warranty, and with no claim as to
40-
its suitability for any purpose.
41-
<p>
42-
Updated: Nov 26, 2000
8+
<h1><img width="277" height="86" id="_x0000_i1025" align="center" src=
9+
"../../../c++boost.gif" alt="c++boost.gif (8819 bytes)">Building an
10+
Extension Module</h1>
11+
12+
<p>The build process for Boost is currently undergoing some evolution,
13+
and, it is to be hoped, improvement. The following facts may help:
14+
15+
<ul>
16+
<li>
17+
Makefiles for various platforms reside in the Boost subdirectory
18+
<tt>libs/python/build</tt>:
19+
20+
<ul>
21+
<li><a href="../build/como.mak">como.mak</a> (Comeau C++ on Linux)
22+
23+
<li><a href="../build/linux_gcc.mak">linux_gcc.mak</a> (GCC on
24+
Linux/Unix)
25+
26+
<li><a href="../build/gcc.mak">gcc.mak</a> (older makefile for GCC
27+
on Linux/Unix. Deprecated.)
28+
29+
<li><a href="../build/mingw32.mak">mingw32.mak</a>
30+
(highly-specialized makefile for mingw32 (Win32-targeted) GCC. Read
31+
the header comment).
32+
33+
<li><a href="../build/tru64_cxx.mak">tru64_cxx.mak</a> (Compaq
34+
Alpha).
35+
</ul>
36+
<br>
37+
38+
<li>
39+
A project workspace for Microsoft Visual Studio is provided at <tt><a
40+
href="../build/build.dsw">libs/python/build/build.dsw</a></tt>. The
41+
include paths for this project may need to be changed for your
42+
installation. They currently assume that python has been installed at
43+
<tt>c:\tools\python</tt>. Three configurations of all targets are
44+
supported:
45+
46+
<ul>
47+
<li>Release (optimization, <tt>-DNDEBUG</tt>)
48+
49+
<li>Debug (no optimization <tt>-D_DEBUG</tt>)
50+
51+
<li>DebugPython (no optimization, <tt>-D_DEBUG
52+
-DBOOST_DEBUG_PYTHON</tt>)
53+
</ul>
54+
55+
<p>When extension modules are built with Visual C++ using
56+
<tt>-D_DEBUG</tt>, Python defaults to <i>force</i> linking with a
57+
special debugging version of the Python DLL. Since this debug DLL
58+
isn't supplied with the default Python installation for Windows,
59+
Boost.Python uses <tt><a href=
60+
"../../boost/python/detail/wrap_python.hpp">boost/python/detail/wrap_python.hpp</a></tt>
61+
to temporarily undefine <tt>_DEBUG</tt> when <tt>Python.h</tt> is
62+
<tt>#include</tt>d.
63+
64+
<p>If you want the extra runtime checks available with the debugging
65+
version of the library, <tt>#define BOOST_DEBUG_PYTHON</tt> to
66+
re-enable library forcing, and link with the DebugPython version of
67+
<tt>boost_python.lib</tt>. You'll need to get the debugging version
68+
of the Python executable (<tt>python_d.exe</tt>) and DLL
69+
(<tt>python20_d.dll</tt> or <tt>python15_d.dll</tt>). The Python
70+
sources include project files for building these. If you <a href=
71+
"http://www.python.org">download</a> them, change the name of the
72+
top-level directory to <tt>src</tt>, and install it under
73+
<tt>c:\tools\python</tt>, the workspace supplied by Boost.Python will
74+
be able to use it without modification. Just open
75+
<tt>c:\tools\python\src\pcbuild\pcbuild.dsw</tt> and invoke "build
76+
all" to generate all the debugging targets.
77+
78+
<p>If you do not <tt>#define BOOST_DEBUG_PYTHON</tt>, be sure that
79+
any source files <tt>#include &lt;<a href=
80+
"../../boost/python/detail/wrap_python.hpp">boost/python/detail/wrap_python.hpp</a>&gt;</tt>
81+
instead of the usual <tt>Python.h</tt>, or you will have link
82+
incompatibilities.<br>
83+
<br>
84+
85+
86+
<li>
87+
The makefiles and Visual Studio project can all build at least the
88+
following:
89+
90+
<ul>
91+
<li>The <tt>boost_python</tt> library for static linking with your
92+
extension module. On the various Unices, this library will be
93+
called <tt>libboost_python.a</tt>. On Win32 platforms, the library
94+
will be called <tt>boost_python.lib</tt>.
95+
96+
<li>A comprehensive test of Boost.Python features. This test builds
97+
a Boost.Python extension module, then runs Python to import the
98+
module, and runs a series of tests on it using <tt><a href=
99+
"../test/doctest.py">doctest</a></tt>. Source code for the module
100+
and tests is available in the Boost subdirectory
101+
<tt>libs/python/test</tt>.<br>
102+
103+
104+
<li>Various examples from the Boost subdirectory
105+
<tt>libs/python/example</tt>. Which examples are built currently
106+
depends on the platform. The most up-to-date examples are
107+
<tt>getting_started</tt><i>n</i><tt>.cpp</tt> from <a href=
108+
"http://cci.lbl.gov/staff/ralf_grosse-kunstleve.html">Ralf W.
109+
Grosse-Kunstleve</a>. All these examples include a doctest modeled
110+
on the comprehensive test above.<br>
111+
<br>
112+
113+
</ul>
114+
115+
<li>
116+
If your platform isn't directly supported, you can build a static
117+
library from the following source files (in the Boost subdirectory
118+
<tt>libs/python/src</tt>), or compile them directly and link the
119+
resulting objects into your extension module:
120+
121+
<ul>
122+
<li><a href=
123+
"../../../libs/python/src/extension_class.cpp">extension_class.cpp</a>
124+
125+
<li><a href=
126+
"../../../libs/python/src/functions.cpp">functions.cpp</a>
127+
128+
<li><a href=
129+
"../../../libs/python/src/init_function.cpp">init_function.cpp</a>
130+
131+
<li><a href=
132+
"../../../libs/python/src/module_builder.cpp">module_builder.cpp</a>
133+
134+
<li><a href="../../../libs/python/src/types.cpp">types.cpp</a>
135+
136+
<li><a href="../../../libs/python/src/objects.cpp">objects.cpp</a>
137+
138+
<li><a href=
139+
"../../../libs/python/src/conversions.cpp">conversions.cpp</a>
140+
141+
<li><a href="../../../libs/python/src/classes.cpp">classes.cpp</a>
142+
</ul>
143+
</ul>
144+
145+
<p>Next: <a href="enums.html">Wrapping Enums</a> Previous: <a href=
146+
"under-the-hood.html">A Peek Under the Hood</a> Up: <a href=
147+
"index.html">Top</a>
148+
149+
<p>&copy; Copyright David Abrahams 2000. Permission to copy, use, modify,
150+
sell and distribute this document is granted provided this copyright
151+
notice appears in all copies. This document is provided ``as is'' without
152+
express or implied warranty, and with no claim as to its suitability for
153+
any purpose.
154+
155+
<p>Updated: Mar 6, 2001
43156
</div>
44157

‎doc/comparisons.html‎

Lines changed: 36 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,14 @@
66
<div>
77
<h1>
88
<img width="277" height="86" id="_x0000_i1025" align="center"
9-
src="../../../c++boost.gif" alt= "c++boost.gif (8819 bytes)">Comparisons with
9+
src="../../../c++boost.gif" alt= "c++boost.gif (8819 bytes)"><br>
10+
Comparisons with
1011
Other Systems
1112
</h1>
1213

1314
<h2>CXX</h2>
1415
<p>
15-
Like BPL, <a href="http://cxx.sourceforge.net/">CXX</a> attempts to
16+
Like Boost.Python, <a href="http://cxx.sourceforge.net/">CXX</a> attempts to
1617
provide a C++-oriented interface to Python. In most cases, as with the
1718
boost library, it relieves the user from worrying about
1819
reference-counts. Both libraries automatically convert thrown C++
@@ -40,9 +41,15 @@ <h2>CXX</h2>
4041
<p>
4142
As far as I can tell, CXX enables one to write what is essentially
4243
idiomatic Python code in C++, manipulating Python objects through the
43-
same fully-generic interfaces we use in Python. While you're hardly programming directly to the ``bare
44-
metal'' with CXX, it basically presents a ``C++-ized''
45-
version of the Python 'C' API.
44+
same fully-generic interfaces we use in Python. While you're hardly
45+
programming directly to the ``bare metal'' with CXX, it basically
46+
presents a ``C++-ized'' version of the Python 'C' API. Some fraction of
47+
that capability is available in Boost.Python through <tt><a
48+
href="../../../boost/python/objects.hpp">boost/python/objects.hpp</a></tt>,
49+
which provides C++ objects corresponding to Python lists, tuples,
50+
strings, and dictionaries, and through <tt><a
51+
href="../../../boost/python/callback.hpp">boost/python/callback.hpp</a></tt>,
52+
which allows you to call back into python with C++ arguments.
4653

4754
<p>
4855
<a href="mailto:dubois1@llnl.gov">Paul F. Dubois</a>, the original
@@ -65,7 +72,7 @@ <h2>SWIG</h2>
6572
languages. Swig relies on a parser to read your source code and produce
6673
additional source code files which can be compiled into a Python (or
6774
Perl or Tcl) extension module. It has been successfully used to create
68-
many Python extension modules. Like BPL, SWIG is trying to allow an
75+
many Python extension modules. Like Boost.Python, SWIG is trying to allow an
6976
existing interface to be wrapped with little or no change to the
7077
existing code. The documentation says ``SWIG parses a form of ANSI C
7178
syntax that has been extended with a number of special directives. As a
@@ -78,15 +85,15 @@ <h2>SWIG</h2>
7885
couldnt handle templates, didnt do func overloading properly etc. For
7986
ANSI C libraries this was fine. But for usual C++ code this was a
8087
problem. Simple things work. But for anything very complicated (or
81-
realistic), one had to write code by hand. I believe BPL doesn't have
88+
realistic), one had to write code by hand. I believe Boost.Python doesn't have
8289
this problem[<a href="#sic">sic</a>]... IMHO overloaded functions are very important to
8390
wrap correctly.''<br><i>-Prabhu Ramachandran</i>
8491
</blockquote>
8592

8693
<p>
87-
By contrast, BPL doesn't attempt to parse C++ - the problem is simply
94+
By contrast, Boost.Python doesn't attempt to parse C++ - the problem is simply
8895
too complex to do correctly. <a name="sic">Technically</a>, one does
89-
write code by hand to use BPL. The goal, however, has been to make
96+
write code by hand to use Boost.Python. The goal, however, has been to make
9097
that code nearly as simple as listing the names of the classes and
9198
member functions you want to expose in Python.
9299

@@ -95,7 +102,7 @@ <h2>SIP</h2>
95102
<a
96103
href="http://www.thekompany.com/projects/pykde/background.php3?dhtml_ok=1">SIP</a>
97104
is a system similar to SWIG, though seemingly more
98-
C++-oriented. The author says that like BPL, SIP supports overriding
105+
C++-oriented. The author says that like Boost.Python, SIP supports overriding
99106
extension class member functions in Python subclasses. It appears to
100107
have been designed specifically to directly support some features of
101108
PyQt/PyKDE, which is its primary client. Documentation is almost
@@ -113,7 +120,7 @@ <h2>ILU</h2>
113120
to a wide range of computer languages, including Common Lisp, C++, C,
114121
Modula-3, and Python. ILU can parse the ISL to generate a C++ language
115122
header file describing the interface, of which the user is expected to
116-
provide an implementation. Unlike BPL, this means that the system
123+
provide an implementation. Unlike Boost.Python, this means that the system
117124
imposes implementation details on your C++ code at the deepest level. It
118125
is worth noting that some of the C++ names generated by ILU are supposed
119126
to be reserved to the C++ implementation. It is unclear from the
@@ -148,7 +155,7 @@ <h2>GRAD</h2>
148155
<h2>Zope ExtensionClasses</h2>
149156
<p>
150157
<a href="http:http://www.digicool.com/releases/ExtensionClass">
151-
ExtensionClasses in Zope</a> use the same underlying mechanism as BPL
158+
ExtensionClasses in Zope</a> use the same underlying mechanism as Boost.Python
152159
to support subclassing of extension types in Python, including
153160
multiple-inheritance. Both systems support pickling/unpickling of
154161
extension class instances in very similar ways. Both systems rely on the
@@ -158,31 +165,35 @@ <h2>Zope ExtensionClasses</h2>
158165
<p>
159166
The major differences are:
160167
<ul>
168+
<li>Zope is entirely 'C' language-based. It doesn't require a C++
169+
compiler, so it's much more portable than Boost.Python, which stresses
170+
the limits of even some modern C++ implementations.
171+
161172
<li>
162-
BPL lifts the burden on the user to parse and convert function
173+
Boost.Python lifts the burden on the user to parse and convert function
163174
argument types. Zope provides no such facility.
164175
<li>
165-
BPL lifts the burden on the user to maintain Python
176+
Boost.Python lifts the burden on the user to maintain Python
166177
reference-counts.
167178
<li>
168-
BPL supports function overloading; Zope does not.
179+
Boost.Python supports function overloading; Zope does not.
169180
<li>
170-
BPL supplies a simple mechanism for exposing read-only and
181+
Boost.Python supplies a simple mechanism for exposing read-only and
171182
read/write access to data members of the wrapped C++ type as Python
172183
attributes.
173184
<li>
174185
Writing a Zope ExtensionClass is significantly more complex than
175-
exposing a C++ class to python using BPL (mostly a summary of the
186+
exposing a C++ class to python using Boost.Python (mostly a summary of the
176187
previous 4 items). <a href=
177188
"http://www.digicool.com/releases/ExtensionClass/MultiMapping.html">A
178189
Zope Example</a> illustrates the differences.
179190
<li>
180191
Zope's ExtensionClasses are specifically motivated by ``the need for a
181-
C-based persistence mechanism''. BPL's are motivated by the desire
192+
C-based persistence mechanism''. Boost.Python's are motivated by the desire
182193
to simply reflect a C++ API into Python with as little modification as
183194
possible.
184195
<li>
185-
The following Zope restriction does not apply to BPL: ``At most one
196+
The following Zope restriction does not apply to Boost.Python: ``At most one
186197
base extension direct or indirect super class may define C data
187198
members. If an extension subclass inherits from multiple base
188199
extension classes, then all but one must be mix-in classes that
@@ -191,21 +202,21 @@ <h2>Zope ExtensionClasses</h2>
191202
Zope requires use of the somewhat funky inheritedAttribute (search for
192203
``inheritedAttribute'' on <a
193204
href="http://www.digicool.com/releases/ExtensionClass">this page</a>)
194-
method to access base class methods. In BPL, base class methods can
205+
method to access base class methods. In Boost.Python, base class methods can
195206
be accessed in the usual way by writing
196207
``<code>BaseClass.method</code>''.
197208
<li>
198209
Zope supplies some creative but esoteric idioms such as <a href=
199210
"http://www.digicool.com/releases/ExtensionClass/Acquisition.html">
200-
Acquisition</a>. No specific support for this is built into BPL.
211+
Acquisition</a>. No specific support for this is built into Boost.Python.
201212
<li>
202213
Zope's ComputedAttribute support is designed to be used from Python.
203214
<a href="special.html#getter_setter">The analogous feature of
204-
BPL</a> can be used from C++ or Python. The feature is arguably
205-
easier to use in BPL.
215+
Boost.Python</a> can be used from C++ or Python. The feature is arguably
216+
easier to use in Boost.Python.
206217
</ul>
207218
<p>
208-
Next: <a href="example1.html">A Simple Example Using BPL</a>
219+
Next: <a href="example1.html">A Simple Example Using Boost.Python</a>
209220
Previous: <a href="extending.html">A Brief Introduction to writing Python Extension Modules</a>
210221
Up: <a href="index.html">Top</a>
211222
<p>
@@ -215,6 +226,6 @@ <h2>Zope ExtensionClasses</h2>
215226
express or implied warranty, and with no claim as to its suitability
216227
for any purpose.
217228
<p>
218-
Updated: Nov 26, 2000
229+
Updated: Mar 6, 2001
219230
</div>
220231

0 commit comments

Comments
 (0)