mirror of
https://github.com/enso-org/enso.git
synced 2024-12-23 21:12:44 +03:00
f0de43a970
Working on compiler IR is a daunting task. I have therefore added a new system property `enso.compiler.dumpIr` that will help with that. It dumps the encountered IRs to `ir-dumps` directory in the [GraphViz](www.graphviz.org) format. More info in updated docs. Note that all the functionality to dump IRs to `dot` files was already implemented. This PR just adds the command line option and updates docs. # Important Notes - `--dump-graphs` cmd line option is removed as per [Jaroslav's request](https://github.com/enso-org/enso/pull/10740#pullrequestreview-2216676140). - To dump graphs, use `-Dgraal.Dump=Truffle:2` system property passed via `JAVA_OPTS` env var. If you run `env JAVA_OPTS='-Denso.compiler.dumpIr=true' enso --run tmp.enso` where `tmp.enso` is, e.g.: ``` from Standard.Base import all main = 42 ``` You will then have something like: ``` $ ls ir-dumps Standard.Base.Data.Filter_Condition.dot Standard.Base.Data.Time.dot Standard.Base.System.Advanced.dot Standard.Base.Warning.dot Standard.Base.Data.Locale.dot Standard.Base.Enso_Cloud.Enso_File.dot Standard.Base.System.File.Advanced.dot tmp.dot Standard.Base.Data.Numeric.dot Standard.Base.Errors.dot Standard.Base.System.File.dot Standard.Base.Data.Numeric.Internal.dot Standard.Base.Network.HTTP.Internal.dot Standard.Base.System.File.Generic.dot Standard.Base.Data.Text.Regex.Internal.dot Standard.Base.Runtime.dot Standard.Base.System.Internal.dot ``` You can then visualize any of these with `dot -Tsvg -O ir-dumps/tmp.dot`. An example how that could look like is 
158 lines
7.6 KiB
Markdown
158 lines
7.6 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_](https://www.graalvm.org/jdk22/tools/igv/) -
|
|
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's IGV page](https://www.graalvm.org/jdk22/tools/igv/) to read and
|
|
download _IGV_. Or follow
|
|
[this link](https://lafo.ssw.uni-linz.ac.at/pub/idealgraphvisualizer/idealgraphvisualizer-0.31-cb98bbf5fef-all.zip)
|
|
to get ZIP with the most up to date version of _Ideal Graph Visualizer_ (as of
|
|
June 2024). Then:
|
|
|
|
```bash
|
|
$ unzip idealgraphvisualizer-*.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 the following system properties:
|
|
|
|
```bash
|
|
enso$ env JAVA_OPTS='-Dgraal.Dump=Truffle:2 -Dgraal.PrintGraph=File' ./built-distribution/enso-engine-0.0.0-dev-linux-amd64/enso-0.0.0-dev/bin/enso --run yourprogram.enso
|
|
```
|
|
|
|
See
|
|
[Graal system props docs](https://github.com/oracle/graal/blob/master/compiler/docs/Debugging.md#jvmci-and-compiler-specific-options)
|
|
for the description of the `graal` system properties.
|
|
|
|
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:
|
|
|
|
```bash
|
|
enso$ env JAVA_OPTS='-Dgraal.Dump=Truffle:2 -Dgraal.PrintGraph=File' ./built-distribution/enso-engine-0.0.0-dev-linux-amd64/enso-0.0.0-dev/bin/enso --run yourprogram.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).
|