@c version 1.16
@menu
* Depuraci@'on del c@'odigo fuente::
* Claves de depuraci@'on::
* Definiciones para Depurado::
@end menu

@node Depuraci@'on del c@'odigo fuente, Claves de depuraci@'on, , Depurado
@section Depuraci@'on del c@'odigo fuente

Maxima es capaz de dar asistencia en la depuraci@'on del c@'odigo fuente. Un usuario puede establecer un punto de referencia dentro del c@'odigo de una funci@'on a partir del cual se siga la ejecuci@'on l@'{@dotless{i}}nea a l@'{@dotless{i}}nea. La compliaci@'on puede ser posteriormente examinada, conjuntamente con los valores que se han ido asignando a las variables.

La instrucci@'on @code{:help}, o @code{:h}, muestra la lista de comandos para la depuraci@'on. (En general, los comandos pueden abreviarse; en algunos casos la lista de alternativas podr@'a ser listada.) Dentro del depurador, el usuario podr@'a examinar tambi@'en cualquier funci@'on propia de Maxima, definirla y manipular variables y expresiones.

El punto de referencia se establecer@'a con la instrucci@'on @code{:br}. Ya dentro del depurador, el usuario podr@'a avanzar una l@'{@dotless{i}}nea de cada vez utilizando la instrucci@'on @code{:n} (de ``next'', en ingl@'es). La orden @code{:bt} (de ``backtrace'') muestra la lista de la pila. Finalmente, con el comando @code{:r} (``resume'') se abandona el depurador continuando con la ejecuci@'on. El uso de estas instrucciones se muestra en el siguiente ejemplo.

@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                  <-- pulsando :bt se retrocede
#0: foo(y=5)(foobar.mac line 1)
#1: bar(x=2,y=3)(foobar.mac line 9)

(dbm:1) :n                   <-- pulsando :n se avanza una l@'{@dotless{i}}nea
(foobar.mac 2)
/tmp/foobar.mac:2::

(dbm:1) :n                   <-- pulsando :n se avanza otra l@'{@dotless{i}}nea
(foobar.mac 3)
/tmp/foobar.mac:3::

(dbm:1) u;                   <-- se pide el valor de u
28

(dbm:1) u: 33;               <-- se cambia el valor de u a 33
33

(dbm:1) :r                   <-- pulsando :r se termina la depuraci@'on

(%o2)                                1094
@end example

El fichero @code{/tmp/foobar.mac} contiene lo siguiente:

@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 DEL DEPURADOR EN EMACS

Si el usuario est@'a corriendo el c@'odigo bajo GNU emacs en un entorno de texto (dbl shell), o est@'a ejecutando el  entorno gr@'afico @code{xmaxima}, entonces cuando una funci@'on pare en el punto de referencia, podr@'a observar su
posici@'on actual en el archivo fuente, el cual ser@'a mostrado en la otra mitad de la ventana, bien resaltada en rojo, o con una peque@~na flecha apuntando a la l@'{@dotless{i}}nea correcta. El usuario puede avanzar l@'{@dotless{i}}neas simples 
tecleando M-n (Alt-n).

Bajo Emacs se debe ejecutar el programa en una ventana de texto @code{dbl}, la cual requiere el archivo @code{dbl.el} que est@'a en el directorio elisp. El usuario debe instalar los archivos elisp o agregar el directorio elisp de Maxima a la ruta de b@'usqueda: por ejemplo, se puede a@~nadir lo siguiente al archivo @file{.emacs} o al @code{site-init.el}

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

entonces en emacs

@example
M-x dbl
@end example

deber@'{@dotless{i}}a abrir una ventana del sistema en la cual se pueden ejecutar programas, por ejemplo
Maxima, gcl, gdb, etc.  En esta ventana tambi@'en se puede ejecutar el depurador, mostrando el c@'odigo fuente en la otra ventana.

El usuario puede colocar un punto de referencia en una l@'{@dotless{i}}nea determinada sin m@'as que teclear @code{C-x space}. Con esto se le hace saber al depurador en qu@'e funci@'on est@'a el cursor y en qu@'e l@'{@dotless{i}}nea del mismo. Si el cursor est@'a en la l@'{@dotless{i}}nea 2 de @code{foo}, entonces insertar@'a en la otra ventana la instrucci@'on ``@code{:br foo 2}'', a fin de detener @code{foo} justo en la segunda l@'{@dotless{i}}nea. Para tener esto operativo, el usuario debe tener activo maxima-mode.el (modo-maxima.el) en la ventana en la que est@'a @code{foobar.mac}. Hay otros comandos disponibles en la ventana, como evaluar la funci@'on dentro de Maxima tecleando @code{Alt-Control-x}.


