XEROX BUGREPORT 2 4 1 BUGREPORT 1 4 By: Ken Feuerman (Feuerman.pasa@Xerox.ARPA) & David Newman (Newman.pasa@Xerox.ARPA) BUGREPORT is a package for getting back information from a non-Lisp-programmer on what went wrong with a particular package. It allows the programmer to decide that he never wants the user to see a break window. Whenever a break occurs, a menu pops up that says roughly what went wrong with the program, and asks the user if a bug report should be made, no bug report, or the usual break window. If no report is chosen, then the effect is as if an "^" was typed at the break window which never appeared. If a bug report is chosen, then a file is created, and on that file information is printed out regarding the current state of the calculations (i.e., stack contents, function calls and their arguments, etc.). The user is allowed to type in any message that would give the programmer some hint as to what he was trying to do to arrive at this state. Also, the programmer can set up forms expected to be useful to be evaluated and printed out on the bug report. Once that file is completed, the bug report is exited via the "^" convention as before. THE BUG REPORT The bug report itself is an unformatted text file that is very useful to the programmer in trying to find the source of the break. The first line shows the date the bug report was generated and the logged in user at the time. The user comment appears next, exactly as it was typed in. After that, the bug report forms (as specified by the programmer) are printed in order, both as the expression being evaluated and the result of that evaluation. Then, starting from the top of the stack, the stack names, variables, and their values are shown. The programmer can specify which stack names are to be printed, and how values of variables are expressed in the bug report. BUGREPORT CONTROL VARIABLES There are several variables that affect the operation of BUGREPORT. These are expected to be set by the programmer who loads BUGREPORT as a part of their system, although they are INITVARed by BUGREPORT to reasonable values. Since INITVAR is used, they may be set by the programmer's package before or after BUGREPORT is LOADed, and that setting will not be over-written. BUGREPORT.REPORTNOBREAK? [Variable] Initially NIL. This is the "on/off" switch for bug reports. When NIL, break windows will occur as always. If non-NIL, a menu pops up asking if the user would like a bug report made. BUGREPORT.DEVICE [Variable] Initially the LITATOM {DSK}. This determines where the bug report file will reside. This should be one of {DSK}, {CORE}, or {FLOPPY}. The bug report file will then be placed on that device, named BUGREPORT.TTY. BUGREPORT.FORMS [Variable] Initially NIL. This is a list of s-expressions set up by the programmer to include information in the bug report about the state of the system that is expected to be of use. Each s-expression is printed together with its value at the time of the break on the bug report. An example of BUGREPORT.FORMS could be ((VMEMSIZE) MyPackageSystemDate). WARNING: When a break occurs, a check is made to see if a bug report is already in the process of being generated, and if so, (ERROR!) is called. As a result, if one of the BUGREPORT.FORMS should cause an error, NIL is printed as its result. Other strange things may also occur, though testing of the package revealed nothing. It is recommended, however, to try to make sure that your BUGREPORT.FORMS list has forms that are as unbreakable as possible. BUGREPORT.FRAMENAMELST [Variable] Initially T. This indicates which frames (stack names) should be included in the bug report. T indicates all frames should be printed. If a list, only those frames in the stack with names that match with some element of this list will be included. A good example use would be to set BUGREPORT.FRAMENAMELST to (FILEFNSLST MyPackageFile). BUGREPORT.EXCLUDED.FRAMENAMELST [Variable] Initially a list of all of the functions on BUGREPORT itself. This list contains the names of frames the programmer is explicitly NOT interested in seeing on the bug report. If BUGREPORT.FRAMENAMELST is T, then frame names are checked against this list before they are included in the bug report. In addition to frame names, if BUGREPORT.EX- CLUDED.FRAMENAMELST includes the LITATOM \ (backslash), then all frames whose names begin with \ will not be included ("system internal" functions). A similar exclusion process happens for names beginning with "*" (the "blips"). The values of the variable bindings at each step of the way are pretty-printed out. The actual function which does that printing looks like this: (LAMBDA (VARIABLE VALUE FILENAME) (printout FILENAME .TAB 5 VARIABLE .TAB 30 .PPV VALUE T)) If more information is desired for instances of a particular data type, a print function can be specified by placing it on the PRINTFN property of the typename of the value. This function should have three arguments, VARIABLE (the actual name of the parameter in the frame name), VALUE (the current binding of that VARIABLE), and FILENAME (the name of the bug report file currently being generated). For example, if it is desired always to know the INFO property of all windows printed on a bug report, one might perform the following: (PUTPROP 'WINDOW 'PRINTFN '(LAMBDA (VARIABLE VALUE FILENAME) (printout FILENAME .TAB 5 VARIABLE .TAB 30 (WINDOWPROP VALUE 'INFO) T] (LIST ((PAGE NIL (PAPERSIZE Letter FOLIOINFO (ARABIC) STARTINGPAGE# 1) (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD CENTERED) CHARLOOKS (SUPERSCRIPT 0 INVISIBLE OFF SELECTPOINT OFF PROTECTED OFF SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF EXPANSION REGULAR SLOPE REGULAR WEIGHT MEDIUM INVERTED OFF USERINFO NIL STYLE NIL) FORMATINFO (ARABIC)) (174 42 288 36) NIL) (HEADING NIL (HEADINGTYPE RUNNINGHEAD) (84 744 528 36) NIL) (TEXT NIL NIL (84 96 456 600) NIL))) (PAGE NIL (PAPERSIZE Letter FOLIOINFO (ARABIC) STARTINGPAGE# NIL) (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD CENTERED) CHARLOOKS (SUPERSCRIPT 0 INVISIBLE OFF SELECTPOINT OFF PROTECTED OFF SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF EXPANSION REGULAR SLOPE REGULAR WEIGHT MEDIUM INVERTED OFF USERINFO NIL STYLE NIL) FORMATINFO (ARABIC)) (174 42 288 36) NIL) (HEADING NIL (HEADINGTYPE RUNNINGHEAD) (84 744 528 36) NIL) (TEXT NIL NIL (84 96 456 600) NIL))) (PAGE NIL (PAPERSIZE Letter FOLIOINFO (ARABIC) STARTINGPAGE# NIL) (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD CENTERED) CHARLOOKS (SUPERSCRIPT 0 INVISIBLE OFF SELECTPOINT OFF PROTECTED OFF SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF EXPANSION REGULAR SLOPE REGULAR WEIGHT MEDIUM INVERTED OFF USERINFO NIL STYLE NIL) FORMATINFO (ARABIC)) (174 42 288 36) NIL) (HEADING NIL (HEADINGTYPE RUNNINGHEAD) (84 744 528 36) NIL) (TEXT NIL NIL (84 96 456 600) NIL)))))4 0l1 0l. ((8(8D PAGEHEADING RUNNINGHEADTERMINAL MODERN MODERN MODERN MODERN MODERNLOGO?1(DEFAULTFONT 1 (GACHA 10) (GACHA 8) (TERMINAL 8))   HRULE.GETFNMODERN  HRULE.GETFNMODERN  HRULE.GETFNMODERN   HRULE.GETFNMODERN  HRULE.GETFNMODERN UES/$ 6.BQP , xO" T+ 5t$0T7pSA@hz