@c Language: Portuguese
@c Source: Debugging.texi (en) 1.16
@menu
* Depura@value{cedilha}@~ao do C@'odigo Fonte::
* Comandos Palavra Chave::
* Defini@value{cedilha}@~oes para Depura@value{cedilha}@~ao::   
@end menu

@node Depura@value{cedilha}@~ao do C@'odigo Fonte, Comandos Palavra Chave, , Depura@value{cedilha}@~ao
@section Depura@value{cedilha}@~ao do C@'odigo Fonte

Maxima tem um depurador interno de c@'odigo fonte.  O utilizador pode
escolher um ponto de parada numa fun@,{c}@~ao, e executar o programa
linha por linha a partir da@'{@dotless{i}}. A pilha de chamadas pode ser
examinada, juntamente com as vari@'aveis existentes nesse n@'{@dotless{i}}vel.

O comando @code{:help} ou @code{:h} mostra a lista de comandos de
depura@,{c}@~ao.  (Em geral, os comandos podem ser abreviados se a
abrevia@,{c}@~ao for @'unica. Se n@~ao for @'unica, as alternativas
podem ser listadas.)  Dentro do depurador, o utilizador pode tamb@'em
usar quaisquer fun@,{c}@~oes comuns do Maxima para examinar, definir,
e manipular vari@'aveis e express@~oes.

Um ponto de parada @'e escolhido atrav@'es do comando @code{:br} na
linha de comando do Maxima. Dentro do depurador, o utilizador pode
avan@,{c}ar uma linha de cada vez usando o comando @code{:n}
(``next'').  o comando @code{:bt} (``backtrace'') mostra uma lista da
pilha de frames.  O comando @code{:r} (``resume'') sai do depurador e
continua com a execu@,{c}@~ao.  Esses comandos s@~ao demostrados no
exemplo a seguir.

@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 digitado aqui lista os frames
#0: foo(y=5)(foobar.mac line 1)
#1: bar(x=2,y=3)(foobar.mac line 9)

(dbm:1) :n                         <-- Aqui digite :n para avan@,{c}ar linha
(foobar.mac 2)
/tmp/foobar.mac:2::

(dbm:1) :n                         <-- Aqui digite :n para avan@,{c}ar linha
(foobar.mac 3)
/tmp/foobar.mac:3::

(dbm:1) u;                         <-- Investiga o valor de u
28

(dbm:1) u: 33;                     <-- Altera u para ser 33
33

(dbm:1) :r                         <-- Digite :r para retomar a computa@,{c}@~ao

(%o2)                                1094
@end example

O ficheiro @code{/tmp/foobar.mac} @'e o seguinte:

@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

USO DO DEPURADOR ATRAV@'ES DO EMACS E DE XMAXIMA

Se o utilizador estiver a executar o c@'odigo sob o GNU Emacs numa janela
shell (shel dbl), ou estiver usando a interface gr@'afica,
@code{xmaxima}, ent@~ao quando parar num ponto de parada, ver@'a a sua
posi@,{c}@~ao actual no ficheiro fonte apresentada na
outra metade da janela, ou em vermelho brilhante, ou com uma pequena
seta apontando na direita da linha. Poder@'a avan@,{c}ar uma linha por
vez digitando M-n (Alt-n).

No Emacs pode executar o Maxima numa shell @code{dbl}, o qual requer o
ficheiro @code{dbl.el} no direct@'orio elisp.
Verifique que tenha instalado os ficheiros elisp ou adicionado o direct@'orio elisp do Maxima ao seu caminho:
e.g., adicione o seguinte ao seu ficheiro @file{.emacs} ou ao seu ficheiro
@code{site-init.el}

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

ent@~ao no Emacs 

@example
M-x dbl
@end example

pode iniciar uma janela shell na qual pode executar programas, por exemplo
Maxima, gcl, gdb etc. Essa janela de shell tamb@'em reconhece informa@,{c}@~oes sobre
depura@,{c}@~ao de c@'odigo fonte, e mostra o c@'odigo fonte em outra janela.  

