| AFNIX Cross Debugger

axd [client]

Synopsis

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

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.

The source code for this example is given below.

The debugger is started with the file to debug. The `axd:info` command can be used to print some information.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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:break`break 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

Example

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

Example

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

Example

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

Example

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

Example

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

Example

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

Example

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

Example

quit

The `axd:quit` command terminates a debugger session. This command is similar to the `axd:exit` command.

Syntax

Example

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

Example

The first example runs the initial file. The second example sets the initial file as `demo.als` and run it.