Lab 1(a): Setting up Spoofax

Project Set-up
September 08, 2020

For the course project and for some of the homework assignments we will use the Spoofax Language Workbench.

Installing Spoofax

Download from the Artifacts of cs4200, the Premade Eclipse installation for your operating system. Choose the “Eclipse with embedded JRE”; this ensures that you have the right version of Java.

Note that this is a special snapshot for the course.

Follow the installation instructions.

From now on we will use ‘Spoofax’ to mean ‘Eclipse with the Spoofax plugin’.

Configuring Eclipse

You may configure Eclipse to your liking using the Preferences dialog. Some typical settings to adjust:

  • General ‣ Appearance: Choose a Theme to your liking
  • General ‣ Appearance ‣ Colors and Fons ‣ Text Font: The JetBrains Mono font supports ligatures and is used in (most of) the lecture slides (install separately).
  • General ‣ Keys: choose Emacs for emacs key bindings

Spoofax Language Projects

In Spoofax you develop a programming language in a ‘language project’.

Creating a Project

To create a new language project use File ‣ New ‣ Project ‣ Spoofax Language Project.

Set the following configuration parameters to create the project for your syntax definition:

  • Project name: chocopy.syntax
  • Use default location: []
  • Location: your gitlab repository
  • Identifier: chocopy.syntax
  • Name: chocopy
  • Version: 0.1.0-SNAPSHOT
  • Group identifier: org.example
  • Extensions: cpy
  • Syntax type: SDF3
  • Analysis type: None
  • Generate examples project: [x]
  • Generate unit testing project: [x]

This will give you three directories in your gitlab repository:

  • chocopy.syntax
  • chocopy.syntax.example
  • chocopy.syntax.test

Configuring a Project

By default, the start symbol for a project is set to Start. We want to change that to Program, the start symbol of the ChocoPy grammar. This requires changes in a couple of files:

  • chocopy.syntax/editor/Syntax.esv: Start => Program
  • chocopy.syntax/syntax/chocopy.sdf3: Start => Program

Apply analoguous changes to the chocopy.types project (once you create it).

In the file metaborg.yaml remove the line

- org.metaborg:dynsem:${metaborgVersion}

Building a Language Project

In Eclipse, you build a project by choosing Project ‣ Build Project or by pressing the corresponding keyboard shortcut (OS X: Cmd + Alt + B, Enter). (Note that you should be in the context of the language project, e.g. while the focus is a file in the syntax definition.) When you later rebuild your project, any open ChocoPy editor is updated to the new version you just built.

To get feedback on the building progress, open the Eclipse console via Window ‣ Show View ‣ Console. In some cases, it is necessary to select Other and then type Console.

Testing the Generated Editor

You can test the generated editor in the same Eclipse instance. Create example ChocoPy programs in the chocopy.syntax.example project with file extension .cpy. You can test the editor by first building your language project and opening a ChocoPy program. The editor should provide syntax highlighting and inline error messages.

Running SPT Tests

In the chocopy.syntax.test project, create tests using the SPT testing language. Once you build your project, you can run the tests in your test project. Select a test file or a directory with test files and run Spoofax (Meta) ‣ run (all) selected tests. See als the next project assignment.

Show Parsed AST

Use Spoofax ‣ Syntax ‣ Show parsed AST in an editor to test your abstract syntax definition interactively. When you change a ChocoPy program in the editor, it is necessary to select Show parsed AST again to visualize its corresponding AST. You might notice that the editor will give you an AST even for syntactically incorrect programs. This is because Spoofax editors support syntactic error recovery.

Agile Language Engineering

Spoofax supports short development cycles. This enables you to develop your language definition step by step. In each step, you focus on a single aspect, for example a particular nonterminal symbol or a particular grammar rule. After each step, you can check your progress by building the project and running your test cases.

Updating Spoofax

To update the Spoofax plugin in Eclipse, perform the following steps:

  1. go to Help -> Install New Software…
  2. in the Work with field, enter http://buildfarm.metaborg.org/job/metaborg/job/spoofax-releng/job/cs4200/lastSuccessfulBuild/artifact/dist/spoofax/eclipse/site/
  3. press enter and wait for the update site to load
  4. press Select All
  5. press Next and wait for Eclipse to calculate what to install and update
  6. press Finish to download and install updates
  7. when a security warning pops up, press OK to dismiss the warning
  8. when Eclipse has installed all updates, it will ask for a restart, press Yes to restart Eclipse

If installation fails with errors indicating that “updates are not permitted”, it means that your Eclipse installation is in a location that requires admin rights to write files. This is the case on Windows if you’ve copied Eclipse to Program Files. Move it to a directory where you have write access, such as the desktop, to solve the problem.

References