# High & Low Runtime Debugging This document describes how to debug **everything** - e.g. how to debug the _Java code_ that powers the Enso _engine & interpreter_ as well as Enso standard _libraries Java code_ (used to interact with the operating system via Java APIs). At the same thetime the document describes how to _map that information_ onto the execution of the actual _Enso source code_ being interpreted. ## Debugging Single Source File To analyze what is happening in the interpreter, we often want to debug excecution of a _single Enso file_. Get started by building the _Engine distribution_ built with `sbt buildEngineDistribution` command. Then configure your IDE to understand the _engine Java & Scala sources_ which are mostly located in the [engine subdirectory](https://github.com/enso-org/enso/tree/develop/engine). The sources are known to be understandable by: - VSCode - with [Enso Extension described herein](../../tools/enso4igv/README.md) - IntelliJ - IGV - with [extension described herein](../../tools/enso4igv/IGV.md) - [NetBeans](http://netbeans.apache.org) - with the same [extension as IGV](../../tools/enso4igv/IGV.md) is using There are two ways to start JVM in a debug mode. The first one is fully integrated into the `sbt` build system. It builds the engine (in case there were any changes) and then starts the JVM in debug mode trying to attach to port `5005`: ```sh sbt:enso> runEngineDistribution --debug --run ./test/Tests/src/Data/Numbers_Spec.enso ``` The second options gives one a complete control as it launches everything from a command line. By specifying `JAVA_OPTS` environment variable one influences the special JVM arguments when launching the `bin/enso` from the engine distribution: ```bash enso$ JAVA_OPTS=-agentlib:jdwp=transport=dt_socket,server=n,address=5005 ./built-distribution/enso-engine-*/enso-*/bin/enso --run ./test/Tests/src/Data/Numbers_Spec.enso ``` Both of the approaches launch the JVM in a _debug mode_. Once the JVM is started, simply attach the debugger to the JVM process at the specified port (usually `5005` is used). ### Attaching from VSCode First of all make sure your VSCode contains the [Enso supporting extension](https://marketplace.visualstudio.com/items?itemName=Enso.enso4vscode). Follow the [instructions provided herein](../../tools/enso4igv/README.md) to install everything that's needed. Once the [Enso extension](https://marketplace.visualstudio.com/items?itemName=Enso.enso4vscode) is installed, open the root of Enso repository as workspace and select _"Listen to 5005"_ debug configuration: ![Listen to 5005](https://github.com/enso-org/enso/assets/26887752/1874bcb1-cf8b-4df4-92d8-e7fb57e1b17a) Once the connection with the Enso JVM is made, debug the Java code as usual. ### Mapping Java and Enso Code The _Enso interpreter_ maintains a mapping between its Java code and appropriate _Enso Code_ internally. It shall be no problem to use that information in the debugger. All the mentioned IDEs (alas except IntelliJ) support such _mixed debugging_ of Java and Enso code. Put a breakpoint into `.enso` file and after a while the breakpoint is hit and one can inspect variables, step over the _Enso statements_ and more... ![Breakpoint in Enso](https://github.com/enso-org/enso/assets/26887752/54ae4126-f77a-4463-9647-4dd3a5f83526) ...as one can seamlessly switch to debugging on the Enso interpreter itself! One can place breakpoint into Java class like `PanicException.java` and continue debugging with `F5`: ![Breakpoint in Java](https://github.com/enso-org/enso/assets/26887752/db3fbe4e-3bb3-4d4a-bb2a-b5039f716c85) Should one ever want to jump back from Java to Enso one can use the _"Pause in GraalVM Script"_ action. Select it and continue with `F5` - as soon as the code reaches a statement in Enso, it stops: ![Pause in GraalVM](https://github.com/enso-org/enso/assets/26887752/98eb0bb7-48c2-4208-9d9a-5b8bacc99de2) Similar behavior to _VSCode_ is available in _IGV_ and _NetBeans_. Understanding both the _engine Java code_ as well as _Enso Code_ shall be pretty simple with these tools. For example _NetBeans_ offers _Toggle Pause in GraalVM Script_ button in the toolbar: ![NetBeans Debugger](https://user-images.githubusercontent.com/26887752/209614191-b0513635-819b-4c64-a6f9-9823b90a1513.png) and your execution shall stop on the next `.enso` line of code. These advanced developer tools allow one to debug both - the _Enso code_ as well as _Java code_. The stack traces shows a _mixture of Java and Enso stack frames_ by default. Right-clicking on the thread allows one to switch to plain Java view (with a way more stack frames) and back. Analyzing low level details as well as Enso developer point of view shall be simple with such tool. ### Tips and Tricks (for poor IntelliJ users) Finding the mapping of the Enso source code to the engine's Java code in _IntelliJ_ isn't easy. Trying to find out how to debug a specific expression is way more tricky than in case of _VSCode_, _IGV_ or _NetBeans_. However, if you really want to stick with _IntelliJ_ as your only tool, following steps may help you to skip all the irrelevant code and get to the code you are interested in: - To get the mapping to Enso source code, evaluate the following expression in the Java debugger: `this.getRootNode().getSourceSection()`. Note that this, obviously, works only when the debugger is stopped in some Truffle node code. - To debug a method called `foo`, put a breakpoint in `org.enso.interpreter.node.ClosureRootNode#execute` with a condition on `this.name.contains("foo")` - To debug a specific expression, put some _unique_ expression, like `Debug.eval "1+1"`, in front of it and put a breakpoint in a Truffle node corresponding to that unique expression, in this case that is `org.enso.interpreter.node.expression.builtin.debug.DebugEvalNode`. ## Debugging annotation processors The Engine uses annotation processors to generate some of the Java code, e.g., the builtin methods with `org.enso.interpreter.dsl.MethodProcessor`, or JMH benchmark sources with `org.enso.benchmarks.processor.BenchProcessor`. Annotation processors are invoked by the Java compiler (`javac`), therefore, we need special instructions to attach the debugger to them. Let's debug `org.enso.interpreter.dsl.MethodProcessor` as an example. The following are the commands invoked in the `sbt` shell: - `project runtime` - `clean` - Delete all the compiled class files along with all the generated sources by the annotation processor. This ensures that the annotation processor will be invoked. - `set javacOptions += FrgaalJavaCompiler.debugArg` - This sets a special flag that is passed to the frgaal Java compiler, which in turn waits for the debugger to attach. Note that this setting is not persisted and will be reset once the project is reloaded. - `compile` - Launches the Java compiler, which will wait for the debugger to attach. Put a breakpoint in some class of `org.enso.interpreter.dsl` package. Wait for the message in the console instructing to attach the debugger. - To reset the `javacOptions` setting, either run `set javacOptions -= FrgaalJavaCompiler.debugArg`, or reload the project with `reload`.