Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
262 changes: 262 additions & 0 deletions .agents/docs/2026-11-21-mcpp-build-plugin-naming-plan.md

Large diffs are not rendered by default.

13 changes: 12 additions & 1 deletion .github/workflows/validate.yml
Original file line number Diff line number Diff line change
Expand Up @@ -475,6 +475,9 @@ jobs:
- uses: actions/checkout@v4
- name: Install lua
run: sudo apt-get install -y --no-install-recommends lua5.4
- name: Build-plugin lints (tests of tests/check_mplugin_layout.lua and check_reserved_namespace.lua)
run: python3 tests/test_check_mplugin.py

- name: Lint package descriptors
run: |
fail=0
Expand Down Expand Up @@ -525,6 +528,14 @@ jobs:
if ! lua5.4 tests/check_reserved_namespace.lua "$f"; then
fail=1
fi
# 5c. The build-plugin layout (docs/build-plugins.md): a namespace
# `<owner>.mplugin` is a descriptor of pkgs/mcpp/, whose files are
# packages of namespace `mcpp` or build plugins; owner and name are
# lower-case identifiers. The module being the package id is checked
# in the plugin's own repository: the index cannot read the archive.
if ! lua5.4 tests/check_mplugin_layout.lua "$f"; then
fail=1
fi
# 6. c++fly admission policy (mcpp design 2026-07-14 §11-Q2, v1):
# c++fly means "toolchain's latest level + every experimental
# gate" — deliberately toolchain-dependent, so a published
Expand Down Expand Up @@ -1727,7 +1738,7 @@ jobs:
shell: bash
env:
SLINT_HEADLESS: "1"
run: python3 tests/mwrap/check_installed_template.py --mcpp "$MCPP" --package mcpplibs.mwrap.slint@1.19.0.2 --deploy
run: python3 tests/mwrap/check_installed_template.py --mcpp "$MCPP" --package mcpplibs.mwrap.slint@1.19.0.3 --deploy

- name: Installed Wuffs wrapper archive, actual default decode template and its relocated notices
if: contains(format(' {0} ', env.MEMBERS), ' wuffs-decode ') && matrix.toolchain == 'default'
Expand Down
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@

### Added

- **构建插件的命名与布局规范(docs/build-plugins.md)与第一个新形态的包 mcpplibs.mplugin.slint 1.19.0。** 构建插件的 id 是 `<owner>.mplugin.<name>`,模块名与 C++ 命名空间就是这个 id(`mcpplibs.mplugin.slint`、`mcpplibs::mplugin::slint`),`mcpp.*` 保留给官方;`mplugin` 是种类段,如同封装包的 `mwrap`,所以引擎不被遮蔽,规则代码直接写 `mcpp::…`,在 CI 固定的 mcpp(2026.11.18.1)上实测零警告。描述符放在新目录 `pkgs/mcpp/`(完整 id 作文件名;目录是 mcpp 自己加载的包,身份仍以描述符声明为准)。新增 lint:`tests/check_mplugin_layout.lua`(`<owner>.mplugin` ↔ `pkgs/mcpp/`,owner 与 name 是标识符);`check_reserved_namespace.lua` 另拒绝 owner 为 `mcpp`、保留名、`platforms` 与种类段(`tests/test_check_mplugin.py`)。`mcpplibs.mplugin.slint@1.19.0` 的归档是 slint-m 的 `mwrap-1.19.0.3`(同一字节、GLOBAL 与 CN),规则版本与封装包修订脱钩;`mcpplibs.mwrap.slint@1.19.0.3` 把规则 reexport,使用方仍只依赖封装包。成员 tests/mwrap/slint-rule 只测 build.mcpp 对该描述符的解析与规则运行(构建包与库包分开测)。设计与实施计划见 `.agents/docs/2026-11-21-mcpp-build-plugin-naming-plan.md`。
- **mcpplibs.slintgen 冻结:** 被 mcpplibs.mplugin.slint 取代;1.19.0.1 与 1.19.0.2 的行与归档保持原样、仍可使用,不再有新版本,描述写明 FROZEN。写了老 id 的工程改依赖名即可迁移;只依赖封装包的工程不受影响。
- **compat.slint 声明它以 `dlopen` 加载的库。** libslint_cpp 的 winit 与 femtovg 后端加载的 X11、xcb、Xcursor、Xi、Xrender、
xkbcommon、Wayland、EGL 与 GL 的 soname 记为运行期的必需(`runtime.dlopen_libs`),能力为 `display` 与 `opengl.egl.driver`;
mcpp 按发起加载的对象判定它们可达。声明宿主能力的程序不能以 `--mode self-contained` 打包;已安装模板的部署检查在 mcpp
Expand Down
140 changes: 140 additions & 0 deletions docs/build-plugins.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,140 @@
# Build plugins: `<owner>.mplugin.<name>`

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

