mcpp.toml

[package]
name        = "plugins"
namespace   = "mcpp"
version     = "0.21.0"
# The first mcpp release that speaks protocol 17 (SPEC-013, mcpp#847): the
# platform's directives `mcpp.plugins.platform` states (`link_driver`,
# `link_input`, `artifact_name`, `seal`, `run_host`), the `platform` phase, and
# `mcpp-package.json` beside every staged tree, which `mcpp::plugins::package`
# reads. It carries protocol 15 (mcpp#755): `xpkg_source`, `xpkg_program`,
# `xpkg_request`, `mcpp::decision`, `mcpp::toolchain`, `mcpp::phase`, and the
# `provision = "on-request"` entries below.
mcpp        = ">=2026.10.30.1"
description = "Official mcpp build plugins: rule packages under mcpp.rules.*, build-time utilities under mcpp.tools.*, each member selected by a feature"
license     = "Apache-2.0"
authors     = ["mcpp-community"]
repo        = "https://github.com/mcpp-community/mcpp-plugins"

[language]
standard   = "c++23"
modules    = true
import_std = true

# The lib root alone is compiled for a consumer that activates no feature. Each
# member of the collection is a module interface unit that one feature adds to
# the source set; mcpp compiles every interface unit among the resolved
# sources as a host module under the name the unit declares (2026.9.5.3+).
[build]
# THE LIB ROOT ALONE, AND THE GENERAL LIBRARY BEHIND A FEATURE.
#
# The units divide by what they may import:
#
#   src/plugins.cppm   `mcpp.plugins`, importing only `std`, so the same code
#                      compiles into `mcpp-embed` -- an ordinary program, which
#                      is what lets the generation be an ACTION and a payload
#                      be that action's declared input
#   src/declare.cppm,  L2, the official general library for build programs
#   src/toolset.cppm,  (mcpp#734): `mcpp.plugins.declare`,
#   src/fs.cppm        `mcpp.plugins.toolset`, `mcpp.plugins.fs`,
#   src/tool.cppm      `mcpp.plugins.tool` -- where a tool a member runs comes
#                      from, one order for every member (mcpp#755)
#   src/testing.cppm   `mcpp.plugins.testing`, the test kit for plugins
#   src/toolchain.cppm `mcpp.plugins.toolchain`, a build toolchain stated by
#                      the root build program (feature `plugins-toolchain`)
#
# The L2 units import `mcpp.core` (spelled `mcpp`), which exists only inside a
# build program, so listing them here would break the ORDINARY build of this
# package -- the build that produces the tool. `[features.plugins-core]`
# scopes them to the consumers that have a build program, and every family
# member implies it.
#
# It also needs mcpp 2026.9.8.1: before that release a package's host modules
# were ordered by PATH, so `rules/spirv.cppm` was compiled before
# `src/declare.cppm` and importing it failed with "failed to read compiled
# module". They are ordered by their import graph now.
sources = ["src/plugins.cppm"]

# EACH RULE STATES WHAT IT COMPILES AND HOW TO REACH IT (mcpp 2026.9.7.1+).
#
# `device_extensions` says which device sources this rule compiles;
# `rule_module` says which module a consumer's build program imports to reach
# it. Two things follow, and neither puts this package's name inside mcpp:
#
#   1. A consumer that activates the feature gets those extensions classified
#      as device sources, so a NEW device language costs no engine change.
#      Slang measured the alternative: adding `.slang` to the engine's built-in
#      table cost an mcpp release and a version bump in this file's CI before
#      the rule could route one file.
#   2. `host-module = true` is implied, because a feature naming a rule module
#      has already said that is the only way to use it. A consumer writes
#      `features = ["rules-spirv"]` and nothing else.
#
# The feature is still requested BY NAME. An earlier revision activated it from
# the extensions a project's sources happened to carry; that was withdrawn
# because two packages may claim one extension -- a third-party CUDA rule is a
# thing someone will write -- and because a derived feature set is information
# a manifest no longer states.
#
# A consumer that outgrows the generated build program writes its own
# `build.mcpp`, which is the same program with edits. Each layer overrides the
# one above it; none is a different mechanism.
[features]
default = []

# L2: THE OFFICIAL GENERAL LIBRARY FOR BUILD PROGRAMS (0.17.0, mcpp#734).
# Every family member implies it, so a project that uses an official plugin
# writes nothing more; a build program that uses only L2, and a third-party
# plugin built on it, name `plugins-core` on the dependency edge. A consumer
# that activates none of them compiles nothing that imports `mcpp`.
#
#   mcpp.plugins.declare   how a generated surface reaches the build graph
#   mcpp.plugins.toolset   the resolved toolchain, translated for a foreign
#                          build system (`instance`, `chain`, `detected`)
#   mcpp.plugins.fs        deterministic file generation and placement
[features.plugins-core]
sources = ["src/declare.cppm", "src/toolset.cppm", "src/fs.cppm", "src/tool.cppm", "src/accel.cppm", "src/progress.cppm",
           "src/compat/detected_toolset.cppm"]

