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
tolibspoofax/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
andlibspoofax/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 withlibspoofax
equivalents.
- Remove all imports to the runtime libraries that do not pertain NaBL, TS, and task engine based static analysis, and replace them with
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.
Created: January 28, 2025