*** empty log message ***

git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@984 626c5289-ae23-0410-ae9c-e8d60b6d4f22

Tools/WAD/Makefile

@@ -1,6 +1,10 @@
 # Generated automatically from Makefile.in by configure.
 # Generated automatically from Makefile.in by configure.
 
+SHELL     = /bin/sh
+prefix    = /usr/local
+execprefix= ${prefix}
+LIB        = $(execprefix)/lib
 
 # Location of your Python installation
 PYINCLUDE = -I/usr/local/include/python2.0
@@ -25,6 +29,9 @@ tcl:
 perl:
 	@cd Wad; $(MAKE) SINCLUDE='$(PERLINCLUDE)' perl
 
+install:
+	cp libwad*.so $(LIB)
+	chmod a+rx $(LIB)/libwad*.so
 
 clean:
 	@cd Wad; $(MAKE) clean

Tools/WAD/Makefile.in

@@ -1,5 +1,9 @@
 # Generated automatically from Makefile.in by configure.
 
+SHELL     = /bin/sh
+prefix    = @prefix@
+execprefix= @exec_prefix@
+LIB        = $(execprefix)/lib
 
 # Location of your Python installation
 PYINCLUDE = @PYINCLUDE@
@@ -24,6 +28,9 @@ tcl:
 perl:
 	@cd Wad; $(MAKE) SINCLUDE='$(PERLINCLUDE)' perl
 
+install:
+	cp libwad*.so $(LIB)
+	chmod a+rx $(LIB)/libwad*.so
 
 clean:
 	@cd Wad; $(MAKE) clean

Tools/WAD/Prebuilt/linux/Makefile.in

@@ -0,0 +1,11 @@
+# Generated automatically from Makefile.in by configure.
+
+SHELL     = /bin/sh
+prefix    = @prefix@
+execprefix= @exec_prefix@
+LIB        = $(execprefix)/lib
+
+install:
+	cp libwad*.so $(LIB)
+	chmod a+rx $(LIB)/libwad*.so
+

Tools/WAD/Prebuilt/solaris/Makefile.in

@@ -0,0 +1,11 @@
+# Generated automatically from Makefile.in by configure.
+
+SHELL     = /bin/sh
+prefix    = @prefix@
+execprefix= @exec_prefix@
+LIB        = $(execprefix)/lib
+
+install:
+	cp libwad*.so $(LIB)
+	chmod a+rx $(LIB)/libwad*.so
+

Tools/WAD/README

@@ -10,42 +10,48 @@ Copyright (C) 2000-2001
 University of Chicago
 All Rights Reserved
 
+$Header$
+
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !!!!!!!!                        DISCLAIMER                           !!!!!!!!
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
 THIS IS EXPERIMENTAL UNSUPPORTED SOFTWARE THAT UTILIZES A HORRIBLE MIX
 OF LOW-LEVEL C, C++, AND ASSEMBLY CODE.  IT IS NOT PORTABLE, IT HAS
-NOT BEEN RIGOROUSLY TESTED, AND IT MIGHT NOT WORK AT ALL.  PLEASE KEEP
+NOT BEEN EXHAUSTIVELY TESTED, AND IT MIGHT NOT WORK AT ALL.  PLEASE KEEP
 AWAY FROM SMALL CHILDREN, PETS, NUCLEAR REACTORS, AIR-TRAFFIC CONTROL,
 AND VOTING MACHINES. SIDE EFFECTS MAY INCLUDE NAUSEA, VOMITING, AND
 HEADACHE.  OTHER THAN THIS, IT'S PERFECTLY SAFE.
 
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-!!!!!!!!                     READ THIS FIRST                         !!!!!!!!
+!!!!!!!!                   SUPPORTED PLATFORMS                       !!!!!!!!
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
-This software is only known to work on Sun Sparc Solaris 2.8 and recent
+This software is only known to work with 32-bit applications on Sun
-i386-Linux systems.  In addition, there are numerous issues concerning
+Sparc Solaris 2.8 and recent i386-Linux systems. In addition, there
-the interaction of this software with signal handling, thread
+are numerous issues concerning the interaction of this software with
-libraries, and compilers.  Please read this entire document before 
+signal handling, thread libraries, and compilers.  Please read this
-proceeding.
+entire document before proceeding.
 
 1. Introduction
 
 WAD is an embedded error-recovery mechanism that attempts to convert