# The operating system of every member: the programs a member asks for a fact
# (`mcpp.plugins.tool::capture`), the libraries it opens and the platform it
# builds on, through mcpplibs.os. No unit includes a system header (0.21.0,
# docs/plugin-development.md §4).
[feature-deps.plugins-core]
mcpplibs.os = "0.4.0"

# `mcpp.plugins.toolchain` -- the builders a root build program states its
# build toolchain with, in the toolchain phase of a project whose `[toolchain]`
# says `configure = "build.mcpp"` (mcpp#755). Its own feature rather than part
# of `plugins-core`: a project that states no toolchain compiles nothing of it.
[features.plugins-toolchain]
sources = ["src/toolchain.cppm"]
implies = ["plugins-core"]

# `mcpp.plugins.platform` -- what a platform's plugin (mcpp SPEC-013 §12) and a
# package format's provider (SPEC-014 §6) state: the link's driver and inputs,
# the artifacts' names, the seal, where the runner runs, and `provide_format`,
# which declares a format on every pass and makes its action from the staged
# package's `mcpp-package.json` in the pass that asks for it. Its own feature:
# a project that provides no platform and no format compiles nothing of it.
[features.plugins-platform]
sources = ["src/platform.cppm"]
implies = ["plugins-core"]

# The test kit: a plugin function runs against a stated build context, and its
# directives are compared. Separate from `plugins-core`, so that no build
# program compiles it unless it asks.
[features.plugins-testing]
sources = ["src/testing.cppm"]
implies = ["plugins-core"]

# COMPATIBILITY UNIT
#   keeps:       the feature name `surface`, the name of `plugins-core` until 0.16.0
#   since:       0.17.0 (2026-09-28)
#   retires:     2027-03-28
#   replacement: `plugins-core`
#   note:        none: a feature name is resolved before any build program runs
[features.surface]
implies = ["plugins-core"]

[features.rules-ascendc]
sources           = ["rules/ascendc.cppm"]
implies           = ["plugins-core"]
rule_module       = "mcpp.rules.ascendc"
device_extensions = [".asc", ".cce"]

[features.rules-cuda]
sources           = ["rules/cuda.cppm"]
implies           = ["plugins-core"]
rule_module       = "mcpp.rules.cuda"
device_extensions = [".cu"]

# `.metal` shaders become Metal libraries through `xcrun metal` and `xcrun
# metallib`, the toolchain Xcode carries. No payload is declared, for the reason
# `dist-apple` gives for `codesign`: Xcode is not redistributable, so the rule
# locates the toolchain and refuses naming the command that found nothing.
[features.rules-metal]
sources           = ["rules/metal.cppm"]
implies           = ["plugins-core"]
rule_module       = "mcpp.rules.metal"
device_extensions = [".metal"]

# `.swift` sources become one object per package through `xcrun swiftc`, with a
# generated header for the package's C and C++ sources and the Swift runtime's
# search directories on the link. No payload is declared, for the reason
# `rules-metal` gives: the compiler ships with Xcode and the Command Line Tools.
[features.rules-swift]
sources           = ["rules/swift.cppm"]
implies           = ["plugins-core"]
rule_module       = "mcpp.rules.swift"
device_extensions = [".swift"]

[features.rules-hip]
sources           = ["rules/hip.cppm"]
implies           = ["plugins-core"]
rule_module       = "mcpp.rules.hip"
device_extensions = [".hip"]

[features.rules-slang]
sources           = ["rules/slang.cppm"]
implies           = ["plugins-core"]
rule_module       = "mcpp.rules.slang"
device_extensions = [".slang"]

# `.glsl` and `.hlsl` carry no stage and are claimed on purpose: the rule
# refuses them by name and says which extensions do carry one, which is a better
# message than the engine's "no rule compiles it".
[features.rules-spirv]
sources           = ["rules/spirv.cppm"]
implies           = ["plugins-core"]
rule_module       = "mcpp.rules.spirv"
device_extensions = [".comp", ".vert", ".frag", ".geom", ".tesc", ".tese",
                     ".mesh", ".task", ".rgen", ".rint", ".rahit", ".rchit",
                     ".rmiss", ".rcall", ".glsl", ".hlsl"]

