2023-10-15 07:43:26 +03:00
# Enso Language Support for VSCode
2022-06-23 07:43:49 +03:00
2023-10-15 07:43:26 +03:00
[![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)
2022-06-23 07:43:49 +03:00
2023-10-15 07:43:26 +03:00
## Downloading
2023-09-23 10:15:24 +03:00
2023-10-15 07:43:26 +03:00
_Enso Tools for VSCode_ is available from
[VSCode marketplace ](https://marketplace.visualstudio.com/items?itemName=Enso.enso4vscode ).
Simply install it from there.
2022-06-23 07:43:49 +03:00
2023-10-15 07:43:26 +03:00
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.
2022-06-23 07:43:49 +03:00
2023-10-15 07:43:26 +03:00
Your Enso files will get proper **syntax coloring** . You'll be able to **debug**
Java/Enso code interchangeably.
2022-06-23 07:43:49 +03:00
2023-10-15 07:43:26 +03:00
After installing the Enso `.vsix` file (and reloading window) we can find
following two extensions in the system:
2022-06-23 07:43:49 +03:00
2023-10-15 07:43:26 +03:00
![Installed VSCode extensions ](https://user-images.githubusercontent.com/26887752/274904239-ae1ad4cc-e2ec-4c5b-bca0-c7d7189c6885.png )
2022-06-23 07:43:49 +03:00
2024-02-12 09:38:11 +03:00
## Debugging a Single Enso File
2022-06-23 07:43:49 +03:00
2024-02-12 09:38:11 +03:00
Open any `.enso` files. Click left editor gutter to place breakpoints. Then
choose _Run/Start Debugging_ . If asked, choose _debug with_ **Java+** (Enso is
Java virtual machine friendly). A prompt appears asking for path to `bin/enso`
binary:
![Select enso executable ](https://github.com/enso-org/enso/assets/26887752/4e1d0666-634d-4fb8-bf61-6dbf765311e8 )
Locate `bin/enso` executable in the Enso engine download. If binding from source
code, the executable is located at root of
[Enso repository ](https://github.com/enso-org/enso/ ) in
`./built-distribution/enso-engine-*/enso-*/bin/enso` . The `.enso` file gets
executed and output is printed in the area below editor:
![Executed ](https://github.com/enso-org/enso/assets/26887752/2165a04f-bc0a-4b62-9ad7-e74e354e6937 )
## Workspace Debugging
To work with all Enso code base continue with choosing _File/Open Folder..._ and
2023-10-15 07:43:26 +03:00
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:
2022-06-23 07:43:49 +03:00
2023-10-15 07:43:26 +03:00
![Enso Projects ](https://github.com/enso-org/enso/assets/26887752/7919d2ee-4bcd-4b7b-954a-e2dc61f7c01a )
2022-06-23 07:43:49 +03:00
2023-10-15 07:43:26 +03:00
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:
2022-06-23 07:43:49 +03:00
2023-10-15 07:43:26 +03:00
![Openning Vector ](https://github.com/enso-org/enso/assets/26887752/0d182fc8-4ff9-48d7-af63-35cad5fb75cc )
2022-06-23 07:43:49 +03:00
2023-10-15 07:43:26 +03:00
It is now possible to place breakpoints into the `Vector_Spec.enso` file. Let's
place one on line 120:
2022-11-15 10:05:53 +03:00
2023-10-15 07:43:26 +03:00
![Breakpoint ](https://github.com/enso-org/enso/assets/26887752/b6ae4725-49ef-439f-b900-3e08724e3748 )
2022-06-23 07:43:49 +03:00
2024-02-12 09:38:11 +03:00
To debug the `test/Base_Tests/src/Data/Vector_Spec.enso` file with the root of
Enso repository opened in the VSCode workspace, choose preconfigured _Launch
Enso File_ debug configuration before _Run/Start Debugging_ .:
![Launch Enso File in a Project ](https://github.com/enso-org/enso/assets/26887752/3680aab2-bf99-41d2-ada7-491d6040f8d2 )
The rest of the workflow remains the same as in case of individual (without any
project )`.enso` file case.
## Attach Debugger to a Process
2023-10-15 07:43:26 +03:00
Let's do a bit of debugging. Select _"Listen to 5005"_ debug configuration:
2022-06-23 07:43:49 +03:00
2023-10-15 07:43:26 +03:00
![Listen to 5005 ](https://github.com/enso-org/enso/assets/26887752/1874bcb1-cf8b-4df4-92d8-e7fb57e1b17a )
2022-06-23 07:43:49 +03:00
2023-10-15 07:43:26 +03:00
And then just
[execute the engine distribution ](https://github.com/enso-org/enso/blob/develop/docs/CONTRIBUTING.md#running-enso )
in debug mode:
2022-06-23 07:43:49 +03:00
```bash
2024-01-17 18:19:19 +03:00
sbt:enso> runEngineDistribution --debug --run test/Base_Tests/src/Data/Vector_Spec.enso
2022-06-23 07:43:49 +03:00
```
2023-10-15 07:43:26 +03:00
After a while the breakpoint is hit and one can inspect variables, step over the
statements and more...
2022-11-15 10:05:53 +03:00
2023-10-15 07:43:26 +03:00
![Breakpoint in Enso ](https://github.com/enso-org/enso/assets/26887752/54ae4126-f77a-4463-9647-4dd3a5f83526 )
2022-11-15 10:05:53 +03:00
2023-10-15 07:43:26 +03:00
...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` :
2022-12-30 08:30:32 +03:00
2023-10-15 07:43:26 +03:00
![Breakpoint in Java ](https://github.com/enso-org/enso/assets/26887752/db3fbe4e-3bb3-4d4a-bb2a-b5039f716c85 )
2022-11-15 10:05:53 +03:00
2023-10-15 07:43:26 +03:00
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:
2022-06-23 07:43:49 +03:00
2023-10-15 07:43:26 +03:00
![Pause in GraalVM ](https://github.com/enso-org/enso/assets/26887752/98eb0bb7-48c2-4208-9d9a-5b8bacc99de2 )
2022-06-23 07:43:49 +03:00
2023-11-27 11:37:51 +03:00
Read more on [Enso & Java Debugging ](../../docs/debugger/runtime-debugging.md )
2023-10-15 07:43:26 +03:00
## Building VSCode Extension
2022-06-23 07:43:49 +03:00
2023-10-15 07:43:26 +03:00
To build this VSCode extension and obtain _Enso_ syntax coloring as well as
support for editing and debugging of `engine/runtime` sources in **VSCode** :
2022-06-23 07:43:49 +03:00
2023-10-15 07:43:26 +03:00
```
enso/tools/enso4igv$ mvn clean install -Pvsix
enso/tools/enso4igv$ ls *.vsix
enso4vscode-*.vsix
```
2022-06-23 07:43:49 +03:00
2023-10-15 07:43:26 +03:00
one needs to have `npm` , Java and `mvn` available to successfully build the
VSCode extension.
2022-06-23 07:43:49 +03:00
2023-10-15 07:43:26 +03:00
![Install from VSIX... ](https://user-images.githubusercontent.com/26887752/269557870-9d7c35d6-44b2-4157-b451-bb27980425c7.png )
2022-06-23 07:43:49 +03:00
2023-10-15 07:43:26 +03:00
Once the `.vsix` file is created, it can be installed into VSCode. Select
_Extension perspective_ and choose _Install from VSIX..._ menu item.
2023-01-06 17:18:20 +03:00
2023-10-15 07:43:26 +03:00
## Reference
2023-01-06 17:18:20 +03:00
2023-10-15 07:43:26 +03:00
There are extensions for [NetBeans ](http://netbeans.apache.org ) and also for
**IGV**. Read more [here ](IGV.md ).