Skip to content

Configuration

The main entry point of a language definition is the spoofaxc.cfg (Spoofax compiler configuration) file, written in the CFG language. The goal of this config file is to configure basic options, enable/disable features, point to main source files of meta-languages, to add/override behaviour, and to serve as an anchor on the filesystem. The directory that the spoofaxc.cfg file is in is called the "root directory" of the language definition, and any relative paths are resolved relative to that directory.

The CFG language has domain-specific syntax for configuring language definitions. However, the syntax follows these conventions:

  • Options are assigned a value with $Option = $Expression. Unless specified otherwise, options may only be given once.
  • Sections $Section { ... } may enable features and group options.
  • Lists $List [ ..., ... ] indicate an option/section may be given 0-many times.
  • Let bindings let $Name = $Expression can be used to give values a name that can be (re-)used in the rest of the configuration file.

If something in the documentation is unclear, the CFG language definition can be found here.

In its most basic form, the spoofaxc.cfg file for a language named Calc looks as follows:

name = "Calc"

which assigns the string "Calc" to the name option. A more interesting example configures more options and enables syntax definition:

name = "Calc"
java-class-id-prefix = java Calc
file-extension = "calc"

sdf3 {}
parser {
  default-start-symbol = sort Program
}

Here, java Calc is assigned to the java-class-id-prefix option. The sdf3 {} section from the example is empty, but is used to enable the SDF3 meta-language. The parser section enables generation of a parser, and also sets the default start symbol to use to sort Program.

Literals

Literals are expressions that are usually directly assigned to options, or bound to a name with let bindings. CFG has the following literals:

Syntax Example(s) Type
(true|false) true false Boolean
-?[0-9]+ 1 -20 Integer
[0-9]+ 1 20 Unsigned integer
'(~[\'\$\n\r\\] | \\~[\n\r])' '[' 'l' Character
"(~[\"\$\n\r\\] | \\~[\n\r])*" "foo" "bar" String
(./|/)~[\n\r\,\;\]\)\}\ ]* ./relative/file /absolute/file Filesystem path
$JavaIdChars Java foo Java identifier
$JavaQIdLit Java foo.bar.Baz Qualified Java identifier
task-def $JavaQIdLit task-def foo.bar.Baz Qualified Java identifier that represents a task definition
sort [a-zA-Z0-9\-\_\$]+ sort Start SDF3 sort identifier
strategy [a-zA-Z0-9\-\_\$]+ strategy Start Stratego strategy identifier
$CoordinateChars:$CoordinateChars:$CoordinateChars org.metaborg:strategolib:1.0.0 Coordinate
$CoordinateChars:$CoordinateChars:$CoordinateRequirementChars org.metaborg:strategolib:* Coordinate requirement

With the following syntax non-terminals:

