1. Configuration Reference¶

Configuration is specified in the metaborg.yaml file at the root of the project.

1.1. Format¶

The configuration is written in YAML, a human-friendly textual data format. YAML is indentation sensitive, be sure to properly indent nested elements with 2 spaces.

We use the commons-configuration2 framework to process configuration, which supports variables, nesting, and lists.

1.1.1. Variables¶

Any existing configuration option can be used as a variable with the ${var} syntax, for example:

id: org.metaborg:org.metaborg.meta.lang.sdf:${metaborgVersion}
metaborgVersion: 2.0.0-SNAPSHOT

Here, the ${metaborgVersion} variable reference is replaced with 2.0.0-SNAPSHOT when reading the id configuration option. Note that the order in which configuration options and variable references occur does not matter.

The ${path:root} builtin property can be used to point to the root of the language specification. Paths in the configuration must be absolute unless stated otherwise. Use ${path:root}/ to make paths absolute, relative to the project root, where required.

Furthermore, environment variables can be used through ${env:}, for example ${env:PATH}. See the documentation on variable interpolation for more detailed informations on how variables work.

1.1.2. Nesting¶

Configuration options can be nested by nesting YAML objects, for example:

language:
  sdf:
    version: sdf2

results in the language.sdf.version option being set to sdf2, and can be referenced with a variable using ${language.sdf.version}. The same option can be set in the following way:

language.sdf.version: sdf2

1.1.3. Lists¶

Lists are supported using the YAML list syntax, for example:

dependencies:
  compile:
  - org.metaborg:org.metaborg.meta.lang.esv:${metaborgVersion}
  - org.metaborg:org.metaborg.meta.lang.nabl:${metaborgVersion}
  - org.metaborg:org.metaborg.meta.lang.test:${metaborgVersion}

results in the dependencies.compile option being set to a list with elements:

org.metaborg:org.metaborg.meta.lang.esv:${metaborgVersion}
org.metaborg:org.metaborg.meta.lang.nabl:${metaborgVersion}
org.metaborg:org.metaborg.meta.lang.test:${metaborgVersion}

1.2. Options¶

All supported configuration options for projects are listed here.

1.2.1. End-user project configuration¶

An end-user project is a project that contains programs of languages, intended to be developed by an end-user of those languages. The configuration for an end-user project specifies dependencies.

dependencies

Compile and source dependencies to other language components, and dependencies to Java artifacts.

compile

List of compile dependencies to language components. A compile dependency to a language component indicates that this project uses files of that language, and as such its compiler should be invoked.

Format: List of language component identifiers (see id option below)
Default: None

Example:

dependencies:
  compile:
  - org.metaborg:org.metaborg.meta.lang.esv:${metaborgVersion}

source

List of source dependencies to language components. A source dependency to a language component indicates that this project uses exported files of that language or library.

Format: List of language component identifiers (see id option below)
Default: None

Example:

dependencies:
  source:
  - org.metaborg:org.metaborg.meta.lib.analysis:${metaborgVersion}

java

List of dependencies to Java artifacts. A Java artifact dependency indicates that when this project is compiled, the Java artifact should be added to the compilation classpath. Spoofax currently does nothing with these dependencies, but they are used by Maven when compiling the project.

Format: List of Maven artifact identifiers (see id option below)
Default: None

Example:

dependencies:
  java:
  - com.google.guava:guava:19.0
  - com.google.inject:guice:4.0

Warning

There is currently a bug in the version parser that parses versions with 1 or 2 components to a version with 3 components. For example, the version 1 is parsed to 1.0.0, and 4.0 to 4.0.0. This will cause build failures since dependencies with those versions cannot be found.

1.2.2. Language specification project configuration¶

A language specification projectis a project that contains a languages 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 listed above, 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.

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

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

1.3. Examples¶

Our meta-languages and meta-libraries have configuration files which can be used as examples: