Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/manuelhentschel/vscode-r-debugger

R Debugger Extension for Visual Studio Code
https://github.com/manuelhentschel/vscode-r-debugger

debugger r vscode

Last synced: 5 days ago
JSON representation

R Debugger Extension for Visual Studio Code

Awesome Lists containing this project

README 

        
# R Debugger



This extension adds debugging capabilities for the

[R](https://www.r-project.org/)

programming language to Visual Studio Code

and depends on the R package [vscDebugger](https://github.com/ManuelHentschel/vscDebugger)

([documentation](https://manuelhentschel.github.io/vscDebugger/)).

For further R support in VS Code see [vscode-R](https://github.com/Ikuyadeu/vscode-R).



## Features



![features.png](images/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](https://marketplace.visualstudio.com/items?itemName=RDebugger.r-debugger).

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](https://manuelhentschel.r-universe.dev),

the source code on [GitHub](https://GitHub.com/ManuelHentschel/vscDebugger),

and a [GitHub Release](https://github.com/ManuelHentschel/VSCode-R-Debugger/releases)

(in that order).

You can also install the package manually using

```r

# 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](https://github.com/ManuelHentschel/VSCode-R-Debugger/releases).



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](https://github.com/ManuelHentschel/VSCode-R-Debugger/actions?query=workflow%3Amain).



## Using the Debugger

### Launch Mode

* Press F5 and select `R Debugger` as debugger. With the default launch configuration, the debugger will start a new R session.

* To run a file, focus the file in the editor and press F5 (or the continue button in the debug controls)

* Output will be printed to the debug console,

expressions entered into the debug console are evaluated in the currently active frame

* During debugging in the global workspace it is often necessary to click the dummy frame

in the callstack labelled 'Global Workspace' to see the variables in `.GlobalEnv`.



### Attach Mode

* Start R in a terminal

* Load `library(vscDebugger)`

* Call `.vsc.listen()`

* Start the debugger with launch configuration including `"request":"attach"`, e.g.:

``` json

{

    "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](https://manuelhentschel.github.io/vscDebugger/articles/configuration.html).



## 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:



* An R process is started inside a child process

* The R package `vscDebugger` is loaded.

* The Debugger starts and controls R programs by sending input to stdin of the child process

* After each step, function call etc., the debugger calls functions from the package `vscDebugger` to get info about the stack/variables



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



* Information sent by functions from `vscDebugger` is encoded as json and sent via a TCP socket.

These lines are parsed by the VS Code extension and not shown to the user.

* Information printed by the `browser()` function is parsed and used to update the source file/line highlighted inside VS Code.

These lines are also hidden from the user.

* Everything else is printed to the debug console



## 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 package must be installed from source code (not CRAN or `.tar.gz`)

* The flag `--with-keep.source` should be set

* Extensions containing C code might cause problems.

Sometimes it helps to install the package using

`devtools::install(quick=FALSE, ...)`

to compile the binaries and again with

`devtools::install(quick=TRUE, ...)`

to retain the source information.



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

```jsonc

"debuggedPackages": ["MyPackage"],

...

```



To overwrite the `print`/`cat`/`message` functions for an individual package,

they need to be explicitly assigned somewhere in the package:

``` r

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](https://manuelhentschel.github.io/vscDebugger/articles/troubleshooting.html)



## Contributing

This package is still under development.

If you have problems, suggestions, bug fixes etc. feel free to open an

[issue](https://github.com/ManuelHentschel/VSCode-R-Debugger/issues)

or submit a pull request.

Any feedback or support is appreciated!

Special thanks to

[@tdeenes](https://github.com/tdeenes)

for providing the C code used in the R package, and

[@renkun-ken](https://github.com/renkun-ken)

for his numerous contributions and feedback!