				*** WARNING! ***

This software is in ALPHA TEST.  It has been released with only ONE PURPOSE
in mind: to CRASH YOUR COMPUTER in cruel and unusual ways.  If you don't
like the sound of this then please DO NOT USE this software.

Note that this software includes functionality that can MODIFY YOUR
FILESYSTEM.  If it malfunctions then it might CORRUPT ARBITRARY FILES in
completely RANDOM and UNPREDICTABLE ways.

If you're still convinced that you want to use this software, here is some
advice on how to maximise the value of your experience.

** Be prepared to submit bug reports.  If you're not prepared to submit a
   bug report then running this software is a waste of your time.

** Be prepared to use your existing experience of debugging C++ programs to
   help you submit bug reports.  If you don't have such experience then
   running this software will be a very stressful waste of your time.

** ALWAYS run this softwre under a debugger.  When it crashes, the
   information that can be extracted from the debugger will be valuable
   for determining the cause of the problem and correcting it.

** ALWAYS run this software with assertions enabled and optimisation
   disabled: comment out the definition of "CXXOPTFLAGS" in the Makefile
   before compiling.

** NEVER run this software using an image that you care about.

** ALWAYS try to maximise the chances for failure.  Try all of the most
   obscure and convoluted Smalltalk operations and programs that you know
   about.  Bizarre manipulations of Contexts/Processes, dynamically
   generated and/or self-modifying Classes and CompiledMethods, creative use
   of #doesNotUnderstand:, and agressive use of the Smalltalk Debugger to
   modify live code and Contexts are a few of the potential candidates.

The following is intended for users of "gdb".  Modify appropriately if you
use some other debugger.

** Note for gdb users: at the time of writing, gdb version 4.18 is broken.
   Use version 4.17 (patch level 0.11 or higher), otherwise debugging C++
   will be almost impossible.

WHEN THIS SOFTWARE CRASHES:

1. Print a backtrace of the C stack: type

	bt

   at the gdb pompt.  Note that the bactrace will probably end with one or
   more frames that gdb prints as:

	#N 0x<bigHexNumber> in ??

   This is normal.  (These are frames executing in dynamically-generated
   code, and they tend to confuse gdb even though their linkage is more or
   less compatible with C.)

2. Attempt to print a backtrace of the Smalltalk stack.  The crash is
   probably the result of an assertion failure or a segmentation fault.
   Locate the topmost "interesting" frame in the C stack, which will almost
   certainly have an argument of type "Frame *".  Point gdb at this frame:
   type

	fr <numberOfTopmostInterestingFrame>

   at the gdb prompt.  Look at the value of the argument of type "Frame *"
   (let's imagine it's called "frame").  If it is non-zero then you can
   probably extract a Smalltalk backtrace by typing

	call frame->printBacktrace()

   at the gdb prompt.  If there are other variables that you suspect might
   be interesting, you can print most things using

	call variableName->print()
	call fflush(stdout)

   (or

	call ((Object *)variableName)->print()
	call fflush(stdout)

   if the variable is of type "int" but you suspect that it contains a
   pointer to an object).  If you get a segmentation fault while doing this
   then the variable did not contain an object pointer.  If gdb crashes
   while doing this then consider submitting a separate bug report to the
   gdb maintainer for your platform.

3. Copy and paste the entire gdb session into a file.

4. Try to determine what caused the crash.  There will be clues in the C
   backtrace about what the VM was trying to do at the time of the crash
   (you should be able to deduce the purpose of most functions from their
   names).  There will also be clues in the Smalltalk backtrace about what
   the Smalltalk program was trying to do at the time of the crash.  (The
   number in square brackets in the "pc" field of each frame is the
   Smalltalk program counter for the frame.  Start a [reliable] VM, browse
   the relevant method[s], and use "show bytecodes" to see exactly where the
   Smalltalk program crashed.)

5. Based on the information from step 4, try to write a minimal Smalltalk
   program that reproduces the crash.

6. Send the file saved in step 3 and the pogram written in step 5 to the
   author (ian.piumarta@inria.fr).  Your reward will be a newer version of
   the software that does not crash for the same reasons.

7. Rinse and repeat until you no longer succeed in provoking a crash.

If you are STILL determined to use this software after reading all of the
above: welcome to j3!
