Tutorial Updates for Building BPL Projects

[SVN r28889]
2026-01-19 16:32:16 +00:00 · 2005-05-14 02:50:34 +00:00
parent 4cec6c4f2f
commit 3ce88daa8b
11 changed files with 272 additions and 2774 deletions
--- a/doc/tutorial/doc/html/index.html
+++ b/doc/tutorial/doc/html/index.html
@@ -30,7 +30,7 @@
 </h3></div></div>
 <div><p class="copyright">Copyright © 2002-2005 Joel de Guzman, David Abrahams</p></div>
 <div><div class="legalnotice">
-<a name="id446800"></a><p>
+<a name="id376623"></a><p>
        Distributed under the Boost Software License, Version 1.0.
        (See accompanying file LICENSE_1_0.txt or copy at
        <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">
@@ -96,7 +96,7 @@ metaprogramming techniques simplifies its syntax for users, so that
 wrapping code takes on the look of a kind of declarative interface
 definition language (IDL).</p>
 <a name="quickstart.hello_world"></a><h2>
-<a name="id376135"></a>Hello World</h2>
+<a name="id376137"></a>Hello World</h2>
 <p>
 Following C/C++ tradition, let's start with the "hello, world". A C++
 Function:</p>
@@ -125,7 +125,7 @@ hello</span><span class="special">,</span><span class="identifier"> world</span>
 </div>
 </div>
 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left"><small><p>Last revised: May 02, 2005 at 15:44:52 GMT</p></small></td>
+<td align="left"><small><p>Last revised: May 14, 2005 at 02:47:50 GMT</p></small></td>
 <td align="right"><small></small></td>
 </tr></table>
 <hr>
--- a/doc/tutorial/doc/html/python/embedding.html
+++ b/doc/tutorial/doc/html/python/embedding.html
@@ -39,7 +39,7 @@ the gaps. However, Boost.Python already makes embedding a lot easier and,
 in a future version, it may become unnecessary to touch the Python/C API at
 all. So stay tuned... <span class="inlinemediaobject"><img src="../images/smiley.png"></span></p>
 <a name="embedding.building_embedded_programs"></a><h2>
-<a name="id460673"></a>Building embedded programs</h2>
+<a name="id460594"></a>Building embedded programs</h2>
 <p>
 To be able to use embedding in your programs, they have to be linked to
 both Boost.Python's and Python's static link library.</p>
@@ -61,21 +61,21 @@ include path.</p>
 In a Jamfile, all the above boils down to:</p>
 <pre class="programlisting"><tt class="literal">projectroot c:\projects\embedded_program ; # location of the program

-    # bring in the rules for python
-    SEARCH on python.jam = $(BOOST_BUILD_PATH) ;
-    include python.jam ;
+# bring in the rules for python
+SEARCH on python.jam = $(BOOST_BUILD_PATH) ;
+include python.jam ;

-    exe embedded_program # name of the executable
-      : #sources
-         embedded_program.cpp
-      : # requirements
-         &lt;find-library&gt;boost_python &lt;library-path&gt;c:\boost\libs\python
-      $(PYTHON_PROPERTIES)
-        &lt;library-path&gt;$(PYTHON_LIB_PATH)
-        &lt;find-library&gt;$(PYTHON_EMBEDDED_LIBRARY) ;
+exe embedded_program # name of the executable
+  : #sources
+     embedded_program.cpp
+  : # requirements
+     &lt;find-library&gt;boost_python &lt;library-path&gt;c:\boost\libs\python
+  $(PYTHON_PROPERTIES)
+    &lt;library-path&gt;$(PYTHON_LIB_PATH)
+    &lt;find-library&gt;$(PYTHON_EMBEDDED_LIBRARY) ;
 </tt></pre>
 <a name="embedding.getting_started"></a><h2>
-<a name="id460764"></a>Getting started</h2>
+<a name="id460675"></a>Getting started</h2>
 <p>
 Being able to build is nice, but there is nothing to build yet. Embedding
 the Python interpreter into one of your C++ programs requires these 4
@@ -110,7 +110,7 @@ messy and especially hard to get right in the presence of C++ exceptions.
 Fortunately Boost.Python provides the <a href="../../../../v2/handle.html" target="_top">handle</a> and
 <a href="../../../../v2/object.html" target="_top">object</a> class templates to automate the process.</p>
 <a name="using_the_interpreter.reference_counting_handles_and_objects"></a><h2>
-<a name="id460895"></a>Reference-counting handles and objects</h2>
+<a name="id460807"></a>Reference-counting handles and objects</h2>
 <p>
 There are two ways in which a function in the Python/C API can return a
 <tt class="literal">PyObject*</tt>: as a <span class="emphasis"><em>borrowed reference</em></span> or as a <span class="emphasis"><em>new reference</em></span>. Which of
@@ -141,7 +141,7 @@ discuss in the next section.</p>
 </td></tr></tbody>
 </table></div>
 <a name="using_the_interpreter.running_python_code"></a><h2>
-<a name="id461200"></a>Running Python code</h2>
+<a name="id461112"></a>Running Python code</h2>
 <p>
 To run Python code from C++ there is a family of functions in the API
 starting with the PyRun prefix. You can find the full list of these
@@ -156,7 +156,7 @@ The <tt class="literal">start</tt> parameter is the start symbol from the Python
 for interpreting the code. The possible values are:</p>
 <div class="informaltable">
 <h4>
-<a name="id461362"></a><span class="table-title">Start symbols</span>
+<a name="id461274"></a><span class="table-title">Start symbols</span>
 </h4>
 <table class="table">
 <colgroup>
@@ -224,7 +224,7 @@ containing a phrase that is well-known in programming circles.</p>
 </td></tr></tbody>
 </table></div>
 <a name="using_the_interpreter.beyond_handles"></a><h2>
-<a name="id461811"></a>Beyond handles</h2>
+<a name="id461723"></a>Beyond handles</h2>
 <p>
 It's nice that <tt class="literal">handle</tt> manages the reference counting details for us, but
 other than that it doesn't do much. Often we'd like to have a more useful
@@ -271,7 +271,7 @@ int</span><span class="identifier"> five_squared</span><span class="special"> =<
 </td></tr></tbody>
 </table></div>
 <a name="using_the_interpreter.exception_handling"></a><h2>
-<a name="id462393"></a>Exception handling</h2>
+<a name="id462304"></a>Exception handling</h2>
 <p>
 If an exception occurs in the execution of some Python code, the <a href="http://www.python.org/doc/current/api/veryhigh.html#l2h-55" target="_top">PyRun_String</a>
 function returns a null pointer. Constructing a <tt class="literal">handle</tt> out of this null
--- a/doc/tutorial/doc/html/python/exposing.html
+++ b/doc/tutorial/doc/html/python/exposing.html
@@ -396,7 +396,7 @@ Calling <tt class="literal">derived.f()</tt>:</p>
 <div class="titlepage"><div><div><h3 class="title">
 <a name="python.class_operators_special_functions"></a>Class Operators/Special Functions</h3></div></div></div>
 <a name="class_operators_special_functions.python_operators"></a><h2>
-<a name="id451998"></a>Python Operators</h2>
+<a name="id451926"></a>Python Operators</h2>
 <p>
 C is well known for the abundance of operators. C++ extends this to the
 extremes by allowing operator overloading. Boost.Python takes advantage of
@@ -434,7 +434,7 @@ you might need to interact with in an operator expression is (cheaply)
 default-constructible. You can use <tt class="literal">other&lt;T&gt;()</tt> in place of an actual
 <tt class="literal">T</tt> instance when writing "self expressions".</p>
 <a name="class_operators_special_functions.special_methods"></a><h2>
-<a name="id452685"></a>Special Methods</h2>
+<a name="id452613"></a>Special Methods</h2>
 <p>
 Python has a few more <span class="emphasis"><em>Special Methods</em></span>. Boost.Python supports all of the
 standard special method names supported by real Python class instances. A
--- a/doc/tutorial/doc/html/python/functions.html
+++ b/doc/tutorial/doc/html/python/functions.html
@@ -43,26 +43,26 @@ overloading and default arguments.</p>
 But before you do, you might want to fire up Python 2.2 or later and type
 <tt class="literal">&gt;&gt;&gt; import this</tt>.</p>
 <pre class="programlisting"><tt class="literal">&gt;&gt;&gt; import this
-    The Zen of Python, by Tim Peters
-    Beautiful is better than ugly.
-    Explicit is better than implicit.
-    Simple is better than complex.
-    Complex is better than complicated.
-    Flat is better than nested.
-    Sparse is better than dense.
-    Readability counts.
-    Special cases aren't special enough to break the rules.
-    Although practicality beats purity.
-    Errors should never pass silently.
-    Unless explicitly silenced.
-    In the face of ambiguity, refuse the temptation to guess.
-    There should be one-- and preferably only one --obvious way to do it
-    Although that way may not be obvious at first unless you're Dutch.
-    Now is better than never.
-    Although never is often better than <span class="bold"><b>right</b></span> now.
-    If the implementation is hard to explain, it's a bad idea.
-    If the implementation is easy to explain, it may be a good idea.
-    Namespaces are one honking great idea -- let's do more of those!
+The Zen of Python, by Tim Peters
+Beautiful is better than ugly.
+Explicit is better than implicit.
+Simple is better than complex.
+Complex is better than complicated.
+Flat is better than nested.
+Sparse is better than dense.
+Readability counts.
+Special cases aren't special enough to break the rules.
+Although practicality beats purity.
+Errors should never pass silently.
+Unless explicitly silenced.
+In the face of ambiguity, refuse the temptation to guess.
+There should be one-- and preferably only one --obvious way to do it
+Although that way may not be obvious at first unless you're Dutch.
+Now is better than never.
+Although never is often better than <span class="bold"><b>right</b></span> now.
+If the implementation is hard to explain, it's a bad idea.
+If the implementation is easy to explain, it may be a good idea.
+Namespaces are one honking great idea -- let's do more of those!
 </tt></pre>
 <div class="section" lang="en">
 <div class="titlepage"><div><div><h3 class="title">
@@ -174,7 +174,7 @@ A reference to <tt class="literal">y.x</tt> is returned
 <li><span class="bold"><b>BOOM!</b></span></li>
 </ol></div>
 <a name="call_policies.call_policies"></a><h2>
-<a name="id454356"></a>Call Policies</h2>
+<a name="id454278"></a>Call Policies</h2>
 <p>
 Call Policies may be used in situations such as the example detailed above.
 In our example, <tt class="literal">return_internal_reference</tt> and <tt class="literal">with_custodian_and_ward</tt>
@@ -336,7 +336,7 @@ are overloaded with a common sequence of initial arguments
 </li>
 </ul></div>
 <a name="default_arguments.boost_python_function_overloads"></a><h2>
-<a name="id456178"></a>BOOST_PYTHON_FUNCTION_OVERLOADS</h2>
+<a name="id456100"></a>BOOST_PYTHON_FUNCTION_OVERLOADS</h2>
 <p>
 Boost.Python now has a way to make it easier. For instance, given a function:</p>
 <pre class="programlisting"><tt class="literal"><span class="keyword">int</span><span class="identifier"> foo</span><span class="special">(</span><span class="keyword">int</span><span class="identifier"> a</span><span class="special">,</span><span class="keyword"> char</span><span class="identifier"> b</span><span class="special"> =</span><span class="number"> 1</span><span class="special">,</span><span class="keyword"> unsigned</span><span class="identifier"> c</span><span class="special"> =</span><span class="number"> 2</span><span class="special">,</span><span class="keyword"> double</span><span class="identifier"> d</span><span class="special"> =</span><span class="number"> 3</span><span class="special">)</span><span class="special">
@@ -355,7 +355,7 @@ and the maximum number of arguments is 4. The <tt class="literal">def(...)</tt>
 automatically add all the foo variants for us:</p>
 <pre class="programlisting"><tt class="literal"><span class="identifier">def</span><span class="special">(</span><span class="string">"foo"</span><span class="special">,</span><span class="identifier"> foo</span><span class="special">,</span><span class="identifier"> foo_overloads</span><span class="special">());</span></tt></pre>
 <a name="default_arguments.boost_python_member_function_overloads"></a><h2>
-<a name="id456457"></a>BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</h2>
+<a name="id456379"></a>BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS</h2>
 <p>
 Objects here, objects there, objects here there everywhere. More frequently
 than anything else, we need to expose member functions of our classes to
@@ -387,7 +387,7 @@ fourth macro argument). The thin wrappers are all enclosed in a class named
 See the <a href="../../../../v2/overloads.html#BOOST_PYTHON_FUNCTION_OVERLOADS-spec" target="_top">overloads reference</a>
 for details.</p>
 <a name="default_arguments.init_and_optional"></a><h2>
