MPS Distribution Build — Ant Pipeline & Plugin Bundling
This skill explains how the generated Ant scripts under build/mps*.xml assemble MPS distribution archives, and how to add a new plain Java/Kotlin plugin module (e.g. plugins/mcp-tools) so it ends up in the produced archives. Authoring the model that generates these Ant scripts is covered separately by mps-build-language — this skill focuses on the output side and the plugin-bundling touchpoints.
Critical Directives
- The Ant files are generated. All
build/mps*.xml files carry <!-- Generated by MPS -->. Do not hand-edit them as a permanent solution — author the change in plugins/mps-build/solutions/mpsBuild/models/build.mps and regenerate.
- A new per-plugin
BuildProject is invisible to the distribution until it is also wired into the mps aggregator BuildProject and mpsDistribution. A plugin can build into build/artifacts/<projectName>/ but never enter the final zip if mps.xml is not updated.
- IDEA platform jars under
<MPS>/lib/ and <MPS>/plugins/<idea-plugin>/lib/ are fetched by build.xml platform (Ivy via getDependencies.xml). They do not exist on a clean checkout, and no BuildProject declares the fetch. Every per-plugin script implicitly requires ant -f build/build.xml platform to have already run.
- There is no
${idea.plugins.dir} macro — do not invent one. Reference fetched IDEA-plugin jars via ${basedir}/plugins/<idea-plugin>/lib/ (matches the IDEA project libraries under .idea/libraries/*.xml).
- The
test/ source root is not part of the production jar. Test compilation belongs in a sibling test-only BuildProject (cf. mpsTesting.xml), not layered onto the production jar.
- Validate cheap first: regenerate, then run
ant -f build/<projectName>.xml assemble in isolation before running the full build/run_build.sh.
Common-Path Workflow — Bundle a New Plain Java/Kotlin Plugin
Running example: bundling plugins/mcp-tools (a JAVA_MODULE with Kotlin sources, depending on com.intellij.mcpServer).
- Diagnose where the plugin currently is.
grep -r <plugin-name> build/ (empty → no generated Ant script). Look under build/artifacts/<projectName>/, build/artifacts/mps/plugins/<x>/, and the final ${build.number}*.zip to find which layer is missing it. See references/diagnostics.md.
- Pick a shape. Model it like
mpsHttpSupportPlugin (Option A, preferred — full Ant compile pipeline) or like mcpserver / terminal (Option B — pre-built, copied from <MPS>/plugins/<x>/ by mpsStandalone). See references/plugin-bundling-options.md.
- Author in
build.mps. Add a BuildProject <projectName> with the right BuildLayout (Java/Kotlin source roots, META-INF/plugin.xml, jar packaging, dependencies via BuildSource_JavaDependencyModule / …ExternalJar). Carry the BuildJavaPlugin marker so the generator emits a plain compile pipeline. Depend on mpsBootstrapCore (and likely mpsCore / mpsWorkbench). See references/build-mps-authoring.md.
- Wire it into the aggregator. Edit the
mps aggregator BuildProject so it imports ${artifacts.<projectName>}, copies ${artifacts.<projectName>}/<plugin-folder> into ${build.layout}/plugins/<plugin-folder>, and invokes the new Ant file in its buildDependents. Add the same <ant antfile="build/<projectName>.xml" …/> line to mpsDistribution.xml's buildDependents.
- Regenerate
build.mps. A new build/<projectName>.xml will appear; build/mps.xml and build/mpsDistribution.xml will be updated by the same regeneration.
- Smoke step (no full build). Run
ant -f build/<projectName>.xml assemble in isolation. Pre-run ant -f build/build.xml platform once so the IDEA jars exist on disk.
- Full build via
build/run_build.sh. Verify the three artefact locations in references/validation.md.
- If the plugin has a
test/ source root, add a sibling test-only BuildProject (<projectName>Tests) — see references/test-suite-wiring.md.
Pipeline at a Glance
build.xml build.txt dependencies.properties
│ │ │
├─ platform ───────────► Ivy fetches IDEA + libs into <MPS>/lib, <MPS>/plugins/*
│ (getDependencies.xml)
│
├─ getResourcesAndBuildAll
│ └─ mpsDistribution.xml buildDependents
│ ├─ mpsTrueBootstrap.xml ──┐
│ ├─ mpsBootstrapCore.xml │ per-plugin Ant scripts
│ ├─ mpsCore.xml │ (compile + jar + layout into
│ ├─ mpsWorkbench.xml │ build/artifacts/<projectName>/)
│ ├─ mpsBuild.xml │
│ ├─ mpsTesting.xml │
│ ├─ mpsPlugins.xml │
│ ├─ mpsJava.xml │
│ ├─ mpsHttpSupportPlugin.xml│
│ ├─ mpsKotlinPlugin.xml │
│ ├─ mpsContextActionsTool.xml│
│ ├─ … (30+ files) ─┘
│ └─ mps.xml (aggregates into build/artifacts/mps/)
│
└─ assemble
└─ mpsDistribution.xml assemble (zips/tars into build/artifacts/mpsDistribution/)
Related Skills
mps-build-language — when you are authoring or editing the build language model itself, not just consuming its output.
mps-tests — when the plugin you are bundling has a JUnit / MPS test suite that must run in CI.
mps-ide-plugin — when the new module is an MPS IDE plugin (plugin.xml, actions, tool windows). Bundling and IDE-plugin authoring are independent steps.
mps-aspect-generator — when the failure is in MPS generation rather than packaging.
Reference Index
- Open
references/architecture.md for the long form of "how Ant files compose" — entry point build/build.xml targets, the three layers of generated scripts (mpsTrueBootstrap.xml/mpsBootstrapCore.xml/per-plugin files; mps.xml aggregator; mpsStandalone.xml), and the final distribution layer mpsDistribution.xml with its per-platform archives. Open when you need to know where a particular file lives in the pipeline or what its buildDependents does.
- Open
references/build-mps-source-of-truth.md when editing plugins/mps-build/solutions/mpsBuild/models/build.mps — explains the BuildProject structure, the meaning of opaque concept indices (1l3spW, 398b33, TrG5h, turDy, 2DA0ip, 1l3spV, 10PD9b), and how regeneration writes the build/*.xml files.
- Open
references/plugin-bundling-options.md to choose between Option A (full Ant compile pipeline like mpsHttpSupportPlugin) and Option B (pre-built drop into mpsStandalone). Includes the rationale for picking Option A for new MPS-authored plugins.
- Open
references/build-mps-authoring.md when adding the new BuildProject to build.mps — BuildLayout shape, BuildSource_JavaModule / BuildSource_JavaContentRoot, the BuildJavaPlugin marker, dependency chain through mpsBootstrapCore, and the convention for referencing fetched IDEA-plugin jars via ${basedir}/plugins/<idea-plugin>/lib/.
- Open
references/diagnostics.md when a plugin is missing from the distribution and you need to figure out which layer dropped it — three-step diagnosis using grep, build/artifacts/<projectName>/, and build/artifacts/mps/plugins/<x>/.
- Open
references/validation.md for the two-stage validation procedure (cheap ant -f build/<projectName>.xml assemble smoke step, then full build/run_build.sh) and the three artefact locations to verify after a full build.
- Open
references/touchpoint-checklist.md for the table of files modified by adding a new Option A plugin — what is hand-edited (build.mps), what is regenerated (build/<projectName>.xml, build/mps.xml, build/mpsDistribution.xml), and what stays unchanged (plugins/<plugin>/META-INF/plugin.xml, .iml).
- Open
references/test-suite-wiring.md when the new plugin has a test/ source root that must run in CI — sibling test-only BuildProject, JUnit launcher, and …Tests.xml aggregator wiring.
- Open
references/key-files.md for the quick reference of every build file mentioned anywhere in this skill, with one-line descriptions.
1---2name: mps-distribution-build3description: Use when bundling a new plain Java/Kotlin plugin into MPS distribution archives, debugging packaging/layout issues in `build/mps*.xml`, tracing where per-plugin artefacts end up, or editing `plugins/mps-build/solutions/mpsBuild/models/build.mps` (the source of truth that generates every `build/mps*.xml`). The skill covers the generated Ant pipeline, plugin-to-distribution wiring, and the per-plugin / aggregator / distribution layers.4type: reference5metadata:6 source: https://skillmd.com/skills/jetbrains/mps-distribution-build7---89# MPS Distribution Build — Ant Pipeline & Plugin Bundling1011This skill explains how the generated Ant scripts under `build/mps*.xml` assemble MPS distribution archives, and how to add a new plain Java/Kotlin plugin module (e.g. `plugins/mcp-tools`) so it ends up in the produced archives. Authoring the model that *generates* these Ant scripts is covered separately by `mps-build-language` — this skill focuses on the **output side** and the plugin-bundling touchpoints.1213## Critical Directives1415- **The Ant files are generated.** All `build/mps*.xml` files carry `<!-- Generated by MPS -->`. Do not hand-edit them as a permanent solution — author the change in `plugins/mps-build/solutions/mpsBuild/models/build.mps` and regenerate.16- A new per-plugin `BuildProject` is invisible to the distribution until it is **also** wired into the `mps` aggregator BuildProject and `mpsDistribution`. A plugin can build into `build/artifacts/<projectName>/` but never enter the final zip if `mps.xml` is not updated.17- IDEA platform jars under `<MPS>/lib/` and `<MPS>/plugins/<idea-plugin>/lib/` are fetched by `build.xml platform` (Ivy via `getDependencies.xml`). They do **not** exist on a clean checkout, and no `BuildProject` declares the fetch. Every per-plugin script implicitly requires `ant -f build/build.xml platform` to have already run.18- There is **no `${idea.plugins.dir}` macro** — do not invent one. Reference fetched IDEA-plugin jars via `${basedir}/plugins/<idea-plugin>/lib/` (matches the IDEA project libraries under `.idea/libraries/*.xml`).19- The `test/` source root is not part of the production jar. Test compilation belongs in a sibling test-only `BuildProject` (cf. `mpsTesting.xml`), not layered onto the production jar.20- Validate cheap first: regenerate, then run `ant -f build/<projectName>.xml assemble` in isolation **before** running the full `build/run_build.sh`.2122## Common-Path Workflow — Bundle a New Plain Java/Kotlin Plugin2324Running example: bundling `plugins/mcp-tools` (a `JAVA_MODULE` with Kotlin sources, depending on `com.intellij.mcpServer`).25261. **Diagnose where the plugin currently is.** `grep -r <plugin-name> build/` (empty → no generated Ant script). Look under `build/artifacts/<projectName>/`, `build/artifacts/mps/plugins/<x>/`, and the final `${build.number}*.zip` to find which layer is missing it. See `references/diagnostics.md`.272. **Pick a shape.** Model it like `mpsHttpSupportPlugin` (Option A, preferred — full Ant compile pipeline) or like `mcpserver` / `terminal` (Option B — pre-built, copied from `<MPS>/plugins/<x>/` by `mpsStandalone`). See `references/plugin-bundling-options.md`.283. **Author in `build.mps`.** Add a `BuildProject <projectName>` with the right `BuildLayout` (Java/Kotlin source roots, `META-INF/plugin.xml`, jar packaging, dependencies via `BuildSource_JavaDependencyModule` / `…ExternalJar`). Carry the `BuildJavaPlugin` marker so the generator emits a plain compile pipeline. Depend on `mpsBootstrapCore` (and likely `mpsCore` / `mpsWorkbench`). See `references/build-mps-authoring.md`.294. **Wire it into the aggregator.** Edit the `mps` aggregator BuildProject so it imports `${artifacts.<projectName>}`, copies `${artifacts.<projectName>}/<plugin-folder>` into `${build.layout}/plugins/<plugin-folder>`, and invokes the new Ant file in its `buildDependents`. Add the same `<ant antfile="build/<projectName>.xml" …/>` line to `mpsDistribution.xml`'s `buildDependents`.305. **Regenerate** `build.mps`. A new `build/<projectName>.xml` will appear; `build/mps.xml` and `build/mpsDistribution.xml` will be updated by the same regeneration.316. **Smoke step (no full build).** Run `ant -f build/<projectName>.xml assemble` in isolation. Pre-run `ant -f build/build.xml platform` once so the IDEA jars exist on disk.327. **Full build** via `build/run_build.sh`. Verify the three artefact locations in `references/validation.md`.338. If the plugin has a `test/` source root, add a sibling test-only `BuildProject` (`<projectName>Tests`) — see `references/test-suite-wiring.md`.3435## Pipeline at a Glance3637```38build.xml build.txt dependencies.properties39 │ │ │40 ├─ platform ───────────► Ivy fetches IDEA + libs into <MPS>/lib, <MPS>/plugins/*41 │ (getDependencies.xml)42 │43 ├─ getResourcesAndBuildAll44 │ └─ mpsDistribution.xml buildDependents45 │ ├─ mpsTrueBootstrap.xml ──┐46 │ ├─ mpsBootstrapCore.xml │ per-plugin Ant scripts47 │ ├─ mpsCore.xml │ (compile + jar + layout into48 │ ├─ mpsWorkbench.xml │ build/artifacts/<projectName>/)49 │ ├─ mpsBuild.xml │50 │ ├─ mpsTesting.xml │51 │ ├─ mpsPlugins.xml │52 │ ├─ mpsJava.xml │53 │ ├─ mpsHttpSupportPlugin.xml│54 │ ├─ mpsKotlinPlugin.xml │55 │ ├─ mpsContextActionsTool.xml│56 │ ├─ … (30+ files) ─┘57 │ └─ mps.xml (aggregates into build/artifacts/mps/)58 │59 └─ assemble60 └─ mpsDistribution.xml assemble (zips/tars into build/artifacts/mpsDistribution/)61```6263## Related Skills6465- `mps-build-language` — when you are authoring or editing the build language model itself, not just consuming its output.66- `mps-tests` — when the plugin you are bundling has a JUnit / MPS test suite that must run in CI.67- `mps-ide-plugin` — when the new module is an MPS IDE plugin (`plugin.xml`, actions, tool windows). Bundling and IDE-plugin authoring are independent steps.68- `mps-aspect-generator` — when the failure is in MPS generation rather than packaging.6970## Reference Index7172- Open `references/architecture.md` for the long form of "how Ant files compose" — entry point `build/build.xml` targets, the three layers of generated scripts (`mpsTrueBootstrap.xml`/`mpsBootstrapCore.xml`/per-plugin files; `mps.xml` aggregator; `mpsStandalone.xml`), and the final distribution layer `mpsDistribution.xml` with its per-platform archives. Open when you need to know where a particular file lives in the pipeline or what its `buildDependents` does.73- Open `references/build-mps-source-of-truth.md` when editing `plugins/mps-build/solutions/mpsBuild/models/build.mps` — explains the `BuildProject` structure, the meaning of opaque concept indices (`1l3spW`, `398b33`, `TrG5h`, `turDy`, `2DA0ip`, `1l3spV`, `10PD9b`), and how regeneration writes the `build/*.xml` files.74- Open `references/plugin-bundling-options.md` to choose between Option A (full Ant compile pipeline like `mpsHttpSupportPlugin`) and Option B (pre-built drop into `mpsStandalone`). Includes the rationale for picking Option A for new MPS-authored plugins.75- Open `references/build-mps-authoring.md` when adding the new `BuildProject` to `build.mps` — `BuildLayout` shape, `BuildSource_JavaModule` / `BuildSource_JavaContentRoot`, the `BuildJavaPlugin` marker, dependency chain through `mpsBootstrapCore`, and the convention for referencing fetched IDEA-plugin jars via `${basedir}/plugins/<idea-plugin>/lib/`.76- Open `references/diagnostics.md` when a plugin is missing from the distribution and you need to figure out which layer dropped it — three-step diagnosis using `grep`, `build/artifacts/<projectName>/`, and `build/artifacts/mps/plugins/<x>/`.77- Open `references/validation.md` for the two-stage validation procedure (cheap `ant -f build/<projectName>.xml assemble` smoke step, then full `build/run_build.sh`) and the three artefact locations to verify after a full build.78- Open `references/touchpoint-checklist.md` for the table of files modified by adding a new Option A plugin — what is hand-edited (`build.mps`), what is regenerated (`build/<projectName>.xml`, `build/mps.xml`, `build/mpsDistribution.xml`), and what stays unchanged (`plugins/<plugin>/META-INF/plugin.xml`, `.iml`).79- Open `references/test-suite-wiring.md` when the new plugin has a `test/` source root that must run in CI — sibling test-only `BuildProject`, JUnit launcher, and `…Tests.xml` aggregator wiring.80- Open `references/key-files.md` for the quick reference of every build file mentioned anywhere in this skill, with one-line descriptions.