[features.rules-sycl]
sources           = ["rules/sycl.cppm"]
implies           = ["plugins-core"]
rule_module       = "mcpp.rules.sycl"
device_extensions = [".sycl"]

# Qt's code generators and Linguist tools. `.ui`, `.qrc` and `.ts` files named
# in `[build] sources` reach the rule through `mcpp::device_sources()`; a header
# declaring a meta-object is found by content, since `.h` is a C++ extension the
# engine already owns. `.ts` is also TypeScript's extension, and that costs
# nothing here: the feature is requested by name, and only the files a
# project's own `sources` names are routed.
[features.rules-qt]
sources           = ["rules/qt.cppm"]
implies           = ["plugins-core"]
rule_module       = "mcpp.rules.qt"
device_extensions = [".ui", ".qrc", ".ts"]

# WHERE QT COMES FROM IS THE PROJECT'S CHOICE, not a feature: `rules-qt` finds
# the SDK from `options::root`, `QT_ROOT_DIR`, or a Qt payload the project
# declares in its own `[xlings]` table at the version it chooses
# (docs/rules-qt.md). A feature states a mechanism and the tools that mechanism
# runs, never a library the program links (docs/plugin-development.md). 0.15.0
# removed `rules-qt-xim`, `rules-qt-xim-base` and `rules-qt-xim-addons`.

# NOT device rules: these embed or declare things a project already has, so they
# claim no extension and name no rule module. A consumer calls them from its own
# `build.mcpp`.
# ── dist: what comes out of the link, and in what form a user installs it ──
#
# A THIRD CATEGORY, AND THE PREFIX IS THE POINT. `rules-*` says how a
# translation unit is compiled; `tools-*` says what the build program does
# itself; `dist-*` says what comes out of the link. A `dist-` member compiles no
# translation unit and does no work while the build program runs: it consumes
# link outputs through a `role = "artifact"` action and produces something a
# user installs, reached with `mcpp pack --format <name>` (mcpp 2026.9.11.1+).
#
# THE ENGINE HOLDS THE DISPATCH AND NOT THE FORMAT. dpkg's control fields,
# AppImage's runtime, WiX's schema and Apple's notarisation each couple a
# release to a release mcpp does not control, so none of them is in mcpp. The
# argument is the one this project already made for languages: Slang is
# supported without being named in the engine, and a distribution format has
# less claim to a name there than a language does.
#
# EACH MEMBER IS ONE PLATFORM'S ANSWER and says so in its own module. A member
# whose target OS does not match refuses by name rather than skipping silently:
# the engine has already accepted the `--format` value because this graph
# declared it, so a silent skip would report a successful pack that produced
# nothing.

# NO `rule_module`, AND THE ENGINE IS RIGHT TO REQUIRE THAT.
#
# `rule_module` names the module a consumer's build program imports TO REACH A
# RULE, and the engine refuses it without `device_extensions` -- "a build rule
# states both: `device_extensions` is what it compiles, `rule_module` is how a
# consumer reaches it". A dist member compiles nothing, so it claims no
# extension and has no business with that key.
#
# It therefore takes the `tools-*` shape: the feature adds the unit, and the
# consumer writes `host-module = true` on the dependency edge and imports the
# module by name. One line more for a consumer than a rule needs, and it says
# something true -- this member is not a rule.
[features.dist-appimage]
sources = ["dist/appimage.cppm"]
implies = ["plugins-core"]

[features.dist-wix]
sources = ["dist/wix.cppm"]
implies = ["plugins-core"]

[features.dist-apple]
sources = ["dist/apple.cppm"]
implies = ["plugins-core"]

[features.dist-web]
sources = ["dist/web.cppm"]
implies = ["plugins-core"]

[features.dist-apk]
sources = ["dist/apk.cppm"]
implies = ["plugins-core"]

# `dist-apk` WITH THE KOTLIN COMPILER, AND WITH THE MAVEN RESOLVER (0.11.0).
# Features of their own rather than payloads of `dist-apk`, for the reason
# `dist-appimage` gives below about downloads: provisioning runs before the
# build program learns what it will compile, so a payload `dist-apk` declared
# would be installed by every Android consumer, and the Kotlin compiler is 90 MB
# an application with no Kotlin never runs. A project with Kotlin sources names
# `dist-apk-kotlin`; one with Maven coordinates names `dist-apk-maven`; either
# implies the member itself.
[features.dist-apk-kotlin]
implies = ["dist-apk"]

[features.dist-apk-maven]
implies = ["dist-apk"]

