💻 Lab: first steps with langium

This first lab aims to play around with Langium to become a little more familiar with the Langium framework. The goal is not yet to implement your own DSL, but to make sure you have everything ready on your system, and to see how a Langium DSL can be compiled and packaged.

1. Prerequisites

Check you have the required prerequisites on your system, and install them if needed.

2. Generating the example Persons DSL

To discover Langium, the Langium Yeoman generator is able to generate an example of very simple DSL by answering Yes to the question "Generate example project?". The example DSL allows to write program where you can simply declare Persons and then Greetings to these persons.

Using Yeoman, initialize a Langium project with the following answers:

  • Your extension name: persons-dsl

  • Your language name: Persons DSL

  • File extensions: .persons

  • Your grammar entry rule name: Persons

  • Include VSCode extension?: Yes

  • Generate example project?: Yes

  • Include CLI?: Yes

  • Include language tests?: No

Before going further, have a look at the files of the resulting project, especially:

  • In the packages folder, observe that there are the three separate components of Langium DSL: language (with the DSL core components), extension (with the code to build a Visual Studio Code extension for the DSL), cli (with the code to build a CLI for the DSL).

  • In the packages/language/src folder, have a quick look at the Langium grammar (.langium) of the language. This file implements the the syntax of the DSL using the Langium Grammar Language (which is a metalanguage).

    Contrary to the method we will see in the course, this default Langium grammar does not use declared types to properly separate the abstract syntax from the concrete syntax. We will do things differently (and better)!

3. Building the Persons DSL

Open your new Langium project in Visual Studio Code, and build the project.

4. Manual testing of the Persons DSL

4.1. Manual testing of the Visual Studio Code extension

Run the Visual Studio Code extension of your DSL in development mode, then in the new Visual Studio Code window create a file name alice_and_bob.persons, and write the following content:

person Alice
person Bob

Hello Alice

Observe that:

  • some words appear colored because they are recognized as keywords of the DSL;

  • in the last line, you can CTRL+click on Alice and it brings you to the first line: this is a default navigation service allowing to browse a program using the cross-references it contains;

  • if you type new content that does not follow the DSL grammar rules, the parser throws an error.

The editor you are testing was entirely generated by Langium based on the DSL grammar, without having to write a single extra line of code. This is a great benefit of language workbenches: using high-level abstraction from metalanguages (here the Langium Grammar Language), we are able to generate significant parts of a DSL implementation.

4.2. Manual testing of the CLI

  • Run the CLI of your DSL to call the code generator of the DSL on the alice_and_bob.persons program. By default, the code generator of the Persons DSL is a code generator that compiles a Persons program into JavaScript. The resulting JavaScript file is simply a sequence of console.log statements that greet each person of the program.

  • Run the produced JavaScript file using node: congratulation, you executed your first DSL program!

5. Packaging the Persons DSL

Close the second Visual Studio Code instance (where you tested the DSL) before continuing.

Let’s first package the Visual Studio Code extension:

  • Package the Visual Studio Code extension of your Langium project into a .vsix file.

  • Install the .vsix file into your Visual Studio Code, then check that the extension is installed in your list of extensions.

  • Try to open alice_and_bob.persons, and observe that you can the Persons DSL editor is successfully used to edit the file (color completion is visible and navigation services work). This time your DSL was properly installed in Visual Studio Code, instead of running in development mode.

  • Uninstall the extension once you are done (to avoid cluttering your Visual Studio Code).

Then let’s package the CLI:

  • Package the CLI of your Langium project into .tgz npm packages.

  • Install the CLI on your system, and try to use it using the newly installed command persons-dsl-cli.

  • Uninstall the CLI once you are done:

    npm uninstall persons-dsl-language persons-dsl-cli

Your are now able to distribute your DSL and install it in user enviroments!