Downloadable VSCode extension (#7861)

.github/workflows/enso4igv.yml

@@ -1,7 +1,4 @@
-# This workflow will build a Java project with Maven, and cache/restore any dependencies to improve the workflow execution time
+name: Enso Language Support for VSCode, IGV, NetBeans
-# 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:
@@ -30,7 +27,7 @@ jobs:
       - name: Update project version
         working-directory: tools/enso4igv
         run: |
-          mvn versions:set -DnewVersion=`mvn -q -DforceStdout help:evaluate -Dexpression=project.version | cut -f1 -d -`.$GITHUB_RUN_NUMBER
+          mvn versions:set -DnewVersion=`mvn -q -DforceStdout help:evaluate -Dexpression=project.version | cut -f1 -d -`.`expr $GITHUB_RUN_NUMBER - 1666`
 
       - name: Build with Maven
         run: mvn -B -Pvsix package --file tools/enso4igv/pom.xml
@@ -43,5 +40,14 @@ jobs:
       - name: Install Node.js modules
         run: mvn -B -Pvsix npm:install --file tools/enso4igv/pom.xml
 
+      - name: Update package.json version
+        run: mvn -B -Pvsix npm:exec@version --file tools/enso4igv/pom.xml
+
       - name: Build VSCode Extension
         run: mvn -B -Pvsix npm:run@vsix --file tools/enso4igv/pom.xml
+
+      - name: Archive VSCode extension
+        uses: actions/upload-artifact@v3
+        with:
+          name: VSCode Extension
+          path: tools/enso4igv/*.vsix

.vscode/launch.json

@@ -0,0 +1,19 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Listen to 5005",
+      "type": "java+",
+      "request": "attach",
+      "listen": "true",
+      "hostName": "localhost",
+      "port": "5005"
+    },
+    {
+      "name": "Debug Adapter Protocol",
+      "type": "node",
+      "debugServer": 4711,
+      "request": "attach"
+    }
+  ]
+}

CHANGELOG.md

@@ -962,6 +962,7 @@
 - [Support runtime checks of intersection types][7769]
 - [Merge `Small_Integer` and `Big_Integer` types][7636]
 - [Inline type ascriptions][7796]
+- [Downloadable VSCode extension][7861]
 - [New `project/status` route for reporting LS state][7801]
 
 [3227]: https://github.com/enso-org/enso/pull/3227
@@ -1105,6 +1106,7 @@
 [7636]: https://github.com/enso-org/enso/pull/7636
 [7796]: https://github.com/enso-org/enso/pull/7796
 [7801]: https://github.com/enso-org/enso/pull/7801
+[7861]: https://github.com/enso-org/enso/pull/7861
 
 # Enso 2.0.0-alpha.18 (2021-10-12)
 

tools/enso4igv/README.md

@@ -2,6 +2,9 @@
 
 [![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)
 
+Searching for **VSCode** support? Read more about
+[VSCode extension for Enso here](vscode.md).
+
 [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
@@ -146,24 +149,7 @@ target/enso4igv-*-SNAPSHOT.nbm
 an NBM file is generated which can be installed into IGV, NetBeans or any other
 NetBeans based application.
 
-## Building VSCode Extension
+## VSCode Extension
 
-One can package the same plugin into a VSCode extension and obtain _Enso_ syntax
+There is also a VSCode extension for Enso. Read more about the extension
-coloring as well as support for editing `engine/runtime` sources in **VSCode**.
+[here](vscode.md).
-Just invoke:
-
-```
-enso/tools/enso4igv$ npm install
-enso/tools/enso4igv$ npm run vsix
-enso/tools/enso4igv$ ls *.vsix
-enso4vscode-*.vsix
-```
-
-one needs to have `npm`, Java and `mvn` available to successfully build the
-VSCode extension. Alternatively one can use Maven to built the VSIX extension
-via `mvn clean install -Pvsix`.
-
-![Install from VSIX...](https://user-images.githubusercontent.com/26887752/210131513-8c729f9b-5ddc-43aa-9ad5-420b7d87d81d.png)
-
-Once the `.vsix` file is created, it can be installed into VSCode. Select
-_Extension perspective_ and choose _Install from VSIX..._ menu item.

tools/enso4igv/pom.xml

@@ -5,7 +5,7 @@
     <artifactId>enso4igv</artifactId>
     <packaging>nbm</packaging>
     <name>Enso Language Support for NetBeans &amp; Ideal Graph Visualizer</name>
-    <version>1.13-NAPSHOT</version>
+    <version>1.15-SNAPSHOT</version>
     <build>
         <plugins>
             <plugin>
@@ -224,6 +224,18 @@
                                     <goal>install</goal>
                                 </goals>
                             </execution>
+                            <execution>
+                                <id>version</id>
+                                <goals>
+                                    <goal>exec</goal>
+                                </goals>
+                                <configuration>
+                                    <command>version</command>
+                                    <args>
+                                        <arg>${project.version}</arg>
+                                    </args>
+                                </configuration>
+                            </execution>
                             <execution>
                                 <id>vsix</id>
                                 <phase>post-integration-test</phase>

tools/enso4igv/vscode.md

@@ -0,0 +1,88 @@
+# Enso Language Support for VSCode
+
+[![Enso Language Support for VSCode](https://github.com/enso-org/enso/actions/workflows/enso4igv.yml/badge.svg)](https://github.com/enso-org/enso/actions/workflows/enso4igv.yml)
+
+## Downloading
+
+**Download** _"VSCode Extension" artifact_ from the
+[latest actions run](https://github.com/enso-org/enso/actions/workflows/enso4igv.yml),
+unzip, install into VSCode:
+
+![Install from VSIX file](https://github.com/enso-org/enso/assets/26887752/9d7c35d6-44b2-4157-b451-bb27980425c7)
+
+Your Enso files will get proper **syntax coloring**. You'll be able to **debug**
+Java/Enso code interchangeably.
+
+After installing the Enso `.vsix` file (and reloading window) we can find
+following two extensions in the system:
+
+![Installed VSCode extensions](https://github.com/enso-org/enso/assets/26887752/7dcfc0a0-8e7f-4aa6-ae67-99c3f875a658)
+
+## 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](../../docs/CONTRIBUTING.md#running-enso)).
+Following set of projects is opened and ready for use:
+
+![Enso Projects](https://github.com/enso-org/enso/assets/26887752/7919d2ee-4bcd-4b7b-954a-e2dc61f7c01a)
+
+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:
+
+![Openning Vector](https://github.com/enso-org/enso/assets/26887752/0d182fc8-4ff9-48d7-af63-35cad5fb75cc)
+
+It is now possible to place breakpoints into the `Vector_Spec.enso` file. Let's
+place one on line 120:
+
+![Breakpoint](https://github.com/enso-org/enso/assets/26887752/b6ae4725-49ef-439f-b900-3e08724e3748)
+
+Let's do a bit of debugging. Select _"Listen to 5005"_ debug configuration:
+
+![Listen to 5005](https://github.com/enso-org/enso/assets/26887752/1874bcb1-cf8b-4df4-92d8-e7fb57e1b17a)
+
+And then just
+[execute the engine distribution](../../docs/CONTRIBUTING.md#running-enso) in
+debug mode:
+
+```bash
+sbt:enso> runEngineDistribution --debug --run test/Tests/src/Data/Vector_Spec.enso
+```
+
+After a while the breakpoint is hit and one can inspect variables, step over the
+statements and more...
+
+![Breakpoint in Enso](https://github.com/enso-org/enso/assets/26887752/54ae4126-f77a-4463-9647-4dd3a5f83526)
+
+...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`:
+
+![Breakpoint in Java](https://github.com/enso-org/enso/assets/26887752/db3fbe4e-3bb3-4d4a-bb2a-b5039f716c85)
+
+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:
+
+![Pause in GraalVM](https://github.com/enso-org/enso/assets/26887752/98eb0bb7-48c2-4208-9d9a-5b8bacc99de2)
+
+## Building VSCode Extension
+
+To build thisVSCode extension and obtain _Enso_ syntax coloring as well as
+support for editing and debugging of `engine/runtime` sources in **VSCode**:
+
+```
+enso/tools/enso4igv$ mvn clean install -Pvsix
+enso/tools/enso4igv$ ls *.vsix
+enso4vscode-*.vsix
+```
+
+one needs to have `npm`, Java and `mvn` available to successfully build the
+VSCode extension.
+
+![Install from VSIX...](https://user-images.githubusercontent.com/26887752/210131513-8c729f9b-5ddc-43aa-9ad5-420b7d87d81d.png)
+
+Once the `.vsix` file is created, it can be installed into VSCode. Select
+_Extension perspective_ and choose _Install from VSIX..._ menu item.