A debugger for the GOBO Eiffel compiler

User’s guide

Wolfgang Jansen
wjansen@soft.cs.uni-potsdam.de

1 Introduction
This manual describes a debugger for the GEC. The debugger has two levels of
functionality. First, a reduced version of the debugger (called the post mortem
analyser) is added to a system if it is compiled with assertion checking on but
and without the debugger. The effect is that, instead of displaying the call stack
contents, the post mortem analyser gets invoked if the program crashes for some
reason. This way, not only stack data but also the data on heap can be analysed.
The post mortem analyser provides commands for the following topics:

• moving up and down the call stack (see Sec. 3);

• evaluating data (see Sec. 4);
• listing source code (see Sec. 5).

Additionally, the full debugger (called debugger in the following) provides com-
mands for the following topics:

• defining and manipulating breakpoints (see Sec. 7);

• running the program in a stop-and-go manner (see Sec. 6).

Further, Sec. 8 describes remaining miscellenous commands.

Some command descriptions in the following sections use a Backus-Naur form
similarly to the one used in B. Meyer: Eiffel. The Language. Moreover, some com-
mand descriptions rely on not explained terms (e.g. TYPE NAME, line count). It
is expected that those terms are sufficiently self-explanatory. The manual applies
the following style rules:

teletype : constant parts of a command;

italic : variable parts of a command, in particular, non-terminals of BNF rules;
sansserif : Eiffel source code;
small : functionality that has been prepared but not yet implemented.

1
2 Command format
2.1 General format
Commands start with a keyword denoting the command, then possibly followed
by more ore less sophisticated parameters. Most command keywords are composed
of letters but there are a few keywords consisting of a single non-alpha-numerical
character. Parameters starting with a letter have to be separated by at least one
blank from the command keyword consisting of letters whereas parameters may
(or even must) follow immediately non-letter keywords. A similar rule applies to
separate consecutive parameters.

2.2 Naming convention

Command names may be abbreviated. If so then the first command (according
to the ordering shown by command overview) that starts with the abbreviation
is selected. Moreover, some commands include specific keywords within para-
meter specifications. They serve mainly as separators to minimise conflicts with
other command parts or are alternatives to a TYPE NAME or a feature name to
achieve special effects. Some keywords are also keywords of Eiffel. The meaning
of those keywords has nothing to do with their meaning in Eiffel class texts, they
are used to avoid conflicts with other, non-keyword parameters. The parameter
keywords (except those which are also Eiffel keywords) may be abbreviated to
one character only.
The class, type, and feature names occurring in command parameters may be
rather long and typing them may be error prone. To ease the typing effort a bit,
those names may be abbreviated to as many characters as necessary to make
the name unique. Thereby, the letter case is ignored. Alternatively, the type’s
internal number may be used in place of TYPE NAME parameters (the internal
number is available by commands queries and types, see Sec. 4.6). Further, a
TYPE NAME may be specified as

like expression.

In this case, the expression (see Sec. 4.1 for explanation) is evaluated and its
dynamic type yields the TYPE NAME. Finally, in case of a generic type the
naming rules apply to its base class name as well as to all generic parameters.

2.3 Repetition
Entering an empty command line repeats, in general, the previous command.
This rule is often modified, e.g. if an error occurred or if precise repetition does
not make sense. The modification may affect the command parameters (possibly
dropping the parameters at all) or may be a related command. For example, if the
command is unknown then the command’s “repetition” is the overview command

2
displaying a short description of all commands. The command descriptions below
contain a hint at the actual repetition mode if it differs from pure repetition.

3 Moving up and down the call stack

Command where displays the call stack, one line per stack frame using the format

indicators stack level CLASS NAME.feature name:line number

The stack level starts with 0 for the innermost called routine. If this routine is in a
rescue clause then the failing routines have a negative stack level. The indicators may be
the following characters:

* indicates the actually selected stack frame;

- indicates a stack frame whose routine has been compiled without stack infor-
mation (e.g. external routines);
> indicates a stack frame whose routine has a rescue clause.

The following commands select a stack frame at a certain level.

up [n] : Go n levels up (to higher level numbers), default: n=1.

down [n] : Go n levels down (to lower level numbers), default: n=1.
. [n] : Go to level n, default: the actually chosen level.

These commands display the source code around the program point of the new
stack frame level and the value of Current at that level.
Repetition: the same command without parameters.

4 Evaluating and assigning data