# ── deps: where a library comes from ─────────────────────────────────────
#
# A FOURTH FAMILY, AND THE PREFIX IS THE POINT AGAIN. A `deps-*` member installs
# a prefix through a program mcpp does not drive -- vcpkg, CMake -- and maps it
# into the build: include directories, the link, the directories the program's
# shared libraries are found in at run time. It compiles none of the project's
# translation units, so it is not a rule; its work cannot happen while the build
# program runs, because an installation outlasts the build program's time limit
# and `mcpp emit build-database` must never trigger one, so it is not a tool;
# and it produces inputs of the link rather than something made from it, so it
# is not a dist member. The installation is a `prepare` ACTION (mcpp's SPEC-007
# R3.3: it fills a declared output directory, and the package's compile and link
# edges wait for it) whose command is the installer itself -- `vcpkg`, or
# `cmake -P` over a script the member writes -- so a consumer's edge names no
# tool (0.15.0). The prefix reaches the
# build by name, and its shared-library directory through
# `mcpp::runtime_search_dir` -- both from the release that lands mcpp#702.
#
# `deps` is the unit the members import, as `plugins-core` is for the rest; a
# consumer never names it.
[features.deps]
sources = ["deps/deps.cppm", "deps/compat/names.cppm"]
implies = ["plugins-core"]

[features.deps-vcpkg]
sources = ["deps/vcpkg.cppm"]
implies = ["deps"]

[features.plugins-progress]
# Standalone workers need no build-program-only mcpp module.
sources = ["src/progress.cppm", "src/progress_writer.cppm"]

# Since 0.3.1 a name in Windows' long spelling is the name it spells (the progress channel's path may
# be one). One release, the one mcpp's own modules name, so a build is the same at any later time.
[feature-deps.plugins-progress]
mcpplibs.os = "0.4.0"

[features.deps-cmake]
sources = ["deps/cmake.cppm"]
implies = ["deps"]

# Files a program reads at run time, from a zip archive the project keeps:
# extracted by an action that names every file (the archive's central
# directory lists them while the build program runs) and deployed beside the
# program. 0.14.0.
[features.deps-archive]
sources = ["deps/archive.cppm"]
implies = ["deps"]

[features.tools-embed]
sources = ["tools/embed.cppm"]
implies           = ["plugins-core"]

[features.tools-island]
sources = ["tools/island.cppm"]
implies           = ["plugins-core"]

# ── The environment each rule needs (mcpp 2026.9.6.6+) ──────────────────────
#
# A RULE OWNS THE LIST OF PACKAGES IT DRIVES. It is the code that runs the
# compiler, reads the headers and puts the library directory on the link line,
# so "which package, and which version of it" is its knowledge. Before this, a
# project repeated the list in its own `[xlings.workspace]` -- a copy that goes
# stale silently, because the rule moves and the projects do not.
#
# TWO GATES, AND BOTH MUST OPEN BEFORE A BYTE IS DOWNLOADED. The feature says
# whether this rule is wanted at all; `cfg(accelerator = ...)` says whether this
# particular build compiles for the device. A CPU-only build of a project that
# depends on this package with `features = ["rules-cuda"]` opens the first and
# not the second, and installs nothing -- which is the build CI runs, and the
# one a multi-gigabyte vendor toolkit would otherwise make the most expensive.
#
# THE SHAPE OF EACH DEFAULT IS A JUDGEMENT ABOUT COUPLING, not a style.
#
#   - An EXACT version where the payload's version is coupled to something the
#     rule cannot see. A CUDA runtime must not be newer than the driver it will
#     meet: the 12.9 line reaches every driver from r525 onward, and the 13.x
#     line raises that to r580. That is a property of the consumer's machines,
#     so the rule offers a line it has verified and the project moves it.
#   - A FLOOR (`>=`) where no such coupling exists and newer is simply newer.
#
# mcpp reads the difference: a bare version is a CHOICE, so a project pinning a
# different one wins and is reported; a `>=` is a REQUIREMENT, so a project
# pinning below it is refused naming both sides. See "One package, one version"
# in mcpp's docs/05.
#
# WHAT IS NOT HERE: anything the produced PROGRAM chooses to run on. A Vulkan
# ICD (`xim:mesa-lavapipe`) is a device, not a build tool, and a rule that
# declared one would force a software renderer onto consumers that have a GPU.
# The rule declares what it needs to COMPILE; the project declares what it needs
# to RUN. The runtime adapters (`compat:cuda-runtime`, `compat:sycl-runtime`,
# `compat:vulkan-runtime`) stay in the project for the same reason and for a
# second one: this package is a `[build-dependencies]` edge, so its own
# `[dependencies]` deliberately do not reach the consumer's target.