Name Syntax
JavaIdChars [a-zA-Z\_\$][a-zA-Z0-9\_\$]*
JavaQIdLit $JavaIdChars(\.$JavaIdChars)*
CoordinateChars (~[\"\:\;\,\*\$\{\}\[\]\n\r\\\ ]|\\~[\n\r])
CoordinateRequirementChars ($CoordinateChars|\*)

For Java, SDF3 sort, and Stratego strategy identifiers, the corresponding keywords of those languages are rejected as identifiers.

Let bindings

Let bindings of the form let $Name = $Expression bind a name to an expression, for example:

let showParsedAst = task-def mb.helloworld.task.HelloWorldShowParsedAst
let showParsedAstCommand = command-def {
  task-def = showParsedAst
  ...
}
editor-context-menu [
  menu "Debug" [
    command-action {
      command-def = showParsedAstCommand
      ...
    }
  ]
]

creates a binding from name showParsedAst to task-def mb.helloworld.task.HelloWorldShowParsedAst, which we then pass to the task-def option in command-def. The command in turn is bound to showParsedAstCommand, assigned to the command-def option in a command-action section.

Top-level options

The following top-level options exist:

Syntax Required? Description Type
group = $Expression no Group identifier of the language, used as the group/groupId in the Java ecosystem. Defaults to org.metaborg. String
id = $Expression no Artifact identifier of the language, used as the name/artifactId in the Java ecosystem. Defaults to the name of the language uncapitalized. String
name = $Expression yes Name of the language. String
version = $Expression no Version of the language, used as the version in the Java ecosystem. Defaults to 0.1.0. String
file-extension = $Expression no File extension of the language. May be given multiple times. Defaults to the name of the language transformed to fit in 3 characters. String
java-package-id-prefix = $Expression no The prefix to add before all package identifiers in Java source files. Defaults to mb.$Name where $Name is transformed to be a valid package identifier. Qualified Java identifier
java-class-id-prefix = $Expression no The prefix to add before all Java classes. Defaults to the name of the language transformed to be a valid class identifier. Java identifier
source-directory = $Expression no Path relative to the root directory that has the sources of the language definition. Defaults to src. Path
build-directory = $Expression no Path relative to the root directory that has the generated sources and build outputs when building the language definition. Defaults to build. Path

Commands

Commands are sections that are also expressions, typically assigned to a name with a let binding, with the following form:

let $Name = command-def {
  $CommandOption*
}

The following options are available in a command:

Syntax Required? Description Type
task-def = $Expression yes The task definition that the command will execute. Qualified Java identifier that represents a task definition, or qualified Java identifier
type = $Expression no The fully qualified Java type we want this command to be generated as. Can be omitted to generate a type based on the name of the task definition. Qualified Java identifier
display-name = $Expression yes The display name of the command. String
description = $Expression no The optional description of the command. String
supported-execution-types = [($ExecutionType ,)*] no The optional supported execution types of the command. Defaults to [Once, Continuous]. n/a
args-type = $Expression no The fully qualified Java type of the argument class. Can be omitted if the argument class is a nested class named Args of the task definition. Qualified Java identifier
parameters = [ $Parameter* ] yes The description of the parameters of the command n/a

The following ExecutionTypes are supported:

  • Once indicates a that this command supports being executed as a one-shot command.
  • Continuous indicates that this command supports being executed every time the source file changes.

A $Parameter has the form $Identifier { $ParameterOptions } with the following options:

Syntax Required? Description Type
type = $Expression yes The fully qualified Java of the type of the parameter. This must match the type of the parameter inside the args-type of the command. Qualified Java identifier
required = $Expression no Whether the parameter is required. Defaults to true. Boolean
converter-type = $Expression no The argument converter for this parameter, which can convert a String value to the type of this parameter. Must implement the ArgConverter interface. Qualified Java identifier
argument-providers = [($ArgumentProvider ,)*] no Argument providers for this parameter that attempt to automatically provide a fitting argument. When providing an argument fails, the next argument provider in the list will be attempted. If no arguments can be provided, and the argument is required, then the argument must be provided by the user that executes the command, or executing the command will fail. n/a

The following ArgumentProviders are supported:

  • Value($Expression) provides a default value given by the expression. The expression must match the type of the parameter, even though this is not currently checked.
  • Context($CommandContext) attempts to infer the argument by context. The following CommandContexts are supported:
    • Directory: attempt to infer a ResourcePath to an existing directory. For example, when right-clicking a directory in an IDE to execute a command on that directory.
    • File: attempt to infer a ResourcePath to an existing file. For example, when right-clicking a file in an IDE to execute a command on that directory, or when executing a command in an editor for a file.
    • HierarchicalResource: attempt to infer a ResourcePath to a hierarchical resource. A hierarchical resource is a resource that belongs to a (tree) hierarchy, such as a file or directory on the local filesystem. Use this when the command relies on the resource being in a filesystem, but does not care whether it is a directory or a file.
    • ReadableResource: attempt to infer a ResourceKey to a readable resource. This is more general than File, as we only ask for a resource that can be read, not one that belongs to a (local) filesystem. Use this when the command does not rely on the resource being in a filesystem.
    • Region: attempt to infer a Region in a source file. Inference succeeds when the context has a selection of size 1 or larger. For example, when executing a command in an editor that has a selection, the region will be that selection.
    • Offset: attempt to infer an int representing an offset in a source file. Inference succeeds when the context has a cursor offset (i.e., a selection of size 0 or larger). For example, when executing a command in an editor, the offset will be the offset to the cursor in the editor.
  • EnclosingContext($EnclosingCommandContext) attempts to infer the argument by the enclosing context. The following EnclosingCommandContexts are supported:
    • Project: attempt to infer a ResourcePath to the enclosing project. For example, when executing a command in an IDE on a file, directory, or editor for a file, that belongs to a project. Or when executing a command in a CLI, the directory will be the current working directory.
    • Directory: attempt to infer a ResourcePath to the enclosing directory. For example, when executing a command in the context of a file, directory, or editor for a file, the directory will be the parent of that file/directory.

Here is an example of a command that shows the parsed AST by taking one file argument that is inferred from context:

let showParsedAstCommand = command-def {
  type = java mb.helloworld.command.HelloWorldShowParsedAstCommand
  task-def = showParsedAst
  args-type = java mb.helloworld.task.HelloWorldShowParsedAst.Args
  display-name = "Show parsed AST"
  description = "Shows the parsed AST"
  supported-execution-types = [Once, Continuous]
  parameters = [
    file = parameter {
      type = java mb.resource.ResourceKey
      required = true
      argument-providers = [Context(ResourceKey)]
    }
  ]
}

Menu items take the form of:

  • a separator representing a horizontal line in a menu used to separate groups of menu items.
  • a menu $Expression [ $MenuItem* ] representing a (nested) menu with a display name defined by the expression which must be a string, and a list of nested menu items.
  • a command-action { $CommandActionOption* } representing an action that executes a command when a user clicks on it.

A command action has the following options:

Syntax Required? Description Type
command-def = $Expression yes The command to execute. Command or qualified Java identifier
execution-type = $ExecutionType yes How the command should be executed. n/a
required-resource-types = [($ResourceType ,)*] no On which kinds of resources this menu item will be shown on resource context menus. Defaults to empty. If empty, it will not be hidden based on resources. n/a
required-enclosing-resource-types = [($EnclosingResourceType ,)*] no On which kinds of enclosing resources this menu item will be shown on resource context menus. Defaults to empty. If empty, it will not be hidden based on enclosing resource. n/a
required-editor-file-types = [($EditorFileType ,)*] no On which kinds of editors belonging to certain file types this menu item will be shown. Defaults to empty. If empty, it will not be hidden based on editor file types. n/a
required-editor-selection-types = [($EditorSelectionType ,)*] no On which kinds of editor selection types this menu item will be shown. Defaults to empty. If empty, it will not be hidden based on editor selections. n/a
display-name = $Expression no The display name of the command action. Defaults to the display name of the command String
description = $Expression no The description of he command action. Defaults to the description of the command String

The following ResourceTypes are supported:

  • Directory: the menu item will only be shown when a directory is selected.
  • File: the menu item will only be shown when a file is selected.

The following EnclosingResourceTypes are supported:

  • Project: the menu item will only be shown when the selected resource has an enclosing project.
  • Directory:: the menu item will only be shown when the selected resource has an enclosing directory.

The following EditorFileTypes are supported:

  • HierarchicalResource: the menu item will only be shown when the editor belongs to a hierarchical resource. That is, a resource that belongs to a tree, such as a file or directory on the local filesystem.
  • ReadableResource: the menu item will only be shown when the editor belongs to a readable resource.

The following EditorSelectionTypes are supported:

  • Region: the menu item will only be shown when a region with size >0 in the source file is selected.
  • Offset: the menu item will only be shown in the context of an editor with a cursor.

Menu items are assigned to 3 particular menus:

  • editor-context-menu [ $MenuItem* ]: the context menu that gets shown in editors of the language, for example when right-clicking in an editor of the language in an IDE. Spoofax automatically creates a top-level submenu with the name of the language to host the editor context menu items. The required-editor-file-types and required-editor-selection-types options are used to filter menu items.
  • resource-context-menu [ $MenuItem* ]: the context menu that gets shown in resource explorers, for example when right-clicking in the file browser in an IDE. Spoofax automatically creates a top-level submenu with the name of the language to host the editor context menu items. The required-resource-types and required-enclosing-resource-types options are used to filter menu items.
  • main-menu [ $MenuIitem* ]: the main menu of the language, which is shown on the menu bar in IDEs. When no main-menu section is given, it defaults to the same menu as editor-context-menu.

For example, we can assign the command defined earlier to several menus:

editor-context-menu [
  menu "Debug" [
    command-action {
      command-def = showParsedAstCommand
      execution-type = Once
    }
    command-action {
      command-def = showParsedAstCommand
      execution-type = Continuous
    }
  ]
]
resource-context-menu [
  menu "Debug" [
    command-action {
      command-def = showParsedAstCommand
      execution-type = Once
      required-resource-types = [File]
    }
  ]
]

Language feature sections

Parser

The parser { $ParserOption* } section enables generation of a parser, and groups options. The sdf3 section must be enabled when the parser section is enabled. The following ParserOptions are supported:

Syntax Required? Description Type
default-start-symbol = $Expression yes The start symbol to use when no specific one is provided. SDF3 sort identifier
variant = $ParserVariant no The parser variant to use. Defaults to jsglr1. n/a

The following ParserVariants are supported:

  • jsglr1: uses the JSGLR1 parser.
  • jsglr2 { $Jsglr2Option* }: uses the JSGLR2 parser. The following Jsglr2Options are supported:
    • preset = $Jsglr2Preset: sets the JSGLR2 preset to use. The following Jsglr2Presets are supported:
      • Standard
      • Elkhound
      • Recovery
      • RecoveryElkhound
      • DataDependent
      • LayoutSensitive
      • Composite
      • Incremental
      • IncrementalRecovery

Comment symbols

The comment-symbols { $CommentSymbolOption* } section enables specification of line and block comment characters, which are required for the "toggle comment" editor service. The following CommentSymbolOptions are supported:

Syntax Required? Description Type
line = $Expression no Adds a line comment symbol. Can be given multiple times to list multiple line comment symbols. The first one will be used to comment a line with the "toggle comment" editor service. String
block = $Expression * $Expression no Adds block comment symbols, with an opening and close symbol. Current "toggle comment" editor services do not use block comment symbols yet. String

Bracket symbols

The bracket-symbols { $BracketSymbolOption* } section enables specification of bracket symbols (e.g., square brackets, curly brackets, parentheses, etc.), which are required for the "bracket matching" editor service. The following BracketSymbolOptions are supported:

Syntax Required? Description Type
bracket = $Expression * $Expression no Adds bracket symbols, with an opening and closing symbol. Can be given multiple times to list multiple bracket symbols. Character

Styler

The styler { $StylerOption* } section enables generation of a styler, and groups options. The esv section must be enabled when the styler section is enabled. Currently, no StylerOptions are supported.

Constraint analyzer

The constraint-analyzer { $ConstraintAnalyzerOption* } section enables generation of a constraint analyzer, and groups options. The statix section must be enabled when the constraint-analyzer section is enabled. The following ConstraintAnalyzerOptions are supported:

Syntax Required? Description Type
multi-file = $Expression no Whether multi-file analysis is enabled. Defaults to false. Boolean
stratego-strategy = $Expression no The stratego strategy entry-point that handles communication with the constraint-solver. Defaults to editor-analyze. Stratego strategy identifier
default-statix-message-stacktrace-length = $Expression no The default Statix message stacktrace length to use. Default is implementation-defined. Does nothing if Statix is not enabled. Unsigned integer
default-statix-message-term-depth = $Expression no The default Statix message term depth to use. Default is implementation-defined. Does nothing if Statix is not enabled. Unsigned integer
default-statix-test-log-level = $Expression no The default Statix test log level to use. Default is implementation-defined. Does nothing if Statix is not enabled. String
default-statix-supress-cascading-errors = $Expression no Whether to suppress cascading errors by default. Default is implementation-defined. Does nothing if Statix is not enabled. Boolean
statix-solver-mode = $StatixSolverMode no Statix solver mode. Defaults to traditional. Does nothing if Statix is not enabled. n/a

The following StatixSolverModes are supported:

  • traditional
  • concurrent
  • incremental

Multi-language analyzer

The multilang-analyzer { $MultilangAnalyzerOption* } section enables generation of a multi-language analyzer, and groups options. The constraint-analyzer and statix sections must be enabled when the multilang-analyzer section is enabled. Currently, no MultilangAnalyzerOptions are supported.

Stratego runtime

The stratego-runtime { $StrategoRuntimeOption* } section enables generation of a stratego runtime, and groups options. The stratego section must be enabled when the stratego-runtime section is enabled. The following StrategoRuntimeOptions are supported:

Syntax Required? Description Type
strategy-package-id = $Expression no Adds a package as a private Stratego package. Can be specified multiple times. Java package identifier
interop-registerer-by-reflection = $Expression no Adds an interop registerer to load by reflection. Can be specified multiple times. Java type identifier
add-spoofax2-primitives = $Expression no Whether to add the Spoofax 2 Stratego primitives. Boolean
add-nabl2-primitives = $Expression no Whether to add the NaBL2 Stratego primitives. Boolean
add-statix-primitives = $Expression no Whether to add the Statix Stratego primitives. Boolean
with-primitive-library = $Expression no Adds a Stratego primitive strategies library (implementing org.spoofax.interpreter.library.IOperatorRegistry) to the generated StrategoRuntimeBuilderFactory. The library must have an @Inject constructor. Can be specified multiple times. Java type identifier
with-interop-registerer = $Expression no Adds a Stratego interop registerer (implementing org.strategoxt.lang.InteropRegisterer) to the generated StrategoRuntimeBuilderFactory. The registerer must have an @Inject constructor. Can be specified multiple times. Java type identifier
class-kind = $Expression no Specifies whether the classes are generated (Generated) or provided manually (Manual). Defaults to Generated. Generated or Manual
base-StrategoRuntimeBuilderFactory = $Expression no Package and name of the generated StrategoRuntimeBuilderFactory. Java type identifier
extend-StrategoRuntimeBuilderFactory = $Expression no Package and name of the extending StrategoRuntimeBuilderFactory, if any. Java type identifier

Completer

The completer { $CompleterOption* } section enables generation of a code completer, and groups options. The constraint-analyzer and statix sections must be enabled when the completer section is enabled. Currently, no CompleterOptions are supported.

Reference resolution

The reference-resolution { $ReferenceResolutionOption* } section enables generation of the reference resolver editor service, and groups options. The following ReferenceResolutionOptions are supported:

Syntax Required? Description Type
variant = $ReferenceResolutionVariant yes The reference resolution variant to use. n/a

The following ReferenceResolutionVariants are supported:

  • Stratego-based: stratego { strategy = strategy $Strategy } where Strategy is a Stratego strategy, typically editor-resolve.

Hover tooltips

The hover { $HoverOption* } section enables generation of the hover text editor service, and groups options. The following HoverOptions are supported:

Syntax Required? Description Type
variant = $HoverVariant yes The reference resolution variant to use. n/a

The following HoverVariants are supported:

  • Stratego-based: stratego { strategy = strategy $Strategy } where Strategy is a Stratego strategy, typically editor-hover.

Meta-language sections

SDF3

The sdf3 { $Sdf3Option* } section enables syntax definition with SDF3. The parser section must be enabled when the sdf3 section is enabled. The following Sdf3Options are supported:

Syntax Required? Description Type
source = $Sdf3Source no The source of the SDF3 definition. Defaults to a files source with the top-level source-directory option as its main source directory, and ./start.sdf3 as its main file relative to the main source directory. n/a

The following $Sdf3Sources are supported:

  • Files: files { $Sdf3FilesOption* }
  • Prebuilt: prebuilt { $Sdf3PrebuiltOption }

The following Sdf3FilesOptions are supported:

Syntax Required? Description Type
main-source-directory = $Expression no The directory relative to the root directory that contains the main SDF3 file. Defaults to the value of the top-level source-directory option. Path
main-file = $Expression no The main SDF3 file relative to the main-source-directory. Defaults to ./start.sdf3. Path
include-directory = $Expression no Adds an include directory from which to resolve SDF3 imports. May be given multiple times. Path
export-directory = $Expression no Exports a directory, making the SDF3 files in it accessable to dependencies. May be given multiple times. Path
parse-table-generator { $ParseTableGeneratorOption* } no Parse table generator options. n/a
stratego-concrete-syntax-extension-main-file = $Expression no Sets the main SDF3 file used to create a concrete syntax extension parse table. Path

The following $Sdf3PrebuiltOptions are supported:

Syntax Required? Description Type
parse-table-aterm-file = $Expression yes The prebuilt SDF3 parse table ATerm file to use (usually called sdf.tbl) relative to the root directory Path
parse-table-persisted-file = $Expression yes The prebuilt SDF3 parse table persisted file to use (usually called sdf.bin) relative to the root directory Path

The following ParseTableGeneratorOptions are supported:

Syntax Required? Description Type
dynamic = $Expression no Whether the generated parse table is dynamic. Defaults to false. Boolean
data-dependent = $Expression no Whether the generated parse table is data-dependent. Defaults to false. Boolean
layout-sensitive = $Expression no Whether the generated parse table is layout-sensitive. Defaults to false. Boolean
solve-deep-conflicts = $Expression no Whether the parse table generator solves deep priority conflicts. Defaults to true. Boolean
check-overlap = $Expression no Whether the parse table generator checks for overlap. Defaults to false. Boolean
check-priorities = $Expression no Whether the parse table generator checks priorities. Defaults to false. Boolean

ESV

The esv { $EsvOption* } section enables syntax-based styling definition with ESV. The styler section must be enabled when the esv section is enabled. The following EsvOptions are supported:

Syntax Required? Description Type
source = $EsvSource no The source of the ESV definition. Defaults to a files source with the top-level source-directory option as its main source directory, and ./main.esv as its main file relative to the main source directory. n/a

The following $EsvSources are supported:

  • Files: files { $EsvFilesOption* }
  • Prebuilt: prebuilt { $EsvPrebuiltOption }

The following EsvFilesOptions are supported:

Syntax Required? Description Type
main-source-directory = $Expression no The directory relative to the root directory that contains the main ESV file. Defaults to the value of the top-level source-directory option. Path
main-file = $Expression no The main ESV file relative to the main-source-directory. Defaults to ./main.esv. Path
include-directory = $Expression no Adds an include directory from which to resolve ESV imports. May be given multiple times. Path
export-directory = $Expression no Exports a directory, making the ESV files in it accessable to dependencies. May be given multiple times. Path

The following $EsvPrebuiltOptions are supported:

Syntax Required? Description Type
file = $Expression yes The prebuilt ESV file to use relative to the root directory Path

Statix

The statix { $StatixOption* } section enables static semantics definition with Statix. The constraint-anaylzer section must be enabled when the statix section is enabled. The following StatixOptions are supported:

Syntax Required? Description Type
source = $StatixSource no The source of the Statix definition. Defaults to a files source with the top-level source-directory option as its main source directory, and ./main.stx as its main file relative to the main source directory. n/a

The following $StatixSources are supported:

  • Files: files { $StatixFilesOption* }
  • Prebuilt: prebuilt { $StatixPrebuiltOption }

The following StatixFilesOptions are supported:

Syntax Required? Description Type
main-source-directory = $Expression no The directory relative to the root directory that contains the main Statix file. Defaults to the value of the top-level source-directory option. Path
main-file = $Expression no The main Statix file relative to the main-source-directory. Defaults to ./main.stx. Path
include-directory = $Expression no Adds an include directory from which to resolve Statix imports. May be given multiple times. Path
export-directory = $Expression no Exports a directory, making the Statix files in it accessable to dependencies. May be given multiple times. Path
sdf3-statix-signature-generation = $Expression no Whether SDF3 to Statix signature generation is enabled. When enabled, stratego { sdf3-statix-explication-generation = true } must also be enabled. Defaults to false. Boolean

The following $StatixPrebuiltOptions are supported:

Syntax Required? Description Type
spec-aterm-directory = $Expression yes The prebuilt Statix spec ATerm directory to use relative to the root directory Path

Stratego

The stratego { $StrategoOption* } section enables definition of transformations with Stratego. The stratego-runtime section must be enabled when the stratego section is enabled. The following StrategoOptions are supported:

Syntax Required? Description Type
source = $StrategoSource no The source of the Statix definition. Defaults to a files source with the top-level source-directory option as its main source directory, and ./main.str2 as its main file relative to the main source directory. n/a
output-java-package = $Expression no The Java package into which compiled Stratego Java files are generated. Defaults to the language's package, followed by .strategies. String

The following $StrategoSources are supported:

  • Files: files { $StrategoFilesOption* }

The following $StrategoFilesOptions are supported:

Syntax Required? Description Type
main-source-directory = $Expression no The directory relative to the root directory that contains the main Stratego file. Defaults to the value of the top-level source-directory option. Path
main-file = $Expression no The main Stratego file relative to the main-source-directory. Defaults to ./main.str2. Path
include-directory = $Expression no Adds an include directory from which to resolve Stratego imports. May be given multiple times. Path
export-directory = $Expression no Exports a directory, making the Stratego files in it accessable to dependencies. May be given multiple times. Path
with-import-strategy-package-id = $Expression no Adds a Java package to import in the Java files that have been compiled from Stratego files. For example, "mb.mylang.strategies" adds import import mb.mylang.strategies.*. May be given multiple times. String
sdf3-statix-explication-generation = $Expression no Whether SDF3 to Statix injection explication/implication generation is enabled. When enabled, statix { sdf3-statix-signature-generation = true } must also be enabled. Defaults to false. Boolean
language-strategy-affix = $Expression no The affix that is used to make certain generated strategies unique to the language. This is used both as a prefix and suffix. Defaults to name of the language transformed to a Stratego strategy identifier. Stratego strategy identifier
concrete-syntax-extension-parse-table = $Expression no Adds a Stratego concrete syntax extension parse table that can be used to parse Stratego files with. May be given multiple times. Path

Dependencies

The dependencies [ $Dependency* ] section allows specifying dependencies to other language (library) projects. A dependency consists of a dependency expression ($Exp) that specifies the source of the dependency. The following expressions are supported:

  • $Coordinate: an exact coordinate to a project, such as org.metaborg:strategolib:1.0.0. Coordinates are resolved to a statically loaded language, or a dynamically loaded language definition.
  • $CoordinateRequirement: a coordinate to a project with an open version, such as org.metaborg:strategolib:*, resolved identically to $Coordinate except that the latest available version will be chosen.
  • $Path: a relative path (relative to the directory spoofaxc.cfg is in) to a language definition.

Dependencies can be of a certain kind ($DependencyKind):

  • Build: a dependency that is resolved at build time, meaning when the language definition is built, allowing the use of sources and binaries of the project the dependency points to.
  • Run: a dependency that is resolved at run time, meaning when the language is executed, allowing use of the classes and tasks of the project the dependency points to. Note: this kind of dependency has not yet been implemented.

The following Dependencys are supported:

Syntax Description
$Exp A dependency to a project defined by the expression, available at Build and Run time.
$Exp { $DependencyOption* } A dependency to project defined by the expression, with configuration options.

The following DependencyOptions are supported:

  • kinds = [ $DependencyKind* ]: set the kinds at which this dependency is resolved.

Additionally, build time dependencies can be quickly defined with the build-dependencies [ $BuildDependency* ] section. The following BuildDependencys are supported:

Syntax Description
$Exp A dependency to project defined by the expression, available only at Build time.

For example, the following configuration adds build dependencies to common libraries shipped with Spoofax 3:

build-dependencies [
  org.metaborg:strategolib:*
  org.metaborg:gpp:*
  org.metaborg:libspoofax2:*
  org.metaborg:libstatix:*
]

spoofaxc.lock

The spoofaxc.lock file, which resides next to the spoofaxc.cfg file, contains values for several options that have defaults derived from other options, in order to keep these derived values stable even when the options they are derived from are changed. For example, when no java-class-id-prefix option is set in spoofaxc.cfg, it will be derived from the name option with some changes to make it compatible as a Java identifier, and is stored under shared.defaultClassPrefix in the spoofaxc.lock file. When you change the name of your language, the stored value will be used, keeping the class prefix the same, making it possible to rename the language without having to rename all class files. Therefore, the spoofaxc.lock file should be checked in to source control, in order to have reproducible builds.

If you do want to re-derive a default from other options, remove the option from the spoofaxc.lock file and rebuild the language. The value will be re-derived and stored in spoofaxc.lock, after which you need to check it into source control again.