MailCrashTrap bundle  version 1.1  1999/03/01
	====================

This is a plugin for Mail.app (3.3 and 4.x) that extends its error
handling in case of an application crash.  It prints a stack backtrace
to the console, and puts up an alert box that offers you to continue
execution of Mail.app instead of just exiting.  Use this feature at your
own risk!!!

Install the contents of `MailCrashTrap.pkg' anywhere in the mail bundle
path (~/Library/Mail, /LocalLibrary/Mail, /NextLibrary/Mail, and the Mail
application wrapper itself) and restart Mail.  The recommended location
for system-wide installation is /LocalLibrary/Mail, for personal
installation ~/Library/Mail.  Mail.app 3.3 expects all bundles in the
same folder--it crashes otherwise (yes, this is a bug in Mail.app 3.3)

The bundle itself is actually named `AAAMailCrashTrap.bundle' to force
Mail.app to load it as early as possible, so that it has a chance to
catch crashes during load of other bundles.  (Mail.app loads its bundles
in alphabetical order.)

This is a quick hack I whipped up one evening around the existing
public-domain HKCrashTrap-1.0 code, slightly adapted so as not to lose
Mail.apps own signal handling.  (After that I spent way too much time
re-hacking the CrashTrap handler itself :-/  It is now more robust,
informative and extensible (or so I'd like to tell myself...))  Stack
backtrace dump still only works for NeXT and Intel; HP-PA and Sparc may
be supported in the future.  The crash _catching_ aspect at least now
should work for all architectures.

For examples of crashes that may occur, see the end of this README.


Enjoy!

	Tom Hageman

Send suggestions, bugreports, etc. to

	<mailapp-utilities@basil.icce.rug.nl>


Version history:

1.1

* German localization, contributed by David Andel <david@nexttoyou.de>

* Add "Close window & Continue" alert button, to handle crashes that
  repeat until the mailbox window is closed more conveniently.

* Some small fixes in an attempt to avoid the postscript error and/or
  "INTERNAL ERROR: uncaught recursive crash." bug when handling crashes
  at startup.


1.0 - first public release.

* finish support for localization.

* prepare for distribution.


0.2 - first beta version.

* localizable crash alert panel.

* lots of internal changes in CrashTrap, like:
  - more informative/accurate stack dump (NeXT, Intel only).
  - now works with HP-PA, Sparc (well, minus the stack dump.)
  - user-configurable, handles the following dwrites:
      CrashTrap_MaxFrameCount (unsigned number, default 50)
        - max. number of frames shown in stack frame backtrace.
      CrashTrap_FunctionArgCount (unsigned number, default 4)
        - number of (long) arguments to show with a function.
      CrashTrap_MaxArgDescriptionLength (unsigned number, default 256)
        - maximum length of (string) arguments to show.
      CrashTrap_DumpBacktrace (boolean, default YES)
        - whether or not to show backtrace.


0.1 - first alpha version.


Crash Example 1.

  objc: <MailCell> does not recognize selector -getSelectedCells:
  *** stack frame Backtrace follows:
  #0  0x05015572 in -(id)[<MailCell:0x65d854> doesNotRecognize:(SEL)"getSelectedCells:"]
  #1  0x0501560b in -(id)[<MailCell:0x65d854> forward:(SEL)"getSelectedCells:" :(void *)0xbffff42c]
  #2  0x050195f5 in -[<MailCell:0x65d854> getSelectedCells:] <unknown method>
  #3  0x002be23d in -(char)[<AColorizer:0x0ade5c> updateThreadButtonStates:(id)<MenuCell:0x0cd99c>]
  #4  0x002bcae7 in -(char)[<MailDriver:0x0cfc3c> updateThreadButtonStates:(id)<MenuCell:0x0cd99c>]
  #5  0x0501548f in -(id)[<MailDriver:0x0cfc3c> perform:(SEL)"updateThreadButtonStates:" with:(id)<MenuCell:0x0cd99c>]
  #6  0x0601ef85 in -(id)[<Menu:0x0b59fc> update]
  #7  0x06024af4 in -(id)[<MailDriver:0x0cfc3c> updateWindowUsingCache]
  #8  0x06024ed4 in -(id)[<MailDriver:0x0cfc3c> updateWindows]
  #9  0x06029fd4 in -(id)[<MailDriver:0x0cfc3c> sendEvent:(struct UNKNOWN *)0x0cfc4c]
  #10 0x060309fd in -(id)[<MailDriver:0x0cfc3c> run]
  #11 0x000255d6 in function (0x00000003, 0xbfffff20, 0xbfffff30, 0x00000000)
  #12 0x0002938f in function (0xbfffff48, 0x00000000, 0xbfffff6c, 0x00000000)

This is an example of a crash that is usually triggered when a Mailbox
window is opened, and repeats itself until the offending window is closed
(through the window's close box or the new "Close window & Continue" alert
button -- attempts to use the close menu or keyboard shortcut fail.)  It
seems to originate from Colorizer.bundle.  Other manifestations of the same
bug seem to be:

  Caught signal #10 (Bus error)
  *** stack frame Backtrace follows:
  #0  0x0508b436 in -(char)[<AColorizer:0x0a6570> updateThreadButtonStates:(id)<MenuCell:0x0c2d9c>]
  ...

  objc: FREED(id): message getSelectedCells: sent to freed object=0x45f518
  ...


Crash Example 2.

  Caught signal #10 (Bus error)
  *** stack frame Backtrace follows:
  #0  0x0508b436 in function (0x05003800, 0x00000000, 0x00000000, 0x0500387e)
  #1  0x050506fe in function (0x0005383c, 0x0005241c, 0x0017fb24, 0x0000dae4)
  #2  0x0002c87e in function (0x0005383c, 0x0005241c, 0x0500387e, 0x0017fb5c)
  #3  0x0000dae4 in -(char)[<Defaults:0x0a5b58> getBool:(const char *)"ReportDuplicateAddresses" defaultVal:(char)'\x0']
  #4  0x00027336 in -(void)[<Alias:0x0a98f4> removeDuplicates]
  #5  0x000215ec in -(id)[<Alias:0x0a98f4> realInitialize]
  #6  0x000276d0 in function (0x000a98f4, 0x00000000, 0x00000000, 0x00000000)
  ...

This crash may occur in an early stages of Mail.app's launch.