Provided by: afnix_2.1.1-3_amd64 bug

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

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

SEE ALSO

       axc, axd, axl,

NOTES

       AFNIX   comes with an extensive documentation. The documentation is available online or in
       the doc directory in the form of formatted xhtml documents.

AUTHOR

       axd has 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-mode package.

       A sample debugger session
       The  cross  debugger  or  axd  is  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 axd is 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 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 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 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: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 uri     : " interp:afnix-uri
       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   :
       minor version number   :
       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   :
       (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  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.

DEBUGGER CONTROL REFERENCE

       This appendix is a reference of the cross debugger or axd. The 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.