Depuración del código fuente
============================

Maxima es capaz de dar asistencia en la depuración del código fuente. Un usuario puede establecer un punto de referencia dentro del código de una función a partir del cual se siga la ejecución línea a línea. La compliación puede ser posteriormente examinada, conjuntamente con los valores que se han ido asignando a las variables.

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

El punto de referencia se establecerá con la instrucción :br. Ya dentro del depurador, el usuario podrá avanzar una línea de cada vez utilizando la instrucción :n (de ``next'', en inglés). La orden :bt (de ``backtrace'') muestra la lista de la pila. Finalmente, con el comando :r (``resume'') se abandona el depurador continuando con la ejecución. El uso de estas instrucciones se muestra en el siguiente ejemplo.

     (%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ínea
     (foobar.mac 2)
     /tmp/foobar.mac:2::

     (dbm:1) :n                   <-- pulsando :n se avanza otra lí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ón

     (%o2)                                1094

El fichero /tmp/foobar.mac contiene lo siguiente:

     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);

USO DEL DEPURADOR EN EMACS

Si el usuario está corriendo el código bajo GNU emacs en un entorno de texto (dbl shell), o está ejecutando el  entorno gráfico xmaxima, entonces cuando una función pare en el punto de referencia, podrá observar su posición actual en el archivo fuente, el cual será mostrado en la otra mitad de la ventana, bien resaltada en rojo, o con una pequeña flecha apuntando a la línea correcta. El usuario puede avanzar líneas simples tecleando M-n (Alt-n).

Bajo Emacs se debe ejecutar el programa en una ventana de texto dbl, la cual requiere el archivo dbl.el que está en el directorio elisp. El usuario debe instalar los archivos elisp o agregar el directorio elisp de Maxima a la ruta de búsqueda: por ejemplo, se puede añadir lo siguiente al archivo .emacs o al site-init.el

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

entonces en emacs

     M-x dbl

debería abrir una ventana del sistema en la cual se pueden ejecutar programas, por ejemplo Maxima, gcl, gdb, etc.  En esta ventana también se puede ejecutar el depurador, mostrando el código fuente en la otra ventana.

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

Claves de depuración
====================

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

     (%i1) :lisp (+ 2 3)
     5

El número de argumentos depende del comando en particular. Además, tampoco es necesario teclear el nombre completo de la instrucción, tan solo lo justo para diferenciarla de las otras instrucciones. Así, :br sería suficiente para :break.

Las claves de depuración se listan a continuación.

:break F n
     Establece un punto de referencia en la función F en la línea n contando a partir del comienzo de la función. Si F es una cadena, entonces se entiende que se trata de un fichero, siendo entonces n el número de línea a partir del comienzo del fichero. El valor n es opcional; en caso de no ser suministrado, se entenderá que vale cero (primera línea de la función o fichero).

:bt
     Retrocede en la pila.

:continue
     Continua el cómputo de la función.

:delete
     Borra los punto de referencia especificados, o todos si no se especifica ninguno.

:disable
     Deshabilita los puntos de referencia especificados, o todos si no se especifica ninguno.

:enable
     Habilita los puntos de referencia especificados, o todos si no se especifica ninguno.

:frame n
     Imprime el elemento n de la pila, o el actualmente activo si no se especifica ninguno.

:help
     Imprime la ayuda sobre un comando del depurador, o de todos los comandos si no se especifica ninguno.

:info
     Imprime información sobre un elemento.

:lisp expresión
     Evalúa la expresión Lisp.

:lisp-quiet expresión
     Evalúa la expresión Lisp sin devolver el resultado.

:next
     Como :step, excepto que :next se salta las llamadas a funciones.

:quit
     Sale del nivel actual del depurador sin completar el cómputo.

:resume
     Continúa con el cómputo.

:step
     Sigue con el cómputo de la función o fichero hasta que alcance una nueva línea fuente.

:top
     Retorna a Maxima desde cualquier nivel del depurador sin completar el cómputo.