O utilizador pode escolher um ponto de parada em certa linha do
ficheiro digitando @code{C-x space}. Isso encontra qual a fun@,{c}@~ao
onde o cursor est@'a posicionado, e mostra qual a linha daquela fun@,{c}@~ao
onde o cursor est@'a habilitado. Se o cursor estiver habilitado, digamos, na linha
2 de @code{foo}, ent@~ao isso ir@'a inserir na outra janela o comando,
``@code{:br foo 2}'', para parar @code{foo} nessa segunda linha.
Para ter isso habilitado, o utilizador deve ter
maxima-mode.el habilitado na janela na qual o ficheiro @code{foobar.mac} estiver interagindo.
Existe comandos adicional dispon@'{@dotless{i}}veis naquela janela de ficheiro, tais como
avaliando a fun@,{c}@~ao dentro do Maxima, atrav@'es da digita@,{c}@~ao de @code{Alt-Control-x}.

@node Comandos Palavra Chave, Defini@value{cedilha}@~oes para Depura@value{cedilha}@~ao, Depura@value{cedilha}@~ao do C@'odigo Fonte, Depura@value{cedilha}@~ao
@section Comandos Palavra Chave

Comandos palavra chave s@~ao palavras chaves especiais que n@~ao s@~ao interpretadas como express@~oes do Maxima.
Um comando palavra chave pode ser inserido na linha de comando do Maxima ou na linha de comando do depurador,
embora n@~ao possa ser inserido na linha de comando de parada.
Comandos palavra chave iniciam com um dois pontos Keyword commands start with a colon, ':'.
Por exemplo, para avaliar um comando do Lisp,
pode escrever @code{:lisp} seguido pelo comando a ser avaliado.  

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

O n@'umero de argumentos necess@'arios depende do comando em particular.
Tamb@'em, n@~ao precisa escrever o comando completo, apenas o suficiente
para ser @'unico no meio das palavras chave de parada. Dessa forma
@code{:br} ser@'a suficiente para @code{:break}.

Os comandos de palavra chave s@~ao listados abaixo.

