Installing the Spoofax 3 language workbench¶

This tutorial gets you set up for language development in Spoofax 3 by installing the Spoofax 3 Eclipse LWB environment.

Requirements¶

Spoofax 3 runs on the major operating systems:

Windows (64 bits)
macOS (64 bits)
Linux (64 bits)

Other than that, nothing is required as everything is contained in the archive we are going to download.

Download¶

To get started, we will download a premade Eclipse installation that comes bundled with the Spoofax 3 LWB plugin. We will download version 0.23.1 released on 24-07-2024. Download the latest version for your platform:

These are bundled with an embedded JVM so that you do not need to have a JVM installed. If your system has a JVM of version 17 (exactly, higher versions are not supported), and would rather use that, use the following download links instead:

Unpack¶

Unpack the downloaded archive to a directory with write access. Write access is required because Eclipse needs to write to several configuration files inside its installation.

Warning

The unpacked directory or application may be renamed, but do not include spaces or other characters that would not be allowed in a URI (i.e., : ? # [ ] @). The same is true for the directory the archive is extracted to. Failing to do so breaks a built-in classpath detection mechanism which will cause Java compilation errors.

Warning

On Windows do not unpack the Eclipse installation into Program Files, because no write access is granted there, breaking both Eclipse and Spoofax.

On macOS Sierra (10.12) and above, after unpacking, open the Terminal and navigate to the directory where the Spoofax3.app file is located and execute:

xattr -rc Spoofax3.app

Running Eclipse¶

Start up Eclipse, depending on your operating system:

Windows: run Spoofax3/eclipse.exe
macOS run Spoofax3.app
Linux run Spoofax3/eclipse

Warning

macOS Sierra (10.12) and above will mark the unpacked Spoofax3.app as "damaged" due to a modified signed/notarized application, because we have modified the eclipse.ini file inside it. To fix this, open the Terminal, navigate to the directory where the Spoofax3.app file is located, and execute:

xattr -rc Spoofax3.app

After starting up, choose where your workspace will be stored. The Eclipse workspace will contain all of your settings, and is the default location for new projects.

Warning

Currently, there are several bugs regarding spaces in the workspace path, so ensure there are no spaces on the workspace path.

Configuring Eclipse's preferences¶

Some Eclipse preferences unfortunately have sub-optimal defaults. After you have chosen a workspace and Eclipse has completely started up (and you have closed the Welcome page), go to the Eclipse preferences by pressing Cmd+, on macOS and by going to the Window ‣ Preferences menu on others, and set these options:

General ‣ Startup and Shutdown
- Enable: Refresh workspace on startup
General ‣ Workspace
- Enable: Refresh using native hooks or polling
General ‣ Workspace ‣ Build
- Enable: Save automatically before manual build

We need to make sure that Eclipse has detected an installed JRE. Open the Eclipse preferences and go to the Java ‣ Installed JREs page:

If there are no installed JREs, and you've downloaded an Eclipse installation with an embedded JVM, press Search... and navigate to the location where you unpacked the Eclipse installation, and choose the jvm directory in it. Then press the checkmark of the JRE to activate it.
If there are no installed JREs, and you've downloaded an Eclipse installation without an embedded JVM, press Search... and navigate to the location where your JVM installed, and choose it. Then press the checkmark of the JRE to activate it.
If there are one or more installed JVMs, but none are selected, select an appropriate one by pressing the checkmark.
If there are one or more installed JVMs, and one is selected, you are good to go.

Finally, you may configure Eclipse to your liking. Some typical settings to adjust:

General ‣ Editors ‣ Text Editors
- Displayed tab width: change to your desired tab width. Most of Spoofax uses 2 by convention.
- Insert spaces for tabs: enable, as Spoofax uses spaces by convention.
- Show print margin: enable and set if you want to set a maximum line length.
- Show line numbers: enable if you want to see line numbers.
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: change keybindings.

Tip

These preferences are stored per workspace. If you create a fresh workspace, you have to re-do these settings. You can create a new workspace with copied preferences by selecting File ‣ Switch workspace ‣ Other..., and then checking Preferences under Copy settings.

Now that Eclipse is set up, continue with creating a language project