From 7defd3bbed0078ffe475f74f48f9062fbc13bf5d Mon Sep 17 00:00:00 2001
From: Dave Abrahams <dave@boostpro.com>
Date: Tue, 7 Jan 2003 18:03:17 +0000
Subject: [PATCH] support for BOOST_PYTHON_STATIC_MODULE clarification

[SVN r16788]
---
 doc/building.html | 53 +++++++++++++++++++++++++++++++++--------------
 1 file changed, 38 insertions(+), 15 deletions(-)

diff --git a/doc/building.html b/doc/building.html
index 6535e891..92fd1694 100644
--- a/doc/building.html
+++ b/doc/building.html
@@ -49,6 +49,15 @@
 
       <dt><a href="#building_ext">Building your Extension Module</a></dt>
 
+      <dd>
+        <dl>
+          <dt><a href="#easy">The Easy Way</a></dt>
+
+          <dt><a href="#outside">Building your module outside the Boost
+          project tree</a></dt>
+        </dl>
+      </dd>
+
       <dt><a href="#variants">Build Variants</a></dt>
 
       <dt><a href="#VisualStudio">Building Using the Microsoft Visual Studio
@@ -65,11 +74,14 @@
 
     <h2><a name="building">Building Boost.Python</a></h2>
 
-    <p>Every Boost.Python extension module must be linked with the
-    <code>boost_python</code> shared library. To build
-    <code>boost_python</code>, use <a href=
-    "../../../tools/build/index.html">Boost.Build</a> in the usual way from
-    the <code>libs/python/build</code> subdirectory of your boost
+    <p>Normally, Boost.Python extension modules must be linked with the
+    <code>boost_python</code> shared library. In special circumstances you
+    may want to link to a static version of the <code>boost_python</code>
+    library, but if multiple Boost.Pythone extension modules are used
+    together, it will prevent sharing of types across extension modules, and
+    consume extra code space. To build <code>boost_python</code>, use <a
+    href="../../../tools/build/index.html">Boost.Build</a> in the usual way
+    from the <code>libs/python/build</code> 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).</p>
 
@@ -231,13 +243,19 @@ bjam -sTOOLS=<i><a href=
     passes. 
 
     <h2><a name="building_ext">Building your Extension Module</a></h2>
-    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
-    <code>libs/python/example</code> 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 best way to build an extension
+    module using Boost.Python is with Boost.Build. If you have to use another
+    build system, you should use Boost.Build at least once with the
+    "<code><b>-n</b></code>" option so you can see the command-lines it uses,
+    and replicate them. You are likely to run into compilation or linking
+    problems otherwise. 
+
+    <h3><a name="easy">The Easy Way</a></h3>
+    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 <code>libs/python/example</code>
+    subdirectory of your boost installation contains a minimal example (along
+    with many extra sources). To copy the example subproject: 
 
     <ol>
       <li>Create a new subdirectory in, <code>libs/python</code>, say
@@ -251,9 +269,14 @@ bjam -sTOOLS=<i><a href=
       change the "<code>subproject</code>" rule invocation at the top, and
       the names of some of the source files and/or targets.</li>
     </ol>
-    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 <code><a href=
+    The instructions <a href="#testing">above</a> for testing Boost.Python
+    apply equally to your new extension modules in this subproject. 
+
+    <h3><a name="outside">Building your module outside the Boost project
+    tree</a></h3>
+    If you can't (or don't wish to) modify 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 <code><a href=
     "../example/project.zip">this archive</a></code>. 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