5 Things to Build a VS Code Extension using Xtext

9 min readJul 3, 2021

Overview

It is a work memo when building the extension of VS Code by Xtext which is a language workbench.
Made only rather than build in, it is basically here just that it is written in.
The procedure itself is not difficult.

At first

What is Xtext

Xtext is a genre of software called the language workbench by TypeFox , and we consider it to facilitate the development of unique programming languages(DSL, domain specific language). A similar one is JetBrains ‘ MPS .

What is VS Code

A popular editor provided by Microsoft that does not require explanation. Beyond the editor, you can no longer think of it as an IDE. VS Code Extension is software dedicated to VS Code that extends the functionality of VS Code.

What is Xtext VS Code Example

VS Code Extension by Xtext provides an editing function for a unique programming language defined in Xtext, and the form of provision is a file with a dedicated extension vsix. Extension build here refers to the process that starts with parser generation (Java) by Xtext, includes jar file(s) generation, packaging to Extension format, and so on.

Build environment

Windows10 Pro 1909
VS Code 1.47
JDK 1.8

Build immediately

The work itself is not difficult.
First, clone the source code from GitHub’s Xtext Visual Studio Code Example to any local location.
Just start the command prompt as described in Quickstart , move to the clone destination folder with the cd command, gradlew startCodeand then type. If you wait for a while and VS Code starts like this image, the build is successful.

Troubleshoot

If you didn’t encounter any errors during the build process, you’re lucky.
Please skip until After starting VS Code described later.
Here is a memorandum about the errors I encountered and what to do about them.
Perhaps you got caught in a typical build system error such as gradle or npm …

JDK version

Exception in thread "main" javax.net.ssl.SSLException: Received fatal alert: protocol_version

If you get the error, check the JDK path with the JDK version and environment variables.
I am using JDK1.7 (old) for the convenience of development, but it seems that gradle included in the cloned source code requires JDK1.8.
After replacing the JAVA_HOME path of the environment variable with the JDK 1.8 path, the error disappeared.
If you google, you will see an article that works even with 1.7, so it may be enough to set only the path of the environment variable, but this is unverified.
In addition, information related to the path set environment variables here is detailed.

Downloading https://services.gradle.org/distributions/gradle-5.6.4-bin.zipException in thread “main” javax.net.ssl.SSLException: Received fatal alert: protocol_version
...

Proxy settings for gradle

a network error occurred

If you get an error, suspect that one of the causes is that you did not configure the Proxy settings used by gradle. The Proxy settings used by gradle are resolved by putting a file called gradle.properties in the root folder of your gradle project. Speaking in this build, because the file corresponding to the README.md the same hierarchy is already, here in reference, it was append the settings that the IT department of the company has set or specified, no longer error.

Proxy settings for npm

error code ENOTFOUND
...
error network This is a problem related to network connectivity

If you get an error, it’s likely that npm also needs Proxy settings. With reference to this , when I reflected the same settings as gradle, the error disappeared.

Proxy settings for Xtext