4.1 Expression parameters
Some commands expect Eiffel expressions as parameters. The debugger distin-
guishes three levels of complexity: expressions, detailed expressions, and expres-
sion list.
An expression is, with a few restictions and additions, any Eiffel expression: a
multi-dot expression like x.y.z or composed of calls to infix and prefix functi-
ons with target and arguments multi-dot expressions. Multi-dot expressions may
include function calls (the arguments are, recursively, expressions as well). The
first item of a multi-dot expression may be one of

• a query of the current class provided that C code has been generated;

3
 • an argument or local variable of the routine at the actual stack level;
• a manifest of BOOLEAN, INTEGER 64, REAL 64, CHARACTER, or STRING
(in case of function arguments, the constant is silently adapted to the ex-
pected type);
• the predefined entities Current, Result, Void, True, False;
• an old value of the actual routine to be written as old: id (with id ≥ 1);
• a once function written as once:CLASS N AM E.f eature name representing the func-
tion’s value (the function must have already been initialized);
• in specific contexts: a question mark ? or an exclamation mark !.

Each of the forthcoming items has to be a query in the dynamic type of its left
neighbour.
A detailed expression selects features of an expression without the need to repeat
the expression’s notation. An expression list is a comma separated list of expres-
sions possibly equipped with a couple of details:
detailed expression := expression [ “[[” index range “]]” ] [ details ]
details := “{” expression list “}”
| “{” “all” [n] “}”
expression list := detailed expression
| expression list “,” detailed expression
The index range will be discussed in Sec. 4.2. The expressions within the braces
of details may start (besides the start item of arbitrary expressions) with the
placeholder ? referencing the value of the expression in front of the braces. The
last variant selects all attributes, attributes of attributes, ... up to depth n of the
expression (default: n=1; n=0 means no attributes). In contrast to expressions,
detailed expressions may not be further referenced.

4.2 SPECIAL objects

Single items of a SPECIAL object are accessible in C like notation: appending the
index (once again an expression) in brackets. The result is an expression and may
be further referenced.
Multiple array items may be selected by specifying an index range within double
brackets as follows:

• two limit indices (that are expressions either) separated by “..” select all
elements at indices within and including the limits;
• keyword all: select all items;
• keyword if followed by a boolean expression: select the items satisfying
this expression where the running array element is referred to by ?.

Each of these notations defines a detailed expression that cannot be further refe-
renced, but details in braces may be added. If so then a placeholder ? in the details

4
part refers to the running array element. Moreover, the placeholder ! denotes the
index itself.
Example: If query table is of a DS HASH TABLE type then command

print table.key storage [[if ? /= Void]] {table.item storage[!]}

displays key and item pairs of all elements of table.

4.3 Alias names

To ease the repeated typing of the same complicated expression, commands

alias name “:=” expression

alias name “->” detailed expression

define or redefine the alias name name, this may be any valid Eiffel identifier.
It is not necessary that name differs from feature names of any class. In case of
“:=” the defining expression is evaluated and name represents its value, in case
of “->” the defining expression is evaluated later. Commands

alias name “--”

status alias

undefine the alias name name or display all defined alias names and (depending
on “:=” or “->”) their values or definitions, respectively.
An alias name may be used when composing a detailed expression: the alias name
is to be prefixed by an underscore; the leading underscore ensures that the alias
name cannot be misunderstood as a feature of a class. If the alias name has been
defined by “:=” then it must be the first item of a multi-dot expression, otherwise
it may be used like a query. Within the detailed expression to be composed the
alias name is replaced by its value (in case of “:=”) or by a copy of its defining
detailed expression (in case of “->”). The resulting detailed expression is in fact
an expression if the defining detailed expression does not contain an index range
or details. In this case it may be further referenced.
Repetition: command status alias.

4.4 Displaying of expression values

The values of variables and expressions built of them can be computed and dis-
played by command

print [“‘”format] [expression list]

5
If expression list is not given then the command displays the values of Current, the
parameters, and local variables of the routine at the execution point. The print
command silently adds {all 1} to each detailed expression of an expression list
if details are not specified.
The format parameter is a non-empty sequence of characters g and x and controls
output formatting. If g is specified the item to be displayed is treated as global
data (see Sec. 4.5 for details). If x is specified and the item to be displayed is
one of INTEGER *, NATURAL *, CHARACTER * then the value is displayed in
hexadecimal form.

4.5 Global data

