Page Numbers: Yes First Page: 33 X: 527  Y: 10.5"
Margins: Binding: 13
Odd Heading: Not-on-first-pagex2qjk40(635)
Debuggery756qck40\b8B
Even Heading:x2qjk40
Debuggery756qck40\b8B
Appendix E: Debuggery684x2e24ck108\f5b
The common facilities available in the Mesa debugger include setting breakpoints, tracing program execution, displaying the runtime state, and interpreting Mesa statements.  It will be easiest to understand how to access these facilities by going through a simple example using many of the common commands.x2e30jk40(1799)
Installing the debuggerx2e24k108(635)\b
Install the debugger from the command line of the Alto Executive by typing XDebug.  To load programs into the debugger at the same time as installing the debugger, list the names of the programs on the command line; use the "L" switch to load programs with code links (to save space).  For example, typing XDebug Foo/L (to the Alto Executive) loads Foo with code links and installs the debugger.  Installing the debugger with the /b switch will video reverse the display (i.e., white characters on a black background).x2e12j\75f8 7f1 143b1B58f0 2f1 20f7 12f0 1f1 30f7 3f1 42f0 36f8 3f0
Fontsx2e12jk80(1799)\i5I
The Debugger requires a strike font named MesaFont.strike or SysFont.strike; a version of Gacha10 is available on <Mesa>MesaFont.strike.  Strike fonts can be found where alto fonts are stored.  (Strike fonts that include kerning are not supported.)x2e12jk40\42f8 15f0 4f8 14f0 39f8 21f0
Memory Bank Managementx2e12jk80\i22I
When running on machines with more than 64K of memory, the client system supplies space to the Debugger for the Debugger's bitmap (unless all but one bank has been disabled; see below); the client can disable this option by using the /k switch.x2e12jk40(2116)\234f8 2f0
It is also possible for the Debugger to be installed with more than one bank of memory available for code swapping; this is done by reducing the amount of memory available to the client using the RunMesa bank switches or the Alto Executive MesaBanks.~ command (in Executive version 11 or later).x2e12jk40\240f8 11f0
MesaBanks.~l4269x2e12jk40\f8 11f0
This command establishes the default memory allocation available to client programs.  Arguments can be in two forms: a sixteen bit octal mask (followed by an optional /b switch) indicating the available banks; a one in bit position n of the mask (counting from the left) indicates that bank n is available.  Form two is a series of decimal bank numbers each followed by the /x switch; each bank mentioned is excluded from use by the client.  Note that a request to exclude bank zero will be ignored.  If no argument is present, the command will display the current value of the bank mask.l4269x2e6jk40\167f8 2f0 24i9I30i1I58i1I82f8 2f0 32i8I
The MesaBanks.~ command establishes the available memory for each .image or .bcd program invoked directly by the Alto Executive.  The default may be overridden by explicitly using RunMesa to invoke the program and optionally specifying bank switches on its command line, before the .image file name.  The bank switches have the same format as the arguments to MesaBanks.~ (except that the /b switch is required in the case of a bitmask).  In the absense of any bank switches, RunMesa always assumes that all banks are available to the client.l4269x2e6jk40\4f8 11f0 51f8 6f0 4f8 4f0 100f8 7f0 95f8 6f0 72f8 11f0 18f8 2f0 85f8 7f0
Using these facilities, it is possible to set up the defaults so that the Debugger has extra banks of memory at the expense of the client program.  For example, on a three bank Alto, the following commands might be used to set the default and then install the Debugger:x2e12jk40
MesaBanks.~ 2/x
RunMesa.run 1/x XDebug.imagel4269x2e6jk40\f8 44f0
Under this arrangement, the client would use banks zero and one, and the Debugger would use banks zero and two (because bank zero is swapped onto Swatee, it can be used by both).  Actually, because the client (by default) is also allocating space for the Debugger's display bitmap, the client actually has only one-and-one-half banks, and the Debugger has two-and-one-half; this can be changed by running the client with the /k switch, resulting in two banks available to each.x2e6jk40\146f8 6f0 273f8 2f0
Note that the MesaBanks.~ command affects all Mesa programs invoked by the Alto Executive, including the Compiler and Binder.  So the above example would run the Compiler in only two banks, not three; this can be changed by saying RunMesa Compiler on the command line, which, because there are no bank switches specified, defaults to all banks available (not really necessary in this case, since the Compiler runs almost as well in two banks as in three).  On the next new session, the Debugger is smart enough to notice that the Compiler (or whoever) has smashed what it thought was in bank two.  (It is also smart enough not to use any memory that the client owns, so that the 1/x switch on the command line above is actually unnecessary.)x2e12jk40(1799)\14f8 11f0 17i3I186f8 16f0 432f8 3f0
Since there are a lot of options here, some "standard" examples of client and Debugger configurations might be helpful:x2e12jk40
Two Banks: Normally, do nothing; client and Debugger will each have one-and-one-half banks.  For small clients and better Debugger performance, use RunMesa 1/x Mesa.image Client.bcd, which will give the client one bank and the Debugger two.  (If you were to use MesaBanks.~ 1/x in this case, the Compiler would also be restricted to one bank).l4269x2e6jk40\i10I138f8 33f0 81f8 15f0
Three Banks: As in the three bank example above.l4269x2e6jk40\i12I
Four Banks: Use MesaBanks.~ 3/x to give the client and the Debugger two-and-one-half banks each and the Compiler three; use MesaBanks.~ 2/x 3/x and Client/k to increase the Debugger's allocation to three banks and restrict the client to two.  Obviously, this can be adjusted based on the size of the client and the desired performance of the Debugger.l4269x2e6jk40\i11I5f8 15f0 93f8 19f0 5f8 8f0
Filesx2e24k108(635)\b
The debugger itself is contained in the file XDebug.image.  There are several other files that are used by the debugger and should not be edited or deleted from your disk.  These are the swapping files used by the debugger:  Swatee (to hold the user's core image), MesaDebugger (to hold the debugger's core image), and Debug.log (used as a record of your debugging session).  If you don't want your swatee to be used, create the file MesaCore and the debugger will use that instead.x2e12j\45f8 12f0 67i46I55f8 6f0 34f8 12f0 42f8 9f0 46f1 60f8 8f1 40f0
Signals and errorsx2e24k108\b
See the Mesa Debugger Documentation for details on the common signal and error messages you might receive and suggestions for recovery.x2e12j\8i27I
Sample programx2e24k108\b
The configuration we are going to use as an example is taken from the Mesa Language Manual (Chapter 7).  The following files should be retrieved from Mesa>Doc: LexiconClient.mesa, Lexicon.mesa, LexiconDefs.mesa, LexiconClient.bcd, Lexicon.bcd, LexiconDefs.bcd, Lex.config, Lex.bcd, and Lex.ts (a sample typescript of the debugging session that follows).x2e12j\70i20I60f8 8f0 2f8 18f0 2f8 12f0 2f8 16f0 2f8 17f0 2f8 11f0 2f8 15f0 2f8 10f0 2f8 7f0 6f8 6f0 1f1 59f0
The sample configuration Lex consists of two modules, Lexicon and LexiconClient.  After the modules have been compiled and the configuration has been successfully bound, you are ready to load and debug the program.x2e12j\25f6b3f0B26f6b7f0B5f6b13f0B
Entering the debuggerx2e24k108\b
Let us assume that the configuration has been loaded and started (by typing Lex to the Alto Executive), and you have interrupted the program and entered the debugger for the first time (by holding down Control-Swat after the program has started).  You get a herald that indicates which version of the debugger you are using and when it was built, followed by the current date and time, a message indicating why you entered the debugger (in this case, interrupting the program), and a prompt for the first command:x2e12jk40\76f8 3f0 123f8 12f0
Alto/Mesa Debugger 6.0m of 12-Sep-80 23:21
12-Sep-80 23:41
*** interrupt ***

