Home

Awesome

R Debugger

This extension adds debugging capabilities for the R programming language to Visual Studio Code and depends on the R package vscDebugger (documentation). For further R support in VS Code see vscode-R.

Features

features.png

The debugger includes the following features:

  1. Run and debug R Code by launching a new R process or attaching to a running one.
  2. View scopes and variables of the currently selected stack frame. For many variables it is also possible to assign a new value to the variable or individual entries/attributes in this view.
  3. Add watch expressions that are evaluated in the selected stack frame on each breakpoint/step.
  4. View and browse through the call stack when execution is paused.
  5. Set breakpoints and break on errors.
  6. Control the program flow using step, step in, step out, continue.
  7. Output generated by the program is printed to the debug console (filtering out text printed by the browser itself).
  8. The debugger adds a modified version of print, cat, message, and str that also print a link to the file and line where the text was printed.
  9. The debug console allows the execution of arbitrary R code in the currently selected stack frame.

Installation

The latest version of the VS Code extension can be installed from the marketplace. After installing the extension, the R package can be installed or updated using the command r.debugger.installOrUpdateRPackage. If your R path is neither in the Windows registry nor the PATH environment variable, make sure to provide a valid path to the R executable in the setting r.rpath.xxx.

If the package installation does not work, the command r.debugger.installRPackage will attempt to install from a release on r-universe.dev, the source code on GitHub, and a GitHub Release (in that order). You can also install the package manually using

# OPTION 1: From r-universe.dev:
install.packages("vscDebugger", repos = "https://manuelhentschel.r-universe.dev")

# OPTION 2: From source code on GitHub:
remotes::install_github("ManuelHentschel/vscDebugger")

or from artifacts on the releases site.

If you want to install a development version of the extension, it can be installed from the .vsix-files found in the artifacts of the GitHub Actions Workflows.

Using the Debugger

Launch Mode

Attach Mode

{
    "type": "R-Debugger",
    "request": "attach",
    "name": "Attach to R process"
}

Configuration

For a detailed explanation of possible launch config entries and other settings, see Configuration.

Encoding issues on windows

Due to some changes in v0.5.0 concerning the communication between this extension and the R package vscDebugger, combined with the way non-utf-8 encodings are handled in R, there might be some problems with this extension on Windows. However, as of R-version 4.2.2, R can handle UTF-8 encoded communication on Windows much better. To avoid these issues, it is recommended to update R to at least v4.2.2 and use the latest version of this extension and the related R package.

How it works

The debugger works as follows:

The output of the R process is read and parsed as follows:

Debugging R Packages

Packages can now be debugged using load_all from pkgload. To do so, it is required to install pkgload (part of devtools). By default, load_all will be masked by a modified version that automatically sets breakpoints in the loaded package and attaches the modified versions of print, cat, message. To always load a package when launching a debug session, you can specify an array of paths in the launch config entry "loadPackages". This is done (for the currently opened package) in the example debug config "Debug R-Package".

Packages with a more complicated installation that might not be compatible with load_all can also be debugged. For this to work, the proper source information must be retained during the installation of the package (check attr(attr(FUNCTION_NAME, 'srcref'), 'srcfile') for some function from the package):

The packages that are being debugged then need to be specified in the launch config as follows:

"debuggedPackages": ["MyPackage"],
...

To overwrite the print/cat/message functions for an individual package, they need to be explicitly assigned somewhere in the package:

print <- print
cat <- cat
message <- message

This assignment can be overwritten by the debugger with .vsc.print/.vsc.cat/.vsc.message, but has no effect when not using the debugger.

Troubleshooting

For troubleshooting info, see Troubleshooting

Contributing

This package is still under development. If you have problems, suggestions, bug fixes etc. feel free to open an issue or submit a pull request. Any feedback or support is appreciated! Special thanks to @tdeenes for providing the C code used in the R package, and @renkun-ken for his numerous contributions and feedback!