From d596474af03d2eba2986af5588fc66a817cdc747 Mon Sep 17 00:00:00 2001 From: Phil Sainty Date: Sat, 23 Jul 2022 21:14:24 +1200 Subject: [PATCH] WIP: Add a 'tracing' section to the elisp manual debugging node --- doc/lispref/debugging.texi | 152 +++++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi index 9fbf3a69f09..afb4e4cbd71 100644 --- a/doc/lispref/debugging.texi +++ b/doc/lispref/debugging.texi @@ -1074,3 +1074,155 @@ the @command{gprof} utility. This feature is mainly useful for debugging Emacs. It actually stops the Lisp-level @kbd{M-x profiler-@dots{}} commands described above from working. @end ifnottex + + +@node Tracing +@section Tracing +@cindex tracing +@cindex trace +@cindex trace function +@cindex trace functions + +You can trace the execution of functions using the tracing facilities +provided by the @file{trace.el} package. Many functions may be traced +at the same time. The functions @code{trace-function-foreground} and +@code{trace-function-background} add a new trace to a single specified +function. The functions @code{trace-package}, @code{trace-regexp}, +and @code{trace-library} enable traces to be added to multiple +functions in bulk. Calls to traced functions, including the values +of their arguments, are logged to the @file{*trace-output*} buffer +(or another buffer as specified). + +In addition, you can call @code{trace-values} in your code to output +the values of its arguments to the trace buffer, to provide more trace +information than is provided by the function calls alone. + +@deffn Command trace-function-foreground function &optional buffer context +This function adds a foreground trace to @var{function}. When called +interactively, it prompts for @var{function} in the minibuffer. With +a prefix argument, also prompt for the trace output @var{buffer} +(defaulting to the value of @var{trace-buffer}), and a Lisp expression +@var{context}. When called from Lisp, @var{context} should be a +function of no arguments which returns a value to insert into +@var{buffer} during the trace. + +Tracing a function causes every call to that function to insert into +@var{buffer} Lisp-style trace messages that display the function's +arguments and return values. It also evaluates @var{context}, if that +is non-nil, and inserts its value too. For example, you can use this +to track the current buffer, or position of point. + +This function creates @var{buffer} if it does not exist. This buffer +will popup whenever FUNCTION is called. Do not use this function to +trace functions that switch buffers, or do any other display-oriented +stuff - use `trace-function-background' instead. + +Calling `trace-function-foreground' again for the same FUNCTION will +update the optional argument behaviours to respect the new values. +@end defun + +@deffn Command trace-function-background function &optional buffer context +This function adds a background trace to @var{function}. This is like +@code{trace-function-foreground}, but without popping up the output +buffer or changing the window configuration. +@end defun + +@deffn Command trace-package prefix &optional after-load buffer context +This function calls @code{trace-function-background} for all functions +with names starting with @var{prefix}. + +For any autoload declarations matching @var{prefix}, the associated +function will be traced if and when it is defined. + +With a prefix argument, also prompt for the optional arguments. If +AFTER-LOAD is non-nil then re-process @var{prefix} after loading any +file. See `trace-function-foreground' for details of @var{buffer} and +@var{context}, and of foreground vs background tracing. + +Calling `trace-package' again for the same @var{prefix} will update +the optional argument behaviours to respect the new values. +@end defun + +@deffn Command trace-regexp regexp &optional after-load buffer context +This function calls @code{trace-function-background} for all functions +matching in @var{regexp}. + +Warning: Do not attempt to trace all functions. Tracing too many +functions at one time will render Emacs unusable. + +Background tracing is used. Switch to the trace output buffer to view +the results. For any autoload declarations matching @var{regexp}, the +associated function will be traced if and when it is defined. + +With a prefix argument, also prompt for the optional arguments. If +AFTER-LOAD is non-nil then re-process @var{regexp} after loading any +file. See `trace-function-foreground' for details of @var{buffer} and +@var{context}, and of foreground vs background tracing. + +Calling `trace-regexp' again for the same @var{regexp} will update the +optional argument behaviours to respect the new values. +@end defun + +@deffn Command trace-library library &optional after-load buffer context +This function calls @code{trace-function-background} for all functions +defined in @var{library}. + +For any autoload declarations with a file name matching @var{library}, +the associated function will be traced if and when it is defined. +(Autoload file names will not match if @var{library} specifies a +longer, more specific path.) + +With a prefix argument, also prompt for the optional arguments. If +AFTER-LOAD is non-nil then re-process @var{library} after loading it +\(ensuring that all of its functions will be traced). See +`trace-function-foreground' for details of @var{buffer} and +@var{context}, and of foreground vs background tracing. + +Calling `trace-library' again for the same @var{library} will update +the optional argument behaviours to respect the new values. +@end defun + +@deffn Command trace-currently-traced &optional display-message +This function returns the list of currently traced function symbols. +When called interactively, or if @var{display-message} is non-nil, it +displays the list as a message. +@end defun + +@deffn Command untrace-function function +This function removes the trace on @var{function}. When called +interactively, it prompts for @var{function} in the minibuffer. +Calling @code{untrace-function} has no effect if @var{function} is not +currently traced. +@end defun + +@deffn Command untrace-package prefix +This function calls @code{untrace-function} for all functions with +names starting with @var{prefix}. When called interactively, it +prompts for @var{prefix} in the minibuffer. +@end defun + +@deffn Command untrace-regexp regexp +This function calls @code{untrace-function} for all functions matching +@var{regexp}. When called interactively, it prompts for @var{regexp} +in the minibuffer. +@end defun + +@deffn Command untrace-library library +This function calls @code{untrace-function} for all functions defined +in @var{library}. When called interactively, it prompts for +@var{library} in the minibuffer. +@end defun + +@deffn Command untrace-all +This function calls @code{untrace-function} for all functions. +@end defun + +@deffn Function trace-values &rest values +This function inserts a message showing @var{values} into the trace +buffer. You can add explicit calls to @code{trace-values} into your +functions in order to provide additional tracing information. +@end defun + +@defvar Variable inhibit-trace +If non-nil, all tracing is inhibited. +@end defvar -- 2.39.5