[target.'cfg(accelerator = "cuda")'.feature-xlings.rules-cuda]
"xim:cuda-nvcc"   = "12.9.86"
"xim:cuda-cudart" = "12.9.79"
# clang's CUDA wrapper includes a cuRAND header for every device unit, and that
# header includes <nv/target> from CCCL. Neither is called by an ordinary
# kernel; on a developer machine the host's /usr/include supplied them silently.
"xim:libcurand"   = "10.3.10.19"
"xim:cuda-cccl"   = "12.9.27"

# The driver sentinel is Linux-only, and the OS goes in the PREDICATE rather
# than in the value: a value carrying platform keys under an already-predicated
# table would state the condition twice and let the two disagree.
[target.'cfg(all(accelerator = "cuda", linux))'.feature-xlings.rules-cuda]
"xim:libcuda-host-link" = "0.0.1"

# HIP on the NVIDIA platform is a header layer over the CUDA runtime, so this
# list is the CUDA one plus the header package HIP includes at its second line.
[target.'cfg(accelerator = "hip")'.feature-xlings.rules-hip]
"xim:hip-nvidia"        = "7.2.4"
"xim:cuda-nvcc"         = "12.9.86"
"xim:cuda-cudart"       = "12.9.79"
"xim:libcurand"         = "10.3.10.19"
"xim:cuda-cccl"         = "12.9.27"
"xim:cuda-profiler-api" = "12.9.79"

[target.'cfg(all(accelerator = "hip", linux))'.feature-xlings.rules-hip]
"xim:libcuda-host-link" = "0.0.1"

# A floor: the compiler's version is not coupled to any driver, and the rule
# needs `-fsycl-link` to behave as it does from 7.1.0 onward.
[target.'cfg(accelerator = "sycl")'.feature-xlings.rules-sycl]
"xim:dpcpp" = ">=7.1.0"

# THE SECOND COMPILER MUST BE TOLD WHERE THE C LIBRARY IS. dpcpp's clang is not
# configured with this ecosystem's glibc, so without these its device units
# compile against the host's -- which no command line shows, because an implicit
# include search never appears on one.
[target.'cfg(all(accelerator = "sycl", linux))'.feature-xlings.rules-sycl]
"xim:gcc"           = "15.1.0"
"xim:glibc"         = ""
"xim:linux-headers" = ""

# The toolkit is visible to SYCL without selecting CUDA source compilation.
# Only a SYCL NVIDIA target requests it; other SYCL targets install nothing.
# Windows has no published CUDA adapter, and the rule refuses it there.
"xim:cuda-nvcc" = { version = "12.9.86", provision = "on-request" }

# ONE COMPILER PER PLATFORM, AND NOT THE SAME ONE EVERYWHERE.
#
# This rule drives both reference compilers and writes the C declaration itself
# on the glslc route, so which one is present is not a difference a consumer
# sees. That is what makes cross-platform parity affordable: it is provided by
# the rule's ability to CHOOSE, not by publishing one compiler three times.
#
# Linux keeps `xim:glslang`, so nothing about an existing Linux build changes.
# macOS and Windows take `xim:shaderc`, which is the compiler this ecosystem
# publishes for them -- glslang has no upstream binary for either, and building
# it three times buys nothing glslc does not already give.
#
# Declaring both on one platform would install both and use one, so each block
# names exactly the compiler that platform will run.
[target.'cfg(all(accelerator = "vulkan", linux))'.feature-xlings.rules-spirv]
"xim:glslang" = ">=15.1.0"

# A FLOOR AGAIN, NOW THAT THE ENGINE ESCAPES THE ARGUMENT FOR cmd.exe.
#
# These two were an exact version for one release, and the reason was the
# engine's command line rather than the package. mcpp hands its provisioning
# request to xlings as a JSON argument on a shell command line; on Windows that
# line is parsed by cmd.exe, whose quoting rules are not the ones the JSON is
# escaped for. The `\"` sequences left cmd's quote state OFF by the time it
# reached the `>` in a version constraint, so the `>` was read as a REDIRECTION.
# Measured on windows-2022 with mcpp 2026.9.6.6:
#
#   Provisioning [xlings.workspace] entries declared by dependencies
#       (xim:shaderc@>=2026.3)
#   The filename, directory name, or volume label syntax is incorrect.
#   error: ... xlings exited 1
#
# -- cmd's own message about an unusable redirection target, arriving as a
# packaging failure. No declaration reachable on Windows had carried a `>`
# before, which is why the whole `>=` shape had never been exercised there.
#
# `mcpp.platform.shell` now escapes for both parsers, and MCPP_VERSION below
# pins the release that carries it, so the constraint these entries were always
# meant to state is expressible again.
[target.'cfg(all(accelerator = "vulkan", macos))'.feature-xlings.rules-spirv]
"xim:shaderc" = ">=2026.3"