[简体中文](zh/build-plugins.md)

## One name, three spellings

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

```cpp
// 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:

1. `<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_cpp` is the same rule).
2. `<owner>` is who maintains the package. `mcpplibs` is for packages the
mcpplibs organization maintains; anyone else uses their own name.
3. `<owner>` is not `mcpp`, 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.
4. The main interface module is exactly the id; every other module of the
package starts with `<id>.`.
5. A package whose first segment is `mcpp` is maintained by the mcpp project
and is not of this form (`mcpp.plugins`, `mcpp.platforms`).
6. For a rule tied to one library, `<name>` is the library (`slint`, `grpc`,
`protobuf`), with no `gen` or `-bind` suffix; several rules for one library
are functions of one package. A general tool takes the tool's name
(`clangtidy`).

## Where a rule lives

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

## Index layout

- The descriptor is `pkgs/mcpp/<full id>.lua`, one flat directory: the
official `pkgs/mcpp/mcpp.plugins.lua`, the plugins
`pkgs/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 for `pkgs/mwrap/`. The directory
does not say what a package is: `mcpp.platforms` is platform data, not a
plugin.
- A descriptor whose namespace is `<owner>.mplugin` is in `pkgs/mcpp/`; a file
in `pkgs/mcpp/` has namespace `mcpp` or `<owner>.mplugin` (lint
`tests/check_mplugin_layout.lua`).
- **A build plugin and its library are tested apart.** A plugin's member
checks what `build.mcpp` can 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 gets `tests/mcpp/<owner>-<name>/`.

## Versions

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.

