Skip to content

Spoofax 2.1.0 Migration Guide

This migration guide describes the differences between Spoofax 2.0 and 2.1 and how to convert to 2.1.

New Stratego library for Spoofax

Historically, the org.metaborg.meta.lib.analysis library (also called the runtime libraries) from this repo, was first used as a library to support NaBL, TS, and task engine based static analysis. However, a lot of other functionality such as completions, refactoring, origin tracking, and annotation handling, was also added to the library for convenience. Likewise, the src-gen/stratego/metaborg.str generated file also contains arbitrary functionality such as parsing and import path primitives, and the src-gen/editor/Colorer.generated generated file contains a default coloring scheme.

Since this kind of functionality does not belong the analysis library and generated files, we have moved this into a new library, libspoofax, which can be found at this repo.

Migration

The org.metaborg.meta.lib.analysis library still contains the old arbitrary functionality, but is now deprecated, meaning we will not update that functionality any more, and that it will be removed in a future version. Any functionality pertaining NaBL, TS, and task engine based static analysis will of course be retained. Likewise, the src-gen/stratego/metaborg.str and src-gen/editor/Colorer.generated generated files are also deprecated, meaning that they will stop being generated in a future version.

The new libspoofax library is now required for every Spoofax project. Add a source dependency to org.metaborg:meta.lib.spoofax:${metaborgVersion} in your metaborg.yaml file. For example, change the following dependencies:

dependencies:
  compile:
  - org.metaborg:org.metaborg.meta.lang.esv:${metaborgVersion}
  - org.metaborg:org.metaborg.meta.lang.template:${metaborgVersion}
  - org.metaborg:org.metaborg.meta.lang.nabl:${metaborgVersion}
  - org.metaborg:org.metaborg.meta.lang.ts:${metaborgVersion}
  source:
  - org.metaborg:org.metaborg.meta.lib.analysis:${metaborgVersion}

into:

dependencies:
  compile:
  - org.metaborg:org.metaborg.meta.lang.esv:${metaborgVersion}
  - org.metaborg:org.metaborg.meta.lang.template:${metaborgVersion}
  - org.metaborg:org.metaborg.meta.lang.nabl:${metaborgVersion}
  - org.metaborg:org.metaborg.meta.lang.ts:${metaborgVersion}
  source:
  - org.metaborg:meta.lib.spoofax:${metaborgVersion}
  - org.metaborg:org.metaborg.meta.lib.analysis:${metaborgVersion}

If you do not use NaBL, TS, and task engine based analysis any more, you can also delete the org.metaborg:org.metaborg.meta.lib.analysis:${metaborgVersion} source dependency.

Some imports have to be changed to point to the new libspoofax library:

  • In editor/Syntax.esv or your equivalent ESV file that handles coloring:
  • Change import editor/Colorer.generated to libspoofax/color/default
  • In trans/analysis.str for NaBL/TS projects:
  • Add import libspoofax/core/language
  • In trans/outline.str:
    • Remove imports to the runtime libraries
    • Add import libspoofax/editor/outline
  • In trans/pp.str:
    • Remove imports to the runtime libraries
    • Add imports libspoofax/sdf/pp and libspoofax/editor/refactoring/-
  • In other Stratego files:
    • Remove all imports to the runtime libraries that do not pertain NaBL, TS, and task engine based static analysis, and replace them with libspoofax equivalents.
    • Remove all imports to the stratego/metaborg generated file, and replace them with libspoofax equivalents.

Here is a list of other imports and strategies that were moved:

  • Imports:
    • runtime/editor/origins -> libspoofax/term/origin
    • runtime/editor/annotations -> libspoofax/term/annotation
    • runtime/completion/- -> libspoofax/editor/completion/-
  • Strategies:
    • *-at-position: libspoofax/term/position
    • parse-file: libspoofax/core/parse
    • language: libspoofax/core/language
    • project-path: libspoofax/resource/path
    • open-import: libspoofax/resource/cache
    • refresh-workspace-file: removed, not needed any more since all file system operations go though VFS, which routes them through Eclipse.
Last update: June 3, 2025
Created: June 3, 2025