@node Claves de depuraci@'on, Definiciones para Depurado, Depuraci@'on del c@'odigo fuente, Depurado
@section Claves de depuraci@'on

Las claves de depuraci@'on son palabras que no son interpretadas como expresiones de Maxima. Una clave de depuraci@'on puede introducirse dentro de Maxima o del depurador. Las claves de depuraci@'on comienzan con dos puntos, ':'. Por ejemplo, para evaluar una expresi@'on Lisp, se puede teclear @code{:lisp} seguido de la expresi@'on a ser evaluada.

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

El n@'umero de argumentos depende del comando en particular. Adem@'as, tampoco es necesario teclear el nombre completo de la instrucci@'on, tan solo lo justo para diferenciarla de las otras instrucciones. As@'{@dotless{i}}, @code{:br} ser@'{@dotless{i}}a suficiente para @code{:break}.

Las claves de depuraci@'on se listan a continuaci@'on.

@table @code
@item :break F n
Establece un punto de referencia en la funci@'on @code{F} en la l@'{@dotless{i}}nea @code{n} contando a partir del comienzo de la funci@'on. Si @code{F} es una cadena, entonces se entiende que se trata de un fichero, siendo entonces @code{n} el n@'umero de l@'{@dotless{i}}nea a partir del comienzo del fichero. El valor @code{n} es opcional; en caso de no ser suministrado, se entender@'a que vale cero (primera l@'{@dotless{i}}nea de la funci@'on o fichero).
@item :bt
Retrocede en la pila.
@item :continue
Continua el c@'omputo de la funci@'on.
@item :delete
Borra los punto de referencia especificados, o todos si no se especifica ninguno.
@item :disable
Deshabilita los puntos de referencia especificados, o todos si no se especifica ninguno.
@item :enable
Habilita los puntos de referencia especificados, o todos si no se especifica ninguno.
@item :frame n
Imprime el elemento @code{n} de la pila, o el actualmente activo si no se especifica ninguno.
@item :help
Imprime la ayuda sobre un comando del depurador, o de todos los comandos si no se especifica ninguno.
@item :info
Imprime informaci@'on sobre un elemento.
@item :lisp expresi@'on
Eval@'ua la @code{expresi@'on} Lisp.
@item :lisp-quiet expresi@'on
Eval@'ua la @code{expresi@'on} Lisp sin devolver el resultado.
@item :next
Como @code{:step}, excepto que @code{:next} se salta las llamadas a funciones.
@item :quit
Sale del nivel actual del depurador sin completar el c@'omputo.
@item :resume
Contin@'ua con el c@'omputo.
@item :step
Sigue con el c@'omputo de la funci@'on o fichero hasta que alcance una nueva l@'{@dotless{i}}nea fuente.
@item :top
Retorna a Maxima desde cualquier nivel del depurador sin completar el c@'omputo.
@end table 


@node Definiciones para Depurado, , Claves de depuraci@'on, Depurado
@section Definiciones para Depurado

@defvr {Variable opcional} refcheck
Valor por defecto: @code{false}

Cuando @code{refcheck} vale @code{true}, Maxima imprime un mensaje cada vez que una variable es utilizada por vez primera en un c@'alculo.

@end defvr

@defvr {Variable opcional} setcheck
Valor por defecto: @code{false}

Cuando el valor de @code{setcheck} es una lista de variables (se admite que tengan sub@'{@dotless{i}}ndices) Maxima devuelve un mensaje indicando si los valores que han sido asignados a las variables lo han sido con el operador ordinario @code{:}, o con el operador de asignaci@'on @code{::} o como resultado de haberse realizado una llamada de funci@'on, pero en ning@'un caso cuando la asignaci@'on haya sido hecha mediante los operadores @code{:=} o @code{::=}. El mensaje contiene el nombre de la variable y su valor.

La variable @code{setcheck} admite tambi@'en los valores @code{all} o @code{true} con lo que el informe incluir@'a todas las variables.

Cada nueva asignaci@'on de @code{setcheck} establece una nueva lista de variables a ser monitorizada, de forma que cualquier otra variable previamente asignada a @code{setcheck} es olvidada.

Los nombres asignados a @code{setcheck} deben estar precedidos del ap@'ostrofo @code{'} a fin de evitar que las variables sean evaluadas antes de ser almacenadas en @code{setcheck}. Por ejemplo, si @code{x}, @code{y} y @code{z} ya guardan alg@'un valor entoces se har@'a

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

para colocarlas en la lista de variables a monitorizar.

No se generar@'a ninguna salida cuando una variable de la lista @code{setcheck} sea asignada a ella misma, como en @code{X: 'X}.