>l4269x2e12jk40\f8 79f0
Setting the contextx2e24k108\b
In order to get to a context from which you can set breakpoints in one of the modules in Lex, let's first check to see which configurations have been loaded by saying:x2e12j\89f6b3f0B
>List Configurations [confirm]l4269x2e12j\f8 30f0
which responds with:x2e12j
Lex
Mesa
  Nucleusl4269x2e12j\f8 18f0
If we check the context at this point, you can see that the current module is NubControl in the Mesa configuration,x2e12j\78f6b10f0B8f6b4f0B
>CUrrent context
Module: DebugNub, G: 172764B, L: 166160B, PSB: 3700B
  Configuration: Mesa.l4269x2e12j\f8 92f0
We need to set the current configuration to be Lex,x2e12j\47f6b3f0B
>SEt Root configuration: Lexl4269x2e12j\1f8 27f0
and find out which modules are in this configuration,x2e12j
>Display Configuration Lex
Lexicon, G: 150404B~
LexiconClient, G: 150424Bl4269x2e12j\f8 73f0
Notice the ~ indicating that Lexicon hasn't been started yet.  Now we can set the context to be Lexicon, so that we can set some breakpointsx2e12j\11f8 1f0 84f6b7f0B
x2e12j
>SEt Module context: Lexiconl4269x2e12j\1f8 27f0
Setting breakpoints by selectionsx2e24k108\b
Let's load the source text for Lexicon into a window so we can set breakpoints by pointing at the text.  This may be done in one of two ways:  either display the stack and ask to see the source (this loads and positions the source file for the current module into the source window of the debugger),x2e12j\31f6b7f0B
>Display Stack
Lexicon, G: 150404B~  >s Cross jumped!
--Lexicon.mesa 
  >ql4269x2e12j\1f8 73f0
