mps-distribution-build

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

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.