## Older packages

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 (no `autoupdate`,
`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.

## Checks

| 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.
2 changes: 2 additions & 0 deletions docs/package-types.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

Module wrappers preserve upstream APIs under `mcpplibs.mwrap.<lib>`. Use `pkgs/mwrap/<lib>.lua`; see [the wrapper specification](mwrap.md). Every -m repository has English and Chinese READMEs.

Build plugins (modules a `build.mcpp` imports) are `<owner>.mplugin.<name>`, descriptors in `pkgs/mcpp/`; see [build plugins](build-plugins.md).


**English** | [简体中文](zh/package-types.md)

Expand Down
5 changes: 3 additions & 2 deletions docs/repository-and-schema.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

**English** | [简体中文](zh/repository-and-schema.md)

Module wrapper descriptors use `pkgs/mwrap/<lib>.lua` and their consumers use `tests/mwrap/<member>/`; see [the mwrap specification](mwrap.md). The category is flat and published unchanged. The workspace test source uses the current pinned mcpp; `index.toml` separately states the descriptor compatibility floor.
Module wrapper descriptors use `pkgs/mwrap/<lib>.lua` and their consumers use `tests/mwrap/<member>/`; see [the mwrap specification](mwrap.md). Build plugins (`<owner>.mplugin.<name>`) and the mcpp project's own packages use `pkgs/mcpp/<full id>.lua`; see [build plugins](build-plugins.md). The category is flat and published unchanged. The workspace test source uses the current pinned mcpp; `index.toml` separately states the descriptor compatibility floor.

## Repository layout

Expand All @@ -20,7 +20,8 @@ tests/examples/<member>/ one test project per library (a workspace member; <
tests/*.cpp behavioral assertions (standalone main; a non-zero exit code is a failure)
tests/check_mirror_urls.lua lint: GLOBAL+CN table completeness, and that CN points at mcpp-res
tests/check_package_name.lua lint: identity shape (name is a single atomic segment, hierarchy belongs to namespace)
tests/check_reserved_namespace.lua lint: a namespace is not a reserved second segment of `mcpp.` (core, plugins, deps, rules, dist, tools)
tests/check_reserved_namespace.lua lint: a namespace is not a reserved second segment of `mcpp.` (core, plugins, deps, rules, dist, tools); an `<owner>.mplugin` owner is not mcpp, a reserved name or a kind segment
tests/check_mplugin_layout.lua lint: `<owner>.mplugin` descriptors are in pkgs/mcpp/, whose files are namespace `mcpp` or build plugins; identifiers
tests/list_cn_urls.lua extracts the CN urls for mirror-cn-reachable
tests/run_members.sh runs workspace members one at a time and times each. The entry point used both by CI
and locally; see "Running workspace members locally" below
Expand Down
98 changes: 98 additions & 0 deletions docs/zh/build-plugins.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
# 构建插件:`<owner>.mplugin.<name>`

**构建插件**是模块由工程的 `build.mcpp` 导入的包(`host-module`):代码生成器、工具封装、规则集。本页是它们的命名与布局规则;设计记录见
`.agents/docs/2026-11-21-mcpp-build-plugin-naming-plan.md`。

[English](../build-plugins.md)

## 一个名字,三种写法

构建插件的 id 是 `<owner>.mplugin.<name>`;模块名和 C++ 命名空间都是这个 id:

| 写法 | 形式 | 例子 |
|---|---|---|
| 包(namespace + name) | `<owner>.mplugin` + `<name>` | `mcpplibs.mplugin.slint` |
| 模块 | id;子模块 `<id>.<子名>` | `mcpplibs.mplugin.slint` |
| C++ 命名空间 | id,`.` 换成 `::` | `mcpplibs::mplugin::slint` |

```cpp
// 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` 是种类段,如同 `mwrap` 之于封装包(`mcpplibs.mwrap.slint` 是封装包,`mcpplibs.mplugin.slint` 是它的构建插件)。命名空间是
`<owner>::mplugin::<name>`,不是 `<owner>::mcpp::<name>`,所以插件内部直接写 `mcpp::…` 调用引擎,不会被遮蔽。

规则:

1. `<owner>` 与 `<name>` 是小写标识符,`[a-z][a-z0-9_]*`:多词用 `_` 连接,不用 `-`(模块名需要标识符;`mcpplibs.mwrap.godot_cpp` 是同一条规则)。
2. `<owner>` 是维护者。`mcpplibs` 只给 mcpplibs 组织维护的包;其他人用自己的名字。
3. `<owner>` 不得是 `mcpp`,不得是 mcpp 项目的保留名(`core`、`plugins`、`deps`、`rules`、`dist`、`tools`、`platforms`),也不得是种类段(`mwrap`、
`mplugin`)。官方新增一个包名即加入保留名,新增时须核对没有 owner 已用此名。
4. 主接口模块恰好是 id;包内其他模块都以 `<id>.` 开头。
5. 第一段是 `mcpp` 的包由 mcpp 项目维护,不属于这个形态(`mcpp.plugins`、`mcpp.platforms`)。
6. 与某个库绑定的规则,`<name>` 是库名(`slint`、`grpc`、`protobuf`),不加 `gen`、`-bind` 后缀;同一个库的多个规则是同一个包的函数。通用工具取工具名
(`clangtidy`)。

## 规则放在哪里

| 类型 | 放在 | 工程怎么写 |
|---|---|---|
| 与某个库绑定 | 该库 `-m` 仓库的 `rules/` 子包;描述符写 `mcpp = "*/rules/mcpp.toml"`;封装包的根 manifest 有 `<id> = { path = "rules", host-module = true, reexport = true }` | 只依赖封装包 |
| 通用工具 | 自己的仓库 | `[build-dependencies] <id> = { version = "…", host-module = true }` |
| 引擎级、跨生态 | mcpp 项目的 `mcpp.plugins` | `mcpp.plugins` 的某个 feature |

规则包自己的依赖写在它的 `[dependencies]`(mcpp 2026.10.11.1 及以后)。认领文件扩展名的 feature 不经 `reexport` 传递,所以与库绑定的规则以 `options`
字段接收输入(`mcpplibs.mplugin.slint` 的 `options::sources`)。

## 索引布局

- 描述符是 `pkgs/mcpp/<完整 id>.lua`,一层平铺:官方的 `pkgs/mcpp/mcpp.plugins.lua`,插件的 `pkgs/mcpp/mcpplibs.mplugin.slint.lua`。这个目录放的是
mcpp 自己加载的包;身份以描述符声明的为准(`namespace = "<owner>.mplugin"`、`name = "<name>"`),与 `pkgs/mwrap/` 相同。目录不说明包是什么:
`mcpp.platforms` 是平台数据,不是插件。
- namespace 为 `<owner>.mplugin` 的描述符在 `pkgs/mcpp/`;`pkgs/mcpp/` 里文件的 namespace 是 `mcpp` 或 `<owner>.mplugin`(lint:
`tests/check_mplugin_layout.lua`)。
- **构建插件与它的库分开测试。** 插件的成员只测 `build.mcpp` 能用它做什么(规则对一个小输入产出什么,生成的模块能否编译,改动的输入是否重新生成);库本身的行为
由封装包的成员与已安装模板检查来测。与库绑定的插件起初通过封装包的成员测(`tests/mwrap/…`);独立的插件用 `tests/mcpp/<owner>-<name>/`。

## 版本

每个包有自己的版本线:首个版本是它所针对的上游版本,修订追加 `.N`,标签不移动。与库绑定的规则随封装包发布:描述符的行指向封装包的标签归档(同样的字节、同一个
sha256、GLOBAL 与 CN),规则自己的 `rules/mcpp.toml` 版本等于这一行,不必等于封装包的修订号(`mcpplibs.mplugin.slint@1.19.0` 在
`mcpplibs.mwrap.slint@1.19.0.3` 的归档里)。这样的描述符不写 `autoupdate`:它的行与封装包的行一起加入。

## 较早的包

本页之前发布的构建规则继续可用:`mcpplibs.slintgen`、`mcpplibs.grpcgen`、`mcpplibs.protogen`、`mcpplibs.clangtidy`、`mcpplibs.openkal-bind` 遵循较早的规则
(模块 `mcpp.<namespace>.<name>`,SPEC-007 §9),并不是错的。它们的描述符与归档保留;已发布的行不改。

- 一个包在下次需要新版本时迁到新形态:新 id 在 `pkgs/mcpp/` 发布,老描述符冻结(无 `autoupdate`,描述里写 `FROZEN: superseded by <id>`),不再有新版本。没有转发模块。
- id 就是身份,老 id 不能改用新的模块名:写着 `x = "1"` 的工程会在升级时被带到新的模块名。
- 写了老 id 的工程保留它的各个版本,改依赖名即可迁移。

| 老 id | 新 id | 迁移 |
|---|---|---|
| `mcpplibs.slintgen` | `mcpplibs.mplugin.slint` | 1.19.0 |
| `mcpplibs.grpcgen` | `mcpplibs.mplugin.grpc` | grpc-m 的下次发布 |
| `mcpplibs.protogen` | `mcpplibs.mplugin.protobuf` | protobuf-m 的下次发布 |
| `mcpplibs.clangtidy` | `mcpplibs.mplugin.clangtidy` | 它的下次发布 |
| `mcpplibs.openkal-bind` | `mcpplibs.mplugin.openkal_bind` | openkal 的下次发布 |

`mcpplibs.rules-cuda` 是指向 `mcpp.rules.cuda` 的占位包,保持原样。

## 检查

| 检查 | 位置 |
|---|---|
| namespace 不是 `mcpp.` 的保留第二段;owner 不是 `mcpp`、保留名或种类段 | `tests/check_reserved_namespace.lua` |
| 布局:`<owner>.mplugin` ↔ `pkgs/mcpp/`;owner 与 name 是标识符 | `tests/check_mplugin_layout.lua` |
| 成员构建不打印引擎对保留模块名的警告 | `tests/run_members.sh` |
| 模块就是包 id | 规则自己仓库的 CI(索引读不到归档里的源码) |

构建插件在构建机器上运行代码:按“会执行代码的包”评审。`mplugin` 不表示已审计;owner 是谁、模仿 `mcpplibs` 的名字,由评审判断。
Loading
Loading