13
13
<!-- = incidental or special damages arising in any way out of the use = -->
14
14
<!-- = of this software. = -->
15
15
<!-- ====================================================================== -->
16
<!-- = copyright (c) 1999-2007 - amaury darsch = -->
16
<!-- = copyright (c) 1999-2011 - amaury darsch = -->
17
17
<!-- ====================================================================== -->
19
19
<chapter client="axd" number="2">
20
20
<title>Using the debugger</title>
23
This chapter describes in detail the usage of the <afnix/>
24
cross debugger or <product>axc</product>. The debugger is a special
25
application that is built on top of the <afnix/> interpreter. For
26
this reason, the debugger provides the full execution environment
27
with special commands bound into a dedicated nameset.
23
This chapter describes in detail the usage of the cross debugger
24
or <product>axc</product>. The debugger is a special
25
application that is built on top of the interpreter. For
26
this reason, the debugger provides the full execution environment
27
with special commands bound into a dedicated nameset.
30
30
<!-- invocation and termination -->
32
32
<title>Invocation and termination</title>
35
The <product>axd</product> debugger is started by typing the
36
command <command>axd</command>. Once started, the debugger reads
37
the commands from the terminal. Since the debugger is built on top
38
of the <afnix/> interpreter, any command is in fact a special form
39
that is executed by the interpreter. The natural way to invoke the
40
debugger is to pass the primary file to debug with eventually some
35
The <product>axd</product> debugger is started by typing the
36
command <command>axd</command>. Once started, the debugger reads
37
the commands from the terminal. Since the debugger is built on top
38
of the interpreter, any command is in fact a special form
39
that is executed by the interpreter. The natural way to invoke the
40
debugger is to pass the primary file to debug with eventually some
45
zsh> axd PROGRAM [arguments]
45
zsh> axd PROGRAM [arguments]
49
When the debugger is started, a prompt <tt>'(axd)'</tt> indicates
50
that the session is running. The debugger session is terminated
51
with the commands <code>axd:exit</code> or <code>axd:quit</code>.
49
When the debugger is started, a prompt <tt>'(axd)'</tt> indicates
50
that the session is running. The debugger session is terminated
51
with the commands <code>axd:exit</code> or <code>axd:quit</code>.
60
60
<!-- debugger options -->
62
62
<title>Debugger options</title>
65
The available options can be seen with the <option>h</option>
66
option and the current version with the <option>v</option>
67
option. This mode of operations is similar to the one found with
68
the <afnix/> interpreter.
65
The available options can be seen with the <option>h</option>
66
option and the current version with the <option>v</option>
67
option. This mode of operations is similar to the one found with
73
usage: axd [options] [file] [arguments]
74
[h] print this help message
75
[v] print version information
76
[i] path add a path to the resolver
77
[e mode] force the encoding mode
78
[f runini] run initial file
79
[f emacs] enable emacs mode
80
[f assert] enable assertion checks
81
[f nopath] do not set initial path
73
usage: axd [options] [file] [arguments]
74
[h] print this help message
75
[v] print version information
76
[i] path add a path to the resolver
77
[e mode] force the encoding mode
78
[f runini] run initial file
79
[f emacs] enable emacs mode
80
[f assert] enable assertion checks
81
[f nopath] do not set initial path
87
87
<title>Running the program</title>
90
When a program is run within the debugger, a primary file must
91
be used to indicate where to start the program. The file name
92
can be given either as an <command>axd</command> command
93
argument or with the <code>axd:load</code> command. The first
94
available form in the primary file is used as the program
90
When a program is run within the debugger, a primary file must
91
be used to indicate where to start the program. The file name
92
can be given either as an <command>axd</command> command
93
argument or with the <code>axd:load</code> command. The first
94
available form in the primary file is used as the program
99
99
<!-- program loading -->
100
<!-- running the program -->
100
<!-- running the program -->
102
102
<title>Loading the program</title>
105
The <code>axd:load</code> command loads the primary file and
106
mark the first available form as the starting form for the
107
program execution. The command takes a file name as its first
108
argument. The <afnix/> resolver rule apply for the file name
105
The <code>axd:load</code> command loads the primary file and
106
mark the first available form as the starting form for the
107
program execution. The command takes a file name as its first
108
argument. The resolver rule apply for the file name
114
If the string name has the <extn>.als</extn> extension, the
115
string is considered to be the file name.
114
If the string name has the <extn>.als</extn> extension, the
115
string is considered to be the file name.
118
If the string name has the <extn>.axc</extn> extension or no
119
extension, the string is used to search a file that has a
120
<extn>.als</extn> extension or that belongs to a librarian.
118
If the string name has the <extn>.axc</extn> extension or no
119
extension, the string is used to search a file that has a
120
<extn>.als</extn> extension or that belongs to a librarian.
125
Note that these operations are also dependent on the
126
<option>i</option> option that adds a path or a librarian to
125
Note that these operations are also dependent on the
126
<option>i</option> option that adds a path or a librarian to
133
133
<title>Starting the program</title>
136
The <code>axd:run</code> command starts the program at the first
137
available form in the primary file. The program is executed
138
until a breakpoint or any other halting condition is
139
reached. Generally, when the program execution is suspended, an
140
entry into the debugger is done and the prompt is shown at the
136
The <code>axd:run</code> command starts the program at the first
137
available form in the primary file. The program is executed
138
until a breakpoint or any other halting condition is
139
reached. Generally, when the program execution is suspended, an
140
entry into the debugger is done and the prompt is shown at the
149
The <code>axd:run</code> is the primary command to execute
150
before the program can be debugged. Eventually, a file name can
151
be used as the primary file to execute.
149
The <code>axd:run</code> is the primary command to execute
150
before the program can be debugged. Eventually, a file name can
151
be used as the primary file to execute.
155
(axd)axd:run "test.als"
155
(axd)axd:run "test.als"
161
161
<title>Setting program arguments</title>
164
Since the debugger is built on top of the <afnix/> interpreter,
165
it is possible to set directly the argument vector. The argument
166
vector is bound to the interpreter with the qualified name
167
<code>interp:argv</code>. The standard vector can be used to
168
manipulate the argument vector.
164
Since the debugger is built on top of the interpreter,
165
it is possible to set directly the argument vector. The argument
166
vector is bound to the interpreter with the qualified name
167
<code>interp:argv</code>. The standard vector can be used to
168
manipulate the argument vector.
172
(axd)interp:argv:reset
173
(axd)interp:argv:append "hello"
172
(axd)interp:argv:reset
173
(axd)interp:argv:append "hello"
177
In this example, the interpreter argument vector is reset and
178
then a single argument string is added to the vector. If one
179
wants to see the interpreter argument vector, a simple procedure
180
can be used as shown below.
177
In this example, the interpreter argument vector is reset and
178
then a single argument string is added to the vector. If one
179
wants to see the interpreter argument vector, a simple procedure
180
can be used as shown below.
184
const argc (interp:argv:length)
185
loop (trans i 0) (< i argc) (i:++) {
184
const argc (interp:argv:length)
185
loop (trans i 0) (< i argc) (i:++) {
186
186
trans arg (interp:argv:get i)
187
187
println "argv[" i "] = " arg
195
195
<title>Breakpoints operations</title>
198
Breakpoints are set with the <code>axd:break</code> command. If a
199
breakpoint is reached during the program execution, the program is
200
suspended and the debugger session is resumed with a command
201
prompt. At the command prompt, the full interpreter is
202
available. It permits to examine symbols.
198
Breakpoints are set with the <code>axd:break</code> command. If a
199
breakpoint is reached during the program execution, the program is
200
suspended and the debugger session is resumed with a command
201
prompt. At the command prompt, the full interpreter is
202
available. It permits to examine symbols.
206
206
<title>Breakpoint command</title>
209
The <code>axd:break</code> command sets a breakpoint in a file
210
at a specified line number. If the file is not specified, the
211
primary file is used instead. If the line number is not
212
specified, the first available form in the current file is
209
The <code>axd:break</code> command sets a breakpoint in a file
210
at a specified line number. If the file is not specified, the
211
primary file is used instead. If the line number is not
212
specified, the first available form in the current file is
217
(axd) axd:break "demo.als" 12
218
Setting breakpoint 0 in file demo.als at line 12
217
(axd) axd:break "demo.als" 12
218
Setting breakpoint 0 in file demo.als at line 12
222
In this example, a breakpoint is set in the file
223
<file>demo.als</file> at the line number 12. The file name does
224
not have to be the primary file. If another file name is
225
specified, the file is loaded, instrumented and the breakpoint
222
In this example, a breakpoint is set in the file
223
<file>demo.als</file> at the line number 12. The file name does
224
not have to be the primary file. If another file name is
225
specified, the file is loaded, instrumented and the breakpoint
232
232
<title>Viewing breakpoints</title>
235
The <code>axd:break-info</code> command reports some information
236
about the current breakpoint setting.
235
The <code>axd:break-info</code> command reports some information
236
about the current breakpoint setting.
240
(axd) axd:break "demo.als" 12
241
(axd) axd:break "test.als" 18
243
Breakpoint 0 in file demo.als at line 12
244
Breakpoint 1 in file test.als at line 18
240
(axd) axd:break "demo.als" 12
241
(axd) axd:break "test.als" 18
243
Breakpoint 0 in file demo.als at line 12
244
Breakpoint 1 in file test.als at line 18
250
250
<title>Resuming execution</title>
253
The <code>axd:continue</code> command resumes the program
254
execution after a breakpoint. The program execution continues
255
until another breaking condition is reached or the program
253
The <code>axd:continue</code> command resumes the program
254
execution after a breakpoint. The program execution continues
255
until another breaking condition is reached or the program
261
Breakpoint 0 in file demo.als at line 12
261
Breakpoint 0 in file demo.als at line 12
266
In this example, the program is run and stopped at breakpoint
267
0. The <code>axd:continue</code> command resumes the program
266
In this example, the program is run and stopped at breakpoint
267
0. The <code>axd:continue</code> command resumes the program
added
removed
src/clt/axd/doc/chapter-2.xml