-fatal errors such as SIGSEGV, SIGBUS, and SIGFPE into sensible error messages
+fatal errors such as SIGSEGV, SIGBUS, and SIGFPE into sensible error
-and exceptions.  It is specifically designed to support scripting language
+messages and exceptions.  It is primarily designed to support
-extension programming although it can also be used with stand-alone C programs.
+scripting language extension programming although it can also be used
+with stand-alone C programs.
 
-The primary goal of this system is to explore alternative approaches
+The primary goal of this system is to explore an alternative approach
-to mixed scripting-compiled debugging.  Feedback is welcome. 
+to mixed scripting-compiled debugging.  It requires no modifications
-Contributions and modifications are even more welcome.
+or recompilation of existing software--only relinking.  Therefore, it
+should be relatively easy to try out.  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: Sun Sparc Solaris and i386-Linux.
+only two platforms are supported: Sun Sparc Solaris and i386-Linux. 
+
 Installation is as follows:
 
       ./configure
@@ -64,34 +70,38 @@ The build process creates the following shared libraries:
                         modules or loaded as 'load libwadtcl.so'.
 
     libwadpl.so      -  Perl WAD.  Can be linked to Perl extension
-                        modules.
+                        modules or loaded as 'libwadpl'.
 
 To install the libraries, simply type 'make install'.  This copies the libraries
 to /usr/local/lib (unless you modify the makefile).
 
+In case the build process does not work, pre-built binaries for both
+platforms can be found in the Prebuilt directory.   Simply go to the appropriate
+platform directory and type 'make install'.
+
 Notes:
 
    -  The Sun version of WAD has only been tested when compiled with the
       Sun Workshop C/C++ compilers.   Although WAD works with other programs
       that have been compiled with gcc.  If gcc is installed on your
-      machine, you may want to set the following environment variables:
+      machine, you may want to set the following environment variables
+      before running configure:
 
            setenv CC cc
            setenv CXX CC
            ./configure
  
-   -  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 if you have installed
       them in non-traditional locations. 
 
+   -  The Linux version has only been tested with 2.2-12 and 2.2-14 kernels
+      and the RedHat 6.0 distribution.  Your mileage may vary. 
      
 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
+it's pretty easy to describe---simply link the appropriate WAD library with
 your C code.  For example:
 
    % cc blah.c -lwad
@@ -113,6 +123,14 @@ Segmentation fault.
       return 1;
     }
 
+For scripting languages, WAD works in a similar manner--simply link
+your scripting language extension module with the appropriate WAD library
+(wadpy, wadtcl, wadpl).  For example:
+
+   % cc pymodule.o -lwadpy
+
+When the scripting module is loaded into the interpreter, WAD should
+automatically initialize.
 
 4. Debugging Modes
 
@@ -167,9 +185,19 @@ General:
   -  WAD does not currently support 64 bit applications on any platform.
 
   -  If executables have been stripped, their symbol tables might not
-     have enough information to recover from errors.  There is very little
+     have enough information to recover from errors.  Therefore, if you
-     practical point in stripping the interpreter symbol table other
+     are using Python, Tcl, or Perl from a binary distribution, you
-     than saving a little disk space.
+     may want to rebuild non-stripped versions of these packages yourself.
+
+  -  WAD only works with programs that utilize the ELF32 linking format
+     and stabs debugging data.  Newer formats such as DWARF2 are not
+     supported at this time.
+
+  -  WAD does not correctly report argument values for structures or
+     floating point numbers yet.
+
+  -  Overly aggressive compiler optimization may lead to very strange
+     WAD output.
 
 Solaris:
 
