Skip to content

Commit 26cecd9

Browse files
ManuelHentschelManuelHentschel
authored
Merge pull request #66 from ManuelHentschel/develop
Develop
2 parents c010890 + 52f2195 commit 26cecd9

File tree

7 files changed

+176
-131
lines changed

7 files changed

+176
-131
lines changed

‎package.json‎

Lines changed: 14 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,11 @@
7272
"file",
7373
"workspace"
7474
],
75+
"enumDescriptions": [
76+
"Debug a single main-function",
77+
"Run an R file",
78+
"Start an empty R workspace"
79+
],
7580
"description": "Debug a single main-FUNCTION, run an R FILE, or just start an empty R WORKSPACE",
7681
"default": "file"
7782
},
@@ -119,6 +124,14 @@
119124
"type": "boolean",
120125
"default": false,
121126
"description": "Set to true to show package scopes in the variable window."
127+
},
128+
"packagesBeforeLaunch": {
129+
"type": "array",
130+
"items": {
131+
"type": "string"
132+
},
133+
"default": [],
134+
"description": "Packages to be loaded before launching the R script."
122135
}
123136
}
124137
}
@@ -173,25 +186,15 @@
173186
"default": "/usr/bin/R",
174187
"description": "R path for Linux."
175188
},
176-
"rdebugger.useRCommandQueue": {
177-
"type": "boolean",
178-
"default": true,
179-
"description": "Whether to queue R commands and send them only if the R-process is idle."
180-
},
181189
"rdebugger.waitBetweenRCommands": {
182190
"type": "integer",
183-
"default": 10,
191+
"default": 0,
184192
"description": "The time (in ms) to wait between R commands."
185193
},
186194
"rdebugger.startupTimeout": {
187195
"type": "number",
188196
"default": 2000,
189197
"description": "The maximum time in ms that is waited for R to startup"
190-
},
191-
"rdebugger.printEverything": {
192-
"type": "boolean",
193-
"default": false,
194-
"description": "For debugging the debugger: Whether to show everything printed to stdoutor stderr by the child process. Recommended to set debug.console.wordWrap=false"
195198
}
196199
}
197200
}

‎readme.md‎