[target.'cfg(all(accelerator = "vulkan", windows))'.feature-xlings.rules-spirv]
"xim:shaderc" = ">=2026.3"

# ONE TABLE FOR ALL THREE PLATFORMS, WHICH `rules-spirv` COULD NOT HAVE.
#
# `xim:slang` ships slangc for linux, macosx and windows and for both x86_64 and
# aarch64, so this rule does not change compilers by platform the way the GLSL
# rule does, and one table says everything.
#
# A FLOOR, WHICH IS WHAT THIS PACKAGE'S RULE FOR THE SHAPE ASKS FOR: Slang's
# version is coupled to no driver, so newer is simply newer.
#
# It is written once rather than per platform because the engine escapes the
# constraint for cmd.exe (see the note above), so the `>` survives on all three.
# An earlier revision of this file pinned it exactly on every platform to avoid
# that defect, and rejected the obvious alternative of `>=` on the two platforms
# that tolerated it: a floor holding on two of three would resolve DIFFERENT
# payloads for one project depending on the machine that built it, which is how
# a defect comes to exist on one operating system only.
[target.'cfg(accelerator = "vulkan")'.feature-xlings.rules-slang]
"xim:slang" = ">=2026.14.1"

# 8.5.0 is a real floor rather than a preference: the mixed-mode object -- the
# one carrying both the device binary and a host-callable launcher, which is
# what lets it join an ordinary link -- and the 38 SoC simulators are what this
# rule drives, and they are present from that version onward.
[target.'cfg(accelerator = "ascend")'.feature-xlings.rules-ascendc]
"xim:cann-toolkit" = ">=8.5.0"

# ── The environment `deps-vcpkg`, `deps-cmake` and `deps-archive` need ───────
#
# THE INSTALLERS ARE THE HOST'S. vcpkg and CMake run on the machine that
# builds, so their payloads are declared on the host axis,
# `[feature-xlings.<feature>]`. They are the tools these members' actions run;
# the libraries those tools install are the project's choice.
#
# `xim:vcpkg` IS THE TOOL AND ITS SCRIPTS, NOT A CLONE OF THE REGISTRY. The
# payload is vcpkg-tool's release binary with the standalone bundle published
# beside it (`vcpkg-bundle.json`, `"usegitregistry": true`), so the scripts a
# port calls are the ones that tool was released with, and a `builtin-baseline`
# manifest resolves through vcpkg's git registry into vcpkg's own per-user
# registry cache. A floor: the tool's version is coupled to nothing a project
# pins -- the baseline is.
#
# NOTHING ELSE FOR vcpkg. It fetches the CMake, Ninja and 7-Zip its ports were
# tested with (and a portable git on Windows) into its downloads directory; a
# payload here would replace them with newer ones, and CMake 4 refuses the
# `cmake_minimum_required` of ports that CMake 3 accepted. On Linux and macOS
# vcpkg's documented host prerequisites -- git, curl, zip, unzip, tar and a C
# compiler -- are the host's, as they are for vcpkg itself.
# PROVISIONED WHEN A BUILD PROGRAM ASKS FOR IT (0.19.0, mcpp#755). A consumer
# whose build program names its own vcpkg -- `options::vcpkg`, or an
# `[xlings.overrides]` entry -- never downloads this one, and a consumer that
# names none asks for it through `mcpp.plugins.tool` and gets it installed
# before the plan is made.
[feature-xlings.deps-vcpkg]
"xim:vcpkg" = { version = ">=2026.7.27", provision = "on-request" }

# A floor: CMake's version is coupled to the subproject's
# `cmake_minimum_required`, which only rises.
[feature-xlings.deps-cmake]
"xim:cmake" = { version = ">=3.31", provision = "on-request" }

# `cmake -E tar xf --touch` extracts a zip on every host; `--touch` is 3.24+.
[feature-xlings.deps-archive]
"xim:cmake" = { version = ">=3.31", provision = "on-request" }