@@ -179,15 +207,17 @@ Linux:
 
   -  The interaction of threads and signals are particularly problematic
      on this platform and may cause WAD not to work at all.   Here are
-     some specific thread-based problems that may arise:
+     some specific thread-based issues that may arise:
 
      1.  WAD causes the program to crash immediately upon startup. 
          This appears to be caused by a bug in in the implemenation
-         of sigaction() and the initialization of signals.  There is no
+         of sigaction() and the initialization of signals.  This 
-         known solution.
+         only occurs if WAD is directly linked to an executable
+         using threads.  It does not occur when WAD is dynamically
+         loaded into a threaded application.
 
-     2.  Programs lock up when an error occurs.  This is sometimes
+     2.  Programs may lock up when an error occurs.  This is sometimes
-         caused by a broken implementation of sigaltstack().
+         caused by an apparently broken implementation of sigaltstack().
          One solution to this is to set the following environment
          variable:
 
@@ -208,9 +238,11 @@ Linux:
   -  WAD has to rely upon a heuristic register recovery scheme when it
      returns to scripting language interpreters.  It seems to
      work, but it relies upon a very specific compiler code generation
-     convention for saving registers in function prologues.
+     convention for saving registers in function prologues.  It also
+     relies upon the register save conventions described in the Linux
+     Assembly HOWTO.
 
-6.  Language dependent issues
+6.  Language specific issues
 
 If WAD is linked with a normal C/C++ program, errors simply produce a stack trace
 that is printed on standard error.
@@ -235,11 +267,14 @@ code derived from the sigtrap module.
 
 7. Testing and Examples
 
-The Tests directory contains some very simple code for testing wad.  In the most simple
+The Test directory contains some very simple code for testing WAD.  In the
-form, compile the stand-along test program 'debug' as follows:
+most simple form, compile the stand-along test program 'debug' as follows:
 
-% cd Tests
+% cd Test
 % make
+
+Now, running it:
+
 % debug
 WAD debug program.
 
@@ -274,8 +309,28 @@ The scripts debug.py, debug.tcl, debug.pl can be used to test these extensions.
 No official documentation exists at this time.  However, the Papers directory contains
 two conference papers that describe WAD's design and high-level operation.
 
+9. To-Do
+
+The current implementation is fairly messy and undergoing constant
+change.  Here is the short list:
+
+    -  Continued clean up and modularization of the core.
+    -  Support for ELF64 linking format.
+    -  Improved support for stack-overflow and heap-corruption.  Although WAD
+       probably won't be able to recover, it still might be able to produce some 
+       informative diagnostics.
+    -  Removal of printf() and other high-level library calls which may not
+       operate with a corrupted heap.
+    -  Better integration with scripting languages.
+    -  Support for new platforms.
+    -  Support for new scripting languages.
+
 Dave Beazley
-December 28, 2000
+January 3, 2001
+
+
+
+
 
 
 

Tools/WAD/Test/Makefile.in

@@ -13,25 +13,32 @@ PYINCLUDE = @PYINCLUDE@
 TCLINCLUDE = @TCLINCLUDE@
 PERLINCLUDE = @PERL5EXT@
 INCLUDE = -I../Include 
+WADLIB = ..
+WADLINK = -L$(WADLIB) $(RPATH)$(WADLIB)
 
 test:
-	$(CC) -g -DNEED_MAIN debug.c $(INCLUDE) -L.. $(RPATH).. -lwad -o debug
+	$(CC) -g -DNEED_MAIN debug.c $(INCLUDE) $(WADLINK) -lwad -o debug
 
