MPS Build Language

The MPS Build Language is a declarative DSL (a stack of MPS languages on top of Ant) that generates an Apache Ant build.xml file. It is used to package MPS-language plugins, build standalone IDE/RCP distributions, package plain Java modules, and run MPS tests or generation-diff tests. Build scripts are root nodes of concept BuildProject inside a regular solution module; pressing Make on that solution runs a generator that writes build.xml to disk.

Critical Directives

• The generator writes build.xml — it does not invoke Ant. To produce artifacts you must run ant separately (from MPS right-click → Run, or from the command line in the generated folder).
• Build scripts are MPS nodes. Edit them via projectional editing or mps_mcp_* JSON tools. Never hand-edit the .mps file as if it were Ant XML.
• Declaring a module in BuildProject.parts does not cause it to be built. Only items referenced from the layout end up in the output. parts is declaration; layout is packaging.
• Build scripts compile languages but do not regenerate them. Generate languages to Java first (or enable the mps build plugin's full-make task) before running Ant.
• Always import jetbrains.mps.ide.build (422c2909-59d6-41a9-b318-40e6256b250f) on the build solution — it is the catalog of well-known externals (IDEA, mps, mpsStandalone, JDK, MPS modules).
• After every change to a module's .mpl / .msd, re-run the Load required information from file intention on the matching BuildMps_* node. Build-script module dependencies must match the actual .mpl declarations or the chunk generator throws "class not found".
• A BuildMps_Group must contain the transitive closure of language dependencies. Missing members appear as red squiggles at generation time.
• Always set internalBaseDirectory — every relative path is resolved against it.

Common-Path Workflow

For a typical "package an MPS language as an installable plugin" task:

1. Create the build solution. A regular solution (not language) named <project>.build. In its .msd, add a dependency on jetbrains.mps.ide.build and declare languages jetbrains.mps.build and jetbrains.mps.build.mps. Set Java facet compile="mps" classes="mps". See references/solution-setup.md.
2. Create the model (conventionally <project>.build) with the same languages as used languages.
3. Insert the BuildProject root with name, internalBaseDirectory, compactBuildScriptFileName. Use mps_mcp_insert_root_node_from_json with the skeleton in references/buildproject-skeleton.md.
4. Add plugins to BuildProject.plugins: at minimum BuildJavaPlugin and BuildMPSPlugin. Add BuildModuleTestsPlugin / BuildSolutionRunnerPlugin only when needed (see references/plugins-and-macros.md).
5. Declare macros (mps_home, optionally idea_home, plus version/timestamp Var macros) — see references/plugins-and-macros.md.
6. Add external dependencies to BuildProject.dependencies for mps (or mpsStandalone) and IDEA, wired to macro paths — see references/dependencies.md.
7. Add parts: one BuildSource_JavaOptions, then a BuildMps_Language / _Solution / _Generator per MPS module (call Load required information from file on each), wrapped in BuildMps_Groups. Add a BuildMps_IdeaPlugin whose content references the groups. See references/mps-modules.md and references/idea-plugins.md.
8. Define the layout: one BuildLayout root, typically wrapping a BuildLayout_Zip named <plugin>.zip, with one BuildMpsLayout_Plugin (AutoPluginLayoutType) per plugin. See references/layouts.md.
9. Make the build solution (Ctrl-F9 on the model) — this writes build.xml at internalBaseDirectory/compactBuildScriptFileName.
10. Run Ant from MPS (right-click BuildProject → Run) or ant -Dmps_home=/path/to/MPS … from the generated folder. Artifacts land in ./build/artifacts.

For other task families: standalone IDE distributions → references/standalone-ide.md; plain Java packaging → references/java-parts.md; tests → references/tests-and-workflow.md.

Disambiguation — Don't Conflate These

Four "dependency" concepts and two "aspect" concepts are routinely confused. See references/disambiguation.md for the full table before designing dependencies or parts. Quick rule:

• Solution .msd deps = what the build solution itself needs at edit time (just jetbrains.mps.ide.build).
• BuildProject.dependencies = references to other build scripts or external layouts (mps, IDEA).
• BuildSource_JavaModule.content deps = classpath of a plain Java module.
• BuildMps_*.dependencies = mirror of the actual .mpl / .msd, auto-filled by Load required information from file.

Related Skills

• mps-distribution-build — the generated Ant pipeline (build/mps*.xml) that builds MPS distributions; complements this skill for bundling plain Java/Kotlin plugins into MPS.
• mps-ide-plugin — authoring the contents of an MPS/IDEA plugin (actions, tool windows, keymaps). The build language packages the result.
• mps-aspect-accessories — module dependencies, used languages, runtime solutions, accessory models. The build script's BuildMps_* deps must match these.
• mps-lang-core-xml — needed when embedding raw XML for plugin.xml enrichment, custom plugin.xml, or BwfAntStatement raw Ant commands.
• mps-tests — NodeTestCase / EditorTestCase test models that BuildAspect_MpsTestModules runs.
• mps-mcp-workflow, mps-node-editing — node creation and validation conventions used by every mps_mcp_* example here.

Reference Index

• Open references/solution-setup.md when creating the build solution and model — .msd content, Java facet settings, used languages, naming conventions, where to find existing build scripts in this repo.
• Open references/buildproject-skeleton.md when inserting or modifying the BuildProject root — JSON skeleton, top-level properties (name, internalBaseDirectory, compactBuildScriptFileName), the role → XML-id table for plugins / macros / dependencies / parts / layout.
• Open references/plugins-and-macros.md when adding build-language plugins or macros — BuildJavaPlugin / BuildMPSPlugin / BuildModuleTestsPlugin / BuildSolutionRunnerPlugin, BuildFolderMacro, BuildVariableMacro initializers (InitWithString, InitWithDate, InitWithPropertyFile, InitWithFileContent), BuildString composition.
• Open references/dependencies.md when wiring inter-script dependencies — BuildExternalLayoutDependency (external prebuilt artifacts like IDEA, mps) vs BuildProjectDependency (sibling build scripts), how to point at named layouts in jetbrains.mps.ide.build, when to omit artifact paths.
• Open references/mps-modules.md when declaring BuildMps_Language / BuildMps_Solution / BuildMps_Generator — minimal JSON, child roles (path, sources, dependencies, runtime, generator), dependency wiring via BuildMps_ExtractedModuleDependency, the compact=true convention, Load required information from file intention, common target modules in jetbrains.mps.ide.build.
• Open references/groups.md when grouping modules via BuildMps_Group — group semantics, transitive-closure rule, when to nest modules inside a group vs leave them at parts level.
• Open references/idea-plugins.md when declaring or packaging an IDEA plugin — BuildMps_IdeaPlugin part vs BuildMpsLayout_Plugin layout entry, fields (id, name, version, containerName, content, dependencies), the three plugin.xml strategies (synthesize / enrich / custom), AutoPluginLayoutType vs ManualPluginLayoutType.
• Open references/layouts.md when shaping the output tree — every layout concept (BuildLayout_Folder / _Zip / _Jar / _File / _Fileset / _ImportContent / _CopyOfContainer, BuildMpsLayout_ModuleJar, BuildMpsLayout_Plugin, BuildLayout_IdeaPlugin), the containerName pattern, typical MPS-plugin layout, plain-Java packaging example.
• Open references/java-parts.md when building plain Java modules or libraries — BuildSource_JavaOptions properties (compiler, javaLevel, heap, resource selectors), BuildSource_JavaModule with content roots and dependencies, BuildSource_JavaLibrary grouping, BuildSource_JavaDependencyJar / _OnModule / _OnLibrary.
• Open references/mps-settings.md when configuring BuildMpsAspect — bootstrap flag, testGeneration (the gentest Ant target plus Test.Generating / Test.Diffing), generationMaxHeapSizeInMB.
• Open references/tests-and-workflow.md when adding module tests or custom Ant statements — BuildAspect_MpsTestModules, BuildMps_TestModuleGroup, BuildMps_TestModule, BuildMps_RunCodeFromSolution, the jetbrains.mps.build.workflow language (BwfTask, BwfSubTask, BwfAntStatement, BwfTaskPart).
• Open references/standalone-ide.md when producing a standalone IDE / RCP distribution — mpsStandalone, branding, startup script, two-stage build, JBR lookup order on Windows/Linux/macOS, trust-dialog suppression, Tips and Tricks integration.
• Open references/disambiguation.md when confused about "dependency" or "aspect" terms — the four "dependency" meanings, "language aspect" vs "additional aspects / parts" vs BuildMps_IdeaPlugin vs BuildMpsLayout_Plugin, "project structure" UI tree vs the docs' "project structure section".
• Open references/ant-targets.md when debugging or extending the generated Ant build — every target the generator emits (compileJava, processResources, classes, test, check, generate, cleanSources, declare-mps-tasks, makeDependents, gentest), generation chunks, why dependency mismatches cause "class not found".
• Open references/concept-catalog.md when looking up concept FQNs and XML ids — full table of concepts under jetbrains.mps.build, jetbrains.mps.build.mps, jetbrains.mps.build.mps.tests, jetbrains.mps.build.mps.runner, jetbrains.mps.build.workflow, with role → XML-id pairs for raw .mps reading.
• Open references/common-failures.md when a build script misbehaves — generator complains about missing dependencies; module compiles but is missing from output; "class not found" mid-generation; group missing transitive members; com.intellij.modules.mps dependency missing; compiler="Eclipse" on Java 21+; hand-edited build.xml reverted.