Language Specification Project Configuration¶

This page describes the options in the metaborg.yaml file of a language specification project. A language specification project is a project that contains a language specification, which contain programs of meta-languages, intended to be developed by a language developer. It is a specialization of an end-user project, so all configuration options from end-user projects can also be used in language specification projects.

The following configuration options are mandatory:

`id`¶

Identifier of the language the language specification is describing.

Format: groupId:id:version where version uses the Maven version syntax; major.minor.patch(-qualifier)?
Example: id: org.metaborg:org.metaborg.meta.lang.sdf:2.0.0-SNAPSHOT

`name`¶

Name of the language the language specification is describing.

Example: name: SDF

The following configuration options are optional and revert to default values when not specified:

`dependencies`¶

Compile and source dependencies to other language components, and dependencies to Java artifacts. See the end-user projects page for more information.

`metaborgVersion`¶

Version of the MetaBorg tools to use.

Format: Maven version syntax (see id option)
Default: Current version of the running Spoofax
Example: metaborgVersion: 2.0.0-SNAPSHOT

`contributions`¶

List of language implementation identifiers the language component generated from this language specification contributes to.

Format: List of language implementation names and identifiers (see id option)
Default: Contribution to single language implementation with the same name and identifier of this language specification.

Example:

contributions:
- name: Green-Marl
  id: com.oracle:greenmarl:1.5.0-SNAPSHOT

`generates`¶

List of language names this language specification generates files for, and into which directory.

Format: List of language name and directory.
Default: None

Example:

generates:
- language: EditorService
  directory: src-gen
- language: Stratego-Sugar
  directory: src-gen

`exports`¶

List of files and directories this language specification exports for use in other language components, and optionally to which language those files and directories belong. Exported resources are packaged into the language component artifact when built.

Format: List of exports. There are 3 kinds of exports which are described below
Default: None

Language-specific Directory Export¶

A language-specific directory export, exports a directory with files of a specific language. The directory must be relative to the project root. Includes and excludes are relative to the specified directory. These files can be used by other language components by specifying a source dependency on the language component built from this language specification.

Format: Language name, path to directory, optional list of includes, and optional list of excludes

Example:

exports:
- language: TemplateLang
  directory: syntax
- language: ds
  directory: src-gen/ds-signatures
- language: Stratego-Sugar
  directory: trans
  includes: "**/*.str"
- language: Stratego-Sugar
  directory: src-gen
  includes: "**/*.str"

Warning

Includes and excludes are only used to package the correct resources into the language component artifact, Spoofax Core does not use the includes and excludes at this moment. This may cause differences in behaviour between development and deployment environments.

Language-specific File Export¶

A language-specific file export, exports a single file of a specific language. The file must be relative to the project root. The file can be used by other language components by specifying a source dependency on the language component built from this language specification.

Format: Language name, path to file

Example:

exports:
- language: SDF
  file: include/libanalysis2.def

Generic Resource Export¶

A generic resource export, exports any resources in a directory. The directory must be relative to the project root. Includes and excludes are relative to the specified directory. These files can be used for tasks specific to the language specification, for example to bundle library files with the language specification.

Format: Relative path to directory, optional list of includes, and optional list of excludes

Example:

exports:
- directory: ./
  includes:
    - lib-java/**/*
    - lib-webdsl/**/*
    - lib/webdsl/HQL-pretty.pp.af
    - lib/webdsl/WebDSL-pretty.pp.af

Warning

All paths are relative to the project root. Do NOT use ${path:root} to make paths absolute!

Note

For directory exports, a list of includes and excludes can be optionally specified, using the Ant pattern syntax. If no includes or excludes are specified, all files in the directory are assumed to be included recursively.

Note

Use ./ to use the root directory as export directory, . triggers an error in the YAML parser.

`pardonedLanguages`¶

List of language names that are pardoned; any errors they produce will not fail builds.

Format: List of language names
Default: None

Example:

pardonedLanguages:
  - EditorService
  - Stratego-Sugar
  - SDF

`language`¶

Language specific configuration options.

`sdf`¶

Configuration options for SDF2 and SDF3.

`enabled`¶

Whether to enable sdf (parse table, parenthesizer) for the current project or not.

Format: Either true or false.
Default: true

Example:

language:
  sdf:
    enabled: false

`parse-table`¶

The relative path to the parse table (if not specified in the ESV).

Default: target/metaborg/sdf.tbl

Example:

language:
  sdf:
    parse-table: "tables/sdf.tbl"

`completion-parse-table`¶

The relative path to the completions parse table.

Default: target/metaborg/sdf-completions.tbl

Example:

language:
  sdf:
    completion-parse-table: "tables/sdf-completions.tbl"

`version`¶

Version of SDF to use.

Format: Either sdf2 or sdf3.
Default: sdf3
Example:
```
language:
  sdf:
    version: sdf2
```

`sdf2table`¶

Version of sdf2table to use.

Format: Either c, java, or dynamic.
Default: c
Example:
```
language:
  sdf:
    sdf2table: java
```

`jsglr-version`¶

Version of the JGSLR parser to use. The options listed after v2 are extensions of v2, which are described here. Note that some of these extensions are experimental.

Format: Either v1, v2, data-dependent, incremental, layout-sensitive, recovery, or recovery-incremental.
Default: v1
Example:
```
language:
  sdf:
    jsglr-version: v2
```

`placeholder`¶

Configuration for completion placeholders.

Format: Quoted strings for prefix, and optionally, quoted strings for suffix.
Default: prefix: [[, and suffix: ]]

