---
name: mps-distribution-build
description: 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.
type: reference
---

# MPS Distribution Build — Ant Pipeline & Plugin Bundling

## Loading companion skills

Companion names in this skill are lazy dependencies: load only those relevant to the current task. If this skill came from an MCP server, use the host's skill loader to resolve the companion's unique discovered entry URI on the same host-assigned originating server. If the host has no server-backed skill loader, stop and report that limitation; do not silently fall back to a filesystem copy. If this skill came from a filesystem catalog, load the named sibling from that same catalog at `<skills-root>/<skill-name>/SKILL.md`, even if remote skill loaders are also available. Do not invent a tool name or server endpoint.

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.