-<a name="id456784"></a>init and optional</h2>
+<a name="id456707"></a>init and optional</h2>
 <p>
 A similar facility is provided for class constructors, again, with
 default arguments or a sequence of overloads. Remember <tt class="literal">init&lt;...&gt;</tt>? For example,
@@ -442,7 +442,7 @@ Then...</p>
 Notice though that we have a situation now where we have a minimum of zero
 (0) arguments and a maximum of 3 arguments.</p>
 <a name="auto_overloading.manual_wrapping"></a><h2>
-<a name="id457431"></a>Manual Wrapping</h2>
+<a name="id457353"></a>Manual Wrapping</h2>
 <p>
 It is important to emphasize however that <span class="bold"><b>the overloaded functions must
 have a common sequence of initial arguments</b></span>. Otherwise, our scheme above
--- a/doc/tutorial/doc/html/python/hello.html
+++ b/doc/tutorial/doc/html/python/hello.html
@@ -26,7 +26,7 @@
 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 <a name="python.hello"></a> Building Hello World</h2></div></div></div>
 <a name="hello.from_start_to_finish"></a><h2>
-<a name="id378425"></a>From Start To Finish</h2>
+<a name="id378500"></a>From Start To Finish</h2>
 <p>
 Now the first thing you'd want to do is to build the Hello World module and
 try it for yourself in Python. In this section, we shall outline the steps