Example:

language:
  sdf:
    placeholder:
      prefix: "$"

`generate-namespaced`¶

Configuration for generating a namespaced grammar. A namespaced grammar can be generated automatically from an SDF3 grammar. This namespacing is done by adding the language name to all module names and sort names. The generated grammar is put in src-gen/syntax.

Format: Either true or false.
Default: false

Example:

language:
  sdf:
    generate-namespaced: true

`externalDef`¶

External SDF definition file to use. If this is specified, the language.sdf.version and language.sdf.args options are ignored, and all SDF2 or SDF3 syntax files are ignored.

Example:

language:
  sdf:
    externalDef: ${path:root}/syntax/Stratego-Sugar.def

`args`¶

List of additional arguments that are passed to pack-sdf when this language specification is built.

Format: List of command-line arguments.
Default: None

Example:

language:
  sdf:
    args:
    - -Idef
    - ${path:root}/lib/SDF.def

`sdf-meta`¶

List of SDF2 files that define a syntax mix of two or more languages, which are turned into extra parse tables when this language specification is built. These are typically used for mixing the grammar of the language with that of Stratego to be able to use concrete syntax of the language to describe abstract syntax in Stratego and transform it.

Format: List of command-line arguments.
Default: [Stratego-<languagename>.sdf]

Example:

language:
  sdf:
    sdf-meta:
    - Stratego-Tiger.sdf
    - Stratego-Tiger-Java15.sdf

`stratego`¶

Configuration options for Stratego.

`format`¶

The output format of the strj compiler when this language specification is built.

Format: Either ctree or jar.
Default: ctree
Example:
```
language:
  stratego:
    format: jar
```

`args`¶

List of additional arguments that are passed to strj when this language specification is built.

Format: List of command-line arguments.
Default: None

Example:

language:
  stratego:
    args:
    - -la
    - stratego-lib
    - -la
    - stratego-sglr
    - -la

`statix`¶

Configuration options for Statix.

`mode`¶

Format: traditional, concurrent or incremental
Default: traditional

Example:

language:
  statix:
    mode: incremental

`build`¶

`useBuildSystemSpec`¶

Whether to use the specification from the build system as a source of configuration for that build system, or this configuration file.

For example, when set to false (the default), and Spoofax's Maven plugin's pomless support is enabled through the .mvn/settings.xml file, Maven will entirely ignore the contents of the pom.xml file, and use this configuration file as a source of information. When this is not desired, for example if your POM file has information that is not covered in this configuration file, set it to true to use the POM file. The id, name, and dependencies must be duplicated from this configuration file into the POM file, since this configuration file is ignored by Maven.

Note that Spoofax itself will use this configuration file regardless of this setting. This setting is only used by build systems such as Maven and Gradle.

Format: Either true or false.
Default: false
Example:
```
build:
  useBuildSystemSpec: true
```

Additional build steps¶

The build configuration option also hosts a list of additional build steps.

Format: List of build steps. There are 2 kinds of additional build steps which are described below. Each build step has a phase in which it is executed, which can be one of the following:
- initialize: runs at the start of a build
- generateSources: runs after compilers for all compile dependencies have generated source files
- compile: runs after the build (i.e. pack-sdf, strj, etc. have been executed), but before compiling Java files
- pkg: runs after Java files have been compiled, and after packaging the language component
- clean: runs when the language specification is cleaned
Default: None

`stratego-cli` (Stratego build step)¶

Build step that runs a command-line Stratego application.

Format: phase, strategy to run, and command-line arguments

Example:

build:
  stratego-cli:
  - phase: compile
    strategy: org.strategoxt.tools.main-parse-pp-table
    args:
    - -i
    - ${path:root}/lib/EditorService-pretty.pp
    - -o
    - ${path:root}/target/metaborg/EditorService-pretty.pp.af

`ant` (Ant build step)¶

Build step that runs a target from an Ant build script.

Format: phase, path to Ant build script, and target in the build script to execute

Example:

build:
  ant:
  - phase: initialize
    file: ${path:root}/build.xml
    target: main

Last update: June 3, 2025
Created: June 3, 2025

Language Specification Project Configuration¶

id¶

name¶

dependencies¶

metaborgVersion¶

contributions¶

generates¶

exports¶

Language-specific Directory Export¶

Language-specific File Export¶

Generic Resource Export¶

pardonedLanguages¶

language¶

sdf¶

enabled¶

parse-table¶

completion-parse-table¶

version¶

sdf2table¶

jsglr-version¶

placeholder¶

generate-namespaced¶

externalDef¶

args¶

sdf-meta¶

stratego¶

format¶

args¶

statix¶

mode¶

build¶

useBuildSystemSpec¶

Additional build steps¶

stratego-cli (Stratego build step)¶

ant (Ant build step)¶

`id`¶

`name`¶

`dependencies`¶

`metaborgVersion`¶

`contributions`¶

`generates`¶

`exports`¶

`pardonedLanguages`¶

`language`¶

`sdf`¶

`enabled`¶

`parse-table`¶

`completion-parse-table`¶

`version`¶

`sdf2table`¶

`jsglr-version`¶

`placeholder`¶

`generate-namespaced`¶

`externalDef`¶

`args`¶

`sdf-meta`¶

`stratego`¶

`format`¶

`args`¶

`statix`¶

`mode`¶

`build`¶

`useBuildSystemSpec`¶

`stratego-cli` (Stratego build step)¶

`ant` (Ant build step)¶