Provided by: afnix_2.8.1-2_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

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

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.