@c Language=Russian
@c Encoding=CP1251
@c File=Debugging.texi 
@c OriginalRevision=1.20
@c TranslatedBy: (c) 2007-05 Vadim V. Zhytnikov <vvzhyt@gmail.com>

@c end concepts Debugging
@menu
* Отладка исходного кода::
* Специальные команды::
* Функции и переменные для отладки::   
@end menu

@node Отладка исходного кода, Специальные команды, , Отладка
@section Отладка на уровне исходного кода

Maxima имеет отладчик исходного кода.  
Пользователь может определить в функции точку останова и
и продолжить выполнение с этой точки строка за строкой.
При этом возможно анализировать стек вызовов и переменные,
имеющие значение на данном уровне.

Команда @code{:help}, или просто @code{:h}, выводит список команд отладчика.
(Команды могут быть сокращены, если сокращение однозначно.
Если оно неоднозначно, то будет выведен список альтернатив.)
В отладчике пользователь может также использовать обычные команды Maxima
для исследования, определения и манипулирования переменными и выражениями.

Точка останова задается командой @code{:br} в командной строке Maxima.
В отладчике, пользователь может продвигаться по одной строке
за раз с помощью команды @code{:n} (``next'').
Команда @code{:bt} (``backtrace'') выводит список кадров стека.
Команда @code{:r} (``resume'') завершает отладчик и продолжает
выполнение программы. Данные команды проиллюстрированы в следующем примере.

@example
(%i1) load ("/tmp/foobar.mac");

(%o1)                           /tmp/foobar.mac

(%i2) :br foo
Turning on debugging debugmode(true)
Bkpt 0 for foo (in /tmp/foobar.mac line 1) 

(%i2) bar (2,3);
Bkpt 0:(foobar.mac 1)
/tmp/foobar.mac:1::

(dbm:1) :bt                        <-- :bt выводим обратную трассировку вызовов
#0: foo(y=5)(foobar.mac line 1)
#1: bar(x=2,y=3)(foobar.mac line 9)

(dbm:1) :n                         <-- :n продвигаем выполнение на одну строку
(foobar.mac 2)
/tmp/foobar.mac:2::

(dbm:1) :n                         <-- :n продвигаем выполнение на одну строку
(foobar.mac 3)
/tmp/foobar.mac:3::

(dbm:1) u;                         <-- Исследуем знасение переменной u
28

(dbm:1) u: 33;                     <-- Устанавливаем значение u равным 33
33

(dbm:1) :r                         <-- :r to возобновляем выполнение программы

(%o2)                                1094
@end example

Содержимое файла @code{/tmp/foobar.mac}:

@example
foo(y) := block ([u:y^2],
  u: u+3,
  u: u^2,
  u);
 
bar(x,y) := (
  x: x+2,
  y: y+2,
  x: foo(y),
  x+y);
@end example

Использование Отладчика в Редакторе Emacs

Если пользователь выполняет программу в командном окне
отладчика (dbl) редактора GNU emacs или в графической оболочке Xmaxima, 
то при достижении точки останова в другой части окна будет показан
участок исходного кода с текущей строкой, выделенной либо красным цветом,
либо маленькой стрелкой. Пользователь может продолжить
выполнение программы построчно, нажимая M-n (Alt-n).

Для использования в Emacs отладчика @code{dbl} требуется файл @code{dbl.el},
расположенный в директории elisp.
Убедитесь, что файлы elisp установлены или добавьте директорию elisp программы Maxima 
к пути: например, добавте следующие строки к файлу @file{.emacs} или файлу @code{site-init.el}