An overview of global data, i.e. values of once routines and unique integers, is
given by command globals. First, it lists all once routines where not yet in-
itialised ones are indicated by a leading Eiffel comment “- -”. In case of once
functions also the values are displayed. Second, it displays the definition of the
unique INTEGERs.
Whether an individual entity is global can be determined by the format g of the
print command. If the item to be displayed is the value of a once function of a
reference type (only those values can be identified uniquely) or is the value of a
unique integer then the definition of the value is displayed instead of the value
itself.

4.6 Type information

queries [TYPE NAME ] displays a list of the attributes and functions of type
TYPE NAME which may be used to build expressions. If no parameter is
given then the type of Current at the actual program point is used. In this
case, also the arguments and local variables of the current routine are listed.
types [r ] displays an overview of the types and classes whose names have a
substring (case sensitive!) matching the regular expression r and which
may be used as TYPE NAME or CLASS NAME in commands. Default:
display all known types and classes.

In case of the types command, each row shows the internal type number, some
indicators, and the type resp. class name. The indicators are:

C : class is a valid CLASS NAME

T : type is a valid TYPE NAME
d : class is deferred
x : type or class is expanded
b : type or class is basic expanded
s : type is separate

6
Repetition: command types.

4.7 Assignment
Command

assign target “:=” source

(where target and source are expressions) assigns the value of source to target.
target may be an attribute in some class, a field of an SPECIAL object, or a local
variable in the actual stack frame. source may any expression that conforms to
the static type of target (but things are more sophisticated, see below).
If target is an attribute of some class then invariant checking must be enabled for this class,
and the invariant must be satisfied after assignment if it was before (otherwise, the previous
state is restored).
The assignment is possible only if the target’s typeset contains the dynamic type
of the source, this means, if somewhere in the system an assigment (or actual
to formal argument association) occurs where an entity of the source’s dynamic
type is assigned to the target entity. Only in this case the polymorphic dispatch
of features called on target works correctly. So it is important to know the typeset
of a target entity, it is provided by command

dynamic target

Restriction: The commands are not available in the post mortem analyser.
Repetition: command print target.

5 Displaying source code

5.1 Line ranges
A line range of a class text may be specified as follows:
line range := [ CLASS NAME ] [“:” first line no [“‘” line count ] ]
| [ CLASS NAME ] “.” feature name
| “like” expression “.” feature name
| “-”[ line offset ] [ “‘” line count ]
The first variant selects the specified range of lines (hint: the line count is intro-
duced by a backspace). The second variant selects many 1 lines of the feature’s
definition. The third variant is a variation of the second: it computes the expres-
sion and the base class name of its type becomes the CLASS NAME. The fourth
variant defines a relative line range, see below for details.
1
Selecting all lines is planned but does currently not work (the compiler does not provide
enough information), instead as many lines are selected as are known to belong to the feature.

7
The following default rules apply in case of the first two variants:

• if CLASS NAME is absent then the CLASS NAME of the most recently
listed class is selected;
• if the first line no is absent then it is set to the most recently listed line
number +1 (or to 1 if end of file had been reached);
• if line count is absent then its setting depends on the command: 1 when
defining a breakpoint and 20 when displaying source code.

A line range of the fourth form is relative to the program point of the actual stack
level. As indicated by the minus sign, the line offset is taken negative. The default
is 0, i.e. the line range starts at the program point. The default of line count is one
plus the modulus of line offset, i.e. the default line range ends at the program
point. After specification, the relative line range is replaced internally by the
corresponding absolute line range. This is then also the default for forthcoming
line range specifications.
A line range is always implicitly defined when the program point of a certain
stack level is displayed, in particular after entering the interactive phase of the
debugger. This line range establishes the default values for the next explicit li-
ne range specification.

5.2 Listing
Source files (or parts thereof) can be listed by command

list line range

Each line listed is preceded by the line number and zero ore more of the following
indicators:

* the line is the stop point of the actual stack level

+ a breakpoint has been set at this line
| a tracepoint has been set at this line

Repetition: command list without parameter which means continuing the last
listing.

5.3 Searching
Commands

/ regexp
/

8
search a string matching the regular expression regexp (if specified) or the regexp
of the previous / command (if not specified) in source code. The regexp may be
constructed like a basic regular expression in the sense of the GOBO library class
RX REGULAR EXPRESSION.
The source code to be searched is related to the list command: the search starts
at the line that would be displayed first by an argument-less list command. If a
match is found then the corresponding line is displayed, and the default line range
for the forthcoming list (consequently, also for the /) commands gets adjusted
to the next line.
Warning: All characters (in particular, white space) following the command name
/ contribute to regexp.
Repetition: command / without parameter.

