ess-tracebug


Tracing and debugging R code in ESS.

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

Labels:
Debug ESS R emacs Traceback Statistics recover debugging trace