mirror of
https://github.com/enso-org/enso.git
synced 2024-12-24 15:22:01 +03:00
5f44e209b8
Adds icon and rewords the main readme file for the Enso VSCode extension. # Important Notes 
153 lines
7.2 KiB
Markdown
153 lines
7.2 KiB
Markdown
# Enso Language Support for Ideal Graph Visualizer & NetBeans
|
|
|
|
[](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
|
|
|
|
Build an instance of the Enso runtime engine (see
|
|
[Running Enso](../../docs/CONTRIBUTING.md#running-enso)) using and then launch
|
|
it with special `--dump-graphs` option:
|
|
|
|
```bash
|
|
enso$ sbt runEngineDistribution --dump-graphs --run yourprogram.enso
|
|
```
|
|
|
|
When executed on [GraalVM 22.3.1](http://graalvm.org) 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_.
|
|
|
|
#### 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
|
|
```
|
|
|
|
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
|
|
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.
|
|
|
|
## 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
|
|
target/enso4igv-*-SNAPSHOT.nbm
|
|
```
|
|
|
|
an NBM file is generated which can be installed into IGV, NetBeans or any other
|
|
NetBeans based application.
|
|
|
|
## VSCode Extension
|
|
|
|
There is also a VSCode extension for Enso. Read more about the extension
|
|
[here](README.md).
|