jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

*** empty log message ***

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@971 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
Dave Beazley 2000-12-29 02:13:54 +00:00
commit d79e71ef2c
1 changed files with 104 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

112
SWIG/Tools/WAD/README
View file

@ -6,22 +6,103 @@ University of Chicago
Chicago, IL 60637
beazley@cs.uchicago.edu
Copyright (C) 2000
Copyright (C) 2001
University of Chicago
All Rights Reserved
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!!!! READ THIS NOW !!!!!!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
THIS IS EXPERIMENTAL UNSUPPORTED SOFTWARE THAT UTILIZES A HORRIBLE MIX
OF LOW-LEVEL SYSTEMS PROGRAMMING, C, C++, AND ASSEMBLY CODE. IT IS
NOT PORTABLE, IT HAS NOT BEEN RIGOROUSLY TESTED, AND IT MIGHT NOT WORK
AT ALL. PLEASE KEEP AWAY FROM SMALL CHILDREN, PETS, NUCLEAR REACTORS,
AIR-TRAFFIC CONTROL, VOTING MACHINES, AND MEDICAL EQUIPMENT. SIDE
EFFECTS MAY INCLUDE NAUSEA, VOMITING, AND HEADACHE. OTHER THAN THIS,
IT'S PERFECTLY SAFE.
1. Introduction
WAD is an embedded error-recovery mechanism that allows fatal errors
such as SIGSEGV, SIGBUS, and SIGFPE to converted into exceptions for
use in scripting languages and similar systems.
WAD is an embedded error-recovery mechanism that attempts to convert
fatal errors such as SIGSEGV, SIGBUS, and SIGFPE into sensible error messages
and exceptions. It is specifically designed to support scripting language
environments although it can also be used with stand-alone C programs.
The primary goal of this system is to explore alternative approaches
to mixed scripting-compiled debugging. Feedback is
welcome. Contributions and modifications are even more welcome.
2. Compilation and Installation
WAD is not particularly portable (for obvious reasons). At this time,
only two platforms are supported: SPARC Solaris and i386-Linux. To
build the Solaris version, type 'make solaris'. To build the Linux
version, type 'make linux'.
The build process creates the following shared libraries:
libwad.so - Standalone WAD. Can be linked with C/C++
programs.
libwadpy.so - Python WAD. Can be linked to Python extension
modules or imported on its own as 'import libwadpy'
libwadtcl.so - Tcl WAD. Can be linked to Tcl extension
modules or loaded as 'load libwadtcl.so'.
libwadpl.so - Perl WAD. Can be linked to Perl extension
modules.
To install the libraries, simply type 'make install'. This copies the libraries
to /usr/local/lib (unless you modify the makefile).
Notes:
- Not all of these libraries are currently available on all platforms.
Most development work has taken place on Solaris.
- You may need to modify the Makefile to point to the installed locations
of various scripting language libraries. Eventually this will be
put under autoconf, but that's for later.
- WAD only supports systems with ELF-format executables and stabs
format debugging tables. This is fairly common on many systems.
However, it also means that WAD does not work with newer compilers
and debugging formats such as DWARF2.
3. Using WAD
WAD has no functional API nor does it have any command line options so
it's pretty easy to use---simply link the appropriate WAD library with
your C code. For example:
% cc blah.c -lwad
Once linked, fatal errors will now produce stack traces. For example:
% ./a.out seg
starting.
Segmentation fault.
#2 0x400571eb in __libc_start_main() in 'libc-start.c', line 90
#1 0x08048b39 in main(argc=0x2,argv=0xbffffce4) in 'debug.c', line 62
#0 0x080489b3 in seg_crash(n=0x0) in 'debug.c', line 9
/r0/beazley/Projects/WAD/Wad/debug.c, line 9
int *a = 0;
if (n > 0) seg_crash(n-1);
=> *a = 3;
return 1;
}
Debugging Modes
---------------
The following WAD debugging modes can be set through the use of environment
variables:
4. Debugging Modes
Due to WAD's experimental nature, a number of debugging modes can be set
through the use of environment variables. These variables control WAD's
runtime behavior and cause the system to dump debugging information for
various stages of error recovery.
WAD_DEBUG_SEGMENT - Displays information about the virtual memory
map and mapping of addresses to segments.
@ -47,3 +128,18 @@ WAD_DEBUG_INIT - Print initialization information.
WAD_NOSTACK - Do NOT use an alternative signal handling stack.
This may be necessary on certain Linux systems when
threads are being used.
WAD_ONESHOT - Disable WAD signal handler after first signal has
been received.
5. Documentation
No official documentation exists at this time. However, the Papers directory contains
two conference papers that describe WAD's design and high-level operation.
Dave Beazley
December 28, 2000