@@ -93,55 +93,65 @@ the command line. Pre-built Boost.Jam executables are available for most
 platforms. The complete list of Bjam executables can be found
 <a href="http://sourceforge.net/project/showfiles.php?group_id=7586" target="_top">here</a>.</p>
 <a name="hello.let_s_jam_"></a><h2>
-<a name="id377025"></a>Let's Jam!</h2>
+<a name="id377104"></a>Let's Jam!</h2>
 <p><span class="inlinemediaobject"><img src="../images/jam.png"></span></p>
 <p>
 Here is our minimalist Jamfile:</p>
-<pre class="programlisting"><tt class="literal">subproject libs/python/example/tutorial ;
+<pre class="programlisting"><tt class="literal"># This is the top of our own project tree
+project-root ;

-    SEARCH on python.jam = $(BOOST_BUILD_PATH) ;
-    include python.jam ;
+import python ;

-    extension hello                     # Declare a Python extension called hello
-    :   hello.cpp                       # source
-        &lt;dll&gt;../../build/boost_python   # dependencies
-        ;
+extension hello                     # Declare a Python extension called hello
+:   hello.cpp                       # source
+    # requirements and dependencies for Boost.Python extensions
+    &lt;template&gt;@boost/libs/python/build/extension
+    ;
 </tt></pre>
 <p>
