
ess-tracebug
An emacs package for interactive debugging and error tracing for ESS.
From ESS v12.02 ess-tracebug is part of ESS. This repository is kept for documentation only.
Activation
From ESS13.05 tracebug is on by default. To deactivate use either M-x
ess-tracebug
or put the following into your .emacs:
(setq ess-use-tracebug nil)
Keys
Tracebug commands are all on ess-dev-map
(C-c C-t). During the debugging
ess-debug-minor-mode-map
is active.
```
Breakpoints (`ess-dev-map'):
b . Set BP (repeat to cycle BP type) .
ess-bp-set'* B . Set conditional BP .
ess-bp-set-conditional' k . Kill BP .ess-bp-kil' K . Kill all BPs .
ess-bp-kill-all' o . Toggle BP state .ess-bp-toggle-state' l . Set logger BP .
ess-bp-set-logger' n . Goto next BP .ess-bp-next' p . Goto previous BP .
ess-bp-previous'(C- prefixed equivalents are also defined)
Debugging (`ess-dev-map'):
. Show traceback .
ess-show-traceback' (also on C-c) ~ . Show callstack .
ess-show-call-stack' (also on C-c ~) e . Toggle error action (repeat to cycle).ess-debug-toggle-error-action'* d . Flag for debugging .
ess-debug-flag-for-debugging' u . Unflag for debugging .ess-debug-unflag-for-debugging' w . Watch window .
ess-watch'(C- prefixed equivalents are also defined)
Interactive Debugging (`ess-debug-minor-mode-map'):
M-C . Continue .
ess-debug-command-continue' M-C-C . Continue multi .
ess-debug-command-continue-multi' M-N . Next step .ess-debug-command-next' M-C-N . Next step multi .
ess-debug-command-next-multi' M-U . Up frame .ess-debug-command-up' M-Q . Quit debugging .
ess-debug-command-quit'Navigation to errors (general emacs functionality):
C-x
, M-g n .
next-error' M-g p . `previous-error'
```
Error Tracing
Navigation
Ess-tracebug provides compilation-like functionality in inferior-ess buffer. The errors with location references are highlighted like this:
https://ess-tracebug.googlecode.com/svn/trunk/img/error_in_iess.png' width='500'>
To navigate between errors, you can use usual binding for next/previous-error
("M-g n" , "M-g p"). Error navigation scope is limited to the most recent
errors located between the last user input mark (indicated by the small arrow)
and the end of buffer:
Often ESS eval commands result in a long series of errors, but only the first being the most relevant one. Now you can quickly find the first error by locating the fringe arrow.
When files are sourced with incomplete file names (source("my_file.R")
), R
reports only the file name in the error references. Ess-traceback reconstructs
the whole path by using the current directory associated with the current
buffer. Usually this is not a problem because all the project files are in the
same directory.
To make ess-tracebug aware of different directories, customize the variable
ess-tracebug-search-path
:
(setq ess-tracebug-search-path '("~/projects/R/project_A" "~/projects/R/project_B"))
Traceback Buffer
Whenever the traceback is available in R (usually immediately after the error
occurred) the ``C-c ``` displays *ess-traceback*
compilation-like buffer:
https://ess-tracebug.googlecode.com/svn/trunk/img/ess_traceback.png' width='500'>
You might want simple keys bound for navigation in ess-traceback
buffer:
(define-key compilation-minor-mode-map [(?n)] 'next-error-no-select)
(define-key compilation-minor-mode-map [(?p)] 'previous-error-no-select)
Visual Debugger #
For the visual debugging you need to set the breakpoints in your source file and
source it either interactively with `C-c C-l` key, or directly with `source()`
command.
Evaluation of functions (`C-c C-c`, `M-C-x`, `C-c C-f`) also automatically
inserts source references.
## Breakpoints ##
* "b" 'ess-bp-set `*` _(set/toggle the breakpoint at point)_
* "o" 'ess-bp-toggle-state `*` _(toggle between active/inactive states of the closest breackpoint in the **visible** part of the buffer)_
* "k" 'ess-bp-kill _(remove the closest bp in the **visible** area of the buffer)_
* "K" 'ess-bp-kill-all _(removes all the bps in the buffer)_
* "n/" 'ess-bp-next _(navigate to next bp)_
* "p" 'ess-bp-previous _(navigate to previous bp)_
`ess-bp-set` is an single-key command and multiple invocation of "b" key
cycles through the breakpoint types defined in
`ess-bp-type-spec-alist`. Currently only `browser()` and `recover()` types
are defined. The `recover` breakpoint is useful whenever you want to examine
the call stack.
See the documentation for `ess-bp-type-spec-alist` for more
details. Available fringe bitmaps are in the variable `fringe-bitmaps`.
`C-c C-t o` toggles the active state of the breakpoint, i.e. comment it out.
Here is a sample of breakpoint types so far discussed (`browser`, `recover`, `commented browser` and the custom `my-browser`):
>
Conditional Breakpoints ##
Use 'C-c C-t B' to set the conditional breackpoint:
>
Loggers ##
* "l" ess-bp-set-logger
Loggers are like breakpoints but don't break the execution. They log the
returned value of the watched expressions (see [Watch](#Watch_Window.md)) into
the variable (a list) with the user provided name:
>
Debugging ##
Ess-tracebug automatically detects when the R session enters the debugger and
turns ess-debug-minor-mode
on. This makes the commands in ess-debug-minor-mode-map
active:
- M-C . Continue . `ess-debug-command-continue'
- M-C-C . Continue multi . `ess-debug-command-continue-multi'
- M-N . Next step . `ess-debug-command-next'
- M-C-N . Next step multi . `ess-debug-command-next-multi'
- M-U . Up frame . `ess-debug-command-up'
- M-Q . Quit debugging . `ess-debug-command-quit'
Ess-tracebug also detects when the session enters the "recover" state. Pressing
a digit produces the same effect as typing it in the terminal followed by
RET. Also for convenience, "q","c" and "n" have the same effect as "0" - not to
interrupt the debugging flow when the recover breackpoint is used.
Flag/Unflag for Debugging
- "d" 'ess-debug-flag-for-debugging
- "u" 'ess-debug-unflag-for-debugging
Ess-tracebug uses http://www.emacswiki.org/emacs/InteractivelyDoThings'>IDO
mechanism (if available) to provide the user with the on the fly debugging
and undebugging of functions and methods.
Debug
'C-c C-t d' asks the user for the function to debug:
If the selected function is a generic, the signature of the method is requested as well:
The following usual http://www.emacswiki.org/emacs/InteractivelyDoThings'>IDO keys are available in the mini-buffer:
- 'C-s'/'C-r' to cycle forward/backward through completions
- 'C-space' to restrict the subsequent search (for example 'mat C-space def' displays all the functions with mat and def in their names)
Library Matrix has a number of methods and S4 classes defined. Load it and play with the methods
library(Matrix)
Undebug
To unflag the debugged function or traced methods use 'C-c C-t u':
Watch Window
- "w" 'ess-watch
In the watch window you can monitor any valid R expression:
Start with 'C-c C-t w' to see all available commands in the watch window.
a
: append new expression
i
: insert new expression
k
: kill
e
: edit the expression
r
: rename
n/p
: navigate
u/U
: move the expression up/down
q
: kill the buffer
The text in the watch window is scaled down by 'text-scale-mode-step'
times 'ess-watch-scale-amount'
. Customize the latter to adjust the display
size of the text. The default is '-1'.
(setq ess-watch-scale-amount -2)
Whenever the watch buffer already exists, it is displayed during the
debugging. To prohibit the display, quit the watch ("q") or just kill the
buffer. Note what watched expressions are not lost. They are registered in
the R session and will be available on the next invocation of 'C-c C-t w'.
By default ess-tracebug tries to split the R process window reasonably. You
can control that behavior by customizing 'ess-watch-height-threshold' and
'ess-watch-width-threshold'. See the documentation for those variables.
On-error Actions
- "e" 'ess-debug-toggle-error-action
When ess-tracebug is turned on, mode line for the current process is changed
into (iESS [R db - ]
, where "-" is an indicator of an "on-error" action,
and can be by default one of:
"-" (none - the default behavior),
"t" (traceback) or
"r" (recover).
To switch between on-error states press 'C-c C-t e', and keep pressing 'e'
till the desired action is set.
You can add your own custom on-error actions to the ess-debug-error-action-alist
. See also R documentation for options(error=)
.
Project Information
- License: GNU GPL v2
- 6 stars
- svn-based source control
Labels:
Debug
ESS
R
emacs
Traceback
Statistics
recover
debugging
trace