@example
(setq load-path (cons "/usr/share/maxima/5.9.1/emacs" load-path))
(autoload 'dbl "dbl")
@end example

После этого при вводе 

@example
M-x dbl
@end example

в emacs должно открываться командное окно, в котором можно
выполнять программы, например, Maxima, gcl, gdb и т.д.   
Это командное окно ``знает'' об отладке исходного кода,
который открыт в другом окне редактора.  

Пользователь может установить точку останова в определенной строке
кода, нажав на @code{C-x space}.  При этом производится анализ: в какой функции находится
данная строка и на какой по порядку строке этой функции стоит курсор.   
Если курсор расположен, скажем, на строке 2 функции @code{foo}, тогда 
в командном окно будет введена команда ``@code{:br foo 2}'', которая
задает точку останова на второй строке функции @code{foo}.   
Для того, чтобы все это работало необходимо, чтобы в окне файла @code{foobar.mac}
был включен режим maxima-mode.el.
Существуют еще дополнительные команды, доступные в таком окне,
такие как вычисление функций Maxima при нажатии @code{Alt-Control-x}.

@opencatbox
@category{Отладка}
@closecatbox

@node Специальные команды, Функции и переменные для отладки, Отладка исходного кода, Отладка
@section Специальные команды

Специальные команды, это ключевые слова, которые не интерпретируются Maxima как обычные выражения.
Специальные команды вводятся в командной строке Maxima или отладчика, но не в точке останова.
Все специальные команды начинаются с двоеточия '@code{:}'.
Например, для вычисления Lisp формы можно ввести @code{:lisp} 
с последующей формой.  

@example
(%i1) :lisp (+ 2 3) 
5
@end example

Число параметров зависит от конкретной команды.  Кроме того,
не обязательно вводить всю команду целиком, достаточно ввести
столько, чтобы сделать команду однозначно определенной среди 
всех ключевых слов.  Таким образом, для @code{:break} достаточно ввести @code{:br}.

Специальные команды перечислены ниже:

@table @code
@item :break F n
Задает точку останова в функции @code{F} на строке номер @code{n} от ее начала.
Если @code{F} является строкой, тогда он рассматривается как файл и смещение
@code{n} отсчитывается от начала этого файла.
Смещение является необязательным. Если оно не указано, то предполагается равным
нулю (первая строка функции или файла).
@item :bt
Выводит обратную трассировку кадров стека
@item :continue
Продолжает вычисление
@c CAN'T SEEM TO GET :delete TO WORK !!!
@item :delete
Удаляет заданную точку останова или все, если ни одна не задана
@c CAN'T SEEM TO GET :disable TO WORK !!!
@item :disable
Деактивирует заданную точку останова или все, если ни одна не задана
@c CAN'T SEEM TO GET :enable TO WORK !!!
@item :enable
Активирует заданную точку останова или все, если ни одна не задана
@item :frame n
Выводит кадр стека номер @code{n} или текущий кадр, если номер не указан
@c CAN'T SEEM TO GET :help TO WORK !!!
@item :help
Печатает справку по указанной команде или по всем если ни одна не задана
@c CAN'T SEEM TO GET :info TO WORK !!!
@item :info
Печатает информацию об элементе
@item :lisp some-form
Вычисляет @code{some-form} в качестве Lisp формы
@item :lisp-quiet some-form
Вычисляет Lisp форму @code{some-form} без вывода результата
@item :next
Как @code{:step}, но @code{:next} пропускает вызовы функций
@item :quit
Выход из текущего уровня отладчика без завершение вычислений
@item :resume
Продолжает вычисление
@item :step
Продолжает вычисление до достижения новой строки
@item :top
Возвращает на уровень командного приглашения Maxima с любого уровня отладчика без
завершения вычислений
@end table 

@opencatbox
@category{Отладка}
@closecatbox

@node Функции и переменные для отладки, , Специальные команды, Отладка
@section Функции и переменные для отладки

@defvr {Управляющая переменная} refcheck
Значение по умолчанию: @code{false}

Если @code{refcheck} равна @code{true}, то Maxima печатает сообщение
каждый раз как имеющая значение переменная используется в вычислении
первый раз.

@opencatbox
@category{Вычисление} @category{Работа в консоли} @category{Глобальные флаги}
@closecatbox
@end defvr

@defvr {Управляющая переменная} setcheck
Значение по умолчанию: @code{false}

Если @code{setcheck} равно списку переменных (возможно с индексом), 
то Maxima печатает сообщение всякий раз как переменным, или
переменным с индексом, присваивается значение при помощи
обычного оператора присваивания @code{:}, или оператора присваивания 
@code{::}, или при связывании параметров функций, но не при
определении функций @code{:=} или макросов @code{::=}.
Сообщение содержит имя переменной и присваиваемое значение.

Переменной @code{setcheck} может быть присвоено значение @code{all} или @code{true},
что подразумевает все переменные.

Каждое присваивание @code{setcheck} устанавливает новый список контролируемых переменных
и все переменные, которые ранее были в списке @code{setcheck}, забываются.

Переменные, присваиваемые @code{setcheck} должны быть экранированы, иначе
они могут быть вычислены. Например, если переменные @code{x}, @code{y} и @code{z} 
уже имеют значения, тогда 

@example
setcheck: ['x, 'y, 'z]$
@end example

устанавливает контроль присваивания для этих переменных.

Сообщение не выводится, если переменной, включенной в список @code{setcheck},
присваивается значение равное ей самой, например,  @code{X: 'X}.

@opencatbox
@category{Работа в консоли} @category{Глобальные флаги}
@closecatbox
@end defvr

@defvr {Управляющая переменная} setcheckbreak
Значение по умолчанию: @code{false}

Если @code{setcheckbreak} равно @code{true},
то Maxima генерирует прерывание всякий раз как переменной
из списка @code{setcheck} присваивается новое значение.
Прерывание случается до присваивания нового значения.
В этот момент, переменная @code{setval} содержит новое значение переменной.
Таким образом, возможно присвоить переменной другое значение путем
присваивания его переменной @code{setval}.

См. также @code{setcheck} и @code{setval}.

@opencatbox
@category{Работа в консоли} @category{Глобальные флаги}
@closecatbox
@end defvr

@defvr {Системная переменная} setval
Содержит новое значение, которое будет присвоено переменной, если случается
прерывание, контролируемое @code{setcheckbreak}.
Таким образом, возможно присвоить переменной другое значение путем
присваивания его переменной @code{setval}.

См. также @code{setcheck} и @code{setcheckbreak}.

@opencatbox
@category{Работа в консоли} @category{Глобальные переменные}
@closecatbox
@end defvr

@deffn {Функция} timer (@var{f_1}, ..., @var{f_n})
@deffnx {Функция} timer (all)
@deffnx {Функция} timer ()
Добавляет функции @var{f_1}, ..., @var{f_n} к списку функций,
для которых собирается статистика тайминга.
Последовательные вызовы @code{timer(f)$ timer(g)$} сначала добавляют к списку @code{f} 
а затем @code{g}, т.е. список пополняется от одного вызова @code{timer} к другому.

@code{timer(all)} добавляет все пользовательские функции,
которые определяются глобальной переменной @code{functions},
к списку контролируемых функций.

Без аргументов, 
@code{timer} возвращает список контролируемых функций.

Maxima сохраняет информацию о времени выполнения контролируемых функций.
Функция @code{timer_info} возвращает статистику тайминга, включающую: 
среднее время выполнения, число вызовов и полное время выполнения.
Функция @code{untimer} удаляет функцию из списка контролируемых функций.

@code{timer} не вычисляет свои аргументы. 
Команды @code{f(x) := x^2$ g:f$ timer(g)$} не добавят @code{f} к списку
тайминг-контроля.

Если действует трассировка @code{trace(f)}, то @code{timer(f)} не работает,
т.к. @code{trace} и @code{timer} не могут действовать одновременно.

См. также @code{timer_devalue}.

@opencatbox
@category{Отладка}
@closecatbox
@end deffn

@deffn {Функция} untimer (@var{f_1}, ..., @var{f_n})
@deffnx {Функция} untimer ()
Удаляет функции @var{f_1}, ..., @var{f_n} из списка 
тайминг-контроля.

Без аргументов, @code{untimer} удаляет все функции из списка тайминг-контроля.

После выполнения @code{untimer (f)}, функция @code{timer_info (f)} продолжает
содержать ранее собранную статистику, хотя
@code{timer_info()} (без аргументов) не возвращает информацию о
функциях, которые на данный момент не включены в список тайминг-контроля.
Вызов @code{timer (f)} обнуляет всю предыдущую статистику и снова
добавляет @code{f} к списку тайминг-контроля.

@opencatbox
@category{Отладка}
@closecatbox
@end deffn

@defvr {Управляющая переменная} timer_devalue
Значение по умолчанию: @code{false}

Если @code{timer_devalue} равно @code{true}, то Maxima вычитает из статистики
контролируемой функции время выполнения других контролируемых функций. 
В противном случае, статистика каждой функции включает время,
затраченное на выполнение других функций.
Заметим, что время, затраченное на выполнение неконтролируемых функций,
не вычитается из общего времени.

См. также @code{timer} и @code{timer_info}.

@opencatbox
@category{Отладка} @category{Глобальные флаги} 
@closecatbox
@end defvr

@deffn {Функция} timer_info (@var{f_1}, ..., @var{f_n})
@deffnx {Функция} timer_info ()
Для функций @var{f_1}, ..., @var{f_n},
возвращает матрицу, содержащую информацию о тайминге каждой из функций.
Без аргументов, @code{timer_info} возвращает информацию для всех
контролируемых функций.

Матрица, возвращаемая @code{timer_info}, содержит: имя функции,
среднее время вызова функции, число вызовов, общее время
и @code{gctime}, что обозначает "время сборки мусора" в Macsyma,
но сейчас это время всегда равно нулю.

Данные, сообщаемые @code{timer_info}, могут быть получены другим способом
при помощи функции @code{get}:

@example
get(f, 'calls);  get(f, 'runtime);  get(f, 'gctime);
@end example

См. также @code{timer}.

@opencatbox
@category{Отладка}
@closecatbox
@end deffn

@deffn {Функция} trace (@var{f_1}, ..., @var{f_n})
@deffnx {Функция} trace (all)
@deffnx {Функция} trace ()
Устанавливает трассировку для функций @var{f_1}, ..., @var{f_n},
т.е. Maxima будет печатать отладочную информацию при каждом
вызове любой из этих функций.
Последовательные вызовы @code{trace(f)$ trace(g)$} сначала включает трассировку @code{f} 
а затем трассировку @code{g}, т.е. список трассируемых функций 
пополняется от одного вызова @code{trace} к другому.

@code{trace(all)} включает трассировку для всех пользовательских функций,
которые определяются глобальной переменной @code{functions}.

Без аргументов, 
@code{trace} возвращает список всех трассируемых функций.

Функция @code{untrace} отменяет трассировку.
См. также @code{trace_options}. 

Функция @code{trace} не вычисляет свои аргументы. 
Команды @code{f(x) := x^2$ g:f$ trace(g)$} не добавят @code{f} к списку
трассируемых функций.

Если функция переопределяется, то она удаляется из списка трассируемых функций.
Т.е. после @code{timer(f)$ f(x) := x^2$},
функция @code{f} трассироваться не будет.

Если действует @code{timer (f)}, то @code{trace (f)} не работает; 
т.к. @code{trace} и @code{timer} не могут действовать одновременно.

@opencatbox
@category{Отладка}
@closecatbox
@end deffn

@deffn {Функция} trace_options (@var{f}, @var{option_1}, ..., @var{option_n})
@deffnx {Функция} trace_options (@var{f})
Устанавливает опции трассировки для функции @var{f}.
Любые предыдущие опции переопределяются.
@code{trace_options (@var{f}, ...)} не действует если не включена 
трассировка @code{trace (@var{f})} (либо до, либо после вызова @code{trace_options}). 

@code{trace_options (@var{f})} возвращает все опции в значение "по умолчанию".

Существуют следующие ключевые слова опций трассировки:

@itemize @bullet
@item
@code{noprint}
Не печатать сообщения при начале и завершении выполнения функции.
@item
@code{break}
Установить точки останова до начала выполнения функции и после ее 
завершения. См. @code{break}.
@item
@code{lisp_print}
Выводить аргументы и возвращаемые значения в виде Lisp объектов.
@item
@code{info}
Печатать @code{-> true} при входе и выходе из функции.
@item
@code{errorcatch}
Перехватывать ошибки с предоставлением опций: сгенерировать ошибку,
вычислить функцию повторно, задать возвращаемое значение.
@end itemize

Опции трассировки могут задаваться двумя способами.
Одно ключевое слово включает соответствующую опцию безусловно.
Заметим, что для включения опции @var{foo} не следует указывать @code{@var{foo}: true},
кроме того, опции не надо экранировать.
Ключевое слово с предикатом включает опцию условно в зависимости
от значения предиката.

Существуют следующие аргументы предиката @code{[level, direction, function, item]},
где @code{level} есть уровень рекурсии;  @code{direction} есть либо @code{enter}, либо @code{exit};
@code{function} есть имя функции; и @code{item} есть список аргументов (при входе)
или возвращаемое значение (при выходе).

Пример применения безусловных опций трассировки:

@example
(%i1) ff(n) := if equal(n, 0) then 1 else n * ff(n - 1)$

(%i2) trace (ff)$

(%i3) trace_options (ff, lisp_print, break)$

(%i4) ff(3);
@end example

Ниже, та же функция условной опцией трассировки @code{break}:

@example
(%i5) trace_options (ff, break(pp))$

(%i6) pp (level, direction, function, item) := block (print (item),
    return (function = 'ff and level = 3 and direction = exit))$

(%i7) ff(6);
@end example

@opencatbox
@category{Отладка}
@closecatbox
@end deffn

@deffn {Функция} untrace (@var{f_1}, ..., @var{f_n})
@deffnx {Функция} untrace ()
Отменяет трассировку функций @var{f_1}, ..., @var{f_n},
установленную ранее при помощи @code{trace}.
Без аргументов, @code{untrace} отменяет трассировку всех функций.

Функция @code{untrace} возвращает список функций, для которых
была отменена трассировка.

@opencatbox
@category{Отладка}
@closecatbox
@end deffn
