                GSBug & Debugging Tools Update Release Notes
                                   1/3/91


This folder contains the latest pre-release version of GSBug & Debugging
Tools.  These tools are useful with or without either the APW or ORCA
development environments (i.e.: if you're using Merlin, Micol, TML, MPW IIGS,
or any other development environment to write Apple IIGS software, then these
tools (especially GSBug) will be VERY useful in finding bugs in the software
you're developing.

These tools are a fully copyrighted work of Apple Computer, Inc and may NOT be
redistributed.  They are being provided to you for your own use as our way of
saying, "Thanks for developing for the Apple IIGS".  All Rights Reserved.

Futher information on using GSBug itself can be found in the "GSBug.Tutorial"
file in the same folder as this "Read.Me" file.  Details on how to use the new
"calls" that have been added to GSBug can be found in the "GSBug.Specs" file
which is also in the same folder as this "Read.Me" file.  Reading those two
files will explain a LOT of things to you.  The tutorial is especially useful
if you do not have the manual (or you have the manual, but never bothered to
read it).

The tutorial and specs files will only teach you the basics, there is a LOT
more that can be done with GSBug, but you'll need the manual to be able to
tap into them.  The 140 page manual for GSBug & Debugging Tools contains full
details on how to use these tools.  Those of you without this manual can get
one by contacting APDA at 1-800-282-2732 (in the U.S.), 1-800-637-0029 (in
Canada), and 408-562-3910 (International).  The part number for this package
is "A0037LL/A" and the price is thirty dollars ($30).

GSBug best supports debugging of 16-bit software.  Recent changes made to it
provide minimal functionality for debugging 8-bit software. Please read the
"GSBug.Specs" file for details.

ONLY the INIT version of GSBug is being provided.  The application version is
most likely going to "go away" in the future.  Instead, we'll provide an easy
way for you to install and remove the INIT version on the fly.  Currently, you
can remove the INIT version after booting by simply entering the debugger (the
tutorial file tells you how) and typing "UNLOAD", then pressing RETURN.  This
removes the debugger.  If your application crashed into the debugger and you
unload the debugger, your application will still be crashed (but into the
monitor now that GSBug is gone).  If your application is NOT crashed (i.e.:
you entered the debugger by pressing the key sequence that drops you in
safely), then unloading GSBug will resume operation of your application as
though nothing happened (actually, plenty happened - GSBug was removed from
memory and you can't drop into it any more because it's gone).

If you use the application named "IR" (short for "INIT Runner") then you can
reload GSBug on the fly.  Simply follow the directions supplied with IR to
reload the INIT.  Otherwise, you have to reboot to reinstall the INIT version
of GSBug.

Having only the INIT version solves several problems you would have
encountered had you tried using the application version of GSBug along with an
application that uses resources.  GSBug is technically the "current"
application, so calls to the Resource Manager would actually look in GSBug's
resource fork (which is non-existant) instead of your application's.  The INIT
version prevents this conflict (and several other similar ones caused by
confusion of which app is the "current" one).

Directions for installing theses tools are below:

GSBug & Debugging Tools installation:
   - copy the files in the "GSBug/System.Setup/" folder
     to your boot disk's System.Setup folder (full path would be:
     "*/System/System.Setup/").  This will provide you with the INIT version
     of GSBug the next time you boot your computer from the disk you just
     installed onto.  It will also provide you with the templates for toolbox
     data structures (such as grafPorts, windows, menu bars, etc).
     Information on using the templates can be found in the "Templates.Info"
     file.  General info on using templates of your own with GSBug can be
     found in the GSBug Reference manual (available from APDA).

   - copy the desk accessories in the "GSBug/Desk.Accs/"
     folder to your boot disk's Desk.Accs folder (full path would be:
     "*/System/Desk.Accs/").  This will provide you with additional debugging
     tools such as loader/dumper, memory mangler, scrambler, and snooper.  You
     must reboot from the disk you just installed onto in order for those desk
     accessories to show up.

   - copy the Exerciser application to where ever you normally install your
     applications.  It doesn't really care what folder it lives in.  There is
     a desk accessory version of the Exerciser, so you don't HAVE to use the
     application version if you don't want to.

   - copy the INIT Runner (IR) application (inside the IR folder which is at
     the same level as this "Read.Me" file) to where ever you normally install
     your applications.  It doesn't really care what folder it lives in.
     There is an icon file (IR.icons) that goes with it (so you can just
     double-click the debugger.init from the Finder as though it were a data
     file for IR).  You'll need to copy this icon file to your boot disk's
     ICONS folder (or to whatever disk you install IR on) and edit the
     application pathname of IR's icons for INITs, etc in order for the
     Finder to know where you've installed IR.  The IR folder also contains
     documentation for using IR, so please read it.  Otherwise, you may not be
     able to get IR to work for you (you don't launch IR like a normal app, it
     ONLY looks for its info in the Message Center - you HAVE to double click
     on an icon that it knows about in order for IR to install things on the
     fly.)  Like I said, there's documentation for IR in the IR folder, read
     it...


Double check your */System/System.Setup folder to be certain that you have
ONLY one copy of the GSBug INIT file.  The old name for this file is
"GSBug.INIT" and some pre-release versions went out with the INIT named
"debug.INIT".  Having two copies of GSBug will cause nasty things to happen
since both copies would be trying to do the same thing.  One GSBug is all you
need.



      DISCLAIMER OF WARRANTY

      THE SOFTWARE IS PROVIDED "AS IS" WITHOUT
      WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
      WITH RESPECT TO ITS MERCHANTABILITY OR ITS FITNESS
      FOR ANY PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO
      THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
      YOU.  SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU (AND
      NOT APPLE OR AN APPLE AUTHORIZED REPRESENTATIVE)
      ASSUME THE ENTIRE COST OF ALL NECESSARY SERVICING,
      REPAIR OR CORRECTION.

      Apple does not warrant that the functions
      contained in the Software will meet your requirements
      or that the operation of the Software will be
      uninterrupted or error free or that defects in the
      Software will be corrected.

      SOME STATES DO NOT ALLOW THE EXCLUSION
      OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSION MAY
      NOT APPLY TO YOU.  THIS WARRANTY GIVES YOU SPECIFIC
      LEGAL RIGHTS AND YOU MAY ALSO HAVE OTHER RIGHTS
      WHICH VARY FROM STATE TO STATE.


Tim Swihart
APW & MPW IIGS Product Manager
Apple Computer, Inc.
