From 4616e3d0cb10641126cdb982d68facd7f1a07802 Mon Sep 17 00:00:00 2001 From: Florian Angerer <florian.angerer@oracle.com> Date: Thu, 1 Jun 2017 17:23:20 +0200 Subject: [PATCH] Added readme for using the NB debugger with FastR. --- documentation/Index.md | 2 ++ documentation/debugging.md | 48 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+) create mode 100644 documentation/debugging.md diff --git a/documentation/Index.md b/documentation/Index.md index 4b1d8167ed..c98e248efe 100644 --- a/documentation/Index.md +++ b/documentation/Index.md @@ -5,3 +5,5 @@ [Limitations](Limitations.md) [For Developers](dev/Index.md) + +[Debugging](debugging.md) diff --git a/documentation/debugging.md b/documentation/debugging.md new file mode 100644 index 0000000000..8122a7f342 --- /dev/null +++ b/documentation/debugging.md @@ -0,0 +1,48 @@ +# Introduction + +Since FastR is implemented atop the Truffle framework, it also supports debugging of applications using NetBeans. +This is a very convenient and more powerful way for debugging compared to R's browser function. + +This section describes how to debug R applications using NetBeans. + +# Pre-Requisites + +* A recent NetBeans IDE (e.g. nightly build). +* The _Truffle Debugging Support_ Plugin for NetBeans. + Install this by starting NetBeans and selecting `Tools > Plugins > Available Plugins > Truffle Debugging Support` + +# Using the NetBeans Debugger + +1. Start NetBeans and install a breakpoint. + Unfortunately, NetBeans does currently not have a suitable R source code editor. + But you can define a breakpoint as you would do for JavaScript. + Open the _Breakpoints_ view: `Window > Debugging > Breakpoints` + Then, create a new breakpoint. + Specify `Debugger: JavaScript` and `Breakpoint Type: Line`. + Enter the path to the R source file in field `File` and the line number for the breakpoint. + +2. Start FastR in debugging mode such that a remote debugger can attach. +`bin/R --J @-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000` + +3. Run your application. + There are many ways to run your R application. The simplest one is using `source(file.R)`. + +# Additional Features + +The NetBeans debugger is source-location-based meaning that it assumes every source of an applicates resides somehwere in a source file. +However, R applications often run deserialized code or the code is created somehow else. + +In order to be still able to use the NetBeans debugger for such source, you first need to generate a temporary source file using a FastR builtin function. + +For example, assume we want to debug function `print`, first run following command: + `.fastr.srcinfo(print)` + +It will output something similar to + `[1] "/tmp/deparse/print-fca37561e0.r#1"` +which is the file containing the deparsed source code of `print`. +The generated source file is now associated with function print and a breakpoint can be installed. + +# Disclaimer + +Since FastR is still in its development phase, debugging may not be possible in all cases. + -- GitLab