Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
axd(1)				 AFNIX Client				axd(1)

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

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	devel-
       oper 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	devel-
       oper  the  opportunity  to  trace an application	and examine the	object
       contents	during the execution. Operations normally available in	a  de-
       bugger  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 de-
       bugger  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 ex-
       ample,  the form	const b	axd:breakwill define the symbol	bas the	break-
       point command, but care should be taken with this approach if your pro-
       gram uses the same symbol.

       Debugging session example
       The first example that demonstrates the use of axdis located in the di-
       rectory exp/ref,	that is	part of	this distribution. The platform	infor-
       mation  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: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:runcom-
       mand will do the	job, but will not give you the opportunity to do some-
       thing since there is no breakpoint installed. So, installing  a	break-
       point  is  simply  achieved by giving the file name and line number. To
       make life easier, the axd:breakcommand takes also 0 or argument.	 With-
       out argument, a breakpoint is set at the	current	position. With one in-
       teger argument, a breakpoint is set at the specified line in  the  cur-
       rent file. If the verbose mode is active	(which is the default),	a mes-
       sage 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:contin-
       uecommand. 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  de-
       bugger  is to pass the primary file to debug with eventually some argu-
       ments.

       zsh> axd	PROGRAM	[arguments]

       When the	debugger is started, a prompt '(axd)'indicates that  the  ses-
       sion  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 ver-
       sion  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 ei-
       ther 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	    .alsexten-
	      sion 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	execu-
       tion 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 vec-
       tor 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  sym-
       bols.

       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 an-
       other 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	break-
       point. 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	break-
       point is	set in the current file	at the current line. With a line  num-
       ber, 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.	 With-
       out  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  re-
       ports the current breakpoint settings.

       continue
       The  axd:continuecontrol	 command resumes the program execution after a
       breakpoint. The program execution continues until a breakpoint  or  an-
       other 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 sim-
       ilar 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 sim-
       ilar 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: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.alsand run it.

AFNIX				  2017-04-29				axd(1)

NAME | SYNOPSIS | OPTIONS | DESCRIPTION | VERSION | SEE ALSO | NOTES | AUTHOR | GETTING STARTED | USING THE DEBUGGER | DEBUGGER CONTROL REFERENCE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=axd&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help