Amiga Times

home *** CD-ROM | disk | FTP | other *** search

/ Amiga Times / AmigaTimes.iso / programme / GoldED / developer / debugger / README

Wrap

Text File | 1998-10-06 | 12.3 KB | 277 lines

COPYRIGHT ©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 valid. 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,ALL/N,CLEANUP/S 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 asynchronous messages to the debugger port immediately (simply ReplyMsg() these messages): template: QUERY FILE/K/A,PORT/K/A,DATA/N,ELEMENTS/N QUERY FILE="<filename>" PORT="<port> examples: QUERY FILE="dh0:main.c" PORT="GOLDED.1" QUERY FILE="dh0:main.c" PORT="GOLDED.1" DATA=4129038 ELEMENTS=5 FILE/K 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. DATA/N and ELEMENT/N are provided if random breakpoints have been created by the user already. The debugger may choose to ignore this information or use it to preset its internal breakpoint list passed to GoldED later. Data format: DATA/N points to an UWORD array consisting of ELEMENT/N elements, one element for each line of the text. Possible values: 0 (no breakpoint), 1 (inactive breakpoint) or 2 (active breakpoint). Please note that the DATA pointer stays valid until the debugger has replied the QUERY message; it will not stay valid after the message has been replied. PORT/K is GoldED's port. Breakpoint information should be sent to this port as soon as possible 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), 2 (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 received (but not deleted). 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). You may wish to additionally send BREAKPT CLEANUP to GoldED in order to have all breakpoints deleted. 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 current buffer. Usually breakpoints are displayed automatically if the debugger sends breakpoint information. This commands allows the user to override the editor's decision to show/hide breakpoints. BREAKPT QUERY/K template: BREAKPT QUERY/K example: BREAKPT QUERY="dh0:main.c" This command is used by the debugger if it wants to receive a description of breakpoints for the specified file. Usually a description of predefined breakpoints is sent to the debugger embedded into QUERY commands if a text is loaded into the editor. This command may be useful to receive a description of predefined breakpoints for files not yet loaded into the editor. The editor will read breakpoint information from "*.bpt" files usually created during a former debugger session. GoldED will start sending the following asynchronous message to the debugger port immediately (simply ReplyMsg() this message): BREAKPT FILE="dh0:main.c" DATA=4129038 ELEMENTS=5 FILE/K is a unique/resolved file name (to simplify file identification for the debugger). DATA/N and ELEMENTS/S are a description of the breakpoints. The data format is similiar to the breakpoint description embedded into QUERY commands (see above). The data can be referenced until the message has been replied. BREAKPT LINE/N,LOCKED/S,STATE/K,TOGGLE/S,NONOTIFY/S,ALL/N,CLEANUP/S template: BREAKPT LINE/N,LOCKED/S,STATE/K,TOGGLE/S,NONOTIFY/S examples: 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 <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, ...) in this message is a locked line number (valid at compile time). STATE/K is the new breakpoint state. FILE/K is the resolved file name. BREAKPT ALL/N template: BREAKPT ALL/N examples: BREAKPT ALL=0 BREAKPT ALL=1 This command is can be used by the user or by the debugger. Sets all breakpoints to a defined state (0 = unset, 1 = set) 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. BREAKPT CLEANUP/S template: BREAKPT CLEANUP/S example: BREAKPT CLEANUP This command is can be used by the user or by the debugger. It deletes all breakpoints in all buffers. Usually sent by the debugger after a debugger session has been terminated (DEBUG STOP). BREAKPT SAVE/S template: BREAKPT SAVE/S example: BREAKPT SAVE This command can be used by the user or by the debugger. Breakpoints of the current text are saved to the file "<textname>.bpt" (e.g. "main.bpt"). They are restored if you reload the text and they are passed to the debugger during a debugger session (see description of QUERY command sent to the debugger). It is recommended to combine this command with SAVE SMART to ensure that the text is saved, too (if modified). PC FILE/K,LINE/N,COLUMN/N,LOCKED/S,UNFOLD/S,ONEWINDOW/S,FREEZE/S,FILETYPE/K,HIGHLIGHT/S,PRESENT/S Example: 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 commands; 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 another 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).