-python:
+python: pydebug.c
-	swig -python debug.i
+	$(CC) $(CCSHARED) -c -g debug.c pydebug.c $(PYINCLUDE)
-	$(CC) $(CCSHARED) -c -g debug.c debug_wrap.c $(PYINCLUDE)
+	$(LDSHARED) debug.o pydebug.o $(WADLINK) -lwadpy -o debugmodule.so
-	$(LDSHARED) debug.o debug_wrap.o -L.. $(RPATH).. -lwadpy -o debugmodule.so
 
-tcl:
+tcl: tcldebug.c
-	swig -tcl debug.i
+	$(CC) $(CCSHARED) -c -g debug.c tcldebug.c $(TCLINCLUDE)
-	$(CC) $(CCSHARED) -c -g debug.c debug_wrap.c $(TCLINCLUDE)
+	$(LDSHARED) debug.o tcldebug.o $(WADLINK) -lwadtcl -o debug.so
-	$(LDSHARED) debug.o debug_wrap.o -L.. $(RPATH).. -lwadtcl -o debug.so
 
-perl:
+perl: pldebug.c
-	swig -perl5 debug.i
+	$(CC) $(CCSHARED) -c -Dbool=char -g debug.c pldebug.c $(PERLINCLUDE)
-	$(CC) $(CCSHARED) -c -Dbool=char -g debug.c debug_wrap.c $(PERLINCLUDE)
+	$(LDSHARED) debug.o pldebug.o $(WADLINK) -lwadpl -o debug.so
-	$(LDSHARED) debug.o debug_wrap.o -L.. $(RPATH).. -lwadpl -o debug.so
 
+pydebug.c:
+	swig -python -o pydebug.c debug.i
+
+tcldebug.c:
+	swig -tcl -o tcldebug.c debug.i
+
+pldebug.c:
+	swig -perl5 -o pldebug.c debug.i
 
 clean:
-	rm -f *.so *.o
+	rm -f *.so *.o debug *_wrap*

Tools/WAD/Test/README

@@ -0,0 +1,5 @@
+Simple test programs for WAD.  This is currently incomplete.
+
+Note: To completely rebuild the Python, Perl, and Tcl tests,
+you need to have SWIG installed (www.swig.org).
+

Tools/WAD/Wad/signal.c

@@ -431,7 +431,10 @@ void wad_signal_init() {
     printf("WAD: Initializing signal handler.\n");
   }
 
+  /* This is buggy in Linux and threads.  disabled by default */
+#ifndef WAD_LINUX
   /* Set up an alternative stack */
+
   sigstk.ss_sp = (char *) wad_sig_stack;
   sigstk.ss_size = STACK_SIZE;
   sigstk.ss_flags = 0;
@@ -440,6 +443,8 @@ void wad_signal_init() {
       perror("sigaltstack");
     }
   }
+#endif
+
   sigemptyset(&newvec.sa_mask);
   sigaddset(&newvec.sa_mask, SIGSEGV);
   sigaddset(&newvec.sa_mask, SIGBUS);
@@ -451,9 +456,11 @@ void wad_signal_init() {
   if (wad_debug_mode & DEBUG_ONESHOT) {
     newvec.sa_flags |= SA_RESETHAND;
   }
+#ifndef WAD_LINUX
   if (!(wad_debug_mode & DEBUG_NOSTACK)) {
     newvec.sa_flags |= SA_ONSTACK;
   } 
+#endif
   newvec.sa_sigaction = ((void (*)(int,siginfo_t *, void *)) wad_signalhandler);
   if (sigaction(SIGSEGV, &newvec, NULL) < 0) goto werror;
   if (sigaction(SIGBUS, &newvec, NULL) < 0) goto werror;

Tools/WAD/configure.in

@@ -349,6 +349,8 @@ dnl We use the following in `AC_OUTPUT' and "make distclean".
 configure_substituted_files=`echo	\
     Wad/Makefile			\
     Test/Makefile  \
+    Prebuilt/linux/Makefile \
+    Prebuilt/solaris/Makefile \
     Makefile				\
 `
 AC_SUBST(configure_substituted_files)