*ATTENTION*
It is recommended to use the ANTLR 3 parser generator (BSD licence - http://www.antlr.org/license.html).
Do you agree to download it (size 1MB) from 'http://download.itemis.com/antlr-generator-3.2.0.jar'? (type 'y' or 'n' and hit enter)y
10046 [main] INFO erator.parser.antlr.AntlrToolFacade - downloading file from 'http://download.itemis.com/antlr-generator-3.2.0.jar' ...
Downloading ANTLR parser generator failed: download.itemis.com
Please install the feature 'Xtext Antlr SDK' manually using the external updatesite:'http://download.itemis.com/updates/'.(see http://www.eclipse.org/Xtext/download.html for details)

If you get an error that antlr3.2 cannot be downloaded, you can get around it with a workaround, although you don’t know if there is a Proxy setting. The procedure is as follows.
1. Access here
2. Click the link that can be downloaded directly in the article
3. When prompted to specify the save destination, save it directly under the org.xtext.example.mydsl folder of the cloned source code
4. For the downloaded file , Add (.) Dot to the beginning of the file name

update build.gradle

(Updated on 2021/06/30)
I noticed that the following error appeared from 2021/06/20 and the build did not complete.

Execution failed for task ':org.xtext.example.mydsl:generateXtext'.
> com.google.common.util.concurrent.ExecutionError: com.google.common.util.concurrent.ExecutionError: com.google.common.util.concurrent.ExecutionError: com.google.common.util.concurrent.ExecutionError: com.google.common.util.concurrent.ExecutionError: java.lang.UnsupportedClassVersionError: org/eclipse/core/runtime/OperationCanceledException has been compiled by a more recent version of the Java Runtime (class file version 55.0), this version of the Java Runtime only recognizes class file versions up to 52.0

As a result of examining the error, in the file org.eclipse.equinox.common-xx.jar on which Xtext depends (where xx is the version), version 3.15 was compiled by Java11, so Java1.8 used by other jar files. It seems that the cause is a version mismatch with the one compiled in. The same case is being discussed on an article , and although there is no solution at this time , a workaround has been applied in Xtext Visual Studio Code Example . I have confirmed that if I apply this workaround to build.gradle, the build will succeed.

`'script' does not exist.`

(Added on 2021/12/07)
From 2021/11/03, I noticed that the following error appeared and the build did not complete.

* What went wrong:
A problem was found with the configuration of task ':vscode-extension-self-contained:vscodeExtension'.
> File （略）tflab.xtext-languageserver-example\node_modules\vsce\out\vsce' specified for property 'script' does not exist.

The only situation I’ve found at this point is that it’s only a new git clone and build, and if the existing build is successful, no error will occur no matter how many times you build.
As a result of examination, it was found that the path where the vsce file is stored in the latest vsce module installed (downloaded) by npm was changed to directly under the root of the vsce module by fix: make it build on windows . I did.
In the existing build.gradle file, even though the path of the vsce file has changed as above,

task vscodeExtension(dependsOn: [npmInstall, npmInstallVsce], type: NodeTask) {
（略）
        script = file("$npmInstallVsce.destPath/out/vsce")
        args = [ 'package', '--out', destPath ]
        execOverrides {
            workingDir = projectDir
        }
    }

And is coded to refer to the original path.
This shouldn’t pass the build.
Also, the applicable versions of fix: make it build on windows are v2.2.0 v2.1.0 v2.0.0 v1.103.1 v1.103.0 v1.102.0 v1.101.0 v1.100.2wide-ranging.
As a result, the path of the vsce file will be changed in the newly downloaded vsce module, and an error will occur. As a countermeasure,

Adjust the path specification of vsce file in gradle to the latest
Specify the version before the change of vsce module with gradle

Must be done as a set.
Isn’t it enough to just adjust the path specification of the vsce file in gradle to the latest? I think some people thought that, but there was also a trap here.
In v2.0.0 and later versions, operator ??are used in some places in the code .
This operator, as you can see here , turned out to be relatively new.
On the other hand, since Node.js specified by gradle is v10, the ??operator is not supported.
Checking all the modified versions can be a daunting task. Perhaps the ??operator, I thought that there might be a version that I haven't used yet , so I investigated from which version of vsce the ??operator was applied, and found that it was after v2.0.0.
From the above, set the version of vsce specified by gradle to v1.103.1.

task npmInstallVsce(type: NpmTask, dependsOn: npmSetup) {
    ext.destPath = "$rootProject.projectDir/node_modules/vsce" 
    outputs.dir(destPath)
    group 'Node'
    description 'Installs the NodeJS package "Visual Studio Code Extension Manager"'
    args = [ 'install', 'vsce@v1.103.1' ]
}

As a result, you can build successfully.

Proxy setting in VS Code

(Updated 2021/06/30)
It seems that Proxy setting is supported from VS Code 1.52 .

After starting VS Code, you will probably see a Proxy Settings dialog box.
You can close it with the ☓ button in the upper right, but it’s a bit annoying that it appears twice each time you start VS Code. See here to
configure the Proxy .

After starting VS Code …

Did VS Code launch successfully for those who needed Proxy settings and those who didn’t?
As shown in the image at the beginning, !I think that the DEMO folder is specified and started, and the error is notified to the line without the end .
You can experience the various features that modern editors support, so give it a try.
I was impressed with how much extension was built that I couldn't believe was done with this effort.

Code completion

If you move the cursor to the place where the error occurs and enter Ctrl + Space, the following !will appear as input candidates . It is confirmed by Enter, and !is automatically entered.

Code formatting

If you select a string that is already implemented and select from the context menu Format Selection, it will look like this: The shaping result is … I’m not convinced a little, but the shaping is done.

Code generation

This extension has a java source generation function.
Did you confirm that the src-gen folder and files such as aGreeter.java were created directly under the DEMO folder?
It looks like opening aGreeter.java, and you can see that the code that outputs the class and the contents entered in a.mydsl to the console is generated.

Extension version check

You can check it by clicking the Extension button on the left side of the screen.

Next…

In the next article, I will explain how to fix the strange behavior of this extension.

Supplement

It’s easy, but I’d like to touch on a little about the technology in the text, which is related to the content of the article.

Xtext

The official website is here .
I understand that it is a genre of software called a language workbench that defines a programming language for a specific area and generates functions for editors such as input completion and syntax highlighting based on the definition.
It seems that the main plug-in is for Eclipse, but it seems that it is designed to work on various platforms and environments such as IntelliJ IDEA, browsers, and LSP.
This article uses LSP.

gradle

The official website is here .
By writing build rules in the groovy language, I understand that it is a system that can consistently acquire and build from the repository on the network without having to rely on the source code and libraries at hand. I am.
Although gradle is devised so that it can be described with a small number of characters, it is difficult for beginners to read the omitted description, and it is difficult to write it even if it is taken care of by many commentary sites including the official site. It was a thing.
In the future, if you want to create a new dependency on the library, understanding will be essential.

npm

The official website is here .
Except for being a Node.js module management tool, the touted functionality is very similar to gradle.
I didn’t really need to be aware of npm in writing this article, so I’d love to study if I get the chance.

Other

Original article(in Japanese) is here.