Native Debugging

Since 2025.1.1 version Enso comes with first class support for native image execution mode. Such a mode is fast to start and is thus really suitable for production. In majority of cases it behaves exactly the same as so called --jvm mode used during development. As such there shall not be so much need, to debug the native image itself. Use runtime debugging in the JVM mode where possible. Should JVM debugging not be enough, continue reading.

Building for Debugging

By default the native image execution mode doesn't contain enough information for debugging. The native executable needs to be re-built with such debugging information. Since #12993 rebuilding is as easy as:

bash

enso$ ENSO_LAUNCHER=native,-ls,fast,debug sbt buildEngineDistribution

and then use VSCode with Enso extension to debug enso native executable. Btw. no need for -ls,fast - they just make the build faster.

Enso VSCode Extension

With the Enso extension one can experience following:

The above picture shows what needs to be done in VSCode:

once the debug ready built is finished
switch to "Run and Debug" perspective
select "Launch Native Image" configuration
select an .enso file in editor like Vector_Spec.enso
press F5 to start debugging it

as soon as the output appears
pause the execution
inspect stack and local variables
add breakpoints
step in, step over, step out, continue

Mixed Debugging

Mixed Debugging is usually performed in JVM mode. However with a bit of patience it is possible to do mixed debugging also in Launch Native Image mode with some more manual steps:

modify launch.json to provide polyglot.dap property
Launch Native Image normally while an .enso file is selected
wait for a request to attach DAP debugger being printed in terminal
then start 2nd debugging via Debug Adapter Protocol configuration

One can debug Java via NI debugger and Enso code via the DAP. One just needs to carefully switch between those two debugging sessions in VSCode.