or load the file into a source window by 1) selecting the file name Lexicon (the extension defaults to .mesa), 2) moving into a source window (there is always at least one around), and 3) choosing the Load command from the menu.  Note the message warning that Lexicon was compiled with the cross jumping switch turned on.  Additional source windows can be created, destroyed, and moved around as needed, using the appropriate menu commands.x2e12j\67f8 1f6b7f0B1f1 27f8 5f1 1f0 33f1 37f0 22f8 4f0
Now move into the window containing the source file, and put this window on top.  This can be done by either clicking the red mouse button in the left or right sections of the window header, or by selecting the window menu command Top.x2e12j\231f8 3f0
Suppose we want to set a breakpoint on the exit of the procedure NewNode.  Scroll the window until this procedure is visible, then select the word RETURN inside this procedure.  Hold down the menu button (yellow button) and choose the SetBreak command.  This sets a breakpoint on the exit of the procedure (similarly, selecting the word PROCEDURE or PROC sets a breakpoint on the entry to the procedure).x2e12j\65f6b7f0B75f7b6f0B82f8 8f0 94f7b9f0B4f7b4f0B
Suppose you want to set a breakpoint in the end of one of the conditional IF-THEN-ELSE statements in the procedure InsertString.  This can be done by selecting any place in the statement ELSE n.llink _ NewNode[];.  Confirmation of where the breakpoint has been set is given by the moving the selection to the first character of the statement: ELSE <>n.llink _ NewNode[]; (Note that in all cases, the closest enclosing statement is the place at which the breakpoint is actually set).x2e12j\74f7b12f0B29f6b12f0B60f7b4f6 21f0B131f7b4f6 23f0B
Setting breakpoints by type-inx2e24k80\b
You may also set entry and exit breakpoints in the program using keyboard commands.  For any breakpoint, you may specify a condition that must be satisfied in order for the breakpoint to be taken.  If, for instance, you want to set a breakpoint on the entry to the procedure FindString, and enter the debugger only if root is not NIL, say:x2e12jk40\275f6b10f0B33f6b4f0B8f7b3f0B
>Break Entry procedure: FindString Breakpoint #3.
>ATtach Condition #: 3, condition: root # NIL.l4269x2e12jk40\1f8 95f0
Inserting commentsx2e24k108\b
Saving some comments along with the commands is a good idea, so that it is easier to remember what happened when looking back at the typescript file.  For instance you might now say,x2e12j
>--This breakpoint was set to skip checking for a lexicon if we
>--know the tree is empty.l4269x2e12j\f8 90f0
Proceedingx2e24k108\b
It is now time to proceed and run the program.  This is done by executing the following command:x2e12j
>Proceed [confirm].l4269x2e12j\f8 18f0
If we try to add the lexeme "xxxxx" to the tree, we will then reach our breakpoints.x2e12j\29f8 5f0
Examine and change the statex2e24k108\b
You next enter the debugger at the first breakpoint with the herald:x2e12j
>Break #1 at exit from NewNode, L: 165424B, PC: 274B (in Lexicon, G: 150404B)l4269x2e12\f8 77f0
to indicate where you are.  At this point you might display the stack and look at the variables,x2e12j
>Display Stack
NewNode, L: 165424B, PC: 274B (in Lexicon, G: 150404B)  >v
  n = 147374B^
  >ql4269x2e12j\f8 93f0
