A build plugin is a package whose modules a project's build.mcpp imports
(host-module): code generators, tool wrappers, rule sets. This page is the
naming and layout rule for them; the design record is
.agents/docs/2026-11-21-mcpp-build-plugin-naming-plan.md.
A build plugin's id is <owner>.mplugin.<name>. Its module and its C++
namespace are that id:
| Spelling | Form | Example |
|---|---|---|
| package (namespace + name) | <owner>.mplugin + <name> |
mcpplibs.mplugin.slint |
| module | the id; sub-modules <id>.<sub> |
mcpplibs.mplugin.slint |
| C++ namespace | the id with :: |
mcpplibs::mplugin::slint |
// build.mcpp
import mcpp;
import mcpplibs.mplugin.slint;
int main() {
mcpplibs::mplugin::slint::options o;
o.sources = {"ui/app.slint"};
return mcpplibs::mplugin::slint::compile(o) ? 0 : 1;
}mplugin is the kind segment, as mwrap is for wrappers
(mcpplibs.mwrap.slint is the wrapper, mcpplibs.mplugin.slint its build
plugin). Because the namespace is <owner>::mplugin::<name> and not
<owner>::mcpp::<name>, code inside a plugin writes the engine as mcpp::…
and nothing shadows it.
Rules:
<owner>and<name>are lower-case identifiers,[a-z][a-z0-9_]*: words are joined with_, never-(a module name needs an identifier;mcpplibs.mwrap.godot_cppis the same rule).<owner>is who maintains the package.mcpplibsis for packages the mcpplibs organization maintains; anyone else uses their own name.<owner>is notmcpp, not one of the mcpp project's reserved names (core,plugins,deps,rules,dist,tools,platforms) and not a kind segment (mwrap,mplugin). A new official package name joins the reserved names; the check that no owner already has it is part of adding it.- The main interface module is exactly the id; every other module of the
package starts with
<id>.. - A package whose first segment is
mcppis maintained by the mcpp project and is not of this form (mcpp.plugins,mcpp.platforms). - For a rule tied to one library,
<name>is the library (slint,grpc,protobuf), with nogenor-bindsuffix; several rules for one library are functions of one package. A general tool takes the tool's name (clangtidy).
| Kind | Lives in | A project writes |
|---|---|---|
| tied to one library | the rules/ sub-package of that library's -m repository; the descriptor says mcpp = "*/rules/mcpp.toml"; the wrapper's root manifest has <id> = { path = "rules", host-module = true, reexport = true } |
only the wrapper |
| a general tool | its own repository | [build-dependencies] <id> = { version = "…", host-module = true } |
| engine-level, across ecosystems | the mcpp project's mcpp.plugins |
a feature of mcpp.plugins |
A rule package's own dependencies are in its [dependencies] (mcpp
2026.10.11.1 and later). A feature that claims a file extension does not pass
through reexport, so a rule tied to a library takes its inputs as options
fields (options::sources of mcpplibs.mplugin.slint).
- The descriptor is
pkgs/mcpp/<full id>.lua, one flat directory: the officialpkgs/mcpp/mcpp.plugins.lua, the pluginspkgs/mcpp/mcpplibs.mplugin.slint.lua. The directory is the packages mcpp itself loads; the identity is what the descriptor declares (namespace = "<owner>.mplugin",name = "<name>"), as forpkgs/mwrap/. The directory does not say what a package is:mcpp.platformsis platform data, not a plugin. - A descriptor whose namespace is
<owner>.mpluginis inpkgs/mcpp/; a file inpkgs/mcpp/has namespacemcppor<owner>.mplugin(linttests/check_mplugin_layout.lua). - A build plugin and its library are tested apart. A plugin's member
checks what
build.mcppcan do with it (what the rule produces from a small input, that a generated module compiles, that an edited input regenerates); how the library behaves is the wrapper's member and installed-template check. A plugin tied to a library is tested at first through the wrapper's member (tests/mwrap/…); a plugin of its own getstests/mcpp/<owner>-<name>/.
Each package has its own line: the first release is the upstream version it is
built for, a revision appends .N, and a tag never moves. A rule tied to a
library is released with the wrapper: its descriptor row points at the
wrapper's tag archive (same bytes, same sha256, GLOBAL and CN), and the rule's
own rules/mcpp.toml version equals that row; it need not equal the wrapper's
revision (mcpplibs.mplugin.slint@1.19.0 is in the archive of
mcpplibs.mwrap.slint@1.19.0.3). Such a descriptor has no autoupdate: its
rows are added with the wrapper's.
Build rules published before this page keep working: mcpplibs.slintgen,
mcpplibs.grpcgen, mcpplibs.protogen, mcpplibs.clangtidy,
mcpplibs.openkal-bind follow the earlier rule (module
mcpp.<namespace>.<name>, SPEC-007 §9) and are not wrong. Their descriptors
and archives stay; a published row never changes.
- A package moves to the new form when it next needs a new version: the new id
is published in
pkgs/mcpp/, the old descriptor is frozen (noautoupdate,FROZEN: superseded by <id>in its description) and gets no more versions. There is no forwarding module. - The id is the identity, so the old id cannot take the new module name: a
project that wrote
x = "1"would be moved to a new module name on update. - A project that wrote the old id keeps its versions and moves by changing the dependency name.
| Old id | New id | Moved |
|---|---|---|
mcpplibs.slintgen |
mcpplibs.mplugin.slint |
1.19.0 |
mcpplibs.grpcgen |
mcpplibs.mplugin.grpc |
with grpc-m's next release |
mcpplibs.protogen |
mcpplibs.mplugin.protobuf |
with protobuf-m's next release |
mcpplibs.clangtidy |
mcpplibs.mplugin.clangtidy |
with its next release |
mcpplibs.openkal-bind |
mcpplibs.mplugin.openkal_bind |
with openkal's next release |
mcpplibs.rules-cuda is a stub that points at mcpp.rules.cuda; it stays as
it is.
| Check | Where |
|---|---|
namespace is not a reserved second segment of mcpp.; an owner is not mcpp, a reserved name or a kind segment |
tests/check_reserved_namespace.lua |
layout: <owner>.mplugin ↔ pkgs/mcpp/; owner and name are identifiers |
tests/check_mplugin_layout.lua |
| a member's build prints no engine warning about a reserved module name | tests/run_members.sh |
| the module is the package id | the rule's own repository CI (the index cannot read the archive's sources) |
A build plugin runs code on the machine that builds: it is reviewed as a
package that executes code. mplugin does not mean audited; who an owner is,
and names that imitate mcpplibs, are for review.