17K. EDBG
---------

bugs fixed for v3.3a:
- Double-clicking on window frames no longer sets breakpoints, etc.
- 'ARG/K' argument now works (sets the arguments for the program being
  debugged)
- More than 16 windows allowed now, without crashing!
- Safer closing of public screen
- Unary negation now works as an expression
- No longer ignores some identifiers with "_"
- Serious (but benign?) bugs in initial breakpoint setup code removed

features new for v3.3a:
- Integrated calls to Explorer to debug objects (extracts type
  information from declarations)
- Can now debug standard global variables
- Can now debug "self" variable (requires EC v3.3a+)
- "Follow Step" mode added (and configurable)
- "Repeat Step" mode added (useful for debugging loops)
- "^var" expression now handled
- Source location of offsets added (useful for finding Enforcer hits)
- Registers now marked with whether they have changed since last step
- Status/flags register now expressed more clearly


Explorer
--------

To examine/watch a variable (in the current scope) double-click on it.
To see it in Explorer, press Shift while you double-click.  If
Explorer is not running it will be automatically started (as
"explorer" or whatever you set in the options, including any
arguments).  It will be instructed to open on the same screen as EDBG,
and will quit when EDBG quits (but only if EDBG started it).  Explorer
ought to be run in Auto-Reply mode, and you need Explorer v2.2j+.



EDBG is the E sourcelevel debugger. To use it, compile your source with
the DEBUG flag (this works on both main program an modules).
This will add debug infos to your executable/module.

NOTE: Do NOT distribute a program of which any part is compiled with DEBUG/S.
(You can check this with ShowHunk, it should not contain any hunk_debug).
Programs with debug-infos are compiled with extra NOPs to facilitate
debugging, which isn't wanted in the final code.

Always make sure sources and compiled are in the current directory, then
fire up EDBG with:

1> EDBG exename

template:

EXECUTABLE/A,PUBSCREEN/K: 

with for example PUBSCREEN=Workbench you can run EDBG anywhere. By default
it opens it own screen, which is a clone of the workbench in size and
display mode. EDBG works fine on the graphics-cards etc.

EDBG opens a window for every source/module in your project, and it will start
with the one that contains 'main'.  From you can step through your code, and
windows will automatically open when necessary.  When code doesn't have a
source attached, it can be executed only (which is sometimes handy, if it
doesn't need to be debugged).

From here all is pretty intuitive. Major buttons are the first two pictures
which are step over/in. Step in follows the code every step as it is
executed, step over does the same but does not enter subroutines.
[Just try it, the debugger is quite intuitive]

Other functions show memory or register windows, and various other functions.
An important one is double-clicking on variable-names:  this will show their
contents in variable view window.  Double clicking somewhere not on a variable
allows you to set a breakpoint.

For the memory views, memory breakpoints, exception raising features a subset
of the E expression language can be used to denote addresses and values:

values: 123, $ABC, %010101, "FORM"
variables: a, {a}
operators: +, -, *, /, ()

For example:
- to check when variable `a' is modified, use `{a}' as a memory breakpoint.
- to view the memory pointed to by array `a' (of LONGs) at offset `b', use
  `a+(b*4)' with a memory view.
- to change the contents of variable `a' into `b*2' click on the variable
  in the variable-view and select 'Modify'.

Note that when raising exceptions, that the handler for the current PROC
is installed only at the first statement after the local DEFs, i.e. you will
want to step past there first before raising an exception that should
go to that handler.

To quit a debugging session in the middle of a program while still freeing
all resources, or to test the capacity of your program to deal with failures,
raise an exception.

Caveats:
- The debugged program runs on the same task as EDBG. this means that
  all code that does something special to the task will have to be
  careful. An example is Forbid() etc.
- A special case is ReadArgs(). because EDBG already read the args, a
  call from the debugged program will cause a read from the console.
  So you can conveniently type the args to your program on the EDBG
  output console and press return.

Know problems:
- The variable view treats scopes on basis of variable names

Future:
- editing in variable and memory views
- more extensive E expression language support
- E types support (OBJECTs in particular)
- cooperation with enforcer (as soon as I can run it)


The LINEDEBUG and SYM options.
The LINEDEBUG option adds linedebug info to your executable (for each line of
code inside a PROC). This option is necessary for EDBG, but the DEBUG switch
automatically turns it on. LINEDEBUG is partially compatible with the "LINE"
HUNK_DEBUG produced by other compilers/assemblers, so it can be useful with
other debug-tools as well. The SYM option is not necessary for EDBG, but
can be useful for others, such as AProf or disassemblers.


The EDBG Arexx port (name: "EDBG")

EDBG's prefs saving works by saving an arexx-script, and running it again on
startup.  It will save specific prefs for every project, remember window
positions (if you want to), and also variables you were watching!

Select 'Settings...', and after that 'Save Settings'.  You may add optional
Arexx-scripts that can be launched directly from EDBG's 'Rexx' menu.  The
saved script is '.edbg-startup.rexx' in the current dir, which you are
encouraged to examine and modify.

currently supported EDBG Arexx commands:

	QUIT

emergency exit (raising an exception is friendlier).

	STEPIN
	STEPOVER
	RUN

step in/over and run to breakpoint. only actually performed when
control returns to the debugged program.

	EVAL exp

allows you to evaluate an E expression. You may use variables
from the scope that is currently being debugged (much like
'Eval E Expression' from the menu). Nearly all Arexx commands
that expect integer arguments can use similar expressions to EVAL.
This is the only command that returns something in the rexx
variable "rc" (the value of the expression). example:

'eval {a}+(b*4)'
say 'rc =' rc

you might need to fiddle with "options failat". Note closely
how these to get their variables from entirely different scopes:

'eval a+b'
'eval' a+b

(from Arexx (!))

	BREAKPOINT linenum

sets the breakpoint to that linenumber (in the current view).

	MEMORYBREAKPOINT addr

sets a memory breakpoint on that address. example:

'memorybreakpoint {a}'
'run'

runs to the spot where variable "a" gets modified.

	RAISE exception exceptioninfo

raises that exception in the debugged program.

	ASSIGN varname exp

modifies a variable in the current scope. example:

'assign a a+1'

increases "a" by one.

	WATCH varname varname ...

may be followed by any number of variable names. these will be
inserted into the list of watched variables, which will then
automatically be shown whenever you get to the scope that
contains those variables.

	MEMORY exp

opens a memory window on the address denoted by exp. doesn't
check for validity of the address.

	VARIABLES left top width height

opens the variable view window on that particular spot on the
EDBG screen. If it was already open, it will resize it if
necessary.

	SRCWINDOW srcname left top width height

same for the source view of source "srcname"

	NOABOUT

prevents the about window from popping up

	NOREFRESH

will not refresh memory windows etc. at every step

	REXX n script

sets up the arexx script "script" for launching within EDBG,
from menu item "n".


[note: if you want EDBG to make debugging steps during the
 execution of your scripts, you should launch them with 'rx',
 as those launched from EDBG execute the whole script before
 returning to the debugged program]