or look at the several levels of the stack,x2e12j
>Display Stack
NewNode, L: 165424B, PC: 274B (in Lexicon, G: 150404B)  >n
InsertString, L: 165434B, PC: 162B (in Lexicon, G: 150404B)  >n
AddString, L: 165444B, PC: 137B (in Lexicon, G: 150404B)  >n
CommandProc, L: 170420B, PC: 470B (in LexiconClient, G: 150424B)  >n
LexiconClient, L: 165464B, PC: 257B (in LexiconClient, G: 150424B)  >n
No symbols for L: 172614B, PC: 702B (in MesaNub, G: 172670B)  >ql4269x2e12\f8 403f0
or ask to see what the node n (in NewNode) looks like (invoke the interpreter by typing SP),x2e12j\28f6b1f0B5f6b7f0B47f7b2f0B
> n^
[llink:NIL, rlink:NIL, string:(5,5)"xxxxx"].l4269x2e12j\f8 48f0
Let's say we wanted to set both the left link and right link of n to point to n itself and then check the value of n.  This may be done by saying,x2e12jk40\64f6b1f0B13f6b1f0B36f6b1f0B
> n.llink _ n; n.rlink _ n; n; n^l4269x2e12jk40\f8 33f0
which responds with,x2e12jk40
147374B^
[llink:147374B^, rlink:147374B^, string:(5,5)"xxxxx"].l4269x2e12k40\f8 63f0
If at this point we want to see the value of the variable root in the module LexiconClient (a variable in the current configuration but not in the current module), this may be done by saying,x2e12j\58f6b4f0B15f6b13f0B
>Find variable: rootl4269x2e12j\f8 20f0
which responds with the value of root, and where it was found:x2e12j\33f6b4f0B
NIL (in Lexicon, G: 150404B).l4269x2e12j\f8 29f0
More breakpoint commandsx2e24k108\b
The following command lists all of the breakpoints that have been set:x2e12j
>LIst Breaks [Confirm] 
1 -- Break at exit from NewNode (in Lexicon, G: 150404B).
2 -- Break in InsertString (in Lexicon, G: 150404B).
 Cross jumped!
                         ELSE <>n.llink _ NewNode[];
3 -- Break at entry to FindString (in Lexicon, G: 150404B).  Condition: root # NIL;l4269x2e12j\f8 286f0
If you decide that you are no longer interested in any of these breakpoints you canx2e12j
>Clear All Breaks [confirm]l4269x2e12j\f8 27f0
which removes all breakpoints and restores the instructions.x2e12j
Look at the user worldx2e24k108\b
If you are interested in seeing the state of the user display, you can look at the user world by saying x2e12j
>Userscreen [confirm].l4269x2e12j\f8 22f0
When you want to return to the debugger, hit either the Swat key or FR5; this brings you back into the debugger, ready to execute more commands.x2e12j\56f8 4f0 8f8 3f0
Setting tracepointsx2e24k108\b
Suppose next you want to set a trace on the entry to the procedure LexicalCompare so that you can simply see the two strings being compared and go on.  You may do so by saying,x2e12j\67f6b14f0B
>Trace Entry procedure: LexicalCompare Breakpoint #4.l4269x2e12j\f8 52f0
Now we should proceedx2e12jk80
>Proceed [confirm]l4269x2e12jk40\f8 18f0
and try to add a new lexeme, say "yyy".x2e12jk40\34f8 3f0
When the tracepoint is reached, you get the herald indicating why you entered the debugger, where you are, and a dump of the input parameters of the procedure:x2e12j
Trace #4 at entry to LexicalCompare, L: 165750B, PC: 276B (in Lexicon, G: 150404B)
>Display Stack
LexicalCompare, L: 165750B, PC: 276B (in Lexicon, G: 150404B)  >P
  s1 = (3,80)"yyy"
  s2 = (5,5)"xxxxx"
  >l4269x2e12j\f8 206f0
leaving you in Display Stack.  Type 'q' to terminate the Display Stack command, and then continue executing your program x2e12j\15f8 13f0 8f8 3f0 18f8 13f0
>Proceed [confirm].l4269x2e12j\f8 18f0
This represents a brief introduction to the use of most of the debugger's commands that you will commonly need.  See the Mesa Debugger Documentation for further details; the best teachers are experienced Mesa programmers and lots of practice!!! x2e12j\121i27I