Spoofax 3 is a modular and incremental textual language workbench running on the JVM: a collection of tools and Java libraries that enable the development of textual languages, embeddable into batch compilers, code editors and IDEs, or custom applications. It is a reimplementation of Spoofax 2, with the goal of being more modular, flexible, and correctly incremental.
Currently, Spoofax 3 is experimental and still a work-in-progress. Therefore, it does not have a stable API, lacks documentation and test coverage, and has not yet been applied to real-world use cases. If you are looking for a more mature alternative, see Spoofax 2, which Spoofax 3 is based on.
See the (incomplete/under construction) documentation website for the motivation, key ideas, and current status of Spoofax 3.
.
├── build.gradle.kts # Gradle build configuration
├── settings.gradle.kts # Gradle build settings (multi-project and composite build)
├── core # Spoofax 3 core libraries
├── lwb # Spoofax 3 language workbench, in a separate composite build because
│ it uses Gradle plugins from core.
├── lwb.distrib # Spoofax 3 language workbench distribution, in a separate composite
│ build because it uses Gradle plugins from core and lwb.
├── example # Spoofax 3 examples, in a separate composite build because
│ it uses Gradle plugins from core and lwb.
├── gradle.properties # Gradle properties file
├── mkdocs.yml # Documentation configuration file (MkDocs)
├── mkdocs_requirements.txt # Documentation Python requirements file
├── docs # Documentation root
├── .github # GitHub issue template and action workflows
├── LICENSE # License file
├── NOTICE # License NOTICE file
├── CHANGELOG.md # Changelog
└── README.md
The master branch of this repository is buildable in isolation, and is used to publish new releases.
The develop branch of this repository is built via the devenv repository, against the develop branch of other repositories that are part of devenv, and is used for development.
Other branches are feature branches and should be merged into develop at some point.
The master branch of this repository can be built in isolation.
However, the develop branch must be built via the devenv repository, due to it depending on development versions of other projects.
This repository is built with Gradle, which requires a JDK of at least version 8 to be installed. Higher versions may work depending on which version of Gradle is used.
To build this repository, run:
./repo checkout
./gradlew buildAllNote
On Windows, instead run:
repo.bat checkout
gradlew.bat buildAllImportant
When using MacOS, ensure you have Docker installed and running.
To run a local Eclipse instance using the Spoofax version in this repository, run:
./gradlew :spoofax3.lwb.distrib.root:spoofax.lwb.eclipse:runEclipseNote
On Windows, instead run:
gradlew.bat :spoofax3.lwb.distrib.root:spoofax.lwb.eclipse:runEclipseTo build the documentation, see docs/README.md.
This repository is built on:
- GitHub actions via
.github/workflows/build.yml. Only themasterbranch is built here. - Our Jenkins buildfarm via
Jenkinsfilewhich uses our Jenkins pipeline library.
This repository is published via Gradle and Git with the Gitonium and Gradle Config plugins. It is published to our artifact server in the releases repository.
First, ensure that you depend on only released versions of other projects. That is, no SNAPSHOT or other development versions.
Most dependencies are managed in the core/spoofax.depconstraints/build.gradle.kts file.
Spoofax 2 versions are managed in gradle.properties:
systemProp.spoofax2Versionsets the version of Spoofax 2 that Spoofax 3 uses, for Spoofax 2 artifacts. At the moment of writing, this is only theorg.metaborg:strategoxt-min-jarartifact.systemProp.spoofax2DevenvVersionsets the version of Spoofax 2 that Spoofax 3 uses, which is built as part of themasterbranch of spoofax-deploy.
NOTE: If you're updating the spoofax2Version because you want to use some changes in a new Spoofax 2 release, you most likely will need to update to spoofax2DevenvVersion too, and in order to do so need to follow the above link and follow the instructions for releasing a new devenv version for the Spoofax 2 artifacts.
Then, update CHANGELOG.md with your changes, create a new release entry, and update the release links at the bottom of the file.
Commit your changes and merge them from the develop branch into the master branch.
To make a new release, create a tag in the form of release-* where * is the version of the release you'd like to make.
Then first build the project with ./gradlew buildAll to check if building succeeds.
If you want our buildfarm to publish this release, just push the tag you just made, and our buildfarm will build the repository and publish the release.
If you want to publish this release locally, you will need an account with write access to our artifact server, and tell Gradle about this account.
Create the ~/.gradle/gradle.properties file if it does not exist.
Add the following lines to it, replacing <username> and <password> with those of your artifact server account:
publish.repository.metaborg.artifacts.username=<username>
publish.repository.metaborg.artifacts.password=<password>
Then run ./gradlew publishAll to publish all built artifacts.
You should also push the release tag you made such that this release is reproducible by others.
Finally, add the release to the documentation by adding the release and date to the top of the release_versions dictionary in docs/macro.py.
Push this change to the develop branch and a GitHub actions build will automatically update the documentation website.
Copyright © 2018-2024 Delft University of Technology
The files in this repository are licensed under the Apache License, Version 2.0. You may use the files in this repository in compliance with the license.