Provided by: afnix_2.9.2-2build1_amd64 
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
[e] mode
force the encoding mode
[f] runini
run initial file
[f] emacs
enable emacs mode
[f] assert
enable assertion checking
[f] noseed
do not seed the random engine
[f] seed
seed the random engine
DESCRIPTION
axdinvokes the AFNIX cross debugger. The axdclient 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 2.9.2release.
SEE ALSO
axc, axd, axl,
NOTES
AFNIX comes with an extensive documentation. The documentation is available onlineor in the docdirectory
in the form of formatted xhtml documents.
AUTHOR
axdhas been written by (amaury@afnix.org) Amaury Darsch.
GETTING STARTED
This chapter is short introduction to the cross debugger or axd. The debugger is a special interpreter
that is designed to help the developer to trace an application. 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-modepackage.
A sample debugger session
The cross debugger or axdis a special interpreter that gives the developer the opportunity to trace an
application 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 axdis built on top of the 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 axdwill do the same. When
the debugger is started, an axdprompt is displayed. At this stage, there is no difference with the
standard interpreter, except that a new namesetcalled axdis defined with all debugger commands. The
axd:quitor axd:quitcommands will terminate the session.
zsh> axd
(axd)axd:quit
Debugger commands
All debugger commands are located in the axdnameset. 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:breakwill define the symbol bas 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 axdis located in the directory exp/ref, that is part of
this distribution. The platform information example 0501.alswill be used for illustration. A simple
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 uri : 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-uri
The debugger is started with the file to debug. The axd:infocommand 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 nameand the form line
numberthat indicates where the debugger is position. Another way to get this information is with the
axd:listcommand 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 uri : " interp:afnix-uri
25
26
(axd)
With this in place it is possible to run the program. The axd:runcommand 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:breakcommand 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 : minor version number : breakpoint 0 in file 0501.als at line 19
(axd)
The axd:runcommand 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:nextcommand. Resuming the execution is done with the axd:continuecommand. The axd:exitor
axd:quitcommand terminates the session.
(axd)axd:next
patch version number : (axd)axd:next
interpreter version : --(axd)axd:continue
program name : axd
operating system name : linux
operating system type : unix
afnix official uri : http://www.afnix.org
(axd)axd:quit
USING THE DEBUGGER
This chapter describes in detail the usage of the cross debugger or axc. The debugger is a special
application that is built on top of the interpreter. For this reason, the debugger provides the full
execution environment with special commands bound into a dedicated nameset.
Invocation and termination
The axddebugger 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 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:exitor axd:quit.
zsh> axd PROGRAM
(axd) axd:quit
zsh>
Debugger options
The available options can be seen with the hoption and the current version with the voption. This mode of
operations is similar to the one found with the 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 axdcommand argument or with the axd:loadcommand. The
first available form in the primary file is used as the program starting point.
Loading the program
The axd:loadcommand 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 resolver rule apply for the
file name resolution.
If the string name has the .alsextension, the string is considered to be the file name.
If the string name has the .axcextension or no extension, the string is used to search a
file that has a .alsextension or that belongs to a librarian.
Note that these operations are also dependent on the ioption that adds a path or a librarian to the
search-path.
Starting the program
The axd:runcommand 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:runis 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 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:breakcommand. 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:breakcommand 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.alsat 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-infocommand 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:continuecommand 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:continuecommand resumes the
program execution.
DEBUGGER CONTROL REFERENCE
This appendix is a reference of the cross debugger or axd. The cross debugger is started with the
axdcommand. All control commands are bound to the axdnameset.
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.alsat 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:infocommand.
break-info
The axd:break-infocontrol 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.alsat line 12 and one in file test.alsat line
18. The axd:break-infocommand reports the current breakpoint settings.
continue
The axd:continuecontrol 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:continuecommand resumes the
program execution.
exit
The axd:exitcommand terminates a debugger session. This command is similar to the axd:quitcommand.
Syntax
axd:exit
(axd) axd:exit
info
The axd:infocommand 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:listcommand display the form listing starting at the current session line number. The current
form line number can also be seen with the axd:infocommand. 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:loadcommand sets the initialor default file to be used with the axd:runcontrol command.
Syntax
axd:load "file"
(axd) axd:load "demo.als"
In this example, the file demo.alsis set as the primary file. Using the axd:infocommand will report at
which line, the first available form has been found.
next
The axd:nextcommand executes the next line in the source file. The axd:nextcommand does not take
argument.
Syntax
axd:next
(axd) axd:next
quit
The axd:quitcommand terminates a debugger session. This command is similar to the axd:exitcommand.
Syntax
axd:quit
(axd) axd:quit
run
The axd:runcommand executes the default file in the slave interpreter. Without argument, the initialor
default file is executed. The axd:loadcommand 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.alsand run it.