# ── The environment `dist-appimage` needs ──────────────────────────────────
#
# ONE PAYLOAD, AND IT CARRIES TWO FILES. `appimagetool` builds the image, and
# the type-2 runtime stub is what the image starts with. Measured on
# appimagetool 1.9.1: without `--runtime-file` the tool DOWNLOADS that stub from
# a GitHub release on every invocation, and with the address unreachable the
# build fails inside the tool. A build must not reach the network -- one that
# does is neither reproducible nor usable offline -- so the recipe installs both
# and the rule passes the stub explicitly.
#
# THE GATE IS THE FEATURE AND THE OS, AND THERE IS DELIBERATELY NO THIRD ONE.
# The rules gate their multi-gigabyte vendor toolkits on `cfg(accelerator =
# ...)` as well, because a CPU-only build of a project that depends on them must
# download nothing. No equivalent exists here and none should: provisioning runs
# BEFORE the build program, so `--format` -- which only the build program
# learns -- cannot be a layer key. The cost of that is bounded and small: a
# Linux consumer that names this feature installs 15 MB whether or not it packs.
#
# A FLOOR RATHER THAN AN EXACT VERSION. appimagetool's version is coupled to
# nothing this rule cannot see; 1.9.1 is where the runtime stub ships beside the
# tool, which is what makes an offline build expressible.
# ASKED FOR WHEN A PACK NEEDS IT (0.19.0, mcpp#755). An ordinary Linux build
# of a project that names this member installed the tool and never ran it:
# provisioning happens before the build program learns `--format`, which is the
# cost this file recorded under `dist-apk`'s `bundletool`. The member now asks
# for it while planning the pack, so a build that packs nothing downloads
# nothing, and `mcpp pack --format appimage` installs it then.
[target.'cfg(linux)'.feature-xlings.dist-appimage]
"xim:appimagetool" = { version = ">=1.9.1", provision = "on-request" }

# WiX IS A PAYLOAD, AND FOR A WHILE THIS FILE SAID IT COULD NOT BE. The
# toolset is under the Microsoft Reciprocal License and its own licence text
# permits redistribution (see the header of dist/wix.cppm); `xim:wix` carries
# 5.0.2. Declared on the Windows target axis, because the produced installer is
# for a Windows program and the tool is a Windows .NET executable. The .NET
# runtime it needs is a Windows component and is not declared: no package can
# honestly own it.
#
# A PLAIN VERSION, NOT A PER-HOST TABLE. `[target.windows...]` already says
# which targets this applies to; a `{ windows = "5.0.2" }` value under a
# section already predicated on `windows` states the same condition twice,
# and a build carrying the fresh engine (past mcpp 2026.9.12.2) refuses that
# as a shape that could disagree with itself:
#
#   error: [target.windows.feature-xlings.dist-wix] xim:wix: the value
#   carries platform keys (windows), but [target.windows] already says
#   which targets this applies to.
#
# The per-host table stays the right shape only at the top level, where
# platform keys select the HOST rather than restating a predicate the
# section has already applied.
#
# 5.0.2-1, NOT 5.0.2, BECAUSE `--format setup` NEEDS THE EXTENSION. The recipe
# revision adds `WixToolset.BootstrapperApplications.wixext` beside the tool,
# and a bundle with WiX's stock bootstrapper application is refused without it
# (WIX0200). An installation made under 5.0.2 keeps the payloads it fetched,
# because xlings does not re-run the install hook of an installed version, so
# the pin names the revision rather than the release.
[target.windows.feature-xlings.dist-wix]
"xim:wix" = "5.0.2-1"

# `dist-apple` declares no payload for `codesign`, `ditto` or `hdiutil`: they are
# part of macOS and Xcode, which are not redistributable, so the member runs the
# system's. The open-source `rcodesign` is the package that would replace the
# `codesign` lookup.
#
# THE RUNNER IS A PAYLOAD, AND ONLY `mcpp run` NEEDS IT. `mcpp run --format app`
# on macOS reaches the bundle through the runner named `app` this member
# supplies, `macapp-run`, which executes the bundle's executable in the
# foreground so that its output and exit status are the program's. `when =
# "run"` keeps a build or a pack from installing it.
[target.'cfg(os = "macos")'.feature-xlings.dist-apple]
"xim:macapp-run" = { version = "0.1.0", when = "run" }

# THE iOS DEVICE ROW'S RUNNER (0.11.0), `devicectl-run`, which installs a signed
# bundle on a connected device and launches it. The simulator row keeps the
# runner its manifest names, so the axis excludes `env = "sim"`, and `when =
# "run"` keeps a build or a pack from installing it.
[target.'cfg(all(os = "ios", not(env = "sim")))'.feature-xlings.dist-apple]
"xim:apple-device-tools" = { version = "0.1.0", when = "run" }

