update

[SVN r16389]

doc/v2/faq.html

@@ -37,6 +37,8 @@
 
       <dt><a href="#c1204">fatal error C1204:Compiler limit:internal
       structure overflow</a></dt>
+
+      <dt><a href="#debugging">How do I debug my Python extensions?</a></dt>
     </dl>
 
 
@@ -215,11 +217,90 @@ void more_of_my_class(class&lt;my_class&gt;&amp; x)
       </ol>
     </blockquote>
 
+    <h2><a name="debugging"></a>How do I debug my Python extensions?</h2>
+
+      <p>Greg Burley gives the following answer for Unix GCC users:
+
+    <blockquote>
+Once you have created a boost python extension for your c++ library or
+class, you may need to debug the code.  Afterall this is one of the
+reasons for wrapping the library in python. An expected side-effect or
+benefit of using BPL is that debugging should be isolated to the c++
+library that is under test, given that python code is minimal and
+boost::python either works or it doesn't. (ie. While errors can occur
+when the wrapping method is invalid, most errors are caught by the
+compiler ;-).
+
+<p>
+
+The basic steps required to initiate a gdb session to debug a c++
+library via python are shown here. Note, however that you should start
+the gdb session in the directory that contains your BPL my_ext.so
+module. 
+
+
+<pre>
+(gdb) target exec python
+(gdb) run
+ &gt;&gt;&gt; from my_ext import *
+ &gt;&gt;&gt; [C-c]
+(gdb) break MyClass::MyBuggyFunction
+(gdb) cont
+ &gt;&gt;&gt; pyobj = MyClass()
+ &gt;&gt;&gt; pyobj.MyBuggyFunction()
+Breakpoint 1, MyClass::MyBuggyFunction ...
+Current language:  auto; currently c++
+(gdb) do debugging stuff
+</pre>
+    </blockquote>
+
+<p>
+
+Greg's approach works even better using Emacs'
+&quot;<code>gdb</code>&quot; command, since it will show you each line
+of source as you step through it. 
+
+<p>
+
+On Windows, my favorite debugging solution is the debugger that comes
+with Microsoft Visual C++ 7. This debugger seems to work with code
+generated by all versions of Microsoft and Metrowerks toolsets; it's
+rock solid and &quot;just works&quot; without requiring any special
+tricks from the user.
+
+<p>
+
+Unfortunately for Cygwin and MinGW users, as of this writing gdb on
+Windows has a very hard time dealing with shared libraries, which
+could make Greg's approach next to useless for you. My best advice for
+you is to use Metrowerks C++ for compiler conformance and Microsoft
+Visual Studio as a debugger when you need one.
+
+<h3>Debugging extensions through Boost.Build</h3>
+
+If you are launching your extension module tests with <a
+href="../../../tools/build">Boost.Build</a> using the
+<code>boost-python-runtest</code> rule, you can ask it to launch your
+debugger for you by adding &quot;-sPYTHON_LAUNCH=<i>debugger</i>&quot;
+to your bjam command-line:
+
+<pre>
+bjam -sTOOLS=metrowerks &quot;-sPYTHON_LAUNCH=devenv /debugexe&quot; test
+bjam -sTOOLS=gcc -sPYTHON_LAUNCH=gdb test
+</pre>
+
+It can also be extremely useful to add the <code>-d+2</code> option
+when you run your test, because Boost.Build will then show you the
+exact commands it uses to invoke it. This will invariably involve
+setting up PYTHONPATH and other important environment variables such
+as LD_LIBRARY_PATH which may be needed by your debugger in order to
+get things to work right.
+
     <hr>
 
     <p>Revised 
     <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
-     13 November, 2002 
+     23 November, 2002 
     <!--webbot bot="Timestamp" endspan i-checksum="39359" -->
     </p>