Installing Spoofax

Spoofax is distributed as an Eclipse plugin. This guide shows how to download, install, and run Spoofax in Eclipse.

Requirements

Spoofax runs on the major operating systems:

  • Windows (32 and 64 bits)
  • Linux (32 and 64 bits)
  • macOS (Intel only)

Spoofax requires a working internet connection to download several libraries when it is first started. These libraries are cached afterwards, and only need to be re-downloaded when you update Spoofax.

Installing the Spoofax Eclipse Plugin

Using Homebrew ( macOS)

On macOS Spoofax can be installed easily using Homebrew. For other platforms, or manual installation, follow the Download (all platforms) instructions below.

Install the latest release of Spoofax Eclipse as follows:

brew tap metaborg/metaborg
brew cask install spoofax

The optional command-line tools are installed with:

brew install strategoxt

Continue at Running Eclipse.

Warning

Upgrading the Spoofax cask using brew cask upgrade --greedy will lose all manually installed plugins. It is recommended to use Eclipse update sites to keep Spoofax up-to-date.

Download (all platforms)

To get started with Spoofax, download an Eclipse Oxygen installation with Spoofax preinstalled for your platform:

These are bundled with an embedded Java Runtime Environment (JRE) version 8, such that a JRE on your system is not required. If your system has a JRE of version 8 or higher installed, and would rather use that, use the following download links instead:

Unpack

Unpack the downloaded archive to a location with write access, since Eclipse requires write access to the unpacked Eclipse installation.

Warning

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

Warning

On macOS Sierra (10.12) and above, you must move the unpacked spoofax.app file to a different location (such as Applications) after unpacking, to prevent App Translocation from moving the app into a read-only filesystem, breaking Eclipse and Spoofax.

Alternatively, you can prevent App Translocation by clearing attributes from the application. To do this, open the Terminal, navigate to the directory where the spoofax.app is located, and execute:

xattr -rc spoofax.app

Running Eclipse

Start up Eclipse, depending on your operating system:

  • Windows: open spoofax/eclipse.exe
  • Linux: open spoofax/eclipse
  • macOS: open spoofax.app

Warning

Do not update Eclipse with Help ‣ Check For Updates, as it will update Eclipse to newer major versions which are not always backwards compatible, and which require a JRE of version 11 or higher which we do not bundle (we bundle JRE8) with Eclipse.

Note

On macOS, if Eclipse cannot be opened because it is from an unidentified developer, right click spoofax.app and choose Open to grant permission to open Eclipse.

If Eclipse cannot be opened because it is damaged, open the Terminal, navigate to the directory where spoofax.app is located, and execute:

xattr -rc spoofax.app

This will clear the attributes that Eclipse has been downloaded from the internet, and grant permission to open Eclipse.

Note

If you downloaded Spoofax Eclipse without an embedded JRE, it may not start or give an error A Java Runtime Environment (JRE) or Java Development Kit (JDK) must be available in order to run Eclipse or To open “spoofax” you need to install the legacy Java SE 6 runtime. To fix this, specify the path to a valid JDK using the -vm option at the start of eclipse.ini (spoofax.app/Contents/Eclipse/eclipse.ini on macOS).

For example, to specify the current JDK installed by Sdkman, add this at the top of your eclipse.ini:

-vm
/Users/myusername/.sdkman/candidates/java/current/lib/jli/libjli.dylib

See this link for more information.

Note

On Ubuntu 16.04, Eclipse is known to have problems with GTK+ 3. To work around this issue, add the following to eclipse.ini:

--launcher.GTK_version
2

before the line:

--launcher.appendVmargs

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.

Some Eclipse settings unfortunately have sub-optimal defaults. After you have chosen a workspace and Eclipse has completely started up, go to the Eclipse preferences and set these options:

  • General ‣ Startup and Shutdown
    • Enable: Refresh workspace on startup
  • General ‣ Workspace
    • Enable: Refresh using native hooks or polling
  • Maven ‣ Annotation Processing
    • Enable: Automatically configure JDT APT

Changing Eclipse Memory Allocation

By default a plain Eclipse has a maximum heap size of 1 GB. You may want to increase this limit. The default for the Eclipse application produced by Spoofax is 2 GB.

To run Eclipse once with a different memory limit, call it from the command-line like this:

eclipse [normal arguments] -vmargs -Xmx2G

If this works, you can permanently apply this limit in the eclipse.ini file in the Eclipse installation directory ( macOS: Contents/Eclipse in the Eclipse package) by changing the -Xmx argument. For example:

-vmargs
[...]
-XstartOnFirstThread
-Xss16M
-Xms2G
-Xmx2G
-Dosgi.requiredJavaVersion=1.8
-server
-Xss
the size of the thread stack
-Xms
the initial size of the heap
-Xmx
the maximum size of the heap

Further Instructions

Follow the Getting Started guide to get started with Spoofax in Eclipse.