NAME
axd - afnix cross debugger
SYNOPSIS
axd [options] file
OPTIONS
[h]
prints the help message
[v]
prints the program version
[i] path
add a directory path to the resolver
[f] assert
enable assertion checking
[f] emacs
enable emacs mode
DESCRIPTION
axd invokes the AFNIX cross debugger. The axd client permits to debug
an AFNIX program by inserting breakpoint at strategic positions in
the source code. During a debugging session, when a breakpoint is
reached, the program is suspended and the debugger prompt is shown.
Since the debugger is based on the AFNIX interpreter, the full power
of the AFNIX interpreter is available at the debugger prompt.
VERSION
The current version is the 1.5.2 release.
SEE ALSO
axc, axd, axl, axs
NOTES
AFNIX comes with an extensive documentation. The documentation is
available online or in the doc directory in the form of formated xhtml
documents.
AUTHOR
axd has been written by (amaury@afnix.org) Amaury Darsch.
GETTING STARTED
This chapter is short introduction to the AFNIX cross debugger or
axd. The AFNIX debugger is a special interpreter that is designed to
help the developer to trace an AFNIX program. The debugger is
designed to operate in a stand-alone mode or with Emacs. If you plan to
use the debugger with Emacs, you will have to install a gud-mode
package for AFNIX .
A sample debugger session
The AFNIX cross debugger} or axd is a special interpreter that gives
the developer the opportunity to trace an AFNIX program and examine
the object contents during the execution. Operations normally available
in a debugger are available with axd. Such operations include
breakpoints, stepping, stack tracing, and many others. Because axd is
built on top of the AFNIX interpreter, all standard operations are
supported by the debugger.
Starting the debugger
The debugger is started with the command axd. Within Emacs, the command
Meta-x axd will do the same. When the debugger is started, an axd
prompt is displayed. At this stage, there is no difference with the
standard AFNIX interpreter, except that a new nameset called axd is
defined with all debugger commands. The axd:quit or axd:quit commands
will terminate the session.
zsh> axd
(axd)axd:quit
Debugger commands
All debugger commands are located in the axd nameset. For example, the
command to set a breakpoint is axd:break. Since typing such command can
be annoying, it is possible to rebind them at your convenience. For
example, the form const b axd:break will define the symbol b as the
breakpoint command, but care should be taken with this approach if your
program uses the same symbol.
Debugging session example
The first example that demonstrates the use of axd is located in the
directory exp/ref, that is part of this distribution. The platform
information example 0501.als will be used for illustration. A simple
AFNIX session and the original source code is given below.
zsh> axi 0501.als
major version number :
minor version number :
patch version number :
interpreter version : ..
program name : afnix
operating system name : linux
operating system type : unix
afnix official url : http://www.afnix.org
The source code for this example is given below.
# many comments before
println "major version number : " interp:major-version
println "minor version number : " interp:minor-version
println "patch version number : " interp:patch-version
println "interpreter version : " interp:version
println "program name : " interp:program-name
println "operating system name : " interp:os-name
println "operating system type : " interp:os-type
println "afnix official url : " interp:afnix-url
The debugger is started with the file to debug. The axd:info command
can be used to print some information.
zsh> axd 0501.als
(axd) axd:info
debugger version : ..
os name : linux
os type : unix
initial file : 0501.als
form file name : 0501.als
form line number : 17
verbose mode : true
max line display : 10
defined breakpoints : 0
(axd)
Along with the version, initial file name and other information, is the
form file name and the form line number that indicates where the
debugger is position. Another way to get this information is with the
axd:list command that display the file at its current break position.
(axd) axd:list
17 println "major version number : " interp:major-version
18 println "minor version number : " interp:minor-version
19 println "patch version number : " interp:patch-version
20 println "interpreter version : " interp:version
21 println "program name : " interp:program-name
22 println "operating system name : " interp:os-name
23 println "operating system type : " interp:os-type
24 println "afnix official url : " interp:afnix-url
25
26
(axd)
With this in place it is possible to run the program. The axd:run
command will do the job, but will not give you the opportunity to do
something since there is no breakpoint installed. So, installing a
breakpoint is simply achieved by giving the file name and line number.
To make life easier, the axd:break command takes also 0 or argument.
Without argument, a breakpoint is set at the current position. With one
integer argument, a breakpoint is set at the specified line in the
current file. If the verbose mode is active (which is the default), a
message is printed to indicate the breakpoint index.
(axd) axd:break 19
setting breakpoint 0 in file 0501.als at line 19
(axd)axd:run
major version number : 0
minor version number : 9
breakpoint 0 in file 0501.als at line 19
(axd)
The axd:run command starts the program and immediately stops at the
breakpoint. Note that the debugger prints a message to indicate the
cause of such break. After this, stepping is achieved with the axd:next
command. Resuming the execution is done with the axd:continue command.
The axd:exit or axd:quit command terminates the session.
(axd)axd:next
patch version number : 1
(axd)axd:next
interpreter version : 1-0-0
(axd)axd:continue
program name : axd
operating system name : linux
operating system type : unix
afnix official url : http://www.afnix.org
(axd)axd:quit
USING THE DEBUGGER
This chapter describes in detail the usage of the AFNIX cross
debugger or axc. The debugger is a special application that is built on
top of the AFNIX interpreter. For this reason, the debugger provides
the full execution environment with special commands bound into a
dedicated nameset.
Invocation and termination
The axd debugger is started by typing the command axd. Once started,
the debugger reads the commands from the terminal. Since the debugger
is built on top of the AFNIX interpreter, any command is in fact a
special form that is executed by the interpreter. The natural way to
invoke the debugger is to pass the primary file to debug with
eventually some arguments.
zsh> axd PROGRAM [arguments]
When the debugger is started, a prompt ’(axd)’ indicates that the
session is running. The debugger session is terminated with the
commands axd:exit or axd:quit.
zsh> axd PROGRAM
(axd) axd:quit
zsh>
Debugger options
The available options can be seen with the h option and the current
version with the v option. This mode of operations is similar to the
one found with the AFNIX interpreter.
zsh> axd [h]
usage: axd [options] [file] [arguments]
[h] print this help message
[v] print version information
[i] path add a path to the resolver
[e mode] force the encoding mode
[f runini] run initial file
[f emacs] enable emacs mode
[f assert] enable assertion checks
[f nopath] do not set initial path
Running the program
When a program is run within the debugger, a primary file must be used
to indicate where to start the program. The file name can be given
either as an axd command argument or with the axd:load command. The
first available form in the primary file is used as the program
starting point.
Loading the program
The axd:load command loads the primary file and mark the first
available form as the starting form for the program execution. The
command takes a file name as its first argument. The AFNIX resolver
rule apply for the file name resolution.
If the string name has the .als extension, the string is
considered to be the file name.
If the string name has the .axc extension or no extension,
the string is used to search a file that has a .als
extension or that belongs to a librarian.
Note that these operations are also dependent on the i option that adds
a path or a librarian to the search-path.
Starting the program
The axd:run command starts the program at the first available form in
the primary file. The program is executed until a breakpoint or any
other halting condition is reached. Generally, when the program
execution is suspended, an entry into the debugger is done and the
prompt is shown at the command line.
(axd)axd:run
The axd:run is the primary command to execute before the program can be
debugged. Eventually, a file name can be used as the primary file to
execute.
(axd)axd:run "test.als"
Setting program arguments
Since the debugger is built on top of the AFNIX interpreter, it is
possible to set directly the argument vector. The argument vector is
bound to the interpreter with the qualified name interp:argv. The
standard vector can be used to manipulate the argument vector.
(axd)interp:argv:reset
(axd)interp:argv:append "hello"
In this example, the interpreter argument vector is reset and then a
single argument string is added to the vector. If one wants to see the
interpreter argument vector, a simple procedure can be used as shown
below.
const argc (interp:argv:length)
loop (trans i 0) (< i argc) (i:++) {
trans arg (interp:argv:get i)
println "argv[" i "] = " arg
}
Breakpoints operations
Breakpoints are set with the axd:break command. If a breakpoint is
reached during the program execution, the program is suspended and the
debugger session is resumed with a command prompt. At the command
prompt, the full interpreter is available. It permits to examine
symbols.
Breakpoint command
The axd:break command sets a breakpoint in a file at a specified line
number. If the file is not specified, the primary file is used instead.
If the line number is not specified, the first available form in the
current file is used.
(axd) axd:break "demo.als" 12
Setting breakpoint 0 in file demo.als at line 12
In this example, a breakpoint is set in the file demo.als at the line
number 12. The file name does not have to be the primary file. If
another file name is specified, the file is loaded, instrumented and
the breakpoint is set.
Viewing breakpoints
The axd:break-info command reports some information about the current
breakpoint setting.
(axd) axd:break "demo.als" 12
(axd) axd:break "test.als" 18
(axd) axd:break-info
Breakpoint 0 in file demo.als at line 12
Breakpoint 1 in file test.als at line 18
Resuming execution
The axd:continue command resumes the program execution after a
breakpoint. The program execution continues until another breaking
condition is reached or the program terminates.
(axd) axd:run
Breakpoint 0 in file demo.als at line 12
(axd) axd:continue
In this example, the program is run and stopped at breakpoint 0. The
axd:continue command resumes the program execution.
DEBUGGER CONTROL REFERENCE
This appendix is a reference of the AFNIX cross debugger or axd. The
AFNIX cross debugger is started with the axd command. All control
commands are bound to the axd nameset.
break
The axd:breakbreak command sets a breakpoint. Without argument a
breakpoint is set in the current file at the current line. With a line
number, the breakpoint is set in the current file. With two arguments,
the first one is used as the file name and the second one is used as
the line number.
Syntax
axd:break axd:break "line" axd:break "file" "line"
(axd) axd:break "demo.als" 12
(axd) axd:break 25
The first example sets a breakpoint in the file demo.als at line 12.
The second example sets a breakpoint in the current file at line 25.
Without argument, the command sets the breakpoint at the current line.
The current line can be seen with the axd:info command.
break-info
The axd:break-info control command reports some information about the
current breakpoints.
Syntax
axd:break-info
(axd) axd:break "demo.als" 12
(axd) axd:break "test.als" 18
(axd) axd:break-info
Breakpoint 0 in file demo.als at line 12
Breakpoint 1 in file test.als at line 18
In this example, two breakpoints are set. One in file demo.als at line
12 and one in file test.als at line 18. The axd:break-info command
reports the current breakpoint settings.
continue
The axd:continue control command resumes the program execution after a
breakpoint. The program execution continues until a breakpoint or
another terminating condition is reached.
Syntax
axd:continue
(axd) axd:run
Breakpoint 0 in file demo.als at line 12
(axd) axd:continue
In this example, the program is run and stopped at breakpoint 0. The
axd:continue command resumes the program execution.
exit
The axd:exit command terminates a debugger session. This command is
similar to the axd:quit command.
Syntax
axd:exit
(axd) axd:exit
info
The axd:info command reports some debugger information. Such
information includes the debugger version, the operating system, the
primary input file, the primary input file source and more.
Syntax
axd:info
(axd) axd:info
debugger version : ..
os name : linux
os type : unix
initial file : 0501
form file name : 0501.als
form line number : 17
verbose mode : true
max line display : 10
defined breakpoints : 0
list
The axd:list command display the form listing starting at the current
session line number. The current form line number can also be seen with
the axd:info command. The number of line is a debugger parameter. The
first line to display can also be set as the first parameter. A file
name can also be set.
Syntax
axd:list axd:list "line" axd:list "file" "line"
(axd) axd:list
(axd) axd:list 20
(axd) axd:list "file.als" 20
The first example shows the listing at the current debugger line. The
second example starts the listing at line 20. The third example starts
at line 20 with file file.als.
load
The axd:load command sets the initial or default file to be used with
the axd:run control command.
Syntax
axd:load "file"
(axd) axd:load "demo.als"
In this example, the file demo.als is set as the primary file. Using
the axd:info command will report at which line, the first available
form has been found.
next
The axd:next command executes the next line in the source file. The
axd:next command does not take argument.
Syntax
axd:next
(axd) axd:next
quit
The axd:quit command terminates a debugger session. This command is
similar to the axd:exit command.
Syntax
axd:quit
(axd) axd:quit
run
The axd:run command executes the default file in the slave interpreter.
Without argument, the initial or default file is executed. The axd:load
command can be used to set the initial file. With one argument, the
file name argument is used as the initial file.
Syntax
axd:run axd:run "file"
(axd) axd:run
(axd) axd:run "demo.als"
The first example runs the initial file. The second example sets the
initial file as demo.als and run it.