-First, we need to specify our location in the boost project hierarchy.
-It so happens that the tutorial example is located in <tt class="literal">/libs/python/example/tutorial</tt>.
-Thus:</p>
-<pre class="programlisting"><tt class="literal">subproject libs/python/example/tutorial ;
+First, we need to specify our location. You may place your project anywhere.
+<tt class="literal">project-root</tt> allows you to do that.</p>
+<pre class="programlisting"><tt class="literal">project-root ;
 </tt></pre>
 <p>
-Then we will include the definitions needed by Python modules:</p>
-<pre class="programlisting"><tt class="literal">SEARCH on python.jam = $(BOOST_BUILD_PATH) ;
-    include python.jam ;
+By doing so, you'll need a Jamrules file. Simply copy the one in the 
+<a href="../../../../../example/tutorial/Jamrules" target="_top">example/tutorial directory</a> and tweak 
+the <tt class="literal">path-global BOOST_ROOT</tt> to where your boost root directory is. The file
+has <a href="../../../../../example/tutorial/Jamrules" target="_top">detailed instructions</a> you can follow.</p>
+<p>
+Then we will import the definitions needed by Python modules:</p>
+<pre class="programlisting"><tt class="literal">import python ;
 </tt></pre>
 <p>
 Finally we declare our <tt class="literal">hello</tt> extension:</p>
 <pre class="programlisting"><tt class="literal">extension hello                     # Declare a Python extension called hello
-    :   hello.cpp                       # source
-        &lt;dll&gt;../../build/boost_python   # dependencies
-        ;
+:   hello.cpp                       # source
+
+    # requirements and dependencies for Boost.Python extensions
+    &lt;template&gt;@boost/libs/python/build/extension
+    ;
 </tt></pre>
+<p>
+The last part tells BJam that we are depending on the Boost Python Library.</p>
 <a name="hello.running_bjam"></a><h2>
-<a name="id377119"></a>Running bjam</h2>
+<a name="id377226"></a>Running bjam</h2>
 <p><span class="emphasis"><em>bjam</em></span> is run using your operating system's command line interpreter.</p>
 <div class="blockquote"><blockquote class="blockquote"><p>Start it up.</p></blockquote></div>
 <p>
 Make sure that the environment is set so that we can invoke the C++
 compiler. With MSVC, that would mean running the <tt class="literal">Vcvars32.bat</tt> batch
 file. For instance:</p>
-<pre class="programlisting"><tt class="literal"><span class="identifier">C</span><span class="special">:\</span><span class="identifier">Program</span><span class="identifier"> Files</span><span class="special">\</span><span class="identifier">Microsoft</span><span class="identifier"> Visual</span><span class="identifier"> Studio</span><span class="special">\</span><span class="identifier">VC98</span><span class="special">\</span><span class="identifier">bin</span><span class="special">\</span><span class="identifier">Vcvars32</span><span class="special">.</span><span class="identifier">bat</span></tt></pre>
+<pre class="programlisting"><tt class="literal">C:\Program Files\Microsoft Visual Studio .NET 2003\Common7\Tools\vsvars32.bat
+</tt></pre>
 <p>
 Some environment variables will have to be setup for proper building of our
 Python modules. Example:</p>
-<pre class="programlisting"><tt class="literal"><span class="identifier">set</span><span class="identifier"> PYTHON_ROOT</span><span class="special">=</span><span class="identifier">c</span><span class="special">:/</span><span class="identifier">dev</span><span class="special">/</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">python</span><span class="identifier">
-set</span><span class="identifier"> PYTHON_VERSION</span><span class="special">=</span><span class="number">2.2</span></tt></pre>
+<pre class="programlisting"><tt class="literal">set PYTHON_ROOT=c:/dev/tools/python
+set PYTHON_VERSION=2.2
+</tt></pre>
 <p>
 The above assumes that the Python installation is in <tt class="literal">c:/dev/tools/python</tt>
-and that we are using Python version 2.2. You'll have to tweak this path
+and that we are using Python version 2.2. You'll have to tweak these
 appropriately.</p>
 <div class="informaltable"><table class="table">
 <colgroup><col></colgroup>
@@ -150,36 +160,41 @@ appropriately.</p>
 even if that's the version you have.</td></tr></tbody>
 </table></div>
 <p>
