Enso Integration with Ideal Graph Visualizer

.github/workflows/enso4igv.yml

@@ -0,0 +1,41 @@
+# This workflow will build a Java project with Maven, and cache/restore any dependencies to improve the workflow execution time
+# For more information see: https://help.github.com/actions/language-and-framework-guides/building-and-testing-java-with-maven
+
+name: Enso Language Support for IGV
+
+on:
+  push:
+    branches: [develop]
+  pull_request:
+    branches: [develop]
+  paths:
+    - "tools/enso4igv/**/*"
+
+jobs:
+  build:
+    runs-on: ubuntu-20.04
+    strategy:
+      matrix:
+        java: ["8"]
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Java
+        uses: actions/setup-java@v2
+        with:
+          distribution: "zulu"
+          java-version: ${{ matrix.java }}
+          cache: maven
+
+      - name: Update project version
+        run: |
+          cd tools/enso4igv
+          mvn versions:set -DnewVersion=`mvn -q -DforceStdout help:evaluate -Dexpression=project.version | cut -f1 -d -`.$GITHUB_RUN_NUMBER
+
+      - name: Build with Maven
+        run: mvn -B package --file tools/enso4igv/pom.xml
+      - name: Archive NBM file
+        uses: actions/upload-artifact@v3
+        with:
+          name: Enso IGV Plugin
+          path: tools/enso4igv/target/*.nbm

tools/enso4igv/README.md

@@ -0,0 +1,133 @@
+# Enso Language Support for NetBeans & Ideal Graph Visualizer
+
+[![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
+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_.
+
+## Installation
+
+Visit [GraalVM.org](http://graalvm.org) download page and continue towards
+_enterprise edition_ option. There is an _Ideal Graph Visualizer_ option. After
+clicking thru 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_.
+
+Now download
+[Enso Language Support module](https://github.com/enso-org/enso/actions/workflows/enso4igv.yml).
+Follow the
+[GitHub actions link](https://github.com/enso-org/enso/actions/workflows/enso4igv.yml)
+and select a build (usually 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_ and install the NBM
+file.
+
+![Tools/Plugins/Downloaded](docs/tools_plugins_downloaded.png)
+
+Proceed by clicking _Install_. You may be asked to download _TextMate Lexer_ - a
+necessary dependency of the _Enso support_ module. Continue thru the wizard to
+_finish_ the installation.
+
+![Tools/Plugins/Downloaded](docs/installer.png)
+
+## Using the IGV
+
+Get an instance of the Enso runtime engine (see
+[Running Enso](../../docs/CONTRIBUTING.md#running-enso)) and then launch it with
+special Java options:
+
+```bash
+enso$ JAVA_OPTS="-Dpolyglot.engine.AllowExperimentalOptions=true\
+ -Dpolyglot.engine.TraceCompilation=true\
+ -Dpolyglot.engine.MultiTier=false\
+ -Dgraal.Dump=Truffle:1"\
+ ./built-distribution/enso-engine-0.0.0-dev-linux-amd64/enso-0.0.0-dev/bin/enso --run yourprogram.enso
+```
+
+When executed on [GraalVM 21.3.0](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$ JAVA_OPTS="-Dpolyglot.engine.AllowExperimentalOptions=true\
+ -Dpolyglot.engine.TraceCompilation=true\
+ -Dpolyglot.engine.MultiTier=false\
+ -Dgraal.Dump=Truffle:1"\
+ ./built-distribution/enso-engine-0.0.0-dev-linux-amd64/enso-0.0.0-dev/bin/enso --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 and let's open graph for one of the
+top-most functions: `TruffleHotSpotCompilation*Primes_next*.bgv`. Choose
+compilation phase _"Before lowering"_:
+
+![Before Lowering Graph](docs/igv_graph.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_:
+
+![Inlining Stacktrace](docs/igv_stacktrace.png)
+
+The stack trace shows what methods of the Enso interpreter and Truffle runtime
+are _"inlined on stack"_ when this node is being compiled. This is all regular
+_IGV_ functionality, but now we can switch to _Enso view_:
+
+![Enso Source](docs/igv_enso.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). Switch
+to this directory and invoke:
+
+```bash
+enso/tools/enso4igv$ mvn clean install
+enso/tools/enso4igv$ ls target/*.nbm
+target/enso4igv-1.0-SNAPSHOT.nbm
+```
+
+an NBM file is generated which can be installed into IGV, NetBeans or any other
+NetBeans based application.

tools/enso4igv/pom.xml

@@ -0,0 +1,111 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <groupId>org.enso.tools</groupId>
+    <artifactId>enso4igv</artifactId>
+    <packaging>nbm</packaging>
+    <name>Enso Language Support for NetBeans &amp; Ideal Graph Visualizer</name>
+    <version>1.0-SNAPSHOT</version>
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.netbeans.utilities</groupId>
+                <artifactId>nbm-maven-plugin</artifactId>
+                <extensions>true</extensions>
+                <version>4.7</version>
+                <configuration>
+                    <useOSGiDependencies>true</useOSGiDependencies>
+                    <author>Enso.org</author>
+                    <licenseName>Apache 2.0</licenseName>
+                    <licenseFile>../../LICENSE</licenseFile>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-jar-plugin</artifactId>
+                <version>3.2.2</version>
+                <configuration>
+                    <archive>
+                        <manifestFile>${project.build.outputDirectory}/META-INF/MANIFEST.MF</manifestFile>
+                    </archive>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+    <dependencies>
+        <dependency>
+            <groupId>org.netbeans.api</groupId>
+            <artifactId>org-netbeans-api-annotations-common</artifactId>
+            <version>${netbeans.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.netbeans.api</groupId>
+            <artifactId>org-netbeans-modules-textmate-lexer</artifactId>
+            <version>${netbeans.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.netbeans.api</groupId>
+            <artifactId>org-netbeans-api-templates</artifactId>
+            <version>${netbeans.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.netbeans.api</groupId>
+            <artifactId>org-openide-filesystems</artifactId>
+            <version>${netbeans.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.netbeans.api</groupId>
+            <artifactId>org-openide-loaders</artifactId>
+            <version>${netbeans.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.netbeans.api</groupId>
+            <artifactId>org-openide-nodes</artifactId>
+            <version>${netbeans.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.netbeans.api</groupId>
+            <artifactId>org-openide-util</artifactId>
+            <version>${netbeans.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.netbeans.api</groupId>
+            <artifactId>org-openide-util-lookup</artifactId>
+            <version>${netbeans.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.netbeans.api</groupId>
+            <artifactId>org-openide-util-ui</artifactId>
+            <version>${netbeans.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.netbeans.api</groupId>
+            <artifactId>org-openide-windows</artifactId>
+            <version>${netbeans.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.netbeans.api</groupId>
+            <artifactId>org-openide-text</artifactId>
+            <version>${netbeans.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.netbeans.api</groupId>
+            <artifactId>org-netbeans-core-multiview</artifactId>
+            <version>${netbeans.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.netbeans.api</groupId>
+            <artifactId>org-openide-awt</artifactId>
+            <version>${netbeans.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.netbeans.api</groupId>
+            <artifactId>org-openide-dialogs</artifactId>
+            <version>${netbeans.version}</version>
+        </dependency>
+    </dependencies>
+    <properties>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <netbeans.version>RELEASE113</netbeans.version>
+    </properties>
+</project>