@comment $OpenXM: OpenXM/src/asir-doc/parts/debug.texi,v 1.3 2003/04/20 08:01:25 noro Exp $
\BJP
@node デバッガ,,, Top
@chapter デバッガ
\E
\BEG
@node Debugger,,, Top
@chapter Debugger
\E

@menu
\BJP
* デバッガとは::
* コマンドの解説::
* デバッガの使用例::
* デバッガの初期化ファイルの例::
\E
\BEG
* What is Debugger::
* Debugger commands::
* Execution example of debugger::
* Sample file of initialization file for Debugger::
\E
@end menu

\BJP
@node デバッガとは,,, デバッガ
@section デバッガとは
\E
\BEG
@node What is Debugger,,, Debugger
@section What is Debugger
\E

@noindent
\BJP
C 言語で書かれたプログラムのためのデバッガ @code{dbx} 
は, ソースレベルでのブレークポイントの設定, ステッ
プ実行, 変数の参照などが可能な強力なデバッガである. @b{Asir} では, 
@code{dbx} 風のデバッガを用意している. デバッグモードに入るには, トッ
プレベルで @code{debug;} と入力する. 
\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 その他, 次の方法, あるいは状況でデバッグモードに入る. 
\BEG
@code{Asir} also enters the debug-mode by the following means or in the
following situations.
\E

@itemize @bullet
@item
\JP 実行中ブレークポイントに達した場合
\EG When it reaches a break point while executing a program.

@item
\JP 割り込みで @samp{d} を選択した場合
\EG When the @samp{d} option is selected at an interruption.

@item
\JP 実行中エラーを起こした場合
\EG When it detects errors while executing a program.

\BJP
この場合, 実行の継続は不可能であるが, 直接のエラーの原因となった
ユーザ定義函数の文を表示してデバッグモードに入るため, エラー時
における変数の値を参照でき, デバッグに役立たせることができる. 
\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()} が呼び出された場合
\EG When built-in function @code{error()} is called.
@end itemize

\BJP
@node コマンドの解説,,, デバッガ
@section コマンドの解説
\E
\BEG
@node Debugger commands,,, Debugger
@section Debugger commands
\E

@noindent
\BJP
コマンドは @code{dbx} のコマンドの内必要最小限のものを採用した. 
更に, @code{gdb} のコマンドからもいくつか便利なものを採用した. 
実際の機能は @code{dbx} とほぼ同様であるが, @code{step}, @code{next} は,
 次の行ではなく次の文を実行する. 
従って, 1行に複数の文がある場合は, その文の数だけ @code{next} 
を実行しなければ次の行に進めない. また, @code{dbx} と同様 
@file{.dbxinit} を読み込むので, @code{dbx} と同じ alias を使うことがで
きる. 
\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 次の文を実行する. 次の文が函数を含むとき, その函数に入る. 
\BEG
Executes the next statement; if the next statement contains a
function call, then enters the function.
\E
@item next
\JP 次の文を実行する. 
\EG Executes the next statement.
@item finish
\BJP
現在実行中の函数の実行が終了した時点で再びデバッグモードに入る. 
誤って @code{step} を実行した場合に有効である. 
\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 デバッグモードから抜け, 実行を継続する. 
\EG Exits from the debug-mode and continues execution.
@item up [@var{n}]
\BJP
スタックフレームを 1 段 (引数 @var{n} がある時は @var{n} 段) 上がる. 
これにより, そのスタックフレームに属する変数の値の参照, 変更ができる. 
\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 スタックフレームを 1 段 (引数 @var{n} がある時は @var{n} 段) 下がる. 
\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
引数がないとき, 現在実行中の函数を表示する. 
引数があるとき, スタックフレームを番号 @var{n} のものに設定する. ここで
スタックフレームの番号とは
@code{where} により表示される呼び出し列において, 先頭に表示される番号の
ことである. 
\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
現在行, または @var{startline}, または @var{function}の先頭から 10 行ソー
スファイルを表示する. 
\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} を表示する. 
\EG Displays @var{expr}.
@item func @var{function}
\JP 対象函数を @var{function} に設定する. 
\EG Set the target function to @var{function}.
@item stop at @var{sourceline} [if @var{cond}]
@itemx stop in @var{function}
\BJP
@var{sourceline}行目, または @var{function} の先頭にブレークポイントを
設定する. ブレークポイントは, 函数が再定義された場合自動的に取り消され
る. @code{if} が続く場合, @var{cond} が評価され, それが 0 でない場合に
実行が中断し, デバッグモードに入る. 
\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} と同様であるが, @code{trace} では単に @var{expr} を表示する
のみで, デバッグモードには入らない. 
\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 ブレークポイント @var{n} を取り消す. 
\BEG
Remove the break point specified by a number @var{n}, which can be
known by the @code{status} command.
\E
@item status
\JP ブレークポイントの一覧を表示する. 
\EG Displays a list of the break-points.
@item where
\JP 現在の停止点までの呼び出し列を表示する. 
\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} に @var{alias} の別名を与える. 
\EG Create an alias @var{alias} for @var{command}
@end table