+Take note that you may also do that through the Jamrules file we put in
+our project as detailed above. The file
+has <a href="../../../../../example/tutorial/Jamrules" target="_top">detailed instructions</a> you 
+can follow.</p>
+<p>
 Now we are ready... Be sure to <tt class="literal">cd</tt> to <tt class="literal">libs/python/example/tutorial</tt>
 where the tutorial <tt class="literal">"hello.cpp"</tt> and the <tt class="literal">"Jamfile"</tt> is situated.</p>
 <p>
 Finally:</p>
-<pre class="programlisting"><tt class="literal"><span class="identifier">bjam</span><span class="special"> -</span><span class="identifier">sTOOLS</span><span class="special">=</span><span class="identifier">msvc</span></tt></pre>
+<pre class="programlisting"><tt class="literal"><span class="identifier">bjam</span><span class="special"> -</span><span class="identifier">sTOOLS</span><span class="special">=</span><span class="identifier">vc</span><span class="special">-</span><span class="number">7</span><span class="identifier">_1</span></tt></pre>
 <p>
-We are again assuming that we are using Microsoft Visual C++ version 6. If
+We are again assuming that we are using Microsoft Visual C++ version 7.1. If
 not, then you will have to specify the appropriate tool. See
 <a href="../../../../../../../tools/build/index.html" target="_top">Building Boost Libraries</a> for
 further details.</p>
 <p>
 It should be building now:</p>
 <pre class="programlisting"><tt class="literal">cd C:\dev\boost\libs\python\example\tutorial
-    bjam -sTOOLS=msvc
-    ...patience...
-    ...found 1703 targets...
-    ...updating 40 targets...
+bjam -sTOOLS=msvc
+...patience...
+...found 1703 targets...
+...updating 40 targets...
 </tt></pre>
 <p>
 And so on... Finally:</p>
-<pre class="programlisting"><tt class="literal">vc-C++ ........\libs\python\example\tutorial\bin\hello.pyd\msvc\debug\
-    runtime-link-dynamic\hello.obj
-    hello.cpp
-    vc-Link ........\libs\python\example\tutorial\bin\hello.pyd\msvc\debug\
-    runtime-link-dynamic\hello.pyd ........\libs\python\example\tutorial\bin\
-    hello.pyd\msvc\debug\runtime-link-dynamic\hello.lib
-       Creating library ........\libs\python\example\tutorial\bin\hello.pyd\
-       msvc\debug\runtime-link-dynamic\hello.lib and object ........\libs\python\
-       example\tutorial\bin\hello.pyd\msvc\debug\runtime-link-dynamic\hello.exp
-    ...updated 40 targets...
+<pre class="programlisting"><tt class="literal">Creating library bin\boost\libs\python\build\boost_python.dll\vc-7_1\debug\th
+reading-multi\boost_python.lib and object bin\boost\libs\python\build\boost_pyth
+on.dll\vc-7_1\debug\threading-multi\boost_python.exp
+vc-C++ bin\tutorial\hello.pyd\vc-7_1\debug\threading-multi\hello.obj
+hello.cpp
+vc-Link bin\tutorial\hello.pyd\vc-7_1\debug\threading-multi\hello.pyd bin\tutori
+al\hello.pyd\vc-7_1\debug\threading-multi\hello.lib
+   Creating library bin\tutorial\hello.pyd\vc-7_1\debug\threading-multi\hello.li
+b and object bin\tutorial\hello.pyd\vc-7_1\debug\threading-multi\hello.exp
+...updated 31 targets...
 </tt></pre>
 <p>
 If all is well, you should now have:</p>
@@ -203,12 +218,10 @@ hello.so
 </ul></div>
 <p>
 if you are on Unix.</p>
-<p><tt class="literal">boost_python.dll</tt> can be found somewhere in <tt class="literal">libs\python\build\bin</tt>
-while <tt class="literal">hello.pyd</tt> can be found somewhere in
-<tt class="literal">libs\python\example\tutorial\bin</tt>. After a successful build, you can just
-link in these DLLs with the Python interpreter. In Windows for example, you
-can simply put these libraries inside the directory where the Python
-executable is.</p>
+<p><tt class="literal">boost_python.dll</tt> and <tt class="literal">hello.pyd</tt> can be found somewhere in your project's
+<tt class="literal">bin</tt> directory. After a successful build, you can just link in these DLLs with 
+the Python interpreter. In Windows for example, you can simply put these libraries 
+inside the directory where the Python executable is.</p>
 <p>
 You may now fire up Python and run our hello module:</p>
 <p></p>
--- a/doc/tutorial/doc/html/python/object.html
+++ b/doc/tutorial/doc/html/python/object.html
@@ -157,7 +157,7 @@ C++:
 </span><span class="identifier">d</span><span class="special">[</span><span class="char">'whatever'</span><span class="special">]</span><span class="special"> =</span><span class="number"> 3</span><span class="special">;</span><span class="comment">           // modifies the copy
 </span></tt></pre>
 <a name="derived_object_types.class__lt_t_gt__as_objects"></a><h2>
-<a name="id459197"></a>class_&lt;T&gt; as objects</h2>
+<a name="id459119"></a>class_&lt;T&gt; as objects</h2>
 <p>
 Due to the dynamic nature of Boost.Python objects, any <tt class="literal">class_&lt;T&gt;</tt> may
 also be one of these types! The following code snippet wraps the class
