How to install WAD, a crash debugger, for usage with PyDS

This document describes how to install a crash debugger that helps with
debugging segfaults in PyDS. PyDS sometimes segfaults when running stuff
from CVS. This is mostly due to extension modules and problems with
deinitialisations. These bugs are very hard to debug, as Python doesn't
give usual tracebacks, but just segfaults with the very helpful message
"segfault" written to stderr.

WAD jumps in to rescue the poor developer by hooking into the critical
signal handlers and trying to restore the state of execution as much
as possible to be able to give more meaningfull messages. Included
are a C stacktrace (if possible) and raising a python exception. This
often helps the developer to find out what went wrong and how this
actually happendd.

To install WAD for PyDS usage, follow these steps (I assume you used
the default INSTALL-FROM-SOURCE procedure - if you installed differently,
you need to fix path names yourself):

cd ~/PyDS/Archives

wget http://systems.cs.uchicago.edu/wad/wad-0.2.tar.gz

cd ~/PyDS/Source/

tar xvfz ../Archives/wad-0.2.tar.gz

cd WAD-0.2

./configure --prefix=/opt/pyds/ \
	--disable-tcl \
	--disable-perl \
	--with-py=/opt/pyds/lib/python2.2/site-packages/ \
	--with-pyincl=/opt/pyds/include/python2.2/ \
	--with-pylib=/opt/pyds/lib/python2.2/

make
sudo make install

sudo mv /opt/pyds/lib/libwadpy.so /opt/pyds/lib/python2.2/site-packages/

Now you can edit the /opt/pyds/bin/pyds-start script to include the
following statement:

import libwadpy

This will enable the WAD the next time you start PyDS. Now you need to
provoke the segfault again. If PyDS segfaults but doesn't show any
stacktrace, read the ~/PyDS/Source/WAD-0.2/README file, especially
the lines about multithreading. You might need to add some
environment settings, for example WAD_NOSTACK, to get it working.

If you are in doubt about any of this, you should either better not
using this thing or you were explicitely told to do it ;-)

Since WAD itself is alpha software, there is absolutely no
guarantee that anything actually works as you expect. It even
might eat your datafiles on your harddrive or do anything
very bad. YOU HAVE BEEN WARNED!

This is a developer tool - so if you are no developer, you better
very closely follow any orders you got by a developer when he
advised you to use this tool. If you are a developer, you might
need to build debugging versions of other libraries to make
full use of WAD, as binary packages often don't include
debugging symbols.