@end defvr

@defvr {Variable opcional} setcheckbreak
Valor por defecto: @code{false}

Si @code{setcheckbreak} es igual @code{true}, Maxima se detendr@'a siempre que a una variable de la lista @code{setcheck} se le asigne un nuevo valor. La detenci@'on tendr@'a lugar justo antes de hacerse la asignaci@'on. En ese momento @code{setval} guarda el valor que se le va a dar a la variable. Entonces el usuario podr@'a darle un valor diferente pas@'andoselo a la variable @code{setval}.

V@'eanse tambi@'en @code{setcheck} y @code{setval}.

@end defvr

@defvr {Variable del sistema} setval

Guarda el valor que va a ser asignado a una variable cuando @code{setcheckbreak} realiza una detenci@'on. Entonces se podr@'a asignarle otro valor pas@'andoselo previamente a @code{setval}.

V@'eanse tambi@'en @code{setcheck} y @code{setcheckbreak}.

@end defvr

@deffn {Funci@'on} timer (@var{f_1}, ..., @var{f_n})
@deffnx {Funci@'on} timer ()
Dadas las funciones @var{f_1}, ..., @var{f_n}, @code{timer} coloca cada una de ellas en la lista de funciones para las cuales se generar@'an estad@'{@dotless{i}}sticas relativas al tiempo de c@'omputo. As@'{@dotless{i}}, @code{timer(f)$ timer(g)$} coloca a @code{f} y luego a @code{g} en dicha lista de forma acumulativa.

Si no se le pasan argumentos a @code{timer} se obtendr@'a la lista de funciones cuyos tiempos de ejecuci@'on se quieren monitorizar.

Maxima almacena la duraci@'on del c@'omputo de cada funci@'on de la lista, de forma que @code{timer_info} devolver@'a las estad@'{@dotless{i}}sticas correspondientes, incluyendo el tiempo medio de cada llamada a la funci@'on, el n@'umero de llamadas realizadas y el tiempo total transcurrido. La instrucci@'on @code{untimer} borra las funciones de la lista.

La funci@'on @code{timer} no eval@'ua sus argumentos, de forma que @code{f(x) := x^2$ g:f$ timer(g)$} no coloca a @code{f} en la lista.

Si @code{trace(f)} est@'a activada, entonces @code{timer(f)} est@'a desactivada; @code{trace} y @code{timer} no pueden estar operativas al mismo tiempo.

V@'ease tambi@'en @code{timer_devalue}.

@end deffn

@deffn {Funci@'on} untimer (@var{f_1}, ..., @var{f_n})
@deffnx {Funci@'on} untimer ()
Dadas las funciones @var{f_1}, ..., @var{f_n}, @code{untimer} las elimina de la lista de funciones cuyos tiempos de ejecuci@'on se quiere monitorizar.

Si no se le suministran argumentos, @code{untimer} borra completamente la lista.

Tras la ejecuci@'on de @code{untimer (f)}, @code{timer_info (f)} a@'un devuelve las estad@'{@dotless{i}}sticas de tiempo previamente registradas, pero @code{timer_info()} (sin argumentos) no devuelve informaci@'on sobre aquellas funciones que ya no est@'an en la lista. La ejecuci@'on de @code{timer (f)} inicializa todas las estad@'{@dotless{i}}sticas a cero y coloca @code{f} nuevamente en la lista.

@end deffn

@defvr {Variable opcional} timer_devalue
Valor por defecto: @code{false}

Si @code{timer_devalue} es igual a @code{true}, Maxima le resta a cada funci@'on cuyos tiempos de ejecuci@'on se quiere monitorizar el tiempo gastado en llamadas a otras funciones presentes tambi@'en en la lista de monitorizaci@'on. En caso contrario, los tiempos que se obtienen para cada funci@'on incluyen tambi@'en los consumidos en otras funciones. N@'otese que el tiempo consumido en llamadas a otras funciones que no est@'an en la lista de monitorizaci@'on no se resta del tiempo total.

V@'eanse tambi@'en @code{timer} y @code{timer_info}.

@end defvr

@deffn {Funci@'on} timer_info (@var{f_1}, ..., @var{f_n})
@deffnx {Funci@'on} timer_info ()
Dadas las funciones @var{f_1}, ..., @var{f_n}, @code{timer_info} devuelve una matriz con informaci@'on relativa a los tiempos de ejecuci@'on de cada una de estas funciones. Sin argumentos, @code{timer_info} devuelve la informaci@'on asociada a todas las funciones cuyos tiempos de ejecuci@'on se quiere monitorizar.

La matriz devuelta por @code{timer_info} incluye los nombres de las funciones, tiempo de ejecuci@'on en cada llamada, n@'umero de veces que ha sido llamada, tiempo total de ejecuci@'on y tiempo consumido en la recolecci@'on de basura, @code{gctime} (del ingl@'es, "garbage collection time") en la versi@'on original de Macsyma, aunque ahora toma el valor constante cero.

Los datos con los que @code{timer_info} construye su respuesta pueden obtenerse tambi@'en con la funci@'on @code{get}:

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

V@'ease tambi@'en @code{timer}.

@end deffn


@deffn {Funci@'on} trace (@var{f_1}, ..., @var{f_n})
@deffnx {Funci@'on} trace ()

Dadas las funciones @var{f_1}, ..., @var{f_n}, @code{trace} imprime informaci@'on sobre depuraci@'on cada vez que estas funciones son llamadas; @code{trace(f)$ trace(g)$} coloca de forma acumulativa a @code{f} y luego a @code{g} en la lista de funciones a ser rastradas.

Si no se suministran argumentos, @code{trace} devuelve una lista con todas las funciones a ser rastreadas.

La funci@'on @code{untrace} desactiva el rastreo. V@'ease tambi@'en @code{trace_options}.

La funci@'on @code{trace} no eval@'ua sus argumentos, de forma que @code{f(x) := x^2$ g:f$ trace(g)$} no coloca a @code{f} en la lista de rastreo.

Cuando una funci@'on se redefine es eliminada de la lista de rastreo. As@'{@dotless{i}}, tras  @code{timer(f)$ f(x) := x^2$}, la funci@'on @code{f} dejar@'a de estar en dicha lista.

Si @code{timer (f)} est@'a activado, entonces @code{trace (f)} est@'a desactivado, ya que @code{trace} y @code{timer} no pueden estar ambos activos para la misma funci@'on.

@end deffn

@deffn {Funci@'on} trace_options (@var{f}, @var{option_1}, ..., @var{option_n})
@deffnx {Funci@'on} trace_options (@var{f})

Establece las opciones de rastreo para la funci@'on @var{f}. Cualquier otra opci@'on previamente especificada queda reemplazada por las nuevas. La ejecuci@'on de @code{trace_options (@var{f}, ...)} no tiene ning@'un efecto, a menos que se haya invocado previamente a @code{trace (@var{f})} (es indiferente que esta invocaci@'on sea anterior o posterior a @code{trace_options}). 

@code{trace_options (@var{f})} inicializa todas las opciones a sus valores por defecto.

Las claves de opciones son:

@itemize @bullet
@item
@code{noprint}:
No se imprime mensaje alguno ni a la entrada ni a la salida de la funci@'on.
@item
@code{break}:
Coloca un punto de referencia antes de que la funci@'on comience a ejecutarse y otro despu@'es de que termine su ejecuci@'on. V@'ease @code{break}.
@item
@code{lisp_print}:
Muestra los argumentos y valores retornados como objetos de Lisp.
@item
@code{info}:
Imprime @code{-> true} tanto a la entrada como a la salida de la funci@'on.
@item
@code{errorcatch}:
Detecta errores, otorgando la posibilidad de marcar un error, reintentar la llamada a la funci@'on o especificar un valor de retorno.
@end itemize

Las opciones de rastreo se especifican de dos formas. La @'unica presencia de la clave de opci@'on ya activa la opci@'on. (N@'otese que la opci@'on @var{foo} no se activa mediante @code{@var{foo}: true} u otra forma similar; se tendr@'a en cuenta tambi@'en que las claves no necesitan ir precedidas del ap@'ostrofo.) Especificando la clave de opci@'on junto con una funci@'on de predicado se hace que la opci@'on quede condicionada al predicado.

La lista de argumentos para las funciones de predicado es siempre @code{[level, direction, function, item]} donde @code{level} es el nivel de recursi@'on para la funci@'on,  @code{direction} puede ser tanto @code{enter} como @code{exit}, @code{function} es el nombre de la funci@'on  y @code{item} es la lista de argumentos (a la entrada) o el valor de retorno (a la salida).

A continuaci@'on un ejemplo de opciones de rastreo no condicionales:

@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

Para la misma funci@'on, con la opci@'on @code{break} condicionada a un 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 {Funci@'on} untrace (@var{f_1}, ..., @var{f_n})
@deffnx {Funci@'on} untrace ()
Dadas las funciones @var{f_1}, ..., @var{f_n},
@code{untrace} desactiva el rastreo previamente activado por la funci@'on @code{trace}. Si no se aportan argumentos, @code{untrace} desactiva el rastreo de todas las funciones.

La llamada a @code{untrace} devuelve una lista con las funciones para las que el rastreo se ha desactivado.

@end deffn