enso-org/enso
1
1
Fork 0
mirror of https://github.com/enso-org/enso.git synced 2024-12-21 12:02:27 +03:00
Code Issues Projects Releases Wiki Activity
6ea716f1b3
enso/tools/enso4igv/IGV.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

158 lines
7.6 KiB
Markdown
Raw Normal View History

Icon and documentation for Enso VSCode extension (#8051) Adds icon and rewords the main readme file for the Enso VSCode extension. # Important Notes ![Enso Icon in VSCode](https://github.com/enso-org/enso/assets/26887752/ae1ad4cc-e2ec-4c5b-bca0-c7d7189c6885)
2023-10-15 07:43:26 +03:00
# Enso Language Support for Ideal Graph Visualizer & NetBeans
[![Enso Language Support for IGV](https://github.com/enso-org/enso/actions/workflows/enso4igv.yml/badge.svg)](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
Updating IGV documentation (#10193) Updating IGV documentation. Putting Run and Debug actions into popup menus. Enabling breakpoints in Enso source files.
2024-06-06 19:36:27 +03:00
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.
Icon and documentation for Enso VSCode extension (#8051) Adds icon and rewords the main readme file for the Enso VSCode extension. # Important Notes ![Enso Icon in VSCode](https://github.com/enso-org/enso/assets/26887752/ae1ad4cc-e2ec-4c5b-bca0-c7d7189c6885)
2023-10-15 07:43:26 +03:00
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
Updating IGV documentation (#10193) Updating IGV documentation. Putting Run and Debug actions into popup menus. Enabling breakpoints in Enso source files.
2024-06-06 19:36:27 +03:00
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:
Icon and documentation for Enso VSCode extension (#8051) Adds icon and rewords the main readme file for the Enso VSCode extension. # Important Notes ![Enso Icon in VSCode](https://github.com/enso-org/enso/assets/26887752/ae1ad4cc-e2ec-4c5b-bca0-c7d7189c6885)
2023-10-15 07:43:26 +03:00
```bash
Updating IGV documentation (#10193) Updating IGV documentation. Putting Run and Debug actions into popup menus. Enabling breakpoints in Enso source files.
2024-06-06 19:36:27 +03:00
$ unzip idealgraphvisualizer-*.zip
Icon and documentation for Enso VSCode extension (#8051) Adds icon and rewords the main readme file for the Enso VSCode extension. # Important Notes ![Enso Icon in VSCode](https://github.com/enso-org/enso/assets/26887752/ae1ad4cc-e2ec-4c5b-bca0-c7d7189c6885)
2023-10-15 07:43:26 +03:00
$ ./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.
![Tools/Plugins/Downloaded](https://user-images.githubusercontent.com/26887752/174608153-9f0b54fa-b507-45be-83de-d7911186d121.png)
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.
![Tools/Plugins/Downloaded](https://user-images.githubusercontent.com/26887752/174608219-1faf2728-0045-478b-a297-e3c06f691b19.png)
## Using the IGV
Build an instance of the Enso runtime engine (see
[Running Enso](../../docs/CONTRIBUTING.md#running-enso)) using and then launch
Add org.enso.compiler.dumpIr system prop (#10740) 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 ![image.svg](https://github.com/user-attachments/assets/26ab8415-72cf-46da-bc63-f475e9fa628e)
2024-08-06 15:00:27 +03:00
it the following system properties:
Icon and documentation for Enso VSCode extension (#8051) Adds icon and rewords the main readme file for the Enso VSCode extension. # Important Notes ![Enso Icon in VSCode](https://github.com/enso-org/enso/assets/26887752/ae1ad4cc-e2ec-4c5b-bca0-c7d7189c6885)
2023-10-15 07:43:26 +03:00
```bash
Add org.enso.compiler.dumpIr system prop (#10740) 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 ![image.svg](https://github.com/user-attachments/assets/26ab8415-72cf-46da-bc63-f475e9fa628e)
2024-08-06 15:00:27 +03:00
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
Icon and documentation for Enso VSCode extension (#8051) Adds icon and rewords the main readme file for the Enso VSCode extension. # Important Notes ![Enso Icon in VSCode](https://github.com/enso-org/enso/assets/26887752/ae1ad4cc-e2ec-4c5b-bca0-c7d7189c6885)
2023-10-15 07:43:26 +03:00
```
Add org.enso.compiler.dumpIr system prop (#10740) 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 ![image.svg](https://github.com/user-attachments/assets/26ab8415-72cf-46da-bc63-f475e9fa628e)
2024-08-06 15:00:27 +03:00
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.
Icon and documentation for Enso VSCode extension (#8051) Adds icon and rewords the main readme file for the Enso VSCode extension. # Important Notes ![Enso Icon in VSCode](https://github.com/enso-org/enso/assets/26887752/ae1ad4cc-e2ec-4c5b-bca0-c7d7189c6885)
2023-10-15 07:43:26 +03:00
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
Add org.enso.compiler.dumpIr system prop (#10740) 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 ![image.svg](https://github.com/user-attachments/assets/26ab8415-72cf-46da-bc63-f475e9fa628e)
2024-08-06 15:00:27 +03:00
each round. Download the file and launch Enso with:
Icon and documentation for Enso VSCode extension (#8051) Adds icon and rewords the main readme file for the Enso VSCode extension. # Important Notes ![Enso Icon in VSCode](https://github.com/enso-org/enso/assets/26887752/ae1ad4cc-e2ec-4c5b-bca0-c7d7189c6885)
2023-10-15 07:43:26 +03:00
```bash
Add org.enso.compiler.dumpIr system prop (#10740) 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 ![image.svg](https://github.com/user-attachments/assets/26ab8415-72cf-46da-bc63-f475e9fa628e)
2024-08-06 15:00:27 +03:00
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
Icon and documentation for Enso VSCode extension (#8051) Adds icon and rewords the main readme file for the Enso VSCode extension. # Important Notes ![Enso Icon in VSCode](https://github.com/enso-org/enso/assets/26887752/ae1ad4cc-e2ec-4c5b-bca0-c7d7189c6885)
2023-10-15 07:43:26 +03:00
```
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:
![Open Project in IGV](https://user-images.githubusercontent.com/26887752/201684275-b3ee7a37-7b55-4290-b426-75df0280ba32.png)
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
![IGV Projects view](https://user-images.githubusercontent.com/26887752/209615348-8911af4c-4680-4e61-ac87-19a19738e2ca.png)
With such setup let's open graph for one of the top-most functions:
`TruffleHotSpotCompilation*Primes*next*.bgv`. Choose compilation phase _"Before
lowering"_:
![Before Lowering Graph](https://user-images.githubusercontent.com/26887752/174608397-331a4438-1f12-40b0-9fcd-59eda5e53fb6.png)
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)
![Inlining Stacktrace](https://user-images.githubusercontent.com/26887752/174608478-e7002c43-d746-42c0-b61c-92ceb9d9f124.png)
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:
![Associated Engine Sources](https://user-images.githubusercontent.com/26887752/201688115-4afdb2ac-9a41-4469-8b7b-d7130f74883e.png)
Not only that, but one we can also switch to _Enso view_:
![Enso Source](https://user-images.githubusercontent.com/26887752/174608595-4ce80b00-949a-4b28-84a7-60d5988bfc70.png)
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).
Reference in New Issue Copy Permalink