--- a/doc/tutorial/doc/html/python/techniques.html
+++ b/doc/tutorial/doc/html/python/techniques.html
@@ -91,10 +91,10 @@ Unix and <tt class="literal">.dll</tt> for Windows, works just as well.</td></tr
 <p>
 Now, we create this directory structure for our Python package:</p>
 <pre class="programlisting"><tt class="literal">sounds/
-        <span class="underline">_init</span>_.py
-        core.pyd
-        filters.pyd
-        io.pyd
+    <span class="underline">_init</span>_.py
+    core.pyd
+    filters.pyd
+    io.pyd
 </tt></pre>
 <p>
 The file <tt class="literal"><span class="underline">_init</span>_.py</tt> is what tells Python that the directory <tt class="literal">sounds/</tt> is
@@ -133,16 +133,16 @@ Note that we added an underscore to the module name. The filename will have to
 be changed to <tt class="literal">_core.pyd</tt> as well, and we do the same to the other extension modules.
 Now, we change our package hierarchy like so:</p>
 <pre class="programlisting"><tt class="literal">sounds/
+    <span class="underline">_init</span>_.py
+    core/
        <span class="underline">_init</span>_.py
-        core/
-            <span class="underline">_init</span>_.py
-            _core.pyd
-        filters/
-            <span class="underline">_init</span>_.py
-            _filters.pyd
-        io/
-            <span class="underline">_init</span>_.py
-            _io.pyd
+        _core.pyd
+    filters/
+        <span class="underline">_init</span>_.py
+        _filters.pyd
+    io/
+        <span class="underline">_init</span>_.py
+        _io.pyd
 </tt></pre>
 <p>
 Note that we created a directory for each extension module, and added a
--- a/doc/tutorial/doc/tutorial.qbk
+++ b/doc/tutorial/doc/tutorial.qbk
@@ -125,41 +125,49 @@ __jam__
 Here is our minimalist Jamfile:

 [pre
-    subproject libs/python/example/tutorial ;
+# This is the top of our own project tree
+project-root ;

-    SEARCH on python.jam = $(BOOST_BUILD_PATH) ;
-    include python.jam ;
+import python ;

-    extension hello                     # Declare a Python extension called hello
-    :   hello.cpp                       # source
-        <dll>../../build/boost_python   # dependencies
-        ;
+extension hello                     # Declare a Python extension called hello
+:   hello.cpp                       # source
+    # requirements and dependencies for Boost.Python extensions
+    <template>@boost/libs/python/build/extension
+    ;
 ]

-First, we need to specify our location in the boost project hierarchy.
-It so happens that the tutorial example is located in [^/libs/python/example/tutorial].
-Thus:
+First, we need to specify our location. You may place your project anywhere.
+[^project-root] allows you to do that.

 [pre
-    subproject libs/python/example/tutorial ;
+project-root ;
 ]

-Then we will include the definitions needed by Python modules:
+By doing so, you'll need a Jamrules file. Simply copy the one in the 
+[@../../../../example/tutorial/Jamrules example/tutorial directory] and tweak 
+the [^path-global BOOST_ROOT] to where your boost root directory is. The file
+has [@../../../../example/tutorial/Jamrules detailed instructions] you can follow.
+
+Then we will import the definitions needed by Python modules:

 [pre
-    SEARCH on python.jam = $(BOOST_BUILD_PATH) ;
-    include python.jam ;
+import python ;
 ]

 Finally we declare our [^hello] extension:

 [pre
-    extension hello                     # Declare a Python extension called hello
-    :   hello.cpp                       # source
-        <dll>../../build/boost_python   # dependencies
-        ;
+extension hello                     # Declare a Python extension called hello
+:   hello.cpp                       # source
+
+    # requirements and dependencies for Boost.Python extensions
+    <template>@boost/libs/python/build/extension
+    ;
 ]