@table @code
@item :break F n
Escolhe um ponto de parada em uma fun@,{c}@~ao @code{F} na linha @code{n} 
a partir do in@'{@dotless{i}}cio da fun@,{c}@~ao.
Se @code{F} for dado como uma sequ@^encia de caracteres, ent@~ao essa sequ@^encia de caracteres @'e assumida referir-se a
um ficheiro, e @code{n} @'e o deslocamente a partir do in@'{@dotless{i}}cio do ficheiro.
O deslocamento @'e opcional. Se for omitido, @'e assumido ser zero
(primeira linha da fun@,{c}@~ao ou do ficheiro).
@item :bt
Imprime na tela uma lista da pilha de frames
@item :continue
Continua a computa@,{c}@~ao
@c CAN'T SEEM TO GET :delete TO WORK !!!
@item :delete
Remove o ponto de parada seleccionado, ou todos se nenum for especificado
@c CAN'T SEEM TO GET :disable TO WORK !!!
@item :disable
Desabilita os pontos de parada seleccionados, ou todos se nenhum for especificado
@c CAN'T SEEM TO GET :enable TO WORK !!!
@item :enable
Habilita os pontos de de parada especificados, ou todos se nenhum for especificado
@item :frame n
Imprime na tela a pilha de frame @code{n}, ou o corrente frame se nenhum for especificado
@c CAN'T SEEM TO GET :help TO WORK !!!
@item :help
Imprime na tela a ajuda sobre um comando do depurador, ou todos os comandos se nenhum for especificado
@c CAN'T SEEM TO GET :info TO WORK !!!
@item :info
Imprime na tela informa@,{c}@~oes sobre um item
@item :lisp alguma-forma
Avalia @code{alguma-forma} como uma forma Lisp
@item :lisp-quiet alguma-forma
Avalia a forma Lisp @code{alguma-forma} sem qualquer sa@'{@dotless{i}}da
@item :next
Como @code{:step}, excepto @code{:next} passos sobre chamadas de fu@,{c}@~ao
@item :quit
Sai do n@'{@dotless{i}}vel corrente do depurador sem concluir a computa@,{c}@~ao
@item :resume
Continua a computa@,{c}@~ao
@item :step
Continua a computa@,{c}@~ao at@'e encontraruma nova linha de c@'odico
@item :top
Retorne para a linha de comando do Maxima (saindo de qualquer n@'{@dotless{i}}vel do depurador) sem 
completar a computa@,{c}@~ao
@end table 


@node Defini@value{cedilha}@~oes para Depura@value{cedilha}@~ao, , Comandos Palavra Chave, Depura@value{cedilha}@~ao
@section Defini@value{cedilha}@~oes para Depura@value{cedilha}@~ao

@defvr {Vari@'avel de op@,{c}@~ao} refcheck
Valor por omiss@~ao: @code{false}

Quando @code{refcheck} for @code{true}, Maxima imprime uma mensagem
cada vez que uma vari@'avel associada for usada pela primeira vez em uma
computa@,{c}@~ao.

@end defvr

@defvr {Vari@'avel de op@,{c}@~ao} setcheck
Valor por omiss@~ao: @code{false}

Se @code{setcheck} for escolhido para uma lista de vari@'aveis (as quais podem
ser subscritas), 
Maxima mostra uma mensagem quando as vari@'aveis, ou
ocorr@^encias subscritas delas, forem associadas com o
operador comum de atribui@,{c}@~ao @code{:}, o operador @code{::}
de atribui@,{c}@~ao, ou associando argumentos de fun@,{c}@~ao,
mas n@~ao com o operador de atribui@,{c}@~ao de fun@,{c}@~ao @code{:=} nem o operador de atribui@,{c}@~ao
@code{::=} de macro.
A mensagem compreende o nome das vari@'aveis e o
valor associado a ela.

@code{setcheck} pode ser escolhida para @code{all} ou @code{true} incluindo
desse modo todas as vari@'aveis.

Cada nova atribui@,{c}@~ao de @code{setcheck} estabelece uma nova lista de vari@'aveis
para verificar, e quaisquer vari@'aveis previamente atribu@'{@dotless{i}}das a @code{setcheck} s@~ao esquecidas.

Os nomes atribu@'{@dotless{i}}dos a @code{setcheck} devem ter um ap@'ostrofo no in@'{@dotless{i}}cio se eles forem de outra forma
avaliam para alguma outra coisa que n@~ao eles mesmo.
Por exemplo, se @code{x}, @code{y}, e @code{z} estiverem actualmente associados, ent@~ao digite

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

para coloc@'a-los na lista de vari@'aveis monitoradas.

Nenhuma sa@'{@dotless{i}}da @'e gerada quando uma
vari@'avel na lista @code{setcheck} for atribu@'{@dotless{i}}da a s@'{@dotless{i}} mesma, e.g., @code{X: 'X}.

@end defvr

@defvr {Vari@'avel de op@,{c}@~ao} setcheckbreak
Valor por omiss@~ao: @code{false}

Quando @code{setcheckbreak} for @code{true},
Maxima mostrar@'a um ponto de parada 
quando uma vari@'avel sob a lista @code{setcheck} for atribu@'{@dotless{i}}da a um novo valor.
A parada ocorre antes que a atribu@'{@dotless{i}}@,{c}@~ao seja conclu@'{@dotless{i}}da.
Nesse ponto, @code{setval} ret@'em o valor para o qual a vari@'avel est@'a 
para ser atribu@'{@dotless{i}}da.
Consequentemente, se pode atribuir um valor diferente atrav@'es da atribui@,{c}@~ao a @code{setval}.

Veja tamb@'em @code{setcheck} e @code{setval}.

@end defvr

@defvr {Vari@'avel de sistema} setval
Mant@'em o valor para o qual a vari@'avel est@'a para ser escolhida quando
um @code{setcheckbreak} ocorrer.
Consequentemente, se pode atribuir um valor diferente atrav@'es da atribui@,{c}@~ao a @code{setval}.

Veja tamb@'em @code{setcheck} e @code{setcheckbreak}.

@end defvr

@deffn {Fun@,{c}@~ao} timer (@var{f_1}, ..., @var{f_n})
@deffnx {Fun@,{c}@~ao} timer ()
Dadas as fun@,{c}@~oes @var{f_1}, ..., @var{f_n},
@code{timer} coloca cada uma na lista de fun@,{c}@~oes para as quais cronometragens estat@'{@dotless{i}}sticas s@~ao colectadas.
@code{timer(f)$ timer(g)$} coloca @code{f} e ent@~ao @code{g} sobre a lista;
a lista acumula de uma chamada para a chamada seguinte.

Sem argumentos, 
@code{timer} retorna a lista das fun@,{c}@~oes tempo estatisticamente monitoradas.

Maxima armazena quanto tempo @'e empregado executando cada fun@,{c}@~ao
na lista de fun@,{c}@~oes tempo estatisticamente monitoradas.
@code{timer_info} retorna a coronometragem estat@'{@dotless{i}}stica, incluindo o
tempo m@'edio decorrido por chamada de fun@,{c}@~ao, o n@'umero de chamadas, e o
tempo total decorrido.
@code{untimer} remove fun@,{c}@~oes da lista de fun@,{c}@~oes tempo estatisticamente monitoradas.

@code{timer} n@~ao avalia seus argumentos. 
@code{f(x) := x^2$ g:f$ timer(g)$} n@~ao coloca @code{f} na lista de fun@,{c}@~oes estatisticamente monitoradas.

Se @code{trace(f)} est@'a vigorando, ent@~ao @code{timer(f)} n@~ao tem efeito; @code{trace} e
@code{timer} n@~ao podem ambas atuarem ao mesmo tempo.

Veja tamb@'em @code{timer_devalue}.

@end deffn
@deffn {Fun@,{c}@~ao} untimer (@var{f_1}, ..., @var{f_n})
@deffnx {Fun@,{c}@~ao} untimer ()
Dadas as fun@,{c}@~oes @var{f_1}, ..., @var{f_n},
@code{untimer} remove cada uma das fun@,{c}@~oes listadas da lista de fun@,{c}@~oes estatisticamente monitoradas.

Sem argumentos, @code{untimer} remove todas as fun@,{c}@~oes actualmente na  lista de fun@,{c}@~oes estatisticamente monitoradas.

Ap@'os @code{untimer (f)} ser executada, @code{timer_info (f)} ainda retorna
estatisticas de tempo previamente colectadas,
embora @code{timer_info()} (sem argumentos) n@~ao
retorna informa@,{c}@~oes sobre qualquer fun@,{c}@~ao que n@~ao estiver actualmente na lista de fun@,{c}@~oes tempo estatisticamente monitoradas.
@code{timer (f)} reposiciona todas as estatisticas de tempo para zero
e coloca @code{f} na lista de fun@,{c}@~oes estatisticamente monitoradas novamente.

@end deffn

@defvr {Vari@'avel de op@,{c}@~ao} timer_devalue
Valor Padr@~ao: @code{false}

Quando @code{timer_devalue} for @code{true}, Maxima subtrai de cada fun@,{c}@~ao estatisticamente monitorada
o tempo empregado em ou fun@,{c}@~oes estatisticamente monitoradas. De outra forma, o tempo reportado 
para cada fun@,{c}@~ao inclui o tempo empregado em outras fun@,{c}@~oes.
Note que tempo empregado em fun@,{c}@~oes n@~ao estatisticamente monitoradas n@~ao @'e subtra@'{@dotless{i}}do do
tempo total.

Veja tamb@'em @code{timer} e @code{timer_info}.

@end defvr

@deffn {Fun@,{c}@~ao} timer_info (@var{f_1}, ..., @var{f_n})
@deffnx {Fun@,{c}@~ao} timer_info ()
Dadas as fun@,{c}@~oes @var{f_1}, ..., @var{f_n},
@code{timer_info} retorna uma matriz contendo informa@,{c}@~oes de cronometragem para cada fun@,{c}@~ao.
Sem argumentos, @code{timer_info} retorna informa@,{c}@~oes de cronometragem para
todas as fun@,{c}@~oes actualmente na lista de fun@,{c}@~oes estatisticamente monitoradas.

A matriz retornada atrav@'es de @code{timer_info} cont@'em o nome da fun@,{c}@~ao,
tempo por chamda de fun@,{c}@~ao, n@'umero de chamadas a fun@,{c}@~oes,tempo total,
e @code{gctime}, cujja forma "tempo de descarte" no Macsyma original
mas agora @'e sempre zero.

Os dados sobre os quais @code{timer_info} constr@'oi seu valor de retorno
podem tamb@'em serem obtidos atrav@'es da fun@,{c}@~ao @code{get}:

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

Veja tamb@'em @code{timer}.

@end deffn

@deffn {Fun@,{c}@~ao} trace (@var{f_1}, ..., @var{f_n})
@deffnx {Fun@,{c}@~ao} trace ()
Dadas as fun@,{c}@~oes @var{f_1}, ..., @var{f_n},
@code{trace} instrui Maxima para mostrar
informa@,{c}@~oes de depura@,{c}@~ao quando essas fun@,{c}@~oes forem chamadas.
@code{trace(f)$ trace(g)$} coloca @code{f} e ent@~ao @code{g} na lista de fun@,{c}@~oes
para serem colocadas sob a a@,{c}@~ao de @code{trace}; a lista acumula de uma chamada para a seguinte.

Sem argumentos,
@code{trace} retorna uma lista de todas as fun@,{c}@~oes actualmente sob a a@,{c}@~ao de @code{trace}.

A fun@,{c}@~ao @code{untrace} desabilita a a@,{c}@~ao de @code{trace}.
Veja tamb@'em @code{trace_options}. 

@code{trace} n@~ao avalia seus argumentos. Dessa forma,
@code{f(x) := x^2$ g:f$ trace(g)$} n@~ao coloca @code{f} sobre a lista de fun@,{c}@~oes monitoradas por @code{trace}.

Quando uma fun@,{c}@~ao for redefinida, ela @'e removida da lista de @code{timer}.
Dessa forma ap@'os @code{timer(f)$ f(x) := x^2$},
a fun@,{c}@~ao @code{f} n@~ao mais est@'a na lista de @code{timer}.

Se @code{timer (f)} estiver em efeito, ent@~ao @code{trace (f)} n@~ao est@'a agindo; @code{trace} e
@code{timer} n@~ao podem ambas estar agindo para a mesma fun@,{c}@~ao.

@end deffn

@deffn {Fun@,{c}@~ao} trace_options (@var{f}, @var{option_1}, ..., @var{option_n})
@deffnx {Fun@,{c}@~ao} trace_options (@var{f})
Escolhe as op@,{c}@~oes de @code{trace} para a fun@,{c}@~ao @var{f}.
Quaisquer op@,{c}@~oes anteriores s@~ao substitu@'{@dotless{i}}das.
@code{trace_options (@var{f}, ...)} n@~ao tem efeito a menos que
@code{trace (@var{f})} tenha sido tamb@'em chamada (ou antes ou ap@'os @code{trace_options}). 

@code{trace_options (@var{f})} reposiciona todas as op@,{c}@~oes para seus valores padr@~ao.

As op@,{c}@~oes de palavra chave s@~ao:

@itemize @bullet
@item
@code{noprint}
N@~ao mostre uma mensagem na entrada da fun@,{c}@~ao e saia.
@item
@code{break}
Coloque um ponto de parada antes da fun@,{c}@~ao ser inserida,
e ap@'os a fun@,{c}@~aos er retirada. Veja @code{break}.
@item
@code{lisp_print}
Mostre argumentos e valores de retorno com objectos Lisp.
@item
@code{info}
Mostre @code{-> true} na entrada da fun@,{c}@`ao e saia.
@item
@code{errorcatch}
Capture os erros, fornecendo a op@,{c}@~ao para sinalizar um erro,
tentar novamente a chamada de fun@,{c}@~ao, ou especificar um valor de retorno.
@end itemize

Op@,{c}@~oes para @code{trace} s@~ao especificadas em duas formas. A presen@,{c}a da palavra chave de 
op@,{c}@~ao sozinha coloca a op@,{c}@~ao para ter efeito incondicionalmente.
(Note que op@,{c}@~ao @var{foo} n@~ao coloca para ter efeito especificando 
@code{@var{foo}: true} ou uma forma similar; note tamb@'em que palavras chave n@~ao precisam
estar com ap@'ostrofo.) Especificando a op@,{c}@~ao palavra chave com uma fun@,{c}@~ao
predicado torna a op@,{c}@~ao condicional sobre o predicado.

A lista de argumentos para a fun@,{c}@~ao predicado @'e sempre 
@code{[level, direction, function, item]} onde @code{level} @'e o n@'{@dotless{i}}vel rerecurs@~ao
para a fun@,{c}@~ao,  @code{direction} @'e ou @code{enter} ou @code{exit}, @code{function} @'e o
nome da fun@,{c}@~ao, e @code{item} @'e a lista de argumentos (sobre entrada)
ou o valor de retorno (sobre a sa@'{@dotless{i}}da).

Aqui est@'a um exemplo de op@,{c}@~oes incondicionais de @code{trace}:

@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

Aqui est@'a a mesma fun@,{c}@~ao, com a op@,{c}@~ao @code{break} condicional
sobre um predicado:

@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

@end deffn

@deffn {Fun@,{c}@~ao} untrace (@var{f_1}, ..., @var{f_n})
@deffnx {Fun@,{c}@~ao} untrace ()
Dadas as fun@,{c}@~oes @var{f_1}, ..., @var{f_n},
@code{untrace} desabilita a a monitora@,{c}@~ao habilitada pela fun@,{c}@~ao @code{trace}.
Sem argumentos, @code{untrace} desabilita a atua@,{c}@~ao da fun@,{c}@~ao @code{trade} para todas as fun@,{c}@~oes.

@code{untrace} retorne uma lista das fun@,{c}@~oes para as quais 
@code{untrace} desabilita a atua@,{c}@~ao de @code{trace}.

@end deffn