Funciones y variables para depurado
===================================

 -- Variable opcional: refcheck
     Valor por defecto: false

     Cuando refcheck vale true, Maxima imprime un mensaje cada vez que una variable es utilizada por vez primera en un cálculo.

 -- Variable opcional: setcheck
     Valor por defecto: false

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

     La variable setcheck admite también los valores all o true con lo que el informe incluirá todas las variables.

     Cada nueva asignación de setcheck establece una nueva lista de variables a ser monitorizada, de forma que cualquier otra variable previamente asignada a setcheck es olvidada.

     Los nombres asignados a setcheck deben estar precedidos del apóstrofo ' a fin de evitar que las variables sean evaluadas antes de ser almacenadas en setcheck. Por ejemplo, si x, y y z ya guardan algún valor entoces se hará

          setcheck: ['x, 'y, 'z]$

     para colocarlas en la lista de variables a monitorizar.

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

 -- Variable opcional: setcheckbreak
     Valor por defecto: false

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

     Véanse también setcheck y setval.

 -- Variable del sistema: setval

     Guarda el valor que va a ser asignado a una variable cuando setcheckbreak realiza una detención. Entonces se podrá asignarle otro valor pasándoselo previamente a setval.

     Véanse también setcheck y setcheckbreak.

 -- Función: timer (F_1, ..., F_N)
 -- Función: timer (all)
 -- Función: timer ()
     Dadas las funciones F_1, ..., F_N, timer coloca cada una de ellas en la lista de funciones para las cuales se generarán estadísticas relativas al tiempo de cómputo. Así, timer(f)$ timer(g)$ coloca a f y luego a g en dicha lista de forma acumulativa.

     La sentencia timer(all) coloca todas las funciones de usuario (las referenciadas por la variable global functions) en la lista de funciones cuyos tiempos de ejecución se quieren monitorizar.

     Si no se le pasan argumentos a timer se obtendrá la lista de funciones cuyos tiempos de ejecución se quieren monitorizar.

     Maxima almacena la duración del cómputo de cada función de la lista, de forma que timer_info devolverá las estadísticas correspondientes, incluyendo el tiempo medio de cada llamada a la función, el número de llamadas realizadas y el tiempo total transcurrido. La instrucción untimer borra las funciones de la lista.

     La función timer no evalúa sus argumentos, de forma que f(x) := x^2$ g:f$ timer(g)$ no coloca a f en la lista.

     Si trace(f) está activada, entonces timer(f) está desactivada; trace y timer no pueden estar operativas al mismo tiempo.

     Véase también timer_devalue.

 -- Función: untimer (F_1, ..., F_N)
 -- Función: untimer ()
     Dadas las funciones F_1, ..., F_N, untimer las elimina de la lista de funciones cuyos tiempos de ejecución se quiere monitorizar.

     Si no se le suministran argumentos, untimer borra completamente la lista.

     Tras la ejecución de untimer (f), timer_info (f) aún devuelve las estadísticas de tiempo previamente registradas, pero timer_info() (sin argumentos) no devuelve información sobre aquellas funciones que ya no están en la lista. La ejecución de timer (f) inicializa todas las estadísticas a cero y coloca f nuevamente en la lista.

 -- Variable opcional: timer_devalue
     Valor por defecto: false

     Si timer_devalue es igual a true, Maxima le resta a cada función cuyos tiempos de ejecución se quiere monitorizar el tiempo gastado en llamadas a otras funciones presentes también en la lista de monitorización. En caso contrario, los tiempos que se obtienen para cada función incluyen también los consumidos en otras funciones. Nótese que el tiempo consumido en llamadas a otras funciones que no están en la lista de monitorización no se resta del tiempo total.

     Véanse también timer y timer_info.

 -- Función: timer_info (F_1, ..., F_N)
 -- Función: timer_info ()
     Dadas las funciones F_1, ..., F_N, timer_info devuelve una matriz con información relativa a los tiempos de ejecución de cada una de estas funciones. Sin argumentos, timer_info devuelve la información asociada a todas las funciones cuyos tiempos de ejecución se quiere monitorizar.

     La matriz devuelta por timer_info incluye los nombres de las funciones, tiempo de ejecución en cada llamada, número de veces que ha sido llamada, tiempo total de ejecución y tiempo consumido en la recolección de basura, gctime (del inglés, "garbage collection time") en la versión original de Macsyma, aunque ahora toma el valor constante cero.

     Los datos con los que timer_info construye su respuesta pueden obtenerse también con la función get:

          get(f, 'calls);  get(f, 'runtime);  get(f, 'gctime);

     Véase también timer.

 -- Función: trace (F_1, ..., F_N)
 -- Función: trace (all)
 -- Función: trace ()

     Dadas las funciones F_1, ..., F_N, trace imprime información sobre depuración cada vez que estas funciones son llamadas; trace(f)$ trace(g)$ coloca de forma acumulativa a f y luego a g en la lista de funciones a ser rastradas.

     La sentencia trace(all) coloca todas las funciones de usuario (las referenciadas por la variable global functions) en la lista de funciones a ser rastreadas.

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

     La función untrace desactiva el rastreo. Véase también trace_options.

     La función trace no evalúa sus argumentos, de forma que f(x) := x^2$ g:f$ trace(g)$ no coloca a f en la lista de rastreo.

     Cuando una función se redefine es eliminada de la lista de rastreo. Así, tras  timer(f)$ f(x) := x^2$, la función f dejará de estar en dicha lista.

     Si timer (f) está activado, entonces trace (f) está desactivado, ya que trace y timer no pueden estar ambos activos para la misma función.

 -- Función: trace_options (F, OPTION_1, ..., OPTION_N)
 -- Función: trace_options (F)

     Establece las opciones de rastreo para la función F. Cualquier otra opción previamente especificada queda reemplazada por las nuevas. La ejecución de trace_options (F, ...) no tiene ningún efecto, a menos que se haya invocado previamente a trace (F) (es indiferente que esta invocación sea anterior o posterior a trace_options).

     trace_options (F) inicializa todas las opciones a sus valores por defecto.

     Las claves de opciones son:

       * noprint: No se imprime mensaje alguno ni a la entrada ni a la salida de la función.

       * break: Coloca un punto de referencia antes de que la función comience a ejecutarse y otro después de que termine su ejecución. Véase break.

       * lisp_print: Muestra los argumentos y valores retornados como objetos de Lisp.

       * info: Imprime -> true tanto a la entrada como a la salida de la función.

       * errorcatch: Detecta errores, otorgando la posibilidad de marcar un error, reintentar la llamada a la función o especificar un valor de retorno.

     Las opciones de rastreo se especifican de dos formas. La única presencia de la clave de opción ya activa la opción. (Nótese que la opción FOO no se activa mediante FOO: true u otra forma similar; se tendrá en cuenta también que las claves no necesitan ir precedidas del apóstrofo.) Especificando la clave de opción junto con una función de predicado se hace que la opción quede condicionada al predicado.

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

     A continuación un ejemplo de opciones de rastreo no condicionales:

          (%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);

     Para la misma función, con la opción break condicionada a un predicado:

          (%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);

 -- Función: untrace (F_1, ..., F_N)
 -- Función: untrace ()
     Dadas las funciones F_1, ..., F_N, untrace desactiva el rastreo previamente activado por la función trace. Si no se aportan argumentos, untrace desactiva el rastreo de todas las funciones.

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