@noindent
\BJP
@code{print} の引数として, トップレベルにおけるほとんどすべての式
がとれる. 通常は, 変数の内容の表示が主であるが, 必要に応じて次の
ような使い方ができる. 
\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{変数の書き換え}
\EG @b{overwriting the variable}

\BJP
実行中のブレークポイントにおいて, 変数の値を変更して実行を継続させたい
場合, 次のような操作を行えばよい. 
\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{函数の呼び出し}
\EG @b{function call}

\JP 函数呼び出しも式であるから, @code{print} の引数としてとれる. 
\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
この例では, 変数 @code{List} に格納されているリストの長さを @code{length()}
により調べている. 
\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
この例は, 計算開始時に CPU 時間の表示の指定をし忘れた場合などに, 計算
途中でデバッグモードから指定を行えることを示している. 

また, 止むを得ず計算を中断しなければならない場合, デバッグモードから
@code{bsave()} などのコマンドにより途中結果をファイルに保存することも
できる. 
\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
デバッグモードからの函数呼び出しで注意すべきことは, 
@code{print} の引数がユーザ定義函数の呼び出しを含む場合, 
その函数呼び出しでエラーが起こった場合に元の函数の実行継続が不可能
になる場合があるということである. 
\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 デバッガの使用例,,, デバッガ
@section デバッガの使用例
\E
\BEG
@node Execution example of debugger,,, Debugger
@section Execution example of debugger
\E

@noindent
\BJP
ここでは, 階乗を再帰的に計算させるユーザ定義函数を例として, デバッガの
実際の使用法を示す. 
\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                     <-- ブレークポイントの設定
(0) stop at "./fac":5
(debug) quit                          <-- デバッグモードを抜ける
[4] factorial(6);                     <-- factorial(6) の呼び出し
stopped in factorial at line 5 in file "./fac"
5           return X * factorial(X - 1);
(debug) where                         <-- ブレークポイントまでの呼び出し列の表示
factorial(), line 5 in "./fac"
(debug) print X                       <-- X の値の表示
X = 6
(debug) step                          <-- ステップ実行 (函数に入る)
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                      <-- ブレークポイント 0 の消去
(debug) cont                          <-- 実行継続
720                                   <-- 結果 = 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 デバッガの初期化ファイルの例,,, デバッガ
@section デバッガの初期化ファイルの例
\E
\BEG
@node Sample file of initialization file for Debugger,,, Debugger
@section Sample file of initialization file for Debugger
\E

@noindent
\BJP
前に述べた通り, @b{Asir} は, 起動時に @samp{$HOME/.dbxinit} を読み込む. 
このファイルは, @code{dbx} のさまざまな初期設定用のコマンドを記述しておく
ファイルであるが, @b{Asir} は, @code{alias} 行のみを認識する. 例えば, 
\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
なる設定により, @code{print}, @code{cont} など, デバッグモードにおいて
頻繁に用いられるコマンドが, それぞれ @code{p}, @code{c} など, 短い
文字列で代用できる. また, デバッグモードにおいて, @code{alias} コマンド
により alias の追加ができる. 
\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