From e865a85b43caa6f453304e836dae3b62ca73c635 Mon Sep 17 00:00:00 2001 From: dos-reis Date: Sat, 18 Apr 2009 06:11:42 +0000 Subject: Fix SF/2757715 * Makefile.pamphlet (all-input): Make all-doc a requirement. (all-doc): Tidy. * doc/Makefile.in: Likewise. Install help files. * doc/help: New. Home for help files. --- src/doc/help/trace.help | 224 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 224 insertions(+) create mode 100644 src/doc/help/trace.help (limited to 'src/doc/help/trace.help') diff --git a/src/doc/help/trace.help b/src/doc/help/trace.help new file mode 100644 index 00000000..d12e3d03 --- /dev/null +++ b/src/doc/help/trace.help @@ -0,0 +1,224 @@ +Copyright The Numerical Algorithms Group Limited 1992-94. All rights reserved. +Copyright (C) 2007-2009, Gabriel Dos Reis. All rights reserved. + +OpenAxiom Help Information. +Section numbers refer to the on-line version of the book +AXIOM: The Scientific Computation System by Richard D. Jenks and Robert S. Sutor + +============================================================================== +A.26. )trace +============================================================================== + +User Level Required: interpreter + +Command Syntax: + + - )trace + - )trace )off + + - )trace function [options] + - )trace constructor [options] + - )trace domainOrPackage [options] + +where options can be one or more of + + - )after S-expression + - )before S-expression + - )break after + - )break before + - )cond S-expression + - )count + - )count n + - )depth n + - )local op1 [... opN] + - )nonquietly + - )nt + - )off + - )only listOfDataToDisplay + - )ops + - )ops op1 [... opN ] + - )restore + - )stats + - )stats reset + - )timer + - )varbreak + - )varbreak var1 [... varN ] + - )vars + - )vars var1 [... varN ] + - )within executingFunction + +Command Description: + +This command is used to trace the execution of functions that make up the +OpenAxiom system, functions defined by users, and functions from the system +library. Almost all options are available for each type of function but +exceptions will be noted below. + +To list all functions, constructors, domains and packages that are traced, +simply issue + +)trace + +To untrace everything that is traced, issue + +)trace )off + +When a function is traced, the default system action is to display the +arguments to the function and the return value when the function is exited. +Note that if a function is left via an action such as a THROW, no return +value will be displayed. Also, optimization of tail recursion may decrease +the number of times a function is actually invoked and so may cause less +trace information to be displayed. Other information can be displayed or +collected when a function is traced and this is controlled by the various +options. Most options will be of interest only to OpenAxiom system developers. If +a domain or package is traced, the default action is to trace all functions +exported. + +Individual interpreter, lisp or boot functions can be traced by listing their +names after )trace. Any options that are present must follow the functions to +be traced. + +)trace f + +traces the function f. To untrace f, issue + +)trace f )off + +Note that if a function name contains a special character, it will be +necessary to escape the character with an underscore + +)trace _/D_,1 + +To trace all domains or packages that are or will be created from a +particular constructor, give the constructor name or abbreviation after +)trace. + +)trace MATRIX +)trace List Integer + +The first command traces all domains currently instantiated with Matrix. If +additional domains are instantiated with this constructor (for example, if +you have used Matrix(Integer) and Matrix(Float)), they will be automatically +traced. The second command traces List(Integer). It is possible to trace +individual functions in a domain or package. See the )ops option below. + +The following are the general options for the )trace command. + + )break after + causes a Lisp break loop to be entered after exiting the traced function. + + )break before + causes a Lisp break loop to be entered before entering the traced + function. + + )break + is the same as )break before. + + )count + causes the system to keep a count of the number of times the traced + function is entered. The total can be displayed with )trace )stats and + cleared with )trace )stats reset. + + )count n + causes information about the traced function to be displayed for the + first n executions. After the nth execution, the function is untraced. + + )depth n + causes trace information to be shown for only n levels of recursion of + the traced function. The command + + )trace fib )depth 10 + + will cause the display of only 10 levels of trace information for the + recursive execution of a user function fib. + + )math + causes the function arguments and return value to be displayed in the + OpenAxiom monospace two-dimensional math format. + + )nonquietly + causes the display of additional messages when a function is traced. + + )nt + This suppresses all normal trace information. This option is useful if + the )count or )timer options are used and you are interested in the + statistics but not the function calling information. + + )off + causes untracing of all or specific functions. Without an argument, all + functions, constructors, domains and packages are untraced. Otherwise, + the given functions and other objects are untraced. To immediately + retrace the untraced functions, issue )trace )restore. + + )only listOfDataToDisplay + causes only specific trace information to be shown. The items are listed + by using the following abbreviations: + + a display all arguments + v display return value + 1 display first argument + 2 display second argument + 15 display the 15th argument, and so on + + )restore + causes the last untraced functions to be retraced. If additional options + are present, they are added to those previously in effect. + + )stats + causes the display of statistics collected by the use of the )count and + )timer options. + + )stats reset + resets to 0 the statistics collected by the use of the )count and )timer + options. + + )timer + causes the system to keep a count of execution times for the traced + function. The total can be displayed with )trace )stats and cleared with + )trace )stats reset. + + )varbreak var1 [... varN] + causes a Lisp break loop to be entered after the assignment to any of the + listed variables in the traced function. + + )vars + causes the display of the value of any variable after it is assigned in + the traced function. Note that library code must have been compiled (see + description of command )compile ) using the )vartrace option in order to + support this option. + + )vars var1 [... varN] + causes the display of the value of any of the specified variables after + they are assigned in the traced function. Note that library code must + have been compiled (see description of command )compile ) using the + )vartrace option in order to support this option. + + )within executingFunction + causes the display of trace information only if the traced function is + called when the given executingFunction is running. + +The following are the options for tracing constructors, domains and packages. + + )local [op1 [... opN]] + causes local functions of the constructor to be traced. Note that to + untrace an individual local function, you must use the fully qualified + internal name, using the escape character _ before the semicolon. + + )trace FRAC )local + )trace FRAC_;cancelGcd )off + + )ops op1 [... opN] + By default, all operations from a domain or package are traced when the + domain or package is traced. This option allows you to specify that only + particular operations should be traced. The command + + )trace Integer )ops min max _+ _- + + traces four operations from the domain Integer. Since + and - are special + characters, it is necessary to escape them with an underscore. + +Also See: +o )boot +o )lisp +o )ltrace + -- cgit v1.2.3