You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: readme.md
+41-48Lines changed: 41 additions & 48 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,8 @@
1
1
# R Debugger
2
2
3
3
This extension adds debugging capabilities for the R programming language to Visual Studio Code.
4
+
This extension depends on the R package [vscDebugger](https://github.com/ManuelHentschel/vscDebugger).
5
+
For further R support see e.g. [vscode-R](https://github.com/Ikuyadeu/vscode-R).
4
6
5
7
## Using the Debugger
6
8
* Install the **R Debugger** extension in VS Code.
@@ -16,10 +18,8 @@ in the callstack labelled 'Global Workspace' to see the variables in `.GlobalEnv
16
18
*For Windows users: If your R installation is from [CRAN](http://cran.r-project.org/mirrors.html) with default installation settings, especially **Save version number in registry** is enabled, then there's no need to specify `rdebugger.rterm.windows`.*
17
19
18
20
## Installation
19
-
The VS code extension can be run from source by opening the project repo's root directory in vscode and pressing F5.
20
-
21
-
Alternatively the VS Code extension can be installed form the .vsix-file found on https://github.com/ManuelHentschel/VSCode-R-Debugger/actions?query=workflow%3Amain.
22
-
To download the correct file, filter the commits by branch (develop or master), click the latest commit,
21
+
The VS Code extension can be installed from the .vsix-file found on https://github.com/ManuelHentschel/VSCode-R-Debugger/actions?query=workflow%3Amain.
22
+
To download the correct file, filter the commits by branch (develop or master), select the latest commit,
23
23
and download the file `r-debugger.vsix` under the caption "Artifacts".
To install from the master branch, omit the argument `ref`.
31
31
32
-
33
32
**Warning:** Currently there is no proper versioning/dependency system in place, so make sure to download both packages/extensions from the same branch (Master/develop) and at the same time.
34
33
35
34
36
35
## Features
37
-
The debugger includes the following features:
38
-
* Controlling the program flow using *step*, *step in*, *step out*, *continue*
39
-
* Breakpoints
40
-
* Information about the stack trace, scopes, variables, and watch expressions in each frame/scope
41
-
* Exception handling (breaks on exception, access to stack info)
42
-
* Evaluation of arbitrary R code in the selected stack frame
43
-
* Overwriting `print()` and `cat()` with modified versions that also print the calling source file and line to the debug console
44
-
* Overwriting `source()` with `.vsc.debugSource()` to allow recursive debugging (i.e. breakpoints in files that are `source()`d from within another file)
45
-
* Supports VS Code's remote development extensions
46
36
37
+
38
+
39
+
The debugger includes the following features:
40
+
1. Run and debug R Code, using one of three debug modes (details see below)
41
+
2. View scopes and variables of the currently selected stack frame.
42
+
The value of most variables can be modified in this view.
43
+
3. Add watch expressions that are evaluated in the selected stack frame on each breakpoint/step.
44
+
4. View and browse through the call stack when execution is pause.
45
+
5. Set breakpoints and break on errors.
46
+
6. Control the program flow using *step*, *step in*, *step out*, *continue*.
47
+
7. Output generated by the program is printed to the debug console (filtering out text printed by the browser itself).
48
+
8. Add a modified version of `print` and `cat` that also prints a link to the file and line where the text was printed.
49
+
9. Allow the execution of arbitrary R code in the currently selected stack frame.
47
50
48
51
## How it works
49
52
The debugger works as follows:
@@ -53,7 +56,7 @@ The debugger works as follows:
53
56
* After each step, function call etc., the debugger calls functions from the package `vscDebugger` to get info about the stack/variables
54
57
55
58
The output of the R process is read and parsed as follows:
56
-
* Information sent by functions from `vscDebugger` is encoded as json and surrounded by keywords (`<v\s\c>...</v\s\c>`).
59
+
* Information sent by functions from `vscDebugger` is encoded as json and sent via a TCP socket.
57
60
These lines are parsed by the VS Code extension and not shown to the user.
58
61
* Information printed by the `browser()` function is parsed and used to update the source file/line highlighted inside VS Code.
59
62
These lines are also hidden from the user.
@@ -67,15 +70,15 @@ The intended usecases for these modes are:
67
70
*`"workspace"`: Starts an R process in the background and sends all input into the debug console to the R process (but indirectly, through `eval()` nested in some helper functions).
68
71
R Files can be run by focussing a file and pressing `F5`.
69
72
The stack view contains a single dummy frame.
70
-
To view the variables in the global environment it is often necessary to click this frame and expand the variables view.
73
+
To view the variables in the global environment it is often necessary to click this frame and expand the variables view!
71
74
This method is 'abusing' the debug adapter protocol to some extent, since the protocol is apparently not designed for ongoing interactive programming in a global workspace.
72
-
*`"file"`: Is pretty much equivalent to launching the debugger with `"workspace"` and then calling `.vsc.debugSource()` on a file.
75
+
*`"file"`: Is pretty much equivalent to launching the debugger with `"workspace"` and immediately calling `.vsc.debugSource()` on a file.
73
76
Is hopefully the behaviour expected by users coming from R Studio etc.
74
77
*`"function"`: The above debug modes introduce significant overhead by passing all input through `eval()` etc.
75
78
and use a custom version of `source()`, which makes changes to the R code in order to set breakpoints.
76
79
To provide a somewhat 'cleaner' method of running code, this debug mode can be used.
77
-
The call to `main()`is entered directly into R's `stdin`, hence there are no additional functions on the call stack (as is the case when entering `main()` into the debug console).
78
-
Breakpoints are set by using R's `trace(..., tracer=browser)` function, which is more robust than the custom breakpoint mechanism.
80
+
The specified file is executed using the default `source` command ad breakpoints are set by using R's `trace(..., tracer=browser)` function, which is more robust than the custom breakpoint mechanism.
81
+
<!-- The call to `main()` is entered directly into R's `stdin`, hence there are no additional functions on the call stack (as is the case when entering `main()` into the debug console). -->
79
82
80
83
The remaining config entries are:
81
84
*`"workingDirectory"`: An absolute path to the desired work directory. Defaults to the workspace folder.
@@ -84,25 +87,30 @@ The remaining config entries are:
84
87
*`"allowGlobalDebugging"`: Whether to keep the R session running after debugging and evaluate expressions from the debug console.
85
88
Essential for debug moge `"workspace"`, recommended for `"file"`, usually not sensible for `"function"`.
86
89
87
-
90
+
## Debugging R Packages
91
+
In principle R packages can also be debugged using this extension.
92
+
For this to work, the proper source information must be retained during installation of the package
I personally do not know a bullet proof way to achieve this, but the following things might help:
95
+
* The package must be installed from source code (not CRAN or `.tar.gz`)
96
+
* The flag `--with-keep.source` should be set
97
+
* Extensions containing C code seem to cause problems sometimes
98
+
99
+
In order to use the modified `print` and `cat` functions,
100
+
import the `vscDebugger` extension in your package,
101
+
assign `print <- vscDebugger::.vsc.print` and `cat <- vscDebugger::.vsc.cat`,
102
+
and deactivate the modified `print`/`cat` statements in the debugger settings.
103
+
Don't forget to remove these assignments after debugging.
88
104
89
105
## Warning
90
-
Since the approach of parsing text output meant for human users is rather error prone, there are probably some cases that are not implemented correctly yet.
91
-
In case of unexpected results, use `browser()` statements and run the code directly from a terminal (or RStudio).
92
-
93
-
In the following cases the debugger might not work correctly:
106
+
In the following cases the debugger might not work correctly/as expected:
94
107
* Calls to `trace()`, `tracingstate()`:
95
108
These are used to implement breakpoints, so usage might interfere with the debugger's breakpoints
96
109
* Calls to `browser()` without `.doTrace()`:
97
-
In normal code, these will be recognized as breakpoints,
98
-
but inside watch-expressions they will cause the debugger to become unresponsive
110
+
Usually, these will be recognized as breakpoints, but they might cause problems in some circumstances (e.g. watch expressions)
99
111
* Custom `options(error=...)`: the debugger uses its own `options(error=...)` to show stack trace etc. on error
100
-
* Any form of (interactive) user input in the terminal during runtime:
101
-
The debugger passes all user input through `eval(...)`, no direct input to stdin is passed to the R process
102
-
* Extensive usage of `cat()` without linebreaks:
103
-
Output parsing relies on parsing complete lines, so any output produced by `cat()` will only be shown after a linebreak.
104
-
Using the option to overwrite `cat()` will show output immediately, but produce a linebreak after each `cat()` call.
105
-
* Output to stdout that looks like output from `browser()`, the input prompt, or text meant for the debugger (e.g. `<v\s\c>...</v\s\c>`)
112
+
* Any form of (interactive) user input in the terminal during runtime (e.g. `readline(stdin())`), since
113
+
the debugger passes all user input through `eval(...)`.
106
114
* Code that contains calls to `sys.calls()`, `sys.frames()`, `attr(..., 'srcref')` etc.:
107
115
Since pretty much all code is evaluated through calls to `eval(...)` these results might be wrong. <!-- This problem might be reduced by using the "functional" debug mode --><!-- (set `debugFunction` to `true` and specify a `mainFunction` in the launch config) -->
108
116
If required, input in the debug console can be sent directly to R's `stdin` by prepending it with `###stdin`.
@@ -113,25 +121,11 @@ It might be possible, however, that the gathering of information about the stack
113
121
Especially watch-expressions must be safe to be evaluated in any frame,
114
122
since these are passed to `eval()` in the currently viewed frame any time the debugger hits a breakpoint or steps through the code.
115
123
116
-
117
-
118
-
## Debugging R Packages
119
-
In principle R packages can also be debugged using this extension.
120
-
Some details need to be considered:
121
-
* The package must be installed from code using `--with-keep.source`
122
-
* The modified `print()` and `cat()` versions are not used by calls from within the package.
123
-
In order to use these, import the `vscDebugger` extension in your package, assign `print <- vscDebugger::.vsc.print` and `cat <- vscDebugger::.vsc.cat`, and deactivate the modified `print`/`cat` statements in the debugger settings.
124
-
Don't forget to remove these assignments after debugging.
125
-
126
-
127
-
## To do
124
+
## Known Issues
128
125
The following topics could be improved/fixed in the future.
129
126
130
127
Variables/Stack view
131
128
* Summarize large lists (min, max, mean, ...)
132
-
* Row-wise display of data.frames, column-wise display of matrices
133
-
* Load large workspaces/lists in chunks (currently hardcoded 1000 items maximum)
134
-
* Enable copying from variables list
135
129
* Refine display of variables (can be customized by `.vsc.addVarInfo`, default config is to be improved)
136
130
137
131
Breakpoints
@@ -147,7 +141,6 @@ General
147
141
Give user more direct access to the R session:
148
142
* Use (visible) integrated terminal instead of background process,
149
143
use `sink(..., split=TRUE)` to simultaneously show stdout to user and the debugger
150
-
* Return results from vscDebugger-Functions via a pipe etc. to keep stdout clean
151
144
* Pipe a copy of stdout to a pseudo-terminal as info for the user
152
145
153
146
If you have problems, suggestions, bug fixes etc. feel free to open an issue at
0 commit comments