Read the documentation in "documentation/debugging.md" in FastR's GitHub repository.
Read the documentation in *documentation/debugging.md* in FastR's GitHub repository.
In order to suppress annoying stack traces when you (accidentally) enter values in the variables view, start FastR with option `--J @-Dtruffle.nbdebug.supressLangErrs=true`.
@@ -18,19 +18,7 @@ binSearch(1:100, 101) # why does this not stop
Set a line breakpoint in function binSearch, step through the loop iterations and find the problem.
## Advanced Debugging
### Inspecting Promises
Promises are in particular difficult to handle during debugging.
The maxime of debugging is to not modify the program as it could change its behavior and make any debugging difficult.
However, this means that you will often not be able to inspect a promise until it is too late since a promise is evaluated at the time it is used.
FastR allows to inspect promises in the variables view.
Every promise (pointed out as type "promise" in the view) has three fields: `value`, `isEvaluated`, and `isEager`
If `isEager` is `true`, then you will immediately see the value of the promise. An eager promise is a special kind where FastR eagerly evaluated the value for performance reasons.
In this case it is safe to have the value already available without changing the semantics of the program.
If *isEager* is *false*, then *isEvaluated* will initially also be *false* and *value* will be *NULL*.
### Debugging Packages 1
## Debugging Packages 1
Packages are usually loaded lazily from a binary file containing the serialized code and data of the package.
Therefore, you can usually only install a function breakpoint to package code.
However, FastR keeps the package source such that you can set a line breakpoint in the package's source files.
...
...
@@ -42,20 +30,23 @@ Determine the path where packages are installed:
To demonstrate this, start FastR in debug mode and attach the NetBeans debugger.
Then enter `.libPaths()` to determine where your R packages are installed.
For example, let's debug package *jsonlite* (so, if you haven't installed it, do so by typing `install.packages("jsonlite")`).
This tutorial assumes *jsonlite* in version 1.5.
Go to the installation directory from package *jsonlite* and open the file *jsonlite/R/toJSON.R*.
Set a line breakpoint at line 32 which calls the generic `asJSON` function.
Now, run our script *dump.r* using `source("R/dump.r")`.
As soon as the debugging cursor stops at the line breakpoint, step into the call of function *asJSON* to find out which of the concrete implementations is actually executed.
### Debugging Packages 2
## Debugging Packages 2
For some reason, it may be that packages do not have source code available.
Then, setting a line breakpoint is not straigt forward.
In this case installing line breakpoints is not straigt forward.
Therefore, FastR provides a facility to query the source of an R function.
As in GnuR, if the source is not available for the function, the function's body is deparsed and a string representation is generated.
FastR then generates a temporary source file containing the deparsed source code.
This temporary source file can be queried using function `.fastr.srcinfo`.
It turns out that the subexpression does not have any attributes.
The reason is that FastR does not create source reference attributes in the parser because the source information is stored differently.
## Inspecting Promises
Promises are in particular difficult to handle during debugging.
The maxime of debugging is to not modify the program as it could change its behavior and make any debugging difficult.
However, this means that you will often not be able to inspect a promise until it is too late since a promise is evaluated at the time it is used.
FastR allows to inspect promises in the variables view.
Every promise (a function parameter) has three fields: `value`, `isEvaluated`, and `isEager`
If `isEager` is `true`, then you will immediately see the value of the promise. An eager promise is a special kind where FastR eagerly evaluated the value for performance reasons.
In this case it is safe to have the value already available without changing the semantics of the program.
If `isEager` is `FALSE`, then `isEvaluated` will initially also be `FALSE` and `value` will be `NULL`.
As soon as the executed function uses the parameter, the promise will be evaluated and `isEvaluated` becomes `TRUE`.
Since the function may never use the value, it is possible to inspect the promise's value by manually setting `isEvaluated` to `TRUE` in the variables view.
The promise is now evaluated and its value can be inspected.
In order to reset the promise to its state before, you can simply set `isEvaluated` to `FALSE` again.
## GraalVM-featured
FastR is part of the Graal/Truffle world and it is therefore easily possible to write R applications that interact with other programming languages like Java.
FastR has its dedicated Java interoperability API that allows to create and use Java objects.
The NetBeans debugger is also capable of stepping over language boundaries.
To demonstrate this:
### Preparation
1. Download GraalVM from [Oracle Technology Network (OTN)](http://www.oracle.com/technetwork/oracle-labs/program-languages/downloads/index.html) and extract the archive.
2. Open NetBeans and add GraalVM as Java Platform:
1. Tools -> Java Platforms
...
...
@@ -106,6 +112,15 @@ To demonstrate this:
3. Open the NetBeans project *InteropDebugging* and ensure that it uses __GraalVM JDK__ as platform:
1. Right click on the project and select *Properties*.
2. Select *Libraries* and choose __GraalVM JDK__ in the dropdown menu labeled with *Java Platform:*.
4. To be able to build the project, ensure that the library *truffle-api.jar* is imported correctly.
* The easiest way is to copy or link the wohle GraalVM into the project's root folder using the folder name `graalvm`.
* Otherwise:
1. Right click on the project and select *Properties*.
2. Then select entry *Libraries*, select the *Compile* tab and look for *Classpath*.
3. Click on *...* and add file *graalvm/lib/truffle/truffle-api.jar*, where *graalvm* is the folder where you extracted the downloaded GraalVM into.
5. Clean and build project *InteropDebugging*.
### Inter-language Debugging
File `Main.java` creates a `PolyglotEngine` object that can execute R code. This is basically the FastR engine.
The engine object can now run R code by creating a source object (representing R code) and submitting the source to the engine.
