Enso language runtime engine is built on top of GraalVM and its Truffle framework. Enso, as a good citizen of the GraalVM ecosystem, benefits from polyglot capabilities of GraalVM as well as its rich tooling offering. One of such tools is IGV - the Ideal Graph Visualizer - an excellent tool to get insights into behavior of Graal compiler.
This document shows how to use IGV with the Enso language. The command line instructions format is Unix oriented. Use instructions appropriate for your operating system to perform the same on different OS. IGV itself as well as the Enso language support are platform neutral with launch scripts for all major operating systems.
Visit GraalVM.org download page and continue towards
enterprise edition option. There is an Ideal Graph Visualizer option. After
clicking through the confirmation dialogs you should get a ZIP - I've just got
idealgraphvisualizer-22.1.0.zip and then:
$ unzip idealgraphvisualizer-22.1.0.zip
$ ./idealgraphvisualizer/bin/idealgraphvisualizer --userdir /tmp/emptyuserdirlaunches the IGV application. One doesn't have to use the --userdir option,
but doing so ensures the newly running IGV process is isolated from any
settings left around by previous usage of IGV.
IGV understands Enso when
Enso Language Support module
is installed. Login to GitHub, follow the
GitHub actions link
and select a build. Unless you have some special needs choose the latest one.
The build summary page provides various information as well as list of artifacts
at the bottom. Download the Enso IGV Plugin ZIP file (make sure you are logged
into GitHub - artifacts are only available to those logged in). Unzip it and get
enso*.nbm file. This file can be installed into IGV (or any other
NetBeans based application). Go to
Tools/Plugins/Downloaded/Add Plugins and select the NBM file.
Proceed by clicking Install. You may be asked to download TextMate Lexer - a necessary dependency of the Enso support module. Continue through the wizard to finish the installation.
Build an instance of the Enso runtime engine (see Running Enso) using:
enso$ sbt buildEngineDistributionand then launch it with special --dump-graphs option:
enso$ ./built-distribution/enso-engine-0.0.0-dev-linux-amd64/enso-0.0.0-dev/bin/enso --dump-graphs --run yourprogram.ensoWhen executed on GraalVM 22.3.0 these options instruct the
Graal/Truffle compiler to dump files into graal_dumps/_sometimestamp_
directory. Generating these files takes a while - make sure yourprogram.enso
runs long enough for the system to warmup, compile the code and run at full
speed.
As an example you can download
sieve.enso
which computes hundred thousand of prime numbers repeatedly and measures time of
each round. Download the file and launch Enso with --dump-graphs argument:
enso$ ./built-distribution/enso-engine-0.0.0-dev-linux-amd64/enso-0.0.0-dev/bin/enso --dump-graphs --run sieve.ensoBunch of files in graal_dumps/* subdirectory is going to be generated:
enso$ ls graal_dumps/*/Truffle* | tail -n5
graal_dumps/2022.06.20.06.18.21.733/TruffleHotSpotCompilation-9889[argument<2>].bgv
graal_dumps/2022.06.20.06.18.21.733/TruffleHotSpotCompilation-9896[IfThenElseMethodGen@3af870b9_<split-62b6b4f3>]_1.bgv
graal_dumps/2022.06.20.06.18.21.733/TruffleHotSpotCompilation-9896[IfThenElseMethodGen@3af870b9_<split-62b6b4f3>].bgv
graal_dumps/2022.06.20.06.18.21.733/TruffleHotSpotCompilation-9935[Primes.next_<split-717d5bdf>]_1.bgv
graal_dumps/2022.06.20.06.18.21.733/TruffleHotSpotCompilation-9935[Primes.next_<split-717d5bdf>].bgvLet's launch IGV with Enso integration. Locate the engine/runtime directory
and open it as "project" in IGV:
The project directories (not only runtime, but also other like
runtime-language-epb, etc.) are recognized only if you have built the Enso
engine sources with sbt buildEngineDistribution. Once the IGV opens the
runtime & co. projects, it allows smooth navigation among the sources
With such setup let's open graph for one of the top-most functions:
TruffleHotSpotCompilation*Primes*next*.bgv. Choose compilation phase "Before
lowering":
Now you can inspect the compiler graphs the regular IGV way. Let's locate
for example LoadField#FunctionSchema.isFullyApplied node and let's check how
it got inlined(you can use search box in the top-right corner)
The stack trace shows what methods of the Enso interpreter and Truffle runtime
are "inlined on stack" when this node is being compiled. However thanks to
integration with engine/runtime sources one can directly jump to the sources
of the interpreter that represent certain graph nodes:
Not only that, but one we can also switch to Enso view:
By choosing the Enso language icon in front of the stack trace combo, the
source code of our .enso program is opened and we can analyze what compiler
nodes refer to what lines in the our Enso program. Click Navigate to Source
icon in the Stack View to get from graph node to source. Select a drop down
widget in the editor toolbar to show you what compiler nodes as associated with
currently selected line.
The plugin can be rebuilt using Apache Maven. The build is platform independent. The following instructions are for Unix like environment. Switch to this directory and invoke:
enso/tools/enso4igv$ mvn clean install
enso/tools/enso4igv$ ls target/*.nbm
target/enso4igv-*-SNAPSHOT.nbman NBM file is generated which can be installed into IGV, NetBeans or any other NetBeans based application.
One can package the same plugin into a VSCode extension and obtain Enso syntax
coloring as well as support for editing engine/runtime sources in VSCode.
Just invoke:
enso/tools/enso4igv$ npm install
enso/tools/enso4igv$ npm run vsix
enso/tools/enso4igv$ ls *.vsix
enso4vscode-*.vsix
one needs to have npm, Java and mvn available to successfully build the
VSCode extension. Alternatively one can use Maven to built the VSIX extension
via mvn clean install -Pvsix.
Once the .vsix file is created, it can be installed into VSCode. Select
Extension perspective and choose Install from VSIX... menu item.