COPYIGHT ©1996 Dietmar Eilert, All Rights Reserved. Dietmar Eilert Mies-v-d-Rohe-Str.31, 52074 Aachen, Germany E-Mail: DIETMAR@TOMATE.TNG.OCHE.DE Tel: +49-(0)241-81665 +49-(0)2525-7776 Fax: +49-(0)241-81665 CONTENTS Information on how GoldED support can be added to debuggers (for debugger programmers). BASICS GoldED can be used to set the state of breakpoints and thus act as debugger frontend (as addition to the standard debugger window with its step gadgets etc.). The advantage of using GoldED as debugger frontend is that users don't have to leave the editor environment and that sources can be modified while debugging. Adding GoldED support to existing debuggers is simple: GoldED's command set has been designed to make this job as simple as possible. How it works: GoldED displays breakpoints next to text lines. The list of available breakpoints is provided by the debugger. GoldED will notify the debugger if the user edits the state of a breakpoint. Communication between the compiler and GoldED is based on standard ARexx messages: GoldED sends messages to the debugger's ARexx port, the debugger sends messages to GoldED's ARexx port. These messages are described below. A simple debugger example is available in the "debugger" drawer. Similar code would have to be added to your debugger in order to allow usage of GoldED as additional frontend. SPECIAL FEATURE Buffers can be modified during debugger sessions. Unmodified buffers are simulated towards the debugger so that the debugger can assume that buffers have not been modified and that line numbers calculated at compile time are still vaild. LINE NUMBERS GoldED internally uses a line/column numbering scheme starting at 0. However, towards the user a numbering scheme starting at 1 is used. The numbering scheme used towards the debugger may vary depending on the situation but usually the 1ff numbering scheme is used. Details are listed below. Two different line number types are available during a debugger session: physical line numbers (reflecting buffer modifications added after compile time) and locked line numbers reflecting the original line number seen by the compiler at compile time. The debugger will want to use the locked line numbers so that it can ignore buffer modifications: It will specify the LOCKED option in commands sent to GoldED. A list of available debugger-related commands is shown below (commands not related to the debugger are described in the standard GoldED documentation): 1. DEBUG START/S,STOP/S,PORT/K 2. VIEW DEBUGGER/K 3. BREAKPT LINE/N,STATE/N,TOGGLE/S,NEXT/S,PREV/S,FILE/K,FORMAT/K,DATA/N 4. PC FILE/K,LINE/N,LOCKED/S,UNFOLD/S,ONEWINDOW/S,FREEZE/S 5. GOTO LINE/N,LOCKED/S DEBUG START/S,PORT/K template: DEBUG START/S,PORT/K example: DEBUG START PORT="DEBUGGER.1" This command is used by the debugger. It activates GoldED's debugger support. PORT/K is the name of the debugger's ARexx port. GoldED will start sending commands to this port immediately in order to obtain breakpoint information for all open buffers. Line numbers are frozen by this command: further buffer modifications will not affect line numbers until the debugger session is terminated. The editor can not be closed completely by the user after this command has been sent to GoldED's ARexx port (until the end of the debugger session). The DEBUG START command can fail if a debugger session has already been started by another program or if your debugger didn't terminate the last session: Check the return code (0=OK, 5 or 20: error). GoldED will start sending the following messages to the debugger port immediately (simply ReplyMsg() these messages): template: QUERY FILE/K,PORT/K QUERY FILE="" PORT=" example: QUERY FILE="dh0:main.c" PORT="GOLDED.1" is a unique/resolved file name (to simplify file identification for the debugger; the name is obtained by GoldED using NameFromLock). GoldED expects that the debugger sends breakpoint information for this file as soon as possible if breakpoints are available. Breakpoint information should be sent to the port PORT/K named in the QUERY message (owned by GoldED) using the following command: template: BREAKPT FILE/K,FORMAT/K,DATA/N,FORMAT/K,ELEMENTS/N example: BREAKPT FILE="dh0:main.c" DATA=1029282 FORMAT="STORMC" ELEMENTS=142 FILE/K: file name (should match exactly the file name sent to the debugger in a QUERY message). DATA/N: pointer to debugger-specific breakpoint data for the file FILE/K (needs to stay valid until the BREAKPT message is replied by GoldED). ELEMENTS/N: number of valid breakpoints in the data section. FORMAT/K: describes the data format. Currently only STORMC can be used unless you have contacted me and we have agreed on a new additional format that suits your needs better (STORMC should not be used in release versions as it will be changed to meet the specific needs of the StormC debugger). Description of this format: DATA/N is a pointer to an UWORDS array, one UWORD for each line. Possible values: 0 (no breakpoint), 1 (breakpoint, not set), breakpoint (set). DEBUG STOP/S template: DEBUG STOP/S example: DEBUG STOP This command is used by the debugger. It terminates a debugger session. Breakpoints are hidden if this command is recieved. Buffers loaded during the debugger session (by the debugger) are closed automatically if unmodified. DEBUG STOP may not be omitted (performance of GoldED suffers during debugger sessions). SET DEBUGGER VALUE/K template: SET DEBUGGER VALUE/K examples: SET DEBUGGER TRUE SET DEBUGGER FALSE SET DEBUGGER TOGGLE This command is available for users only (and not used by the debugger). It shows/hides the breakpoints of the currrent buffer. Usually breakpoints are displayed automatically if the debugger sens breakpoint information. This commands allows the user to override the editor's decision to show/hide breakpoints. BREAKPT LINE/N,LOCKED/S,STATE/K,TOGGLE/S,NONOTIFY/S template: BREAKPT LINE/N,LOCKED/S,STATE/K,TOGGLE/S,NONOTIFY/S example: BREAKPT LINE=1 LOCKED STATE=1 BREAKPT LINE=1 LOCKED TOGGLE This command can be used by the user or by the debugger. It sets/unsets the breakpoint in line (1, ...) depending on STATE/K (0/1). LOCKED/S indicates that LINE/N refers to a locked line number (valid at compile time). The editor will notify the debugger immediately that a breakpoint has been set or unset (unless you specify NONOTIFY). The following message is sent to the debugger's port: template: BREAKPT FILE/K,LINE/N,STATE/K example: BREAKPT FILE="dh0:main.c" LINE=1 STATE=1 LINE/N (1, ...) is a locked line number (valid at compile time). STATE/K is the new breakpoint state. FILE/K is the resolved file name. BREAKPT NEXT/S,PREV/S template: BREAKPT NEXT/S,PREV/S example: BREAKPT NEXT BREAKPT PREV This command is can be used by the user or by the debugger. It moves the cursor to the next/last breakpoint. PC FILE/K,LINE/N,COLUMN/N,LOCKED/S,UNFOLD/S,ONEWINDOW/S,FREEZE/S,FILETYPE/K,HIGHLIGHT/S,PRESENT/S Beispiel: PC PRESENT FILE="dh0:main.c" LOCKED LINE=100 COLUMN=1 ONEWINDOW FREEZE This command is used by the debugger. It moves the cursor to column COLUMN/N (1, ...) and line LINE/N (1, ...) in file FILE/K. The line is highlighted if HIGHLIGHT is specified (useful to show the current line of execution). LOCKED/S specifies that LINE/N refers to a locked line number (the LOCKED option can only be used during a debugger session). The file is loaded if not yet present. You may override automatic file type detection using FILETYPE/K for files loaded by this command. The buffer's window is activated and brought to the front if you specify PRESENT (the buffer's screen is always brought to the front). ONEWINDOW instructs the editor to close all but one windows that have been opened by the debugger so far. This option helps you to reduce the number of open windows if debugging large projects. The buffers are either unloaded completely or - if the FREEZE/S option is used - simply hidden (kept in the background without a window): usage of FREEZE avoids unnecessary disk accesses. The FORMAT/K and DATA/K options allow the debugger to pass new breakpoint information to the editor (overriding the information sent to GoldED while processing QUERY commmands; see above). These options may be useful if the debugger maintains multiple breakpoint lists for a file and wants to switch from one set of breakpoints to nother set of breakpoints. DATA/N and FORMAT/K are ignored if a pointer to the same block of data is specified multiple times. GOTO LINE/N LOCKED/S template: GOTO LINE/N LOCKED/S example: GOTO LINE=1 LOCKED This command can be used by the user or by the debugger. It moves the cursor to line LINE/N (1, ...) in the current file. LOCKED/S indicates that LINE/N refers to a locked line number (the LOCKED option can only be used during a debugger session).