Return to debug.texi CVS log

Up to [local] / OpenXM / src / asir-doc / parts

Various changes.
Added descriptions of new (old?) functions.

@comment $OpenXM: OpenXM/src/asir-doc/parts/debug.texi,v 1.3 2003/04/20 08:01:25 noro Exp $
\BJP
@node $B%G%P%C%,(B,,, Top
@chapter $B%G%P%C%,(B
\E
\BEG
@node Debugger,,, Top
@chapter Debugger
\E

@menu
\BJP
* $B%G%P%C%,$H$O(B::
* $B%3%^%s%I$N2r@b(B::
* $B%G%P%C%,$N;HMQNc(B::
* $B%G%P%C%,$N=i4|2=%U%!%$%k$NNc(B::
\E
\BEG
* What is Debugger::
* Debugger commands::
* Execution example of debugger::
* Sample file of initialization file for Debugger::
\E
@end menu

\BJP
@node $B%G%P%C%,$H$O(B,,, $B%G%P%C%,(B
@section $B%G%P%C%,$H$O(B
\E
\BEG
@node What is Debugger,,, Debugger
@section What is Debugger
\E

@noindent
\BJP
C $B8@8l$G=q$+$l$?%W%m%0%i%`$N$?$a$N%G%P%C%,(B @code{dbx} 
$B$O(B, $B%=!<%9%l%Y%k$G$N%V%l!<%/%]%$%s%H$N@_Dj(B, $B%9%F%C(B
$B%W<B9T(B, $BJQ?t$N;2>H$J$I$,2DG=$J6/NO$J%G%P%C%,$G$"$k(B. @b{Asir} $B$G$O(B, 
@code{dbx} $BIw$N%G%P%C%,$rMQ0U$7$F$$$k(B. $B%G%P%C%0%b!<%I$KF~$k$K$O(B, $B%H%C(B
$B%W%l%Y%k$G(B @code{debug;} $B$HF~NO$9$k(B. 
\E
\BEG
A debugger @code{dbx} is available for C programs on @code{Sun},
@code{VAX} etc.
In @code{dbx}, one can use commands such as setting break-point on
a source line, stepwise execution, inspecting a variable's value etc.
@b{Asir} provides such a @code{dbx}-like debugger.
In addition to such commands, we adopted several useful commands
from @code{gdb}.
In order to enter the debug-mode, type @code{debug;} at the top level
of @b{Asir}.
\E

@example
[10] debug;
(debug)
@end example

@noindent
\JP $B$=$NB>(B, $B<!$NJ}K!(B, $B$"$k$$$O>u67$G%G%P%C%0%b!<%I$KF~$k(B. 
\BEG
@code{Asir} also enters the debug-mode by the following means or in the
following situations.
\E

@itemize @bullet
@item
\JP $B<B9TCf%V%l!<%/%]%$%s%H$KC#$7$?>l9g(B
\EG When it reaches a break point while executing a program.

@item
\JP $B3d$j9~$_$G(B @samp{d} $B$rA*Br$7$?>l9g(B
\EG When the @samp{d} option is selected at an interruption.

@item
\JP $B<B9TCf%(%i!<$r5/$3$7$?>l9g(B
\EG When it detects errors while executing a program.

\BJP
$B$3$N>l9g(B, $B<B9T$N7QB3$OIT2DG=$G$"$k$,(B, $BD>@\$N%(%i!<$N860x$H$J$C$?(B
$B%f!<%6Dj5AH!?t$NJ8$rI=<($7$F%G%P%C%0%b!<%I$KF~$k$?$a(B, $B%(%i!<;~(B
$B$K$*$1$kJQ?t$NCM$r;2>H$G$-(B, $B%G%P%C%0$KLrN)$?$;$k$3$H$,$G$-$k(B. 
\E
\BEG
In this case, to continue the execution of the program is impossible.
But because it reports the statement in the user defined function
that caused the error, then enters the debug-mode, user can inspect
the values of variables at the error state.  This helps to analyze
the error and debug the program.
\E

@item
\JP @code{error()} $B$,8F$S=P$5$l$?>l9g(B
\EG When built-in function @code{error()} is called.
@end itemize

\BJP
@node $B%3%^%s%I$N2r@b(B,,, $B%G%P%C%,(B
@section $B%3%^%s%I$N2r@b(B
\E
\BEG
@node Debugger commands,,, Debugger
@section Debugger commands
\E

@noindent
\BJP
$B%3%^%s%I$O(B @code{dbx} $B$N%3%^%s%I$NFbI,MW:G>.8B$N$b$N$r:NMQ$7$?(B. 
$B99$K(B, @code{gdb} $B$N%3%^%s%I$+$i$b$$$/$D$+JXMx$J$b$N$r:NMQ$7$?(B. 
$B<B:]$N5!G=$O(B @code{dbx} $B$H$[$\F1MM$G$"$k$,(B, @code{step}, @code{next} $B$O(B,
 $B<!$N9T$G$O$J$/<!$NJ8$r<B9T$9$k(B. 
$B=>$C$F(B, 1$B9T$KJ#?t$NJ8$,$"$k>l9g$O(B, $B$=$NJ8$N?t$@$1(B @code{next} 
$B$r<B9T$7$J$1$l$P<!$N9T$K?J$a$J$$(B. $B$^$?(B, @code{dbx} $B$HF1MM(B 
@file{.dbxinit} $B$rFI$_9~$`$N$G(B, @code{dbx} $B$HF1$8(B alias $B$r;H$&$3$H$,$G(B
$B$-$k(B. 
\E
\BEG
Only indispensable commands of @code{dbx} are supported
in the current version.
Generally, the effect of a command is the same as that of @code{dbx}.
There are, however, slight differences:
Commands @code{step} and @code{next} execute the next statement, but not
the next line; therefore, if there are multiple statements in one line,
one should issue such commands several times to proceed the next line.
The debugger reads in @file{.dbxinit}, which allows the same aliases
as is used in @code{dbx}.
\E

@table @code
@item step
\JP $B<!$NJ8$r<B9T$9$k(B. $B<!$NJ8$,H!?t$r4^$`$H$-(B, $B$=$NH!?t$KF~$k(B. 
\BEG
Executes the next statement; if the next statement contains a
function call, then enters the function.
\E
@item next
\JP $B<!$NJ8$r<B9T$9$k(B. 
\EG Executes the next statement.
@item finish
\BJP
$B8=:_<B9TCf$NH!?t$N<B9T$,=*N;$7$?;~E@$G:F$S%G%P%C%0%b!<%I$KF~$k(B. 
$B8m$C$F(B @code{step} $B$r<B9T$7$?>l9g$KM-8z$G$"$k(B. 
\E
\BEG
Enter the debug-mode again after finishing
the execuction of the current function.
This is useful when an unnecessary @code{step} has been executed.
\E
@item cont
@itemx quit
\JP $B%G%P%C%0%b!<%I$+$iH4$1(B, $B<B9T$r7QB3$9$k(B. 
\EG Exits from the debug-mode and continues execution.
@item up [@var{n}]
\BJP
$B%9%?%C%/%U%l!<%`$r(B 1 $BCJ(B ($B0z?t(B @var{n} $B$,$"$k;~$O(B @var{n} $BCJ(B) $B>e$,$k(B. 
$B$3$l$K$h$j(B, $B$=$N%9%?%C%/%U%l!<%`$KB0$9$kJQ?t$NCM$N;2>H(B, $BJQ99$,$G$-$k(B. 
\E
\BEG
Move up the call stack one level.
Move up the call stack @var{n} levels if @var{n} is specified.
\E
@item down [@var{n}]
\JP $B%9%?%C%/%U%l!<%`$r(B 1 $BCJ(B ($B0z?t(B @var{n} $B$,$"$k;~$O(B @var{n} $BCJ(B) $B2<$,$k(B. 
\BEG
Move down the call stack one level.
Move down the call stack @var{n} levels if @var{n} is specified.
\E
@item frame [@var{n}]
\BJP
$B0z?t$,$J$$$H$-(B, $B8=:_<B9TCf$NH!?t$rI=<($9$k(B. 
$B0z?t$,$"$k$H$-(B, $B%9%?%C%/%U%l!<%`$rHV9f(B @var{n} $B$N$b$N$K@_Dj$9$k(B. $B$3$3$G(B
$B%9%?%C%/%U%l!<%`$NHV9f$H$O(B
@code{where} $B$K$h$jI=<($5$l$k8F$S=P$7Ns$K$*$$$F(B, $B@hF,$KI=<($5$l$kHV9f$N(B
$B$3$H$G$"$k(B. 
\E
\BEG
Print the current stack frame with no argument. @var{n}
specifies the stack frame number to be selected. Here the
stack frame number is a number at the top of lines displayed
by executing @code{where}.
\E
@item list [@var{startline}]
@itemx list @var{function}
\BJP
$B8=:_9T(B, $B$^$?$O(B @var{startline}, $B$^$?$O(B @var{function}$B$N@hF,$+$i(B 10 $B9T%=!<(B
$B%9%U%!%$%k$rI=<($9$k(B. 
\E
\BEG
Displays ten lines in a source file from @var{startline},
the current line if the @var{startline} is not specified,
or from the top line of current target @var{function}.
\E
@item print @var{expr}
\JP @var{expr} $B$rI=<($9$k(B. 
\EG Displays @var{expr}.
@item func @var{function}
\JP $BBP>]H!?t$r(B @var{function} $B$K@_Dj$9$k(B. 
\EG Set the target function to @var{function}.
@item stop at @var{sourceline} [if @var{cond}]
@itemx stop in @var{function}
\BJP
@var{sourceline}$B9TL\(B, $B$^$?$O(B @var{function} $B$N@hF,$K%V%l!<%/%]%$%s%H$r(B
$B@_Dj$9$k(B. $B%V%l!<%/%]%$%s%H$O(B, $BH!?t$,:FDj5A$5$l$?>l9g<+F0E*$K<h$j>C$5$l(B
$B$k(B. @code{if} $B$,B3$/>l9g(B, @var{cond} $B$,I>2A$5$l(B, $B$=$l$,(B 0 $B$G$J$$>l9g$K(B
$B<B9T$,CfCG$7(B, $B%G%P%C%0%b!<%I$KF~$k(B. 
\E
\BEG
Set a break-point at the @var{sourceline}-th line of the source file,
or at the top of the target function.
Break-points are removed whenever the relevant function is redefined.
When @code{if} statements are repeatedly encountered,
@b{Asir} enters debug-mode only when the corresponding
@var{cond} parts are evaluated to a non-zero value.
\E
@item trace @var{expr} at @var{sourceline} [if @var{cond}]
@item trace @var{expr} in @var{function}
\BJP
@code{stop} $B$HF1MM$G$"$k$,(B, @code{trace} $B$G$OC1$K(B @var{expr} $B$rI=<($9$k(B
$B$N$_$G(B, $B%G%P%C%0%b!<%I$K$OF~$i$J$$(B. 
\E
\BEG
These are similar to @code{stop}. @code{trace} simply displays the value
of @var{expr} and without entering the debug-mode.
\E
@item delete @var{n}
\JP $B%V%l!<%/%]%$%s%H(B @var{n} $B$r<h$j>C$9(B. 
\BEG
Remove the break point specified by a number @var{n}, which can be
known by the @code{status} command.
\E
@item status
\JP $B%V%l!<%/%]%$%s%H$N0lMw$rI=<($9$k(B. 
\EG Displays a list of the break-points.
@item where
\JP $B8=:_$NDd;_E@$^$G$N8F$S=P$7Ns$rI=<($9$k(B. 
\BEG
Displays the calling sequence of functions from the top level
through the current level.
\E
@item alias @var{alias} @var{command}
\JP @var{command} $B$K(B @var{alias} $B$NJLL>$rM?$($k(B. 
\EG Create an alias @var{alias} for @var{command}
@end table

@noindent
\BJP
@code{print} $B$N0z?t$H$7$F(B, $B%H%C%W%l%Y%k$K$*$1$k$[$H$s$I$9$Y$F$N<0(B
$B$,$H$l$k(B. $BDL>o$O(B, $BJQ?t$NFbMF$NI=<($,<g$G$"$k$,(B, $BI,MW$K1~$8$F<!$N(B
$B$h$&$J;H$$J}$,$G$-$k(B. 
\E
\BEG
The debugger command @code{print} can take almost all expressions
as its argument.  The ordinary usage is to print the values of
(programming) variables.  However, the following usage is worth to
remember.
\E

@itemize @bullet
@item
\JP @b{$BJQ?t$N=q$-49$((B}
\EG @b{overwriting the variable}

\BJP
$B<B9TCf$N%V%l!<%/%]%$%s%H$K$*$$$F(B, $BJQ?t$NCM$rJQ99$7$F<B9T$r7QB3$5$;$?$$(B
$B>l9g(B, $B<!$N$h$&$JA`:n$r9T$($P$h$$(B. 
\E
\BEG
One might sometimes wish to continue the execution with several values of
variables modified.  For such an purpose, take the following procedure.
\E

@example
(debug) print A
A = 2
(debug) print A=1
A=1 = 1
(debug) print A
A = 1
@end example


@item
\JP @b{$BH!?t$N8F$S=P$7(B}
\EG @b{function call}

\JP $BH!?t8F$S=P$7$b<0$G$"$k$+$i(B, @code{print} $B$N0z?t$H$7$F$H$l$k(B. 
\BEG
A function call is also an expression, therefore, it can appear at
the argument place of @code{print}.
\E

@example
(debug) print length(List)
length(List) = 14
@end example

\BJP
$B$3$NNc$G$O(B, $BJQ?t(B @code{List} $B$K3JG<$5$l$F$$$k%j%9%H$ND9$5$r(B @code{length()}
$B$K$h$jD4$Y$F$$$k(B. 
\E
\BEG
In this example, the length of the list assigned to the variable
@code{List} is examined by a function @code{length()}.
\E

@example
(debug) print ctrl("cputime",1)
ctrl("cputime",1) = 1
@end example

\BJP
$B$3$NNc$O(B, $B7W;;3+;O;~$K(B CPU $B;~4V$NI=<($N;XDj$r$7K:$l$?>l9g$J$I$K(B, $B7W;;(B
$BESCf$G%G%P%C%0%b!<%I$+$i;XDj$r9T$($k$3$H$r<($7$F$$$k(B. 

$B$^$?(B, $B;_$`$rF@$:7W;;$rCfCG$7$J$1$l$P$J$i$J$$>l9g(B, $B%G%P%C%0%b!<%I$+$i(B
@code{bsave()} $B$J$I$N%3%^%s%I$K$h$jESCf7k2L$r%U%!%$%k$KJ]B8$9$k$3$H$b(B
$B$G$-$k(B. 
\E
\BEG
This example shows such a usage where measuring CPU time is activated
from within the debug-mode, even if one might have forgotten to specify
the activation of CPU time measurement.
      
It is also useful to save intermediate results to files from within
the debug-mode by the built-in function @code{bsave()} when one is
forced to quit the computation by any reason.
\E

@example
(debug) print bsave(A,"savefile")
bsave(A,"savefile") = 1
@end example

\BJP
$B%G%P%C%0%b!<%I$+$i$NH!?t8F$S=P$7$GCm0U$9$Y$-$3$H$O(B, 
@code{print} $B$N0z?t$,%f!<%6Dj5AH!?t$N8F$S=P$7$r4^$`>l9g(B, 
$B$=$NH!?t8F$S=P$7$G%(%i!<$,5/$3$C$?>l9g$K85$NH!?t$N<B9T7QB3$,IT2DG=(B
$B$K$J$k>l9g$,$"$k$H$$$&$3$H$G$"$k(B. 
\E
\BEG
Note that continuation of the parent function will be impossible if
an error will occur in the function call from within the debug-mode.
\E
@end itemize

\BJP
@node $B%G%P%C%,$N;HMQNc(B,,, $B%G%P%C%,(B
@section $B%G%P%C%,$N;HMQNc(B
\E
\BEG
@node Execution example of debugger,,, Debugger
@section Execution example of debugger
\E

@noindent
\BJP
$B$3$3$G$O(B, $B3,>h$r:F5"E*$K7W;;$5$;$k%f!<%6Dj5AH!?t$rNc$H$7$F(B, $B%G%P%C%,$N(B
$B<B:]$N;HMQK!$r<($9(B. 
\E
\BEG
Here, the usage of the Debugger is explained by showing an example
for debugging a program which computes the integer factorial by a
recursive definition.
\E

@example
% asir
[0] load("fac")$
[3] debug$
(debug) list factorial
1   def factorial(X) @{
2       if ( !X )
3           return 1;
4       else 
5           return X * factorial(X - 1);
6   @}
7   end$
\BJP
(debug) stop at 5                     <-- $B%V%l!<%/%]%$%s%H$N@_Dj(B
(0) stop at "./fac":5
(debug) quit                          <-- $B%G%P%C%0%b!<%I$rH4$1$k(B
[4] factorial(6);                     <-- factorial(6) $B$N8F$S=P$7(B
stopped in factorial at line 5 in file "./fac"
5           return X * factorial(X - 1);
(debug) where                         <-- $B%V%l!<%/%]%$%s%H$^$G$N8F$S=P$7Ns$NI=<((B
factorial(), line 5 in "./fac"
(debug) print X                       <-- X $B$NCM$NI=<((B
X = 6
(debug) step                          <-- $B%9%F%C%W<B9T(B ($BH!?t$KF~$k(B)
stopped in factorial at line 2 in file "./fac"
2		if ( !X )
(debug) where
factorial(), line 2 in "./fac"
factorial(), line 5 in "./fac"
(debug) print X
X = 5
(debug) delete 0                      <-- $B%V%l!<%/%]%$%s%H(B 0 $B$N>C5n(B
(debug) cont                          <-- $B<B9T7QB3(B
720                                   <-- $B7k2L(B = 6!
[5] quit;
\E
\BEG
(debug) stop at 5                     <-- setting a break point
(0) stop at "./fac":5
(debug) quit                          <-- leaving the debug-mode
[4] factorial(6);                     <-- call for factorial(6)
stopped in factorial at line 5 in file "./fac"
5           return X * factorial(X - 1);
(debug) where                         <-- display the calling sequence
factorial(), line 5 in "./fac"            up to this break point
(debug) print X                       <-- Display the value of X
X = 6 
(debug) step                          <-- step execution
                                          (enters function)
stopped in factorial at line 2 in file "./fac"
2       if ( !X )
(debug) where
factorial(), line 2 in "./fac"
factorial(), line 5 in "./fac"
(debug) print X
X = 5 
(debug) delete 0                      <-- delete the break point 0
(debug) cont                          <-- continue execution
720                                   <-- result = 6!
[5] quit;
\E
@end example

\BJP
@node $B%G%P%C%,$N=i4|2=%U%!%$%k$NNc(B,,, $B%G%P%C%,(B
@section $B%G%P%C%,$N=i4|2=%U%!%$%k$NNc(B
\E
\BEG
@node Sample file of initialization file for Debugger,,, Debugger
@section Sample file of initialization file for Debugger
\E

@noindent
\BJP
$BA0$K=R$Y$?DL$j(B, @b{Asir} $B$O(B, $B5/F0;~$K(B @samp{$HOME/.dbxinit} $B$rFI$_9~$`(B. 
$B$3$N%U%!%$%k$O(B, @code{dbx} $B$N$5$^$6$^$J=i4|@_DjMQ$N%3%^%s%I$r5-=R$7$F$*$/(B
$B%U%!%$%k$G$"$k$,(B, @b{Asir} $B$O(B, @code{alias} $B9T$N$_$rG'<1$9$k(B. $BNc$($P(B, 
\E
\BEG
As is previously mentioned, @b{Asir} reads in the file
@samp{$HOME/.dbxinit} at its invocation.
This file is originally used to define various initializing commands
for @code{dbx} debugger, but @b{Asir} recognizes only @code{alias}
lines. For example, by the setting
\E

@example
% cat ~/.dbxinit
alias n next
alias c cont
alias p print
alias s step
alias d delete
alias r run
alias l list
alias q quit
@end example

@noindent
\BJP
$B$J$k@_Dj$K$h$j(B, @code{print}, @code{cont} $B$J$I(B, $B%G%P%C%0%b!<%I$K$*$$$F(B
$BIQHK$KMQ$$$i$l$k%3%^%s%I$,(B, $B$=$l$>$l(B @code{p}, @code{c} $B$J$I(B, $BC;$$(B
$BJ8;zNs$GBeMQ$G$-$k(B. $B$^$?(B, $B%G%P%C%0%b!<%I$K$*$$$F(B, @code{alias} $B%3%^%s%I(B
$B$K$h$j(B alias $B$NDI2C$,$G$-$k(B. 
\E
\BEG
one can use short aliases, e.g., @code{p}, @code{c} etc., for frequently
used commands such as @code{print}, @code{cont} etc. One can create
new aliases in the debug-mode during an execution.
\E

@example
lex_hensel(La,[a,b,c],0,[a,b,c],0);
stopped in gennf at line 226 in file "/home/usr3/noro/asir/gr"
226        N = length(V); Len = length(G); dp_ord(O); PS = newvect(Len);
(debug) p V
V = [a,b,c]
(debug) c
...
@end example