# ── The environment `dist-apk` needs ───────────────────────────────────────
#
# THE GATE IS THE TARGET ENVIRONMENT, NOT AN ACCELERATOR. `env = "android"` is
# a property of `--target`, resolved before provisioning runs, exactly the
# axis `dist-wix` gates its own payload on (`target.windows`) rather than a
# feature-only gate: a non-Android build must install none of this even when
# the feature is named, the same "two gates, and both must open before a byte
# is downloaded" shape the accelerator rules use, applied to the target axis
# instead.
#
# FOUR OF THE FIVE PACKAGES, EACH OWNED BY A DIFFERENT HALF OF THE PIPELINE. `aapt2`,
# `zipalign`, and the `apksigner`/`d8` wrappers all live in one archive
# (`xim:android-build-tools`); `android.jar` is versioned by API level on its
# own (`xim:android-platform`) because that is the number a project pins, not
# a build-tools release; `xim:jdk-temurin` is declared here directly for
# `javac`/`jar`, which `xim:android-build-tools`' own runtime dependency
# provisions for ITS OWN wrappers without making visible to a consumer's
# build program (docs/31, "declare the tool where it will be looked up");
# `xim:android-debug-keystore` is the published debug-signing convention, a
# data file rather than a program, resolved the identical way.
#
# A FLOOR FOR THE TOOLS, AN EXACT VERSION FOR THE JDK AND THE PLATFORM. The
# build-tools release is coupled to nothing this rule can see -- newer is
# simply newer, as `dist-appimage`'s own `>=1.9.1` argues for `appimagetool`.
# `xim:jdk-temurin` is pinned to the exact store key `xim:android-build-
# tools`'s own runtime dependency resolves (`25.0.4+7`, not the alias
# `25.0.4`): that package's header records a resolver defect where an alias
# key can be handed back as a dependency's "version" and joined to a store
# path that does not exist, and this rule's own tools inherit the identical
# hazard if they pin the alias. `xim:android-platform`'s table is keyed by
# alias too (`"36" = { ref = "36-r2" }`), so this declares the resolved key
# directly for the same reason -- `targetSdkVersion` is read back from the
# directory this entry resolves to (`api_level_from_platform_dir`), so an
# alias that silently failed to resolve would surface as a build-time
# refusal rather than a wrong number, but there is no reason to court it.
#
# `xim:bundletool` BUILDS `--format aab`. It is installed with the other four
# for the reason `dist-appimage` gives above: provisioning runs before the
# build program learns `--format`, so the format cannot gate a download. Its
# launcher runs the JDK it was installed against, which is the one pinned here.
[target.'cfg(env = "android")'.feature-xlings.dist-apk]
"xim:android-build-tools"     = ">=37.0.0"
"xim:android-platform"        = "36-r2"
"xim:jdk-temurin"             = "25.0.4+7"
"xim:android-debug-keystore"  = "1.0.0"
# `xim:bundletool` BUILDS `--format aab` AND IS ASKED FOR THEN (0.19.0,
# mcpp#755): the member requests it while planning a bundle, so an ordinary
# `--format apk` build installs nothing for it.
"xim:bundletool"              = { version = "1.18.3", provision = "on-request" }

# The compiler `options::kotlin_sources` needs, and the resolver `options::maven`
# needs, each behind its own feature (see `[features.dist-apk-kotlin]`). The
# Kotlin compiler's launcher runs the JDK pinned above, the same store key.
[target.'cfg(env = "android")'.feature-xlings.dist-apk-kotlin]
"xim:kotlin" = "2.4.20"

[target.'cfg(env = "android")'.feature-xlings.dist-apk-maven]
"xim:coursier" = "2.1.24"

[targets.plugins]
kind = "lib"

# mcpp-embed -- the surface generator as a PROGRAM, so that the graph can invoke
# it and the payloads it embeds can be declared inputs of that invocation.
#
# WHY THE TOOL IS BUILT FROM THIS PACKAGE RATHER THAN PUBLISHED SEPARATELY.
# docs/05 section 2.14 states the reason, and it is not convenience: "The tool's
# version IS the dependency's version, so a `protoc` that does not match its
# runtime is not expressible. This is the problem with packaging the tool
# separately, and it is the failure mode that bites at run time rather than
# compile time." The generator and the declarations it writes are one decision;
# a separately published payload would let them drift by one release.
#
# A consumer asks for it on the same edge that asks for the rules:
#
#   [build-dependencies.mcpp]
#   plugins = { version = "0.4.0", features = ["rules-spirv"],
#               host-module = true, tools = ["mcpp-embed"] }
#
# Only under `storage::object`. The default storage compiles the payload in as
# generated source and needs no program, so nothing is built unless someone
# asks -- and a rule that needs it and cannot find it refuses, naming the line
# to add.
[targets.mcpp-embed]
kind = "bin"
main = "tools/embed_main.cpp"