-
Notifications
You must be signed in to change notification settings - Fork 323
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Icon and documentation for Enso VSCode extension (#8051)
Adds icon and rewords the main readme file for the Enso VSCode extension. # Important Notes 
- Loading branch information
1 parent
f18d132
commit 5f44e20
Showing
7 changed files
with
243 additions
and
209 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,4 +1,5 @@ | ||
| *.vsix | ||
| dist | ||
| nbcode | ||
| !.idea | ||
| .idea/* |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,152 @@ | ||
| # 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). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,155 +1,97 @@ | ||
| # Enso Language Support for NetBeans, Ideal Graph Visualizer & VSCode | ||
| # Enso Language Support for VSCode | ||
|
|
||
| [](https://github.com/enso-org/enso/actions/workflows/enso4igv.yml) | ||
| [](https://github.com/enso-org/enso/actions/workflows/enso4igv.yml) | ||
|
|
||
| Searching for **VSCode** support? Read more about | ||
| [VSCode extension for Enso here](vscode.md). | ||
| ## Downloading | ||
|
|
||
| [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. | ||
| _Enso Tools for VSCode_ is available from | ||
| [VSCode marketplace](https://marketplace.visualstudio.com/items?itemName=Enso.enso4vscode). | ||
| Simply install it from there. | ||
|
|
||
| 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. | ||
| It is possible to download the latest development version of the _"VSCode | ||
| Extension" artifact_ from the | ||
| [latest actions run](https://github.com/enso-org/enso/actions/workflows/enso4igv.yml). | ||
| After downloading the ZIP file unzip a `.vsix` from it and install the `.vsix` | ||
| file into VSCode. | ||
|
|
||
| ## Installation | ||
| Your Enso files will get proper **syntax coloring**. You'll be able to **debug** | ||
| Java/Enso code interchangeably. | ||
|
|
||
| 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: | ||
| After installing the Enso `.vsix` file (and reloading window) we can find | ||
| following two extensions in the system: | ||
|
|
||
| ```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. | ||
| ## Using & Debugging | ||
|
|
||
|  | ||
| Once installation is over let's continue with choosing _File/Open Folder..._ and | ||
| opening root of [Enso Git Repository](http://github.com/enso-org/enso) | ||
| (presumably already built with | ||
| [sbt buildEngineDistribution](https://github.com/enso-org/enso/blob/develop/docs/CONTRIBUTING.md#running-enso)). | ||
| Following set of projects is opened and ready for use: | ||
|
|
||
| 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. | ||
|  | ||
|
|
||
|  | ||
| With the workspace opened, you can open any Enso or Java file. Let's open for | ||
| example `Vector_Spec.enso` - a set of unit tests for `Vector` - a core class of | ||
| Enso standard library: | ||
|
|
||
| ## 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: | ||
| It is now possible to place breakpoints into the `Vector_Spec.enso` file. Let's | ||
| place one on line 120: | ||
|
|
||
| ```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_. | ||
| Let's do a bit of debugging. Select _"Listen to 5005"_ debug configuration: | ||
|
|
||
| #### 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: | ||
| And then just | ||
| [execute the engine distribution](https://github.com/enso-org/enso/blob/develop/docs/CONTRIBUTING.md#running-enso) | ||
| in debug mode: | ||
|
|
||
| ```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 | ||
| sbt:enso> runEngineDistribution --debug --run test/Tests/src/Data/Vector_Spec.enso | ||
| ``` | ||
|
|
||
| Let's launch IGV with Enso integration. Locate the `engine/runtime` directory | ||
| and open it as _"project"_ in IGV: | ||
| After a while the breakpoint is hit and one can inspect variables, step over the | ||
| statements and more... | ||
|
|
||
|  | ||
|  | ||
|
|
||
| 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 | ||
| ...as one can seamlessly switch to debugging on the Enso interpreter itself! One | ||
| can place breakpoint into Java class like `PanicException.java` and continue | ||
| debugging with `F5`: | ||
|
|
||
|  | ||
|  | ||
|
|
||
| With such setup let's open graph for one of the top-most functions: | ||
| `TruffleHotSpotCompilation*Primes*next*.bgv`. Choose compilation phase _"Before | ||
| lowering"_: | ||
| Should one ever want to jump back from Java to Enso one can use the _"Pause in | ||
| GraalVM Script"_ action. Select it and continue with `F5` - as soon as the code | ||
| reaches a statement in Enso, it stops: | ||
|
|
||
|  | ||
|  | ||
|
|
||
| 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) | ||
| ## Building VSCode Extension | ||
|
|
||
|  | ||
| To build this VSCode extension and obtain _Enso_ syntax coloring as well as | ||
| support for editing and debugging of `engine/runtime` sources in **VSCode**: | ||
|
|
||
| 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 | ||
| ``` | ||
| enso/tools/enso4igv$ mvn clean install -Pvsix | ||
| enso/tools/enso4igv$ ls *.vsix | ||
| enso4vscode-*.vsix | ||
| ``` | ||
|
|
||
| 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: | ||
| one needs to have `npm`, Java and `mvn` available to successfully build the | ||
| VSCode extension. | ||
|
|
||
| ```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. | ||
| Once the `.vsix` file is created, it can be installed into VSCode. Select | ||
| _Extension perspective_ and choose _Install from VSIX..._ menu item. | ||
|
|
||
| ## VSCode Extension | ||
| ## Reference | ||
|
|
||
| There is also a VSCode extension for Enso. Read more about the extension | ||
| [here](vscode.md). | ||
| There are extensions for [NetBeans](http://netbeans.apache.org) and also for | ||
| **IGV**. Read more [here](IGV.md). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.