+The last part tells BJam that we are depending on the Boost Python Library.
+
 [h2 Running bjam]

 ['bjam] is run using your operating system's command line interpreter.
@@ -170,29 +178,38 @@ Make sure that the environment is set so that we can invoke the C++
 compiler. With MSVC, that would mean running the [^Vcvars32.bat] batch
 file. For instance:

-    C:\Program Files\Microsoft Visual Studio\VC98\bin\Vcvars32.bat
+[pre
+C:\Program Files\Microsoft Visual Studio .NET 2003\Common7\Tools\vsvars32.bat
+]

 Some environment variables will have to be setup for proper building of our
 Python modules. Example:

-    set PYTHON_ROOT=c:/dev/tools/python
-    set PYTHON_VERSION=2.2
+[pre
+set PYTHON_ROOT=c:/dev/tools/python
+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
+and that we are using Python version 2.2. You'll have to tweak these
 appropriately.

 [blurb __tip__ Be sure not to include a third number, e.g. [*not]  "2.2.1",
 even if that's the version you have.]

+Take note that you may also do that through the Jamrules file we put in
+our project as detailed above. The file
+has [@../../../../example/tutorial/Jamrules detailed instructions] you 
+can follow.
+
 Now we are ready... Be sure to [^cd] to [^libs/python/example/tutorial]
 where the tutorial [^"hello.cpp"] and the [^"Jamfile"] is situated.

 Finally:

-    bjam -sTOOLS=msvc
+    bjam -sTOOLS=vc-7_1

-We are again assuming that we are using Microsoft Visual C++ version 6. If
+We are again assuming that we are using Microsoft Visual C++ version 7.1. If
 not, then you will have to specify the appropriate tool. See
 [@../../../../../../tools/build/index.html Building Boost Libraries] for
 further details.
@@ -200,26 +217,26 @@ further details.
 It should be building now:

 [pre
-    cd C:\dev\boost\libs\python\example\tutorial
-    bjam -sTOOLS=msvc
-    ...patience...
-    ...found 1703 targets...
-    ...updating 40 targets...
+cd C:\dev\boost\libs\python\example\tutorial
+bjam -sTOOLS=msvc
+...patience...
+...found 1703 targets...
+...updating 40 targets...
 ]

 And so on... Finally:

 [pre
-    vc-C++ ..\..\..\..\libs\python\example\tutorial\bin\hello.pyd\msvc\debug\
-    runtime-link-dynamic\hello.obj
-    hello.cpp
-    vc-Link ..\..\..\..\libs\python\example\tutorial\bin\hello.pyd\msvc\debug\
-    runtime-link-dynamic\hello.pyd ..\..\..\..\libs\python\example\tutorial\bin\
-    hello.pyd\msvc\debug\runtime-link-dynamic\hello.lib
-       Creating library ..\..\..\..\libs\python\example\tutorial\bin\hello.pyd\
-       msvc\debug\runtime-link-dynamic\hello.lib and object ..\..\..\..\libs\python\
-       example\tutorial\bin\hello.pyd\msvc\debug\runtime-link-dynamic\hello.exp
-    ...updated 40 targets...
+Creating library bin\boost\libs\python\build\boost_python.dll\vc-7_1\debug\th
+reading-multi\boost_python.lib and object bin\boost\libs\python\build\boost_pyth
+on.dll\vc-7_1\debug\threading-multi\boost_python.exp
+vc-C++ bin\tutorial\hello.pyd\vc-7_1\debug\threading-multi\hello.obj
+hello.cpp
+vc-Link bin\tutorial\hello.pyd\vc-7_1\debug\threading-multi\hello.pyd bin\tutori
+al\hello.pyd\vc-7_1\debug\threading-multi\hello.lib
+   Creating library bin\tutorial\hello.pyd\vc-7_1\debug\threading-multi\hello.li
+b and object bin\tutorial\hello.pyd\vc-7_1\debug\threading-multi\hello.exp
+...updated 31 targets...
 ]

 If all is well, you should now have:
@@ -234,12 +251,10 @@ 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
-link in these DLLs with the Python interpreter. In Windows for example, you
-can simply put these libraries inside the directory where the Python
-executable is.
+[^boost_python.dll] and [^hello.pyd] can be found somewhere in your project's
+[^bin] directory. After a successful build, you can just link in these DLLs with 
+the Python interpreter. In Windows for example, you can simply put these libraries 
+inside the directory where the Python executable is.

 You may now fire up Python and run our hello module:

@@ -721,27 +736,27 @@ But before you do, you might want to fire up Python 2.2 or later and type
 [^>>> import this].

 [pre
-    >>> import this
-    The Zen of Python, by Tim Peters
-    Beautiful is better than ugly.
-    Explicit is better than implicit.
-    Simple is better than complex.
-    Complex is better than complicated.
-    Flat is better than nested.
-    Sparse is better than dense.
-    Readability counts.
-    Special cases aren't special enough to break the rules.
-    Although practicality beats purity.
-    Errors should never pass silently.
-    Unless explicitly silenced.
-    In the face of ambiguity, refuse the temptation to guess.
-    There should be one-- and preferably only one --obvious way to do it
-    Although that way may not be obvious at first unless you're Dutch.
-    Now is better than never.
-    Although never is often better than *right* now.
-    If the implementation is hard to explain, it's a bad idea.
-    If the implementation is easy to explain, it may be a good idea.
-    Namespaces are one honking great idea -- let's do more of those!
+>>> import this
+The Zen of Python, by Tim Peters
+Beautiful is better than ugly.
+Explicit is better than implicit.
+Simple is better than complex.
+Complex is better than complicated.
+Flat is better than nested.
+Sparse is better than dense.
+Readability counts.
+Special cases aren't special enough to break the rules.
+Although practicality beats purity.
+Errors should never pass silently.
+Unless explicitly silenced.
+In the face of ambiguity, refuse the temptation to guess.
+There should be one-- and preferably only one --obvious way to do it
+Although that way may not be obvious at first unless you're Dutch.
+Now is better than never.
+Although never is often better than *right* now.
+If the implementation is hard to explain, it's a bad idea.
+If the implementation is easy to explain, it may be a good idea.
+Namespaces are one honking great idea -- let's do more of those!
 ]

 [section Call Policies]
@@ -1401,20 +1416,20 @@ include path.
 In a Jamfile, all the above boils down to:

 [pre
-    projectroot c:\projects\embedded_program ; # location of the program
+projectroot c:\projects\embedded_program ; # location of the program

-    # bring in the rules for python
-    SEARCH on python.jam = $(BOOST_BUILD_PATH) ;
-    include python.jam ;
+# bring in the rules for python
+SEARCH on python.jam = $(BOOST_BUILD_PATH) ;
+include python.jam ;

-    exe embedded_program # name of the executable
-      : #sources
-         embedded_program.cpp
-      : # requirements
-         <find-library>boost_python <library-path>c:\boost\libs\python
-      $(PYTHON_PROPERTIES)
-        <library-path>$(PYTHON_LIB_PATH)
-        <find-library>$(PYTHON_EMBEDDED_LIBRARY) ;
+exe embedded_program # name of the executable
+  : #sources
+     embedded_program.cpp
+  : # requirements
+     <find-library>boost_python <library-path>c:\boost\libs\python
+  $(PYTHON_PROPERTIES)
+    <library-path>$(PYTHON_LIB_PATH)
+    <find-library>$(PYTHON_EMBEDDED_LIBRARY) ;
 ]

 [h2 Getting started]
@@ -1825,11 +1840,11 @@ Unix and [^.dll] for Windows, works just as well.]
 Now, we create this directory structure for our Python package:

 [pre
-    sounds/
-        __init__.py
-        core.pyd
-        filters.pyd
-        io.pyd
+sounds/
+    __init__.py
+    core.pyd
+    filters.pyd
+    io.pyd
 ]

 The file [^__init__.py] is what tells Python that the directory [^sounds/] is
@@ -1873,17 +1888,17 @@ be changed to [^_core.pyd] as well, and we do the same to the other extension mo
 Now, we change our package hierarchy like so:

 [pre
-    sounds/
+sounds/
+    __init__.py
+    core/
        __init__.py
-        core/
-            __init__.py
-            _core.pyd
-        filters/
-            __init__.py
-            _filters.pyd
-        io/
-            __init__.py
-            _io.pyd
+        _core.pyd
+    filters/
+        __init__.py
+        _filters.pyd
+    io/
+        __init__.py
+        _io.pyd
 ]

 Note that we created a directory for each extension module, and added a
--- a/doc/tutorial/doc/tutorial.xml
+++ b/doc/tutorial/doc/tutorial.xml
--- a/example/tutorial/Jamfile
+++ b/example/tutorial/Jamfile
@@ -1,14 +1,18 @@
 #   Hello World Example from the tutorial
+#   Copyright Joel de Guzman 2002-2004. 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)
 #   [Joel de Guzman 10/9/2002]

-#   Specify our location in the boost project hierarchy
-subproject libs/python/example/tutorial ;
+# This is the top of our own project tree
+project-root ;

 #   Include definitions needed for Python modules
 import python ;

 extension hello                     # Declare a Python extension called hello
 :   hello.cpp                       # source
-    <dll>../../build/boost_python   # dependencies
+    # requirements and dependencies for Boost.Python extensions
+    <template>@boost/libs/python/build/extension
    ;

--- a/example/tutorial/Jamrules
+++ b/example/tutorial/Jamrules
@@ -0,0 +1,36 @@
+# Copyright David Abrahams 2003. See accompanying LICENSE for terms
+# and conditions of use.
+
+# If you move this example from its place in the Boost tree, edit this
+# path to point at the root directory of your Boost installation (the
+# one containing a subdirectory called "boost/" and a sub-subdirectory
+# "boost/python/" full of .hpp files).  Absolute paths work, too.
+#
+path-global BOOST_ROOT : ../../../.. ;
+
+# Boost.Python configuration variables, as described in
+# http://www.boost.org/libs/python/doc/building.html#configuration.
+# Usually you don't need to set these; the defaults will work.  If you
+# do set them, try to change as few of them as possible, starting with
+# the first ones.
+
+  # PYTHON_VERSION = <the two-part Major.Minor version number, e.g. 2.2> ;
+  # PYTHON_ROOT = <root directory of your Python installation, e.g. /usr> ;
+  # PYTHON_INCLUDES = <path to Python #include directories> ;
+  # PYTHON_LIB_PATH = <path to Python library object> ;
+
+# You may need to configure your compiler toolset, especially if you
+# want to build with a compiler that is not the "system default" or if
+# it is installed in a nonstandard place; see
+# http://www.boost.org/more/getting_started.html#Configuring for
+# details.  
+
+# Makes a project id for boost so that other Boost.Build projects can
+# refer to it by name.
+#
+project boost : $(BOOST_ROOT) ;
+
+# Change this setting to have all your built products placed under a
+# single directory:
+#
+# ALL_LOCATE_TARGET = <root directory for all built products>