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