2023-01-06 17:18:20 +03:00
# Enso Language Support for NetBeans, Ideal Graph Visualizer & VSCode
2022-06-23 07:43:49 +03:00
[](https://github.com/enso-org/enso/actions/workflows/enso4igv.yml)
[Enso language ](http://enso.org ) runtime engine is built on top of
[GraalVM ](http://graalvm.org ) 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.
## Installation
Visit [GraalVM.org ](http://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:
```bash
$ unzip idealgraphvisualizer-22.1.0.zip
$ ./idealgraphvisualizer/bin/idealgraphvisualizer --userdir /tmp/emptyuserdir
```
launches 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 ](https://github.com/enso-org/enso/actions/workflows/enso4igv.yml )
is installed. Login to GitHub, follow the
[GitHub actions link ](https://github.com/enso-org/enso/actions/workflows/enso4igv.yml )
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 ](http://netbeans.apache.org ) 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.
## Using the IGV
2022-11-15 10:05:53 +03:00
Build an instance of the Enso runtime engine (see
[Running Enso ](../../docs/CONTRIBUTING.md#running-enso )) using:
```bash
enso$ sbt buildEngineDistribution
```
and then launch it with special `--dump-graphs` option:
2022-06-23 07:43:49 +03:00
```bash
enso$ ./built-distribution/enso-engine-0.0.0-dev-linux-amd64/enso-0.0.0-dev/bin/enso --dump-graphs --run yourprogram.enso
```
2022-11-23 17:30:48 +03:00
When executed on [GraalVM 22.3.0 ](http://graalvm.org ) these options instruct the
2022-06-23 07:43:49 +03:00
_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_.
#### Sieve of Eratosthenes Example
As an example you can download
[sieve.enso ](https://github.com/jtulach/sieve/blob/5b32450da35415322e683bb9769aa45f0d71f1df/enso/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:
```bash
enso$ ./built-distribution/enso-engine-0.0.0-dev-linux-amd64/enso-0.0.0-dev/bin/enso --dump-graphs --run sieve.enso
```
Bunch of files in `graal_dumps/*` subdirectory is going to be generated:
```bash
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 > ].bgv
```
2022-11-15 10:05:53 +03:00
Let'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
2022-12-30 08:30:32 +03:00
engine sources with `sbt buildEngineDistribution` . Once the IGV opens the
`runtime` & co. projects, it allows smooth navigation among the sources
2022-11-15 10:05:53 +03:00
With such setup let's open graph for one of the top-most functions:
`TruffleHotSpotCompilation*Primes*next*.bgv` . Choose compilation phase _"Before
lowering"_:
2022-06-23 07:43:49 +03:00
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
2022-11-15 10:05:53 +03:00
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_ :
2022-06-23 07:43:49 +03:00
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.
## Building
The plugin can be rebuilt using [Apache Maven ](http://maven.apache.org ). The
build is platform independent. The following instructions are for Unix like
environment. Switch to this directory and invoke:
```bash
enso/tools/enso4igv$ mvn clean install
enso/tools/enso4igv$ ls target/*.nbm
2022-12-30 08:30:32 +03:00
target/enso4igv-*-SNAPSHOT.nbm
2022-06-23 07:43:49 +03:00
```
an NBM file is generated which can be installed into IGV, NetBeans or any other
NetBeans based application.
2023-01-06 17:18:20 +03:00
## Building VSCode Extension
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.
