axd






axd ‐ afnix cross debugger

axd [options] file



[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

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.

The current version is the 2.8.1release.

axc, axd, axl,

AFNIX comes with an extensive documentation. The
documentation is available onlineor in the docdirectory in
the form of formatted xhtml documents.

axdhas been written by (amaury@afnix.org) Amaury Darsch.












                             ‐2‐


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.

     debuggerAsample
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.

     debuggerStartingthe
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


     Debuggercommands
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.

     exampleDebuggingsession
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









                             ‐3‐


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.









                             ‐4‐


(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


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.

     terminationInvocationand
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>


     Debuggeroptions
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.










                             ‐5‐


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


     programRunningthe
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.

     programLoadingthe
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.

     programStartingthe
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"


     argumentsSettingprogram
Since the debugger is built on top of the interpreter, it is
possible to set directly the argument vector. The argument









                             ‐6‐


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
}


     Breakpointsoperations
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.

     Breakpointcommand
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.

     Viewingbreakpoints
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


     Resumingexecution
The axd:continuecommand resumes the program execution after









                             ‐7‐


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.

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.









                             ‐8‐


     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









                             ‐9‐


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









                            ‐10‐


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.