# Mps Distribution Build

> 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.

- Skill: `jetbrains/mps-distribution-build` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add jetbrains/mps-distribution-build`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jetbrains/mps-distribution-build/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: jetbrains (https://skillmd.com/u/jetbrains)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jetbrains/mps-distribution-build

---


# 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`).

1. **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`.
2. **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`.
3. **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`.
4. **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`.
5. **Regenerate** `build.mps`. A new `build/<projectName>.xml` will appear; `build/mps.xml` and `build/mpsDistribution.xml` will be updated by the same regeneration.
6. **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.
7. **Full build** via `build/run_build.sh`. Verify the three artefact locations in `references/validation.md`.
8. 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.