6 Stop and go
The debugger gets invoked by any of the following reasons:

• just after program start;

• if the program reaches the target condition of a dynamic command (see
below);
• if a debug instruction is performed;
• if an exception (assertation violation or OS signal) occurs and if no routine in the call
stack has a rescue clause;
• if the program is interrupted (i.e. when pressing Ctrl-C on a UNIX platform), rescue
clauses do not play any role;
• after program end.

The program can be run from the debugger in a stop-and-go manner by the
following commands:

cont [mode] [n] : n-times continues the execution to the next breakpoint.
next [mode] [n] : Executes next n instructions, do not step into called routines.
step [mode] [n] : Executes next n instructions, step into called routines.
finish [mode] [n] : Returns from the actual routine and from n-1 of its callers.
exit [mode] [n] : Executes the program until n nested loops are completed.

The default value of n is always 1. Command finish allows also for parameter
“.”: all routines are finished until the actually selected stack level is reached.
Parameter mode is one of the keywords break (default), trace, or silent. If
mode equals break then these commands check for breakpoints and tracepoints
on the way: display a message if a tracepoint is passed, stop (in case of next,
step, finish, exit) if a breakpoint has been reached, or stop after the n-th

9
breakpoint (in case of cont). If mode equals trace then breakpoints are treated
as tracepoints, but if mode equals silent then breakpoints and tracepoints are
ignored totally.
There is no explicit run command. After debugger start the program is started
and immediately stopped. Then one of the commands above is to be applied to
get the program running.
Repetition: the same command without parameters.
The program state (variables on heap and stack, once function values, and pro-
gram point) may be stored to a file for later restoring during the same debugger
run. The stored program state remains valid as long as the actual routine is not
left to its caller. Saving/restoring the program state may be used to approximate
a critical program point more and more closely.

mark : Stores the program state and marks the program point to be recoverable.
The marked program point is identified by a positive integer value.
reset [m] : Restore the marked program state number m, default m=0.
status mark : Displays a list of all valid marked points.

Moreover, the system’s initial state is always marked with number 0.

Warnings:

• Non-Eiffel data, e.g. file contents, are not stored and reset. This may cause
the program state to be incorrect after reset.
• Debugger settings such as breakpoint defintions are not saved/restored.
• The program state is written to a binary file with name system name.mm.
This file should not be viewed or printed and must not be modified.

Repetition: status mark.

7 Breakpoints
7.1 Definition and management
Breakpoints are defined by command

break [ n ] [ conditions ] [ actions ]

The command creates a new breakpoint if n is not specified or edits the existing
breakpoint no. n. The meaning of parameters conditions and actions is described
in Secs. 7.2 and 7.3, respectively.
Breakpoints are managed by the following commands.

status break : Displays the definition of all breakpoints.

10
enable n : Enables breakpoint no. n.
disable n : Disables breakpoint no. n.
delete n : Deletes breakpoint no. n.

Parameter n may be the number of an existing breakpoint or may be the keyword

all.
Repetition: command status break.

7.2 Conditions
Conditions of a breakpoint match are specified as a sequence of parameters:

conditions :=

[“catch” x ] [“at” l ] [“depth” d [“++”]] [“watch” e] [“type” T ] [“if” b]

where x is a keyword (see below), l is a line range, e is an expression, d is an

integer, T is a TYPE NAME, and b is a boolean expression. The breakpoint
matches if the conjunction (in the sense of and then 2 ) of all conditions evaluates
to true (where not specified conditions are considered true).
The conditions have the following meaning.

catch : The condition is satisfied if an exception of kind x occurs that will be

rescued in the given line range. More precisely,
• if the range is not specified then all rescue clauses of all classes match;
• if a CLASS NAME is specified but no feature name then all rescue
clauses of this class match;
• if (a CLASS NAME and) a feature name is specified then only the
rescue clause of this feature matches;
• if first line no or line count are given then they will be ignored.
The exception x may be one of the following keywords (the keyword may
be abbreviated by the same rules as for command names):
2
Easier checkable conditions have been arranged before complicated ones to detect a non-
match as soon as possible, and type is arranged before if to serve as a guard of the latter.