Lines changed: 101 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,61 @@
11
# R Debugger
22

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).
3+
This extension adds debugging capabilities for the
4+
[R](https://www.r-project.org/)
5+
programming language to Visual Studio Code
6+
and depends on the R package [vscDebugger](https://github.com/ManuelHentschel/vscDebugger).
7+
For further R support in VS Code see e.g. [vscode-R](https://github.com/Ikuyadeu/vscode-R) and [R LSP](https://github.com/REditorSupport/vscode-r-lsp).
68

7-
## Using the Debugger
8-
* Install the **R Debugger** extension in VS Code.
9-
* Install the **vscDebugger** package in R (https://github.com/ManuelHentschel/vscDebugger).
10-
* If your R path is neither in Windows registry nor in `PATH` environment variable, make sure to provide valid R path in `rdebugger.rterm.*`.
11-
* Press F5 and select `R Debugger` as debugger. With the default launch configuration, the debugger will start a new R session.
12-
* To run a file, focus the file in the editor and press F5 (or the continue button in the debug controls)
13-
* Output will be printed to the debug console,
14-
expressions entered into the debug console are evaluated in the currently active frame
15-
* During debugging in the global workspace it is often necessary to click the dummy frame
16-
in the callstack labelled 'Global Workspace' to see the variables in `.GlobalEnv`.
9+
## Features
10+
11+
![features.png](images/features.png)
12+
13+
The debugger includes the following features:
14+
1. Run and debug R Code, using one of three debug modes (for details see below).
15+
2. View scopes and variables of the currently selected stack frame.
16+
For many variables it is also possible to assign a new value to the variable or individual entries/attributes in this view.
17+
3. Add watch expressions that are evaluated in the selected stack frame on each breakpoint/step.
18+
4. View and browse through the call stack when execution is paused.
19+
5. Set breakpoints and break on errors.
20+
6. Control the program flow using *step*, *step in*, *step out*, *continue*.
21+
7. Output generated by the program is printed to the debug console (filtering out text printed by the browser itself).
22+
8. The debugger adds a modified version of `print` and `cat` that also print a link to the file and line where the text was printed.
23+
9. The debug console allows the execution of arbitrary R code in the currently selected stack frame.
1724

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`.*
1925

2026
## Installation
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.
27+
The latest "stable" version of the VS Code extension and the R package can be found on the
28+
[Releases Site](https://github.com/ManuelHentschel/VSCode-R-Debugger/releases).
29+
For compatibility reasons make sure to install both from the same release.
30+
31+
If you want to install a development version, the VS Code extension can be installed from the .vsix-files found
32+
[here](https://github.com/ManuelHentschel/VSCode-R-Debugger/actions?query=workflow%3Amain).
2233
To download the correct file, filter the commits by branch (develop or master), select the latest commit,
2334
and download the file `r-debugger.vsix` under the caption "Artifacts".
24-
25-
26-
To install the latest development version of the required R-package from GitHub, run the following command in R:
35+
To install the latest development version of the required R-package from GitHub, run the following command in R
36+
(to install from the master branch, omit the argument `ref="develop"`):
2737
```r
2838
devtools::install_github("ManuelHentschel/vscDebugger", ref = "develop")
2939
```
30-
To install from the master branch, omit the argument `ref`.
31-
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.
3340

41+
Installing/running from code is a little more involved, but the files `.vscode/tasks.json` and `tsconfig.json` from this repo
42+
as well as `build.R` and `.vscode/tasks.json` from [vscDebugger](https://github.com/ManuelHentschel/vscDebugger)
43+
might be helpful.
3444

35-
## Features
36-
37-
![features.png](images/features.png)
3845

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.
46+
## Using the Debugger
47+
* Install this extension in VS Code.
48+
* Install the package [**vscDebugger**](https://github.com/ManuelHentschel/vscDebugger) in R.
49+
* 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 `rdebugger.rterm.*`.
50+
* Press F5 and select `R Debugger` as debugger. With the default launch configuration, the debugger will start a new R session.
51+
* To run a file, focus the file in the editor and press F5 (or the continue button in the debug controls)
52+
* Output will be printed to the debug console,
53+
expressions entered into the debug console are evaluated in the currently active frame
54+
* During debugging in the global workspace it is often necessary to click the dummy frame
55+
in the callstack labelled 'Global Workspace' to see the variables in `.GlobalEnv`.
5056

51-
## How it works
52-
The debugger works as follows:
53-
* An R process is started inside a child process
54-
* The R package `vscDebugger` is loaded.
55-
* The Debugger starts and controls R programs by sending input to stdin of the child process
56-
* After each step, function call etc., the debugger calls functions from the package `vscDebugger` to get info about the stack/variables
57+
*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`.*
5758

58-
The output of the R process is read and parsed as follows:
59-
* Information sent by functions from `vscDebugger` is encoded as json and sent via a TCP socket.
60-
These lines are parsed by the VS Code extension and not shown to the user.
61-
* Information printed by the `browser()` function is parsed and used to update the source file/line highlighted inside VS Code.
62-
These lines are also hidden from the user.
63-
* Everything else is printed to the debug console
6459

6560
## Launch config
6661
The behaviour of the debugger can be configured with the entry `"debugMode"`,
@@ -78,29 +73,69 @@ Is hopefully the behaviour expected by users coming from R Studio etc.
7873
and use a custom version of `source()`, which makes changes to the R code in order to set breakpoints.
7974
To provide a somewhat 'cleaner' method of running code, this debug mode can be used.
8075
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). -->
8276

8377
The remaining config entries are:
8478
* `"workingDirectory"`: An absolute path to the desired work directory. Defaults to the workspace folder.
8579
* `"file"`: Required for debug modes `"file"` and `"function"`. The file to be debugged/sourced before calling the main function.
8680
* `"mainFunction"`: The name of the main function to be debugged. Must be callable without arguments.
8781
* `"allowGlobalDebugging"`: Whether to keep the R session running after debugging and evaluate expressions from the debug console.
8882
Essential for debug moge `"workspace"`, recommended for `"file"`, usually not sensible for `"function"`.
83+
* `"setBreakpointsInPackages"`: Defaults to `false` for performance reasons.
84+
Set to `true` to debug packages.
85+
* `"includePackageScopes"`: Set to `true` to view the scopes of packages in the variable view.
86+
87+
There is also a number of settings that are managed within R, using `getOption(...)`.
88+
These are not documented yet and might change in the future.
89+
The names of these settings are of the form `vsc.XXXXX` and most are "self-explanatory" booleans.
90+
To get an idea of the available settings you can search the source code for `getOption('vsc.`/`getOption("vsc.`.
91+
Alternatively, don't hesitate to open an issue if you are looking for a particular setting/behaviour.
92+
93+
## How it works
94+
The debugger works as follows:
95+
* An R process is started inside a child process
96+
* The R package `vscDebugger` is loaded.
97+
* The Debugger starts and controls R programs by sending input to stdin of the child process
98+
* After each step, function call etc., the debugger calls functions from the package `vscDebugger` to get info about the stack/variables
99+
100+
The output of the R process is read and parsed as follows:
101+
* Information sent by functions from `vscDebugger` is encoded as json and sent via a TCP socket.
102+
These lines are parsed by the VS Code extension and not shown to the user.
103+
* Information printed by the `browser()` function is parsed and used to update the source file/line highlighted inside VS Code.
104+
These lines are also hidden from the user.
105+
* Everything else is printed to the debug console
106+
89107

90108
## 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
93-
(check `attr(attr(FUNCTION_NAME, 'srcref'), 'srcfile')`).
94-
I personally do not know a bullet proof way to achieve this, but the following things might help:
109+
In general, R packages can also be debugged using this extension.
110+
For this to work, the proper source information must be retained during the installation of the package
111+
(check `attr(attr(FUNCTION_NAME, 'srcref'), 'srcfile')` for some function from the package).
112+
I personally do not know a bulletproof way to achieve this, but the following might help:
95113
* The package must be installed from source code (not CRAN or `.tar.gz`)
96114
* The flag `--with-keep.source` should be set
97115
* Extensions containing C code seem to cause problems sometimes
98116

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.
117+
To set breakpoints, the debug config entry `"setBreakpointsInPackages"` needs to be set to `true`.
118+
If `debugMode=="file"` or `debugMode=="workspace"` it is also necessary to specify the debugged package(s) in the launch config to be loaded before launch, e.g.:
119+
```json
120+
"debugMode": "file",
121+
"setBreakpointsInPackages": true,
122+
"packagesBeforeLaunch": ["MyPackage"],
123+
...
124+
```
125+
126+
The modified `print` and `cat` functions also work if source information is retained during the installation,
127+
but some modifications to the package are necessary.
128+
To use `.vsc.print` and `.vsc.cat` without breaking the package when not using the debugger,
129+
add the following code to the package:
130+
```r
131+
print <- print
132+
cat <- cat
133+
134+
.onLoad <- function(){
135+
try(print <<- vscDebugger::.vsc.print, silent=TRUE)
136+
try(cat <<- vscDebugger::.vsc.cat, silent=TRUE)
137+
}
138+
```
104139

105140
## Warning
106141
In the following cases the debugger might not work correctly/as expected:
@@ -112,38 +147,31 @@ Usually, these will be recognized as breakpoints, but they might cause problems
112147
* Any form of (interactive) user input in the terminal during runtime (e.g. `readline(stdin())`), since
113148
the debugger passes all user input through `eval(...)`.
114149
* Code that contains calls to `sys.calls()`, `sys.frames()`, `attr(..., 'srcref')` etc.:
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) -->
116-
If required, input in the debug console can be sent directly to R's `stdin` by prepending it with `###stdin`.
150+
Since pretty much all code is evaluated through calls to `eval(...)` these results might be wrong.
151+
If required, input in the debug console can be sent directly to R's `stdin` by prepending `###stdin`.
117152
* Any use of graphical output/input, stdio-redirecting, `sink()`
118153
* Extensive use of lazy evaluation, promises, side-effects:
119154
In the general case, the debugger recognizes unevaluated promises and preserves them.
120155
It might be possible, however, that the gathering of information about the stack/variables leads to unexpected side-effects.
121156
Especially watch-expressions must be safe to be evaluated in any frame,
122157
since these are passed to `eval()` in the currently viewed frame any time the debugger hits a breakpoint or steps through the code.
123158

124-
## Known Issues
125-
The following topics could be improved/fixed in the future.
126-
127-
Variables/Stack view
128-
* Summarize large lists (min, max, mean, ...)
129-
* Refine display of variables (can be customized by `.vsc.addVarInfo`, default config is to be improved)
159+
## To Do
160+
The following topics could be improved/fixed in the future:
130161

131-
Breakpoints
132162
* Auto adjustment of breakpoint position to next valid position
133163
* Conditional breakponts, data breakpoints
134164
* Setting of breakpoints during runtime (currently most of these are silently ignored)
135-
136-
General
137-
* Improve error handling
165+
* Improve error handling/argument checks
138166
* Handling graphical output etc.?
139167
* Attach to currently open R process instead of spawning a new one?
140-
141-
Give user more direct access to the R session:
142168
* Use (visible) integrated terminal instead of background process,
143169
use `sink(..., split=TRUE)` to simultaneously show stdout to user and the debugger
144170
* Pipe a copy of stdout to a pseudo-terminal as info for the user
171+
* Improve performance when viewing very large lists/vectors in the variables windows
172+
* Handling parallel computing (currently not looking very promising...)
145173

146-
If you have problems, suggestions, bug fixes etc. feel free to open an issue at
147-
https://github.com/ManuelHentschel/VSCode-R-Debugger/issues
174+
If you have problems, suggestions, bug fixes etc. feel free to open an
175+
[issue](https://github.com/ManuelHentschel/VSCode-R-Debugger/issues)
148176
or submit a pull request.
149177
Any feedback or support is welcome :)

‎src/debugProtocolModifications.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ export interface DebugConfiguration extends VsCode.DebugConfiguration {
3838
// specify how to debug (optional)
3939
includePackageScopes?: boolean;
4040
setBreakpointsInPackages?: boolean;
41+
packagesBeforeLaunch?: string[];
4142
assignToAns?: boolean;
4243
overwritePrint?: boolean;
4344
overwriteCat?: boolean;

0 commit comments

Comments
 (0)