11
 Keyword Meaning
void call on void target
memory no more memory
require violation of precondition
ensure violation of postcondition
invariant violation of class invariant
check false check expression
failure routine failure
inspect incorrect inspect value
loop violation of loop invariant or variant
signal OS signal
catcall catcall
developer call to routine raise
all all exceptions
If exception x is specified then this exception and all exceptions above x in
the table will match.
If the breakpoint matches (i.e. if the catch condition and all other conditions
are satisfied) then the debugger will be invoked before the call stack gets
unwound, i.e. at the place where the exception occurred. Moreover, all other
breakpoint conditions refer to this program point.
at : The line range l specifies a part of a class text. It is to be written just like
the line range of the list command. If catch is not specified then the
condition is satisfied if the program performs an instruction within the line
range.
depth : The condition is satisfied if the depth of the call stack is at least d. If the
break point matches (i.e. all conditions are satisfied ) and if ++ is specified
then d is set to the actual stack depth plus one.
watch : The expression e specifies a memory address to be watched for changes of
its contents. The expression is evaluated just after definition of the break-
point, and its address and value are stored for forthcoming comparisons.
The contents of that memory location is then compared during program
run with the stored value. The condition is satisfied if the value has chan-
ged. The value will be replaced by the new one if the breakpoint matches
(i.e. if all break conditions are true). A breakpoint having a watch condition
will be called a watchpoint.
type : The parameter T may be a TYPE NAME or the CLASS NAME of the
base class of a generic type. The condition is satisfied if the dynamic type
of Current conforms to T (if T is a TYPE NAME ), or if its base class is a
descendant of T (if T is a CLASS NAME ).
if : This part specifies a boolean expression that is evaluated at the breakpoints
(with Current at the breakpoint to start the evaluation). Not surprising,
the condition is satisfied if the expression has value true. Moreover, the
debugger is invoked if the expression has errors or does not result in a
BOOLEAN value.
Hint: The type part may be used to ensure that the if expression is defined

12
 for Current at the breakpoint.

7.3 Actions
When a breakpoint matches then its associated actions will be performed. The
actions include displaying a message consisting of the breakpoint number and,
possibly, much more. Other actions can be set as parameters to the break com-
mand:

[ “print” e ] [ “cont” | “stop” ]

where e is an expression list. These parameters must be specified in the given

order and must follow the conditions.

print : The message includes the value of e evaluated at the matching point.
cont : The program does not stop if the breakpoint matches. This means that the
breakpoint is turned into a tracepoint. A breakpoint having this condition
will be called a tracepoint.
stop : The program stops if the breakpoint matches: the debugger gets invoked
and the message contains also the breakpoint text and the output of the
“.” command.

Among cont and stop is stop the default value. Specifying stop is necessary
only if a tracepoint is edited to become a breakpoint.

7.4 Editing
A breakpoint definition may be rather complex, therefore, error prone. To over-
come this problem, it is possible to edit an already defined breakpoint. The same
conditions and actions can be specified as when defining a new breakpoint. Any
specified condition or action overwrites that of the breakpoint in question, any
not specified condition or action remains as it was. An already existing condition
or action (except cont, stop) can be removed by specifying it with the special
parameter “--” (Eiffel‘s comment indicator).

8 Other commands
The post mortem analyser provides the following commands:

status [s] : Displays an overview of debugger settings. Possible values of s are

alias, break, mark.
status > [file] : Stores the alias names of the “->” form as well as breakpoint
and tracepoint definitions to file file (default: system name.dg) for use in
later system runs. (Watchpoints are not stored since their addresses may
be not valid after restoring.)

13
status < [file] : Restores the alias names and breakpoint/tracepoint definitions
from file file (default: system name.dg). The alias names and breakpoints
get added to the list of already existing alias names and breakpoints, re-
spectively.
help : Displays help information, see below.
quit : Quits the program.

Additionally, the debugger has the commands:

gc : Runs the garbage collector (provided the program has been compiled with garbage collec-
tion enabled).

A more detailed description of command help may be in order. The help consists
essentially of the contents of this manual split into many, logically arranged pages.
Each page offers a menu asking how to proceed:

• switch to a related page (if any);

• go back to the previous page: choice “^”;
• leave help (and display the actual program point): choice “--”.

Only the first character of the answer is checked for matching a menu entry.
Further, the menu offers a default answer enclosed in angle brackets.

14