diff --git a/.agents/docs/2026-11-21-mcpp-build-plugin-naming-plan.md b/.agents/docs/2026-11-21-mcpp-build-plugin-naming-plan.md new file mode 100644 index 00000000..58e2a8af --- /dev/null +++ b/.agents/docs/2026-11-21-mcpp-build-plugin-naming-plan.md @@ -0,0 +1,262 @@ +# 设计方案与实施计划:mcpp 构建插件包规范(`.mplugin.`,描述符放 `pkgs/mcpp/`) + +状态:**v2 已按目标实施**(2026-11-21,见 §9 执行记录)。v2 纳入了维护者对 Q1–Q7、Q9、Q10 的决定(§7),Q8 未答、暂按建议;并加入多视角自审(§8)及其引出的修改。本文含:决策记录(§1)、实测证据(§2)、规范正文草案(§3,评审通过后成为 `docs/build-plugins.md` 与 `docs/zh/build-plugins.md`)、影响面(§4)、实施计划与任务关系(§5)、风险与未验证项(§6)、决定与待决(§7)、自审(§8)。 +事实均为实测或读源码所得,出处写在各条之后;没有验证的写在 §6。 + +## 0. 目标与范围 + +**问题。** 索引里的构建插件(带 `build.mcpp` 可 `import` 的规则模块)现在没有统一的包命名规范:`mcpplibs.slintgen`、`mcpplibs.grpcgen`、`mcpplibs.openkal-bind`、`mcpplibs.clangtidy`,后缀(`gen`、`-bind`)是各包随手加的;包 id、模块名(`mcpp.mcpplibs.slintgen`)、C++ 命名空间(`mcpp::mcpplibs::slintgen`)靠约定对应;描述符散在 `pkgs/<首字母>/`,没有统一的地方管理。mcpp 的 `mcpp add` 也无从知道一个包是不是构建插件。 + +**范围。** +1. 定一个规范:包 id = 模块名 = C++ 命名空间,由同一个字符串得出,`mcpp.*` 保留给官方。 +2. 索引里新增 `pkgs/mcpp/`,放官方的与 mcpplibs 的、以及以后第三方的 mcpp 扩展包。 +3. 老包不删、不改已发布的行,冻结;新版本以新 id 发布,按需迁移。 +4. 以 slint 作为第一个新形态包,走通整条链并做冷装验收。 +5. 向 mcpp 仓库提一个 issue:`mcpp add` 对符合规范的包默认写入构建依赖。 + +**不在范围。** 引擎改动(§2 证明不需要);官方 mcpp-plugins 的包内容;已发布版本的任何改写;`mcpplibs.mwrap.*` 包装包的规范(已有 `docs/mwrap.md`)。 + +## 1. 决策记录 + +| # | 决策 | 理由 | 否决的备选(及证据) | +|---|---|---|---| +| D1 | 种类段叫 **`mplugin`**(单数),构建插件包 id 为 `.mplugin.`,namespace 为 `.mplugin`(两段,与 `mcpplibs.mwrap` 同形),name 是单个原子段 | owner 永远是第一段,`mcpp.*` 一律是官方;与 `mcpplibs.mwrap.` 同构;包 id、模块名、C++ 命名空间严格是同一个字符串 | `mcpp..`:现有引擎对 `mcpp.` 下的模块要求 `mcpp.<自己的 namespace>.*`,模块名等于包 id 时每次构建警告(§2-A)。`.mcpp.`:C++ 里 `mcpplibs::mcpp` 遮蔽全局 `mcpp`,规则代码必须到处写 `::mcpp::`(§2-I)。把 C++ 命名空间与模块名脱钩(`mcpplibs::slint`):失去三者一致,且占用 `mcpplibs::` 根下的名字,须额外查重(§2-L)。`mcpp.slint`(全放进官方 namespace):官方与各家抢同一批名字,看不出谁维护 | +| D2 | **单数**,目录同样不出现 `plugins` | `mwrap` 是单数的种类段;官方 `mcpp.plugins` 是复数集合包,含义不同 | `mplugins` | +| D3 | 描述符放 **`pkgs/mcpp/`**,里面有官方(`mcpp.plugins`、`mcpp.platforms`)、`.mplugin.`;文件名用**完整 id** | 客户端按描述符声明的身份扫描 `pkgs` 的各个子目录,目录和文件名都不决定身份(`docs/mwrap.md`);目录按“谁来加载它”分:mcpp 自己加载的扩展包。owner 会变,所以不能像 mwrap 那样省前缀 | `pkgs/mplugin/`(仅社区):官方包就没有归处;目录名等于种类段的对称性不是必需 | +| D4 | 老包**冻结**,不改已发布的行,不删;新版本以新 id 在 `pkgs/mcpp/` 发布;**按需迁移**(下次要发新版本时才迁) | 老包按现行 SPEC-007 §9 是合规的,不是违规;同一个 id 改模块名会让写着 `x = "1"` 的使用者在升级时被悄悄带到新模块名,构建就坏;新 id 才能保证老使用者不被动受影响 | 同 id 发新版本并改模块名;一次性全迁 | +| D5 | 库绑定的规则:name 取**库名**(`slint`,不加 `gen`),规则放对应 -m 仓库的 `rules/` 子包,由包装包 `reexport`;通用工具规则独立仓库;引擎级能力才进官方 mcpp-plugins | 使用者只依赖包装包,不必知道规则包名;种类段已说明它是插件,后缀多余 | 沿用 `slintgen` | +| D6 | **不转发**:老包不提供转发到新模块的垫片 | 老包冻结,老使用者不受影响;垫片模块名不以包 id 开头,会违反 §3 的前缀不变式,还需要例外字段 | 保留一个周期的转发模块 | +| D7 | 规范文档放 **mcpp-index 的 `docs/`**(沿用 mwrap 先例),mcpp 仓库只提一个 issue | mwrap 规范就在这里;引擎不需要改(§2) | 在 mcpp 的 SPEC-007 里改写 | +| D8 | `mcpp add` 的判定用**包 id**:第二段是 `mplugin` 的写入 `[build-dependencies]` 并带 `host-module = true`;官方 `mcpp.plugins` 单独处理(需要 `features`);`mcpp.platforms` 不自动处理 | `mcpp.platforms` 是目标平台的数据行(`platform = "mcpp.platforms@…"`),不是 host-module;目录不能用来判断种类 | “第一段是 `mcpp` 就是插件”(会把 `mcpp.platforms` 误判) | +| D9 | **构建包与库包分开测试**:构建插件的测试成员只测 `build.mcpp` 层面的简单功能(规则对一个小输入产出什么、生成的模块能否编译、改输入是否重新生成);库本身的行为由包装包的成员测。slint 的成员先留在 `tests/mwrap/slint-ui`,最终收敛到 `tests/mcpp/` | 构建插件的职责只到构建期;运行期行为属于库包。测试位置先不动,避免为新目录补一整套 `run_members.sh`/`validate.yml` 分支 | 现在就把成员移到 `tests/mcpp/` | +| D10 | **slint 的新 id 版本线从头开始**:`mcpplibs.mplugin.slint` 的首个版本是它所针对的上游版本 `1.19.0`,不继承 `1.19.0.3`(slint 还没有使用者)。归档仍是包装包 `mwrap-1.19.0.3` 的那个(同一个标签、同一个 sha256);规则包自己的 `rules/mcpp.toml` 版本与描述符的行一致,即 `1.19.0`,与包装包的修订号脱钩 | 规范“首个版本等于上游版本、修订追加 `.N`”对新 id 同样成立;包装包 `mcpplibs.mwrap.slint` 不能回到 `1.19.0`(标签 `mwrap-1.19.0` 已存在、行 `1.19.0.1/.2` 已发布),所以只有新 id 能“从头开始” | 延续 `1.19.0.3` 的编号;连同包装包一起重来(做不到:标签不移动) | +| D11 | 向 mcpp 只提**一个 issue**,汇总背景、规范链接、实测证据与对 `mcpp add` 的建议行为,不拆成多条功能请求 | 维护者决定;mcpp 侧自行决定实现范围与顺序 | 五条分别提;带优先级清单 | +| D12 | 实施顺序:T1 → T3 → T4 → T2(先让 slint 成为 `pkgs/mcpp/` 的第一个文件,再搬官方包;T2 可推后,不阻塞 slint)。**Q8 维护者未答,暂按此,待确认** | T4 只需要目录存在,它自己的第一个文件就能创建目录;这样 U1 先在低风险的包上验证 | T4 依赖 T2 | + +## 2. 实测证据(mcpp 2026.11.20.1,gcc 16.1,Linux x86_64) + +方法:每项是一个最小的 host-module 包(一个 `export module <模块名>;` 加一个 `answer()` 函数)加一个在 `build.mcpp` 里 `import` 它的消费者,依赖键决定包的 namespace;`mcpp build`,看警告与退出码。所有项构建都成功(exit 0),区别只在警告。 + +| 项 | 依赖键(包 id) | 模块名 | 警告 | +|---|---|---|---| +| A | `mcpp.mcpplibs.slint` | `mcpp.mcpplibs.slint` | **有**:`is under 'mcpp.' but not under its own namespace … a plugin names its modules 'mcpp.mcpp.mcpplibs.*'`(文字与索引 gate 匹配的那句不同,gate 抓不到) | +| B | `mcpp.acme.x` | `mcpp.plugins.x` | 有:`which belongs to the modules maintained by the mcpp project`(整串 namespace 比较:`mcpp.acme` ≠ `mcpp`) | +| C | `acme.x` | `mcpp.plugins.x` | 有(同 B) | +| D | `mcpp.x` | `mcpp.plugins.x` | 无(namespace `mcpp` 豁免) | +| E | `mcpplibs.mcpp.slint` | `mcpplibs.mcpp.slint` | 无 | +| F | `mcpplibs.slintgen`(现有老包) | `mcpp.mcpplibs.slintgen` | 无 | +| G | `mcpp.mcpplibs.slint` | `mcpp.mcpp.mcpplibs.slint` | 无(引擎要求的写法,包 id ≠ 模块名) | +| H | `mcpp.slint` | `mcpp.slint` | 无 | +| I | `mcpplibs.mcpp.slint`,模块内 `import mcpp;` 调 `mcpp::graph_file()` | 同 E | **编译失败**:`'graph_file' is not a member of 'mcpplibs::mcpp'` | +| J | 同 I,改写 `::mcpp::graph_file()` | 同 E | 无 | +| K | **`mcpplibs.mplugin.slint`**,模块内 `import mcpp;` 调 `mcpp::graph_file()`,消费者 `using namespace mcpplibs;` 后用 `mcpp::` 与 `mplugin::` | `mcpplibs.mplugin.slint` | **无,且不加 `::`** | +| L | `mcpplibs.mcpp.slint`,C++ 命名空间 `mcpplibs::slint` | `mcpplibs.mcpp.slint` | 无 | + +结论: +1. 引擎不需要改。B 证明保护没有丢:它比较的是整串 namespace,不是第一段。 +2. 现有引擎只检查 `mcpp.` 下的模块名,`mcpplibs.mplugin.*` 不在范围内,**这类包不会触发任何 R9.6 警告**。 +3. `mplugin` 避开了 `::mcpp` 遮蔽(I 对 K)。 +4. 老包(F)合规,不是错误。 + +**在 CI 固定的版本上复验。** 索引 CI 固定 `MCPP_VERSION: "2026.11.18.1"`(`validate.yml`),上表是在本机 2026.11.20.1 上测的。自审时我取了 v2026.11.18.1 的发布包、用独立的 `MCPP_HOME` 把 K、B、D、F 再跑了一遍:K 无警告且不加 `::` 即可调用 `mcpp::graph_file()`;B 有 R9.6 警告;D、F 无警告。结果与 2026.11.20.1 一致。A、E、I、L 没有在固定版本上重测(它们是被否决的备选,不影响结论)。 + +另一处事实:索引已有一个 namespace 检查 `tests/check_reserved_namespace.lua`(`validate.yml` 步骤 5b),拒绝以 `core/plugins/deps/rules/dist/tools` 开头的 namespace。成员 gate `tests/run_members.sh` 对构建输出匹配 R9.6 的那一句警告来失败。 + +## 3. 规范正文草案(成稿为 `docs/build-plugins.md` + `docs/zh/build-plugins.md`) + +### 3.1 术语 +- **构建插件**:提供 `build.mcpp` 可 `import` 的规则模块的包(`host-module`)。 +- **种类段**:包的 namespace 里表示种类的一段,包装包是 `mwrap`,构建插件是 `mplugin`。 +- **官方包**:namespace 第一段是 `mcpp` 的包,由 mcpp 项目维护。 + +### 3.2 身份(一个名字,三种写法) + +构建插件包的 id 是 `.mplugin.`: + +| 写法 | 形式 | 例子 | +|---|---|---| +| 包 id(namespace + name) | `.mplugin` + `` | `mcpplibs.mplugin.slint` | +| 模块名 | 与包 id 相同;子模块为 `.<子名>` | `mcpplibs.mplugin.slint` | +| C++ 命名空间 | 包 id 的 `.` 换成 `::` | `mcpplibs::mplugin::slint` | + +规则: +1. `` 与 `` 都必须是小写标识符:`[a-z][a-z0-9_]*`;多词用下划线,不用连字符(模块名需要标识符,mwrap 已如此:`godot_cpp`)。 +2. `` 是维护者:`mcpplibs` 只给 mcpplibs 组织维护的包;个人或其他组织用自己的名字。 +3. `` 不得是 `mcpp`,不得是官方保留名(`core`、`plugins`、`deps`、`rules`、`dist`、`tools`、`platforms`),也不得是种类段(`mwrap`、`mplugin`)。官方以后每新增一个包,须检查是否与已有 owner 重名。 +4. 包的主接口模块名必须恰好等于包 id;其余模块必须以 `.` 开头。 +5. 包 id 的第一段是 `mcpp` 的只能是官方维护的包;`mcpp.` 不属于此规范的 `.mplugin.` 形态。 +6. 库绑定规则的 `` 取库名(`slint`、`grpc`、`protobuf`),不加 `gen`、`-bind` 之类后缀;同一个库有多个规则时,用函数名区分,不再另起包。通用工具规则取工具名(`clangtidy`)。 +7. 规则代码里调用引擎写 `mcpp::…`;此命名不会遮蔽全局 `mcpp`(§2-K)。 + +### 3.3 规则放在哪里 + +| 类型 | 放哪里 | 使用者怎么用 | +|---|---|---| +| 库绑定规则(slint、grpc、protobuf、openkal) | 对应 -m 仓库的 `rules/` 子包,描述符 `mcpp = "*/rules/mcpp.toml"`;根 `mcpp.toml` 里 `[build-dependencies] = { path = "rules", host-module = true, reexport = true }` | 只依赖包装包 | +| 通用工具规则(clangtidy 等) | 独立仓库,独立发布 | `[build-dependencies] = { version = "…", host-module = true }` | +| 引擎级、跨生态通用的能力 | 官方 mcpp-plugins(`mcpp.plugins`) | `mcpp.plugins` 的 feature | + +规则包自己的依赖写在它的 `[dependencies]`(mcpp ≥ 2026.10.11.1;`[build-dependencies.mcpp]` 已弃用)。`device_extensions` 之类的 feature 认领不经 `reexport` 传递,库绑定规则因此不带 feature,输入以 `options` 字段传入(slint 的 `options::sources` 是先例)。 + +### 3.4 索引布局 +- 描述符放 `pkgs/mcpp/<完整 id>.lua`,如 `pkgs/mcpp/mcpplibs.mplugin.slint.lua`、`pkgs/mcpp/mcpp.plugins.lua`;不加额外的字母目录层。 +- 声明 `namespace = ".mplugin"`、`name = ""`;`mcpp = "*/rules/mcpp.toml"`(子包形态)或省略(搜索 `*/mcpp.toml`)。 +- **构建包与库包分开测试。** 构建插件的测试成员只测 `build.mcpp` 层面的简单功能:规则对一个小输入产出什么、生成的模块能否编译、改输入是否重新生成;库本身的行为由包装包的成员与已安装模板检查来测。 +- 测试位置分两个阶段:**阶段 1(现在)**:slint 的成员留在 `tests/mwrap/slint-ui`,不新增 `tests/mcpp/`,因为 `run_members.sh`、`validate.yml` 的选择与分片都只认 `tests/examples/` 和 `tests/mwrap/`。**阶段 2(收敛)**:第一个独立规则(如 clangtidy)迁移时,给这些脚本补 `tests/mcpp/` 的分支,此后构建插件成员统一放 `tests/mcpp/<成员>/`(成员名为 `-` 加用途后缀),slint 补一个只测 `build.mcpp` 的最小成员,`slint-ui` 回到只测库。 +- `pkgs/mcpp/` 里允许两种文件:namespace 第一段是 `mcpp` 的官方包,或 namespace 第二段是 `mplugin` 的插件包;反过来,namespace 第二段是 `mplugin` 的描述符必须在 `pkgs/mcpp/`。目录**不用于**判断种类(`mcpp.platforms` 是平台数据行)。 + +### 3.5 版本 +- 每个包有自己的版本线:首个版本等于它所针对的上游版本,修订追加 `.N`;标签不移动。 +- 库绑定规则随包装包发布,**描述符的行指向包装包的标签归档**(同一个归档、同一个 sha256、GLOBAL 与 CN 两处 URL);规则包自己的 `rules/mcpp.toml` 的 `version` 必须等于描述符的行,但**不必**等于包装包的修订号。slint:`mcpplibs.mplugin.slint@1.19.0` 的归档是 `mwrap-1.19.0.3`,包装包 `mcpplibs.mwrap.slint` 同时发 `1.19.0.3`;规则内容之后若有改动,规则发 `1.19.0.1`,指向当时的包装包标签。 +- 库绑定规则的描述符不写 `extensions.autoupdate`(行由与包装包行同一个 PR 加入,避免机器人给同一归档开出第二条版本线)。 + +### 3.6 老包与冻结 +- 老包 = 已发布的、id 不以 `mcpp.` 开头且不符合 §3.2 的构建规则包。其描述符、归档、已安装的 xpkg 保持原样,依赖老 id 的 `mcpp.toml` 继续解析。 +- 冻结的描述符:删除 `extensions.autoupdate`,`description` 写明 “FROZEN: superseded by `<新 id>`”,已发布的行不改。 +- 老包不再追加新版本;其后继以新 id 在 `pkgs/mcpp/` 发布,版本号延续原来的线。 +- 不提供转发模块。 +- 迁移按需:一个老包在下次要发新版本时才迁。 + +### 3.7 `mcpp add`(向 mcpp 提的**一个** issue 的内容) +issue 只汇总信息,是否实现、实现多少由 mcpp 侧决定。要写进去的有:背景与本规范的链接、§2 的实测、以及对 `mcpp add` 的建议行为: +- id 第二段是 `mplugin` 时,默认写入 `[build-dependencies]` 并带 `host-module = true`;官方 `mcpp.plugins` 同样写入构建依赖,但需要 `--features`(现在 `mcpp add` 只有 `--dev`);`mcpp.platforms` 不自动处理(它是 `platform = "…"` 的数据行)。 +- 判定只用包 id,不用目录。 +- 顺带的想法(不要求):显式覆盖项 `--build`/`--dep`;对冻结的老 id 给出提示和新 id;`mcpp remove` 对称处理。 + +### 3.8 lint(索引实施) +| 检查 | 位置 | 内容 | +|---|---|---| +| namespace 保留名 | `tests/check_reserved_namespace.lua`(已有) | 补:`.mplugin` 的 owner 不得是 `mcpp`、官方保留名、官方包名(含 `platforms`) | +| 布局 | 新增 `tests/check_mplugin_layout.lua`,在 `validate.yml` lint 里作步骤 5c | §3.4 的双向检查;``、`` 是小写标识符 | +| 前缀不变式(模块名以包 id 为前缀) | 描述符层看不到模块名(它在包内的 `.cppm` 里),所以不在 5c;靠评审,或加一个读 `.cppm` 的扫描脚本(§7-Q5) | §6-U5 | +| 保留名警告 | `tests/run_members.sh`(已有) | 保持不变 | + +### 3.9 安全说明 +构建插件在 `build.mcpp` 里以 host-module 运行,**会在构建机上执行任意代码**,这与任何依赖里的 `build.mcpp` 相同,`mplugin` 这个名字并不表示被审计过。索引对 `pkgs/mcpp/` 里的新增和版本更新按“会执行代码的包”评审;owner 的归属、与 `mcpplibs` 相像的名字(抢注)都靠评审,没有自动校验。若仓库有 CODEOWNERS,`pkgs/mcpp/mcpp.*` 应归官方维护者。 + +## 4. 影响面 + +### 4.1 老的构建规则包(冻结 + 按需迁移) + +| 老包 | 描述符 | 后继 id(建议) | 触发迁移 | +|---|---|---|---| +| `mcpplibs.slintgen` | `pkgs/s/slintgen.lua` | `mcpplibs.mplugin.slint`(版本线从 `1.19.0` 起,D10) | **第一个,本计划 T3/T4** | +| `mcpplibs.grpcgen` | `pkgs/g/grpcgen.lua` | `mcpplibs.mplugin.grpc` | grpc-m 下次发布 | +| `mcpplibs.protogen` | `pkgs/p/protogen.lua` | `mcpplibs.mplugin.protobuf` | protobuf-m 下次发布 | +| `mcpplibs.clangtidy` | `pkgs/c/clangtidy.lua` | `mcpplibs.mplugin.clangtidy` | clangtidy 下次发布 | +| `mcpplibs.openkal-bind` | `pkgs/o/openkal-bind.lua` | `mcpplibs.mplugin.openkal_bind` | openkal 下次发布 | +| `mcpplibs.rules-cuda` | `pkgs/r/rules-cuda.lua` | 无:它只是指向官方 `mcpp.rules.cuda` 的垫片,保持冻结,不迁移 | — | + +grpcgen、protogen、clangtidy 的模块名我没有逐个核对(§6-U6)。 + +### 4.2 不属于此规范的包 +- `xpkg`、`std-freestanding`、`mcpplibs.capi.lua`:普通库。 +- `marzer.tomlplusplus`:普通库,使用方可以把它作为 host-module,不是构建插件。 +- `mcpp.platforms`:官方的目标平台数据行,搬进 `pkgs/mcpp/`,但不是构建插件。 + +### 4.3 官方包 +`mcpp.plugins`、`mcpp.platforms` 从 `pkgs/m/` 纯 `git mv` 到 `pkgs/mcpp/`,文件名不变,已发布的行不变。 + +## 5. 实施计划与任务关系 + +### 5.1 任务清单 + +| 任务 | 仓库 | 内容 | 前置 | 验收 | +|---|---|---|---|---| +| **T0** | mcpp-index | 本文评审 | — | 维护者确认(Q8 尚待确认) | +| **T1** | mcpp-index(PR A1) | `docs/build-plugins.md` + `docs/zh/build-plugins.md`;`tests/check_mplugin_layout.lua` 及其正反例测试;`check_reserved_namespace.lua` 扩展(owner 不得是 `mcpp`、官方保留名、官方包名、种类段);`validate.yml` lint 步骤 5c;`package-types.md`、`repository-and-schema.md`、README 的引用;CHANGELOG | T0 | lint 通过;反例(owner 为保留名或种类段、`mplugin` 描述符不在 `pkgs/mcpp/` 等)被拒绝;中英文文档一致 | +| **T3** | slint-m(PR)+ 标签与发布 | 规则包改为 `name = "slint"`、模块 `mcpplibs.mplugin.slint`、C++ 命名空间 `mcpplibs::mplugin::slint`;`rules/mcpp.toml` 的 `version` 为 `1.19.0`(D10),包装包版本 `1.19.0.3`;根 `mcpp.toml` 的构建依赖键改名;`templates/hello`、`tests/rule-consumer`、`docs/rules.md`、`docs/usage.md`、README 中英文、`tools/test_template.py`、`ci.yml` 同步;新增 `rules/LICENSE`(仓库根许可证的副本,收掉 `mcpp pack` 的无许可证警告;`STATIC_NOTICES` 不扩展);规则仓库 CI 加一行检查:`rules/src` 的 `export module` 等于包 id(Q5);CI 通过后打标签 `mwrap-1.19.0.3`,发布 release,镜像到 `gitcode.com/mcpp-res/mwrap-slint` | T0(不依赖 T1) | CI 四个任务通过;**在 CI 固定的 mcpp(2026.11.18.1)上**重命名后的 `reexport` 仍把规则传给消费者;规则版本(1.19.0)与包装包版本(1.19.0.3)不同时 `mcpp pack`、描述符解析不报错(U12);两处 release 的归档逐字节一致 | +| **T4** | mcpp-index(PR B) | 新增 `pkgs/mcpp/mcpplibs.mplugin.slint.lua`(版本 `1.19.0`,行指向 `mwrap-1.19.0.3` 的归档,GLOBAL + CN,无 autoupdate,`mcpp = "*/rules/mcpp.toml"`);`pkgs/mwrap/slint.lua` 加 `1.19.0.3` 行;**冻结** `pkgs/s/slintgen.lua`(默认:删 autoupdate、标注 FROZEN、行不动;是否改为删除见 §8-R11);`tests/prepare_mwrap_indices.py` 增 `mcpplibs.mplugin` 视图(若成员需要);`tests/mwrap/slint-ui` 与 `validate.yml` 验收步骤升到 1.19.0.3;CHANGELOG | T1(lint 认得这个布局)、T3(发布与镜像就绪) | 全部 lint 通过(含 `check_cross_package_refs`、`check_duplicate_versions`、`check_platform_version_parity`);候选 CI 全绿;**客户端从 `pkgs/mcpp/` 解析到新包(U1 的第一次实测)**;`check_installed_template.py --published-index --mirror GLOBAL` 与 `--mirror CN` 冷装 `mcpplibs.mwrap.slint@1.19.0.3` 通过;`mcpplibs.slintgen@1.19.0.1/.2` 与 `mcpplibs.mwrap.slint@1.19.0.1/.2` 仍可解析 | +| **T2** | mcpp-index(PR A2) | `git mv pkgs/m/mcpp.plugins.lua pkgs/m/mcpp.platforms.lua` 到 `pkgs/mcpp/`;适配 `tests/select_members.py`(`pkgs/*/*.lua` 的选择结果不变,`test_select_members.py` 加用例);其他对旧路径的引用(`rules-cuda.lua`、`mcpp.plugins.lua` 注释) | T4(U1 已验证);T2 前核对 mcpp-plugins 的发布流程(U4) | 全量 CI 通过;搬迁前后 `select` 的成员集合一致;已发布行字节不变。**可推后,不阻塞 slint** | +| **T5** | mcpp-community/mcpp | **一个** issue:背景、本规范链接、§2 实测、对 `mcpp add` 的建议行为(§3.7) | T1 已合入 | issue 开出;不阻塞任何后续任务 | +| **T6** | 各 -m 仓库与索引 | 其余老包按需迁移:grpc、protobuf、clangtidy、openkal-bind;每个包 = 新 id(版本线从其上游版本起)+ 冻结老描述符;第一个独立规则迁移时完成测试阶段 2(`tests/mcpp/`,§3.4) | 对应包下次要发版 | 按 T3/T4 的同一套验收 | + +### 5.2 依赖关系 + +``` +T0 评审 + ├─► T1 (A1: 规范 + lint) ──► T4 (索引 PR B: 新描述符 + 冻结老的 + 冷装验收) ──► T2 (A2: 官方两包搬迁,可推后) + │ └──► T5 (mcpp issue) ▲ └─► T6 (其余老包,按需) + └─► T3 (slint-m: 改名、1.19.0.3、标签、两处发布) ─┘ +``` + +- T1 与 T3 可并行;T4 同时依赖 T1、T3;T2 排在 T4 之后(Q8,待确认),不阻塞 slint。 +- T5 只依赖 T1。slint 的新形态**今天就能用**,不需要 mcpp 发布任何东西(§2 在 CI 固定的版本上复验过)。 +- 每个 PR 单独开、单独 CI、单独合入(A1、T3、T4、A2);T3 的发布遵循既有流程(CI 在标签提交上成功才能发布,已存在的 release 不覆盖,标签不移动)。 + +### 5.3 回滚 +- A1/A2/T4 是索引内的 PR:合入后出问题,用后续 PR 修;已发布的行从不改。 +- T3 的标签不移动;出问题以修订 `1.19.0.4` 修复。 +- 老 id 与老版本全程保持可用,所以任何一步失败都不影响已有使用者。 + +## 6. 风险与未验证项 + +| # | 项 | 状态 / 处理 | +|---|---|---| +| U1 | 客户端从目录名为 `mcpp` 的目录找到包:`docs/mwrap.md` 写明按声明身份扫描子目录,没有用 `pkgs/mcpp/` 实测 | T4 的验收就是第一次实测(slint 是 `pkgs/mcpp/` 的第一个文件);若失败,回退为 `pkgs/mplugin/` 只放社区包,官方留在 `pkgs/m/` | +| U2 | `prepare_mwrap_indices.py` 按 namespace 建视图(`compat`、`mcpplibs.mwrap`、`grpc`、`mcpplibs`),新 namespace `mcpplibs.mplugin` 的成员可能需要新视图 | T4 内适配;若成员测试不需要则不加 | +| U3 | `select_members.py` 对 `pkgs/*/*.lua` 的选择是否因搬迁而变 | T2 的验收:搬迁前后选择集合一致 | +| U4 | mcpp-plugins 的发布自动化是否改 `pkgs/m/mcpp.plugins.lua`:我在 mcpp-index、mcpp-community、各 -m 仓库里 grep 了路径,CI 里没有引用,但没读 mcpp-plugins 的发布流程 | T2 前核对 | +| U5 | 规则包的模块名以包 id 为前缀,在描述符层看不出(模块名在归档的源码里,索引 lint 看不到) | 评审 + 规则仓库自己的 CI 加一行检查(Q5) | +| U6 | grpcgen、protogen、clangtidy 的模块名没有逐个核对 | T6 各包迁移时核对 | +| U7 | 第三方 owner 的归属没有自动校验 | 文档写明;评审把关;不是本规范新增的负担 | +| U8 | `mplugin` 与官方 `mcpp.plugins`、`mcpp.rules` 字面相近,可能被误认 | 文档中用一句话说明;种类段已决定(Q1) | +| U9 | 搜索 `mcpp` 找不到 `mplugin` 包 | 描述符 `description` 写明 “mcpp build plugin” | +| U10 | 未迁移的老使用者要在某一天自己改依赖名才能拿到新版本 | 冻结描述符的 `description` + 文档对照表 + CHANGELOG | +| U11 | 构建插件会在构建机上执行任意代码,`mplugin` 不代表被审计 | §3.9;评审 | +| U12 | 描述符的行版本(`1.19.0`)与包装包版本(`1.19.0.3`)、规则 `rules/mcpp.toml` 的 `version` 三者不同,引擎或 `mcpp pack` 是否要求一致没有实测 | T3 的验收项;若要求一致,退回为“规则版本等于包装包版本”(`1.19.0.3`),D10 改为只对描述符生效,由维护者再定 | +| U13 | 新形态在比 2026.11.18.1 更早的 mcpp 上的行为没有测 | 新包声明的 mcpp 版本下限取 CI 固定版本;沿用 `mcpp.plugins` 描述符声明下限的方式(T4 核对写法) | + +## 7. 决定与待决 + +### 7.1 维护者已决定(2026-11-21) + +| 问题 | 决定 | +|---|---| +| Q1 种类段 | `mplugin` | +| Q2 目录 | `pkgs/mcpp/` 放官方 + mcpplibs + 第三方,文件名完整 id;U1 失败则回退 | +| Q3 PR 切分 | A1 / A2 / T3 / T4 四个 PR | +| Q4 老包 | 只冻结,不转发;冻结时删 `autoupdate`、描述加 FROZEN | +| Q5 前缀不变式 | 评审 + 规则仓库 CI 一行检查 | +| Q6 测试成员位置 | 先 a:留 `tests/mwrap/slint-ui`;最终收敛到 `tests/mcpp/`;构建包与库包分开测,构建包只测 `build.mcpp` 的简单功能(D9) | +| Q7 `rules/LICENSE` | 加;`STATIC_NOTICES` 不扩展 | +| Q9 slint 版本号 | 新 id 从头开始(首个版本 `1.19.0`),因为还没有使用者(D10) | +| Q10 mcpp issue | 一个 issue 汇总信息(D11) | + +### 7.2 待决 +- **Q8**(维护者未答):实施顺序 T1 → T3 → T4 → T2,T2 可推后。暂按此(D12)。 +- **R11**(自审引出,§8):slint 还没有使用者,老的 `mcpplibs.slintgen` 是**冻结保留**(默认)还是**从索引删除**? +- **R12**(自审引出,§8):U12 若实测要求规则版本等于包装包版本,D10 的“规则版本从 1.19.0 起”是否改为“规则版本等于包装包版本”? + +## 8. 多视角自审 + +自审的方法:把 §1 到 §7 当作评审对象,分别站在九个角色的位置,逐条核对文档里的断言是否有证据、有没有漏掉的前提;能查的当场查(结果写在各条),查不了的转成 §6 的未验证项或 §7 的待决。 + +| 视角 | 检查点 | 结论 / 因此做的修改 | +|---|---|---| +| **R1 已有使用者与兼容** | 老 id、老版本、老归档、已安装 xpkg 是否全程可用;包装包对规则的 `reexport` 是否影响老版本 | 全程不动;包装包老版本自带老规则,不受影响。唯一的副作用是写死老 id 的使用者拿不到新版本(U10),已列出;slint 目前没有使用者 | +| **R2 索引维护与 CI 基础设施** | `pkgs/mcpp/` 会不会被发布、被 lint 覆盖 | **已查**:发布脚本 `tools/publish_mcpp_index.sh` 对整个 `pkgs/` 做 `cp -a`;`validate.yml` 的 lint 全部用 `pkgs/*/*.lua` 通配,所以 `pkgs/mcpp/` 自动被发布和 lint。需要适配的只有按 namespace 建视图的 `prepare_mwrap_indices.py`(U2)与成员选择(U3)。T4 验收里补了三个跨包检查 | +| **R3 引擎与客户端** | 新形态在 CI 固定的版本上是否零警告 | **已补测**:CI 固定 2026.11.18.1,我之前只测了 2026.11.20.1;用 v2026.11.18.1 复验 K、B、D、F,结果一致(§2)。更早版本没测(U13)。U1(目录 `mcpp`)仍未实测,已把验证放在 T4 | +| **R4 发布与流程** | 标签不移动、两处镜像、归档与 sha256、autoupdate | 新增:库绑定规则的描述符行指向包装包的归档,所以**不写 autoupdate**(§3.5),否则机器人可能给同一归档开第二条版本线。D10 引出的“规则版本与包装包版本脱钩”是新增风险(U12),在 T3 验收里实测 | +| **R5 第三方贡献者** | 一个陌生人按文档能不能把包放对位置、过 lint | 路径清楚:取 `.mplugin.`,描述符放 `pkgs/mcpp/` 用完整 id,lint 反馈具体。空缺:没有给第三方的插件仓库模板;不在本计划范围,T6 之后再看 | +| **R6 安全与信任** | `mplugin` 是否会被误读成“已审计”;owner 抢注;官方 `mcpp.*` 冒用 | 新增 §3.9 与 U11:构建插件会在构建机上执行任意代码;owner 与抢注靠评审;lint 查不了“谁维护”,若有 CODEOWNERS 把 `pkgs/mcpp/mcpp.*` 归官方 | +| **R7 规范自身的一致性** | owner、种类段、保留名之间有没有漏洞 | 补了一条:owner 不得是种类段(`mwrap`、`mplugin`),否则出现 `mwrap.mplugin.x` 这类难读的 id(§3.2-3,T1 lint)。另:我之前把 `mrule` 说成“不会和官方混淆”是错的(官方也有 `mcpp.rules.*`),已在决定 Q1 的说明里更正 | +| **R8 测试策略** | 构建包与库包的测试是否分开 | 按 D9 写入 §3.4:构建包只测 `build.mcpp` 的简单功能;位置分两个阶段,避免现在为 `tests/mcpp/` 补一整套脚本分支 | +| **R9 迁移可行性与工作量** | slint 的 T3/T4 是否是已跑通流程的重复;有无新增步骤 | 主体重复我之前做过的 1.19.0.2 流程。新增的有三处:规则版本脱钩(U12)、`reexport` 键改名在固定版本上的验证、`pkgs/mcpp/` 首次解析(U1)。T4 不再依赖 T2(D12),顺序改为 T1 → T3 → T4 → T2 | +| **R10 可逆性** | 每一步出问题能否回退 | A1、T4、A2 是索引内 PR,出问题用后续 PR 修;已发布的行从不改;T3 的标签不移动,出问题发修订;老 id 全程可用,所以任何一步失败都不影响已有使用者 | +| **R11 slint 的老包(自审引出)** | 因为“还没有使用者”,是不是不必冻结老的 `mcpplibs.slintgen` | 删除可以让索引更干净,但已发布的归档、GitHub release 与 CN 镜像不会随之消失,且删除不可逆、与“老 xpkg 不删除、仍可用”的原则相悖;冻结没有代价。**默认冻结**,请维护者确认 | +| **R12 版本脱钩的退路(自审引出)** | 若 U12 实测失败怎么办 | 退回规则版本 = 包装包版本(`1.19.0.3`),D10 只保留“新 id、描述符独立”这一层;由维护者再定 | + +自审修改汇总:补 owner 不得为种类段;补 §3.9 安全说明;补“在 CI 固定版本上复验”;库绑定规则描述符不写 autoupdate;T4 验收加三个跨包 lint 与首次 `pkgs/mcpp/` 解析;顺序改为 T1 → T3 → T4 → T2;新增 U11–U13 与 R11、R12 两个待决。 + +## 9. 执行记录(2026-11-21) + +维护者以目标“按本文实施,每个仓库尽量单 PR,CI 通过后 squash 合入、发布,最后综合汇报”授权;未答的 Q8 按建议(顺序 T1 → T3 → T4 → T2),R11 按默认(冻结保留),R12 按 D10(实测通过则保持脱钩)。mcpp 项目只提一个 issue,不提 PR。 + +| 任务 | 结果 | +|---|---| +| T3 slint-m | PR #4 squash 合入(3a24e15),四个 CI 任务与 templates 通过;标签 `mwrap-1.19.0.3`,release 与 `mcpp-res/mwrap-slint` 的 `1.19.0.3` 归档逐字节一致(sha256 `d4e409ad…384b`) | +| T1 + T4 mcpp-index | 合并为一个 PR(文档 + lint + `pkgs/mcpp/` 的第一个文件 + 老包冻结 + 成员 + 验收步骤),结果见 PR | +| T5 mcpp issue | 一个 issue,见 PR 合入之后 | +| T2 官方两包搬迁 | 视风险与 CI,单独处理或推后 | + diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index c540fe78..4812889e 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -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 @@ -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 + # `.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 @@ -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' diff --git a/CHANGELOG.md b/CHANGELOG.md index 66dd1294..3e845d5e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,8 @@ ### Added +- **构建插件的命名与布局规范(docs/build-plugins.md)与第一个新形态的包 mcpplibs.mplugin.slint 1.19.0。** 构建插件的 id 是 `.mplugin.`,模块名与 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`(`.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 diff --git a/docs/build-plugins.md b/docs/build-plugins.md new file mode 100644 index 00000000..e2db6576 --- /dev/null +++ b/docs/build-plugins.md @@ -0,0 +1,140 @@ +# Build plugins: `.mplugin.` + +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 `.mplugin.`. Its module and its C++ +namespace are that id: + +| Spelling | Form | Example | +|---|---|---| +| package (namespace + name) | `.mplugin` + `` | `mcpplibs.mplugin.slint` | +| module | the id; sub-modules `.` | `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 `::mplugin::` and not +`::mcpp::`, code inside a plugin writes the engine as `mcpp::…` +and nothing shadows it. + +Rules: + +1. `` and `` 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. `` is who maintains the package. `mcpplibs` is for packages the + mcpplibs organization maintains; anyone else uses their own name. +3. `` 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 `.`. +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, `` 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 ` = { path = "rules", host-module = true, reexport = true }` | only the wrapper | +| a general tool | its own repository | `[build-dependencies] = { 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/.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 = + ".mplugin"`, `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 `.mplugin` is in `pkgs/mcpp/`; a file + in `pkgs/mcpp/` has namespace `mcpp` or `.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/-/`. + +## 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..`, 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 ` 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: `.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. diff --git a/docs/package-types.md b/docs/package-types.md index 7331ac5e..9c803c7c 100644 --- a/docs/package-types.md +++ b/docs/package-types.md @@ -2,6 +2,8 @@ Module wrappers preserve upstream APIs under `mcpplibs.mwrap.`. Use `pkgs/mwrap/.lua`; see [the wrapper specification](mwrap.md). Every -m repository has English and Chinese READMEs. +Build plugins (modules a `build.mcpp` imports) are `.mplugin.`, descriptors in `pkgs/mcpp/`; see [build plugins](build-plugins.md). + **English** | [简体中文](zh/package-types.md) diff --git a/docs/repository-and-schema.md b/docs/repository-and-schema.md index 0fa34ccd..e6c47e53 100644 --- a/docs/repository-and-schema.md +++ b/docs/repository-and-schema.md @@ -2,7 +2,7 @@ **English** | [简体中文](zh/repository-and-schema.md) -Module wrapper descriptors use `pkgs/mwrap/.lua` and their consumers use `tests/mwrap//`; 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/.lua` and their consumers use `tests/mwrap//`; see [the mwrap specification](mwrap.md). Build plugins (`.mplugin.`) and the mcpp project's own packages use `pkgs/mcpp/.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 @@ -20,7 +20,8 @@ tests/examples// 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 `.mplugin` owner is not mcpp, a reserved name or a kind segment +tests/check_mplugin_layout.lua lint: `.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 diff --git a/docs/zh/build-plugins.md b/docs/zh/build-plugins.md new file mode 100644 index 00000000..900e34d6 --- /dev/null +++ b/docs/zh/build-plugins.md @@ -0,0 +1,98 @@ +# 构建插件:`.mplugin.` + +**构建插件**是模块由工程的 `build.mcpp` 导入的包(`host-module`):代码生成器、工具封装、规则集。本页是它们的命名与布局规则;设计记录见 +`.agents/docs/2026-11-21-mcpp-build-plugin-naming-plan.md`。 + +[English](../build-plugins.md) + +## 一个名字,三种写法 + +构建插件的 id 是 `.mplugin.`;模块名和 C++ 命名空间都是这个 id: + +| 写法 | 形式 | 例子 | +|---|---|---| +| 包(namespace + name) | `.mplugin` + `` | `mcpplibs.mplugin.slint` | +| 模块 | 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` 是它的构建插件)。命名空间是 +`::mplugin::`,不是 `::mcpp::`,所以插件内部直接写 `mcpp::…` 调用引擎,不会被遮蔽。 + +规则: + +1. `` 与 `` 是小写标识符,`[a-z][a-z0-9_]*`:多词用 `_` 连接,不用 `-`(模块名需要标识符;`mcpplibs.mwrap.godot_cpp` 是同一条规则)。 +2. `` 是维护者。`mcpplibs` 只给 mcpplibs 组织维护的包;其他人用自己的名字。 +3. `` 不得是 `mcpp`,不得是 mcpp 项目的保留名(`core`、`plugins`、`deps`、`rules`、`dist`、`tools`、`platforms`),也不得是种类段(`mwrap`、 + `mplugin`)。官方新增一个包名即加入保留名,新增时须核对没有 owner 已用此名。 +4. 主接口模块恰好是 id;包内其他模块都以 `.` 开头。 +5. 第一段是 `mcpp` 的包由 mcpp 项目维护,不属于这个形态(`mcpp.plugins`、`mcpp.platforms`)。 +6. 与某个库绑定的规则,`` 是库名(`slint`、`grpc`、`protobuf`),不加 `gen`、`-bind` 后缀;同一个库的多个规则是同一个包的函数。通用工具取工具名 + (`clangtidy`)。 + +## 规则放在哪里 + +| 类型 | 放在 | 工程怎么写 | +|---|---|---| +| 与某个库绑定 | 该库 `-m` 仓库的 `rules/` 子包;描述符写 `mcpp = "*/rules/mcpp.toml"`;封装包的根 manifest 有 ` = { path = "rules", host-module = true, reexport = true }` | 只依赖封装包 | +| 通用工具 | 自己的仓库 | `[build-dependencies] = { 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 = ".mplugin"`、`name = ""`),与 `pkgs/mwrap/` 相同。目录不说明包是什么: + `mcpp.platforms` 是平台数据,不是插件。 +- namespace 为 `.mplugin` 的描述符在 `pkgs/mcpp/`;`pkgs/mcpp/` 里文件的 namespace 是 `mcpp` 或 `.mplugin`(lint: + `tests/check_mplugin_layout.lua`)。 +- **构建插件与它的库分开测试。** 插件的成员只测 `build.mcpp` 能用它做什么(规则对一个小输入产出什么,生成的模块能否编译,改动的输入是否重新生成);库本身的行为 + 由封装包的成员与已安装模板检查来测。与库绑定的插件起初通过封装包的成员测(`tests/mwrap/…`);独立的插件用 `tests/mcpp/-/`。 + +## 版本 + +每个包有自己的版本线:首个版本是它所针对的上游版本,修订追加 `.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..`,SPEC-007 §9),并不是错的。它们的描述符与归档保留;已发布的行不改。 + +- 一个包在下次需要新版本时迁到新形态:新 id 在 `pkgs/mcpp/` 发布,老描述符冻结(无 `autoupdate`,描述里写 `FROZEN: superseded by `),不再有新版本。没有转发模块。 +- 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` | +| 布局:`.mplugin` ↔ `pkgs/mcpp/`;owner 与 name 是标识符 | `tests/check_mplugin_layout.lua` | +| 成员构建不打印引擎对保留模块名的警告 | `tests/run_members.sh` | +| 模块就是包 id | 规则自己仓库的 CI(索引读不到归档里的源码) | + +构建插件在构建机器上运行代码:按“会执行代码的包”评审。`mplugin` 不表示已审计;owner 是谁、模仿 `mcpplibs` 的名字,由评审判断。 diff --git a/docs/zh/package-types.md b/docs/zh/package-types.md index 8c122426..b8718ba5 100644 --- a/docs/zh/package-types.md +++ b/docs/zh/package-types.md @@ -2,6 +2,8 @@ 模块封装统一使用 `mcpplibs.mwrap.`,描述符位于 `pkgs/mwrap/.lua`;见 [mwrap 规范](mwrap.md)。每个 -m 仓库必须提供默认英文与中文 README。 +构建插件(`build.mcpp` 导入的模块)是 `.mplugin.`,描述符位于 `pkgs/mcpp/`;见[构建插件](build-plugins.md)。 + [English](../package-types.md) | **简体中文** diff --git a/docs/zh/repository-and-schema.md b/docs/zh/repository-and-schema.md index 88aca800..c9b64ce4 100644 --- a/docs/zh/repository-and-schema.md +++ b/docs/zh/repository-and-schema.md @@ -2,7 +2,7 @@ [English](../repository-and-schema.md) | **简体中文** -模块封装描述符使用 `pkgs/mwrap/.lua`,消费者使用 `tests/mwrap//`,见 [mwrap 规范](mwrap.md)。分类目录平铺并原样发布。workspace 测试源码使用当前固定的 mcpp;`index.toml` 单独声明描述符兼容下限。 +模块封装描述符使用 `pkgs/mwrap/.lua`,消费者使用 `tests/mwrap//`,见 [mwrap 规范](mwrap.md)。构建插件(`.mplugin.`)与 mcpp 项目自己的包使用 `pkgs/mcpp/<完整 id>.lua`,见[构建插件](build-plugins.md)。分类目录平铺并原样发布。workspace 测试源码使用当前固定的 mcpp;`index.toml` 单独声明描述符兼容下限。 ## 仓库布局 @@ -19,7 +19,8 @@ tests/examples// 每库测试工程(workspace 成员; 为包 tests/*.cpp 行为断言(独立 main,退出码非 0 即失败) tests/check_mirror_urls.lua lint:GLOBAL+CN 表完整性,以及 CN 指向 mcpp-res tests/check_package_name.lua lint:身份形态(name 为单一原子段,层级归 namespace) -tests/check_reserved_namespace.lua lint:命名空间不得是 `mcpp.` 的保留第二段(core、plugins、deps、rules、dist、tools) +tests/check_reserved_namespace.lua lint:命名空间不得是 `mcpp.` 的保留第二段(core、plugins、deps、rules、dist、tools);`.mplugin` 的 owner 不得是 mcpp、保留名或种类段 +tests/check_mplugin_layout.lua lint:`.mplugin` 描述符在 pkgs/mcpp/,其中的文件是 namespace `mcpp` 或构建插件;owner 与 name 是标识符 tests/list_cn_urls.lua 抽取 CN url,供 mirror-cn-reachable 使用 tests/run_members.sh 逐个运行 workspace 成员并计时。CI 与本地共用的入口,见下文「本地运行 workspace 成员」 tests/plan_shards.lua 依实测耗时将成员分配到各分片。由 `select` job 调用一次,`run_members.sh --shard` diff --git a/mcpp.toml b/mcpp.toml index 22a0a57d..25e2d500 100644 --- a/mcpp.toml +++ b/mcpp.toml @@ -24,6 +24,7 @@ members = [ "tests/mwrap/libpng-image", "tests/mwrap/libwebp-image", "tests/mwrap/slint-ui", + "tests/mwrap/slint-rule", "tests/mwrap/wuffs-decode", "tests/mwrap/concurrentqueue-mpmc", "tests/mwrap/fribidi-bidi", diff --git a/pkgs/mcpp/mcpplibs.mplugin.slint.lua b/pkgs/mcpp/mcpplibs.mplugin.slint.lua new file mode 100644 index 00000000..d303c063 --- /dev/null +++ b/pkgs/mcpp/mcpplibs.mplugin.slint.lua @@ -0,0 +1,72 @@ +-- mcpplibs.mplugin.slint -- slint-compiler as an importable build plugin. +-- +-- A build plugin is `.mplugin.`; its module and its C++ namespace are +-- that id (docs/build-plugins.md): +-- +-- package mcpplibs.mplugin.slint +-- module mcpplibs.mplugin.slint +-- namespace mcpplibs::mplugin::slint +-- +-- Most projects never name it: mcpplibs.mwrap.slint re-exports it, so +-- +-- [dependencies] +-- mcpplibs.mwrap.slint = "1.19.0.3" +-- +-- // 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; +-- } +-- +-- A project without the wrapper writes `mcpplibs.mplugin.slint = { version = +-- "1.19.0", host-module = true }` under [build-dependencies] and depends on +-- compat.slint for the SDK. +-- +-- The package's version is the Slint it drives; its archive is the one of the +-- wrapper's tag (slint-m mwrap-1.19.0.3: same bytes, same sha256, GLOBAL and +-- CN), `rules/` of it. The rows are added with the wrapper's, so there is no +-- autoupdate here. It replaces mcpplibs.slintgen (frozen, pkgs/s/slintgen.lua). +package = { + spec = "1", + namespace = "mcpplibs.mplugin", + name = "slint", + description = "slint-compiler as an importable mcpp build plugin (host-module mcpplibs.mplugin.slint)", + licenses = {"Apache-2.0"}, + repo = "https://github.com/mcpplibs/slint-m", + type = "package", + + xpm = { + linux = { + ["1.19.0"] = { + url = { + GLOBAL = "https://github.com/mcpplibs/slint-m/releases/download/mwrap-1.19.0.3/slint-m-1.19.0.3.tar.gz", + CN = "https://gitcode.com/mcpp-res/mwrap-slint/releases/download/1.19.0.3/slint-m-1.19.0.3.tar.gz", + }, + sha256 = "d4e409ad021215cccedf45d3d66932b82fabcd07627c5d6ce6961a4ef88a384b", + }, + }, + macosx = { + ["1.19.0"] = { + url = { + GLOBAL = "https://github.com/mcpplibs/slint-m/releases/download/mwrap-1.19.0.3/slint-m-1.19.0.3.tar.gz", + CN = "https://gitcode.com/mcpp-res/mwrap-slint/releases/download/1.19.0.3/slint-m-1.19.0.3.tar.gz", + }, + sha256 = "d4e409ad021215cccedf45d3d66932b82fabcd07627c5d6ce6961a4ef88a384b", + }, + }, + windows = { + ["1.19.0"] = { + url = { + GLOBAL = "https://github.com/mcpplibs/slint-m/releases/download/mwrap-1.19.0.3/slint-m-1.19.0.3.tar.gz", + CN = "https://gitcode.com/mcpp-res/mwrap-slint/releases/download/1.19.0.3/slint-m-1.19.0.3.tar.gz", + }, + sha256 = "d4e409ad021215cccedf45d3d66932b82fabcd07627c5d6ce6961a4ef88a384b", + }, + }, + }, + + mcpp = "*/rules/mcpp.toml", +} diff --git a/pkgs/mwrap/slint.lua b/pkgs/mwrap/slint.lua index dca0995d..26875148 100644 --- a/pkgs/mwrap/slint.lua +++ b/pkgs/mwrap/slint.lua @@ -1,5 +1,5 @@ --- Immutable upstream-aligned mwrap source releases (slint-m mwrap-1.19.0.2, and --- mwrap-1.19.0.1 with its published bytes); +-- Immutable upstream-aligned mwrap source releases (slint-m mwrap-1.19.0.3, and +-- mwrap-1.19.0.2 and mwrap-1.19.0.1 with their published bytes); -- GLOBAL and CN bytes are identical. -- -- The wrapper is Apache-2.0. The library it links, compat.slint (Slint 1.19.0, @@ -9,8 +9,9 @@ -- license texts beside programs (runtime.deploy). Linux x86_64, macOS arm64 and -- Windows x86_64: compat.slint's payload has no Linux aarch64 row yet. -- --- The build rule mcpp.mcpplibs.slintgen is the separate package --- mcpplibs.slintgen (rules/ of the same archive), re-exported from 1.19.0.2 on. +-- The build rule is the separate package mcpplibs.mplugin.slint (rules/ of the +-- same archive; module and C++ namespace of that name), re-exported from 1.19.0.3 +-- on; 1.19.0.2 and 1.19.0.1 carry the earlier name mcpplibs.slintgen. package = { spec = "1", namespace = "mcpplibs.mwrap", @@ -27,6 +28,13 @@ package = { }, xpm = { linux = { + ["1.19.0.3"] = { + url = { + GLOBAL = "https://github.com/mcpplibs/slint-m/releases/download/mwrap-1.19.0.3/slint-m-1.19.0.3.tar.gz", + CN = "https://gitcode.com/mcpp-res/mwrap-slint/releases/download/1.19.0.3/slint-m-1.19.0.3.tar.gz", + }, + sha256 = "d4e409ad021215cccedf45d3d66932b82fabcd07627c5d6ce6961a4ef88a384b", + }, ["1.19.0.2"] = { url = { GLOBAL = "https://github.com/mcpplibs/slint-m/releases/download/mwrap-1.19.0.2/slint-m-1.19.0.2.tar.gz", @@ -43,6 +51,13 @@ package = { }, }, macosx = { + ["1.19.0.3"] = { + url = { + GLOBAL = "https://github.com/mcpplibs/slint-m/releases/download/mwrap-1.19.0.3/slint-m-1.19.0.3.tar.gz", + CN = "https://gitcode.com/mcpp-res/mwrap-slint/releases/download/1.19.0.3/slint-m-1.19.0.3.tar.gz", + }, + sha256 = "d4e409ad021215cccedf45d3d66932b82fabcd07627c5d6ce6961a4ef88a384b", + }, ["1.19.0.2"] = { url = { GLOBAL = "https://github.com/mcpplibs/slint-m/releases/download/mwrap-1.19.0.2/slint-m-1.19.0.2.tar.gz", @@ -59,6 +74,13 @@ package = { }, }, windows = { + ["1.19.0.3"] = { + url = { + GLOBAL = "https://github.com/mcpplibs/slint-m/releases/download/mwrap-1.19.0.3/slint-m-1.19.0.3.tar.gz", + CN = "https://gitcode.com/mcpp-res/mwrap-slint/releases/download/1.19.0.3/slint-m-1.19.0.3.tar.gz", + }, + sha256 = "d4e409ad021215cccedf45d3d66932b82fabcd07627c5d6ce6961a4ef88a384b", + }, ["1.19.0.2"] = { url = { GLOBAL = "https://github.com/mcpplibs/slint-m/releases/download/mwrap-1.19.0.2/slint-m-1.19.0.2.tar.gz", diff --git a/pkgs/s/slintgen.lua b/pkgs/s/slintgen.lua index c3de592d..d9772974 100644 --- a/pkgs/s/slintgen.lua +++ b/pkgs/s/slintgen.lua @@ -1,5 +1,8 @@ -- slintgen -- slint-compiler as an importable build rule. -- +-- FROZEN: superseded by mcpplibs.mplugin.slint (pkgs/mcpp/, docs/build-plugins.md). +-- This package keeps 1.19.0.1 and 1.19.0.2 as published and gets no more versions. +-- -- One name in three spellings, as mcpplibs.openkal-bind is (SPEC-007 R9.6, a -- third-party plugin's `mcpp..`): -- @@ -36,7 +39,7 @@ package = { spec = "1", namespace = "mcpplibs", name = "slintgen", - description = "slint-compiler as an importable mcpp build rule (host-module mcpp.mcpplibs.slintgen)", + description = "FROZEN: superseded by mcpplibs.mplugin.slint. slint-compiler as an importable mcpp build rule (host-module mcpp.mcpplibs.slintgen)", licenses = {"Apache-2.0"}, repo = "https://github.com/mcpplibs/slint-m", type = "package", diff --git a/tests/check_mplugin_layout.lua b/tests/check_mplugin_layout.lua new file mode 100644 index 00000000..19e26dad --- /dev/null +++ b/tests/check_mplugin_layout.lua @@ -0,0 +1,48 @@ +-- Lint the build-plugin layout (docs/build-plugins.md). +-- +-- A descriptor whose namespace is `.mplugin` is a build plugin: it lives in +-- pkgs/mcpp/, and its owner and name are lower-case identifiers. The other way +-- round, a file in pkgs/mcpp/ is a package of the mcpp project (namespace `mcpp`) +-- or a build plugin. The directory is what mcpp itself loads, not what a package +-- is (mcpp.platforms is platform data), so the layout is the only thing checked +-- here; the reserved owners are tests/check_reserved_namespace.lua. +-- +-- Usage: lua5.4 tests/check_mplugin_layout.lua + +function import(...) + return setmetatable({}, {__index = function() return function() end end}) +end + +local path = assert(arg[1], "usage: check_mplugin_layout.lua ") +package = nil +local chunk = assert(loadfile(path, "t")) +chunk() + +local p = package +if type(p) ~= "table" or type(p.namespace) ~= "string" then os.exit(0) end +local ns, name = p.namespace, p.name + +local dir = path:match("^(.*)/[^/]+$") or "" +local in_mcpp_dir = dir == "pkgs/mcpp" or dir:match("/pkgs/mcpp$") ~= nil +local owner = ns:match("^([^.]+)%.mplugin$") +local function fail(msg) + io.stderr:write(string.format("::error file=%s::%s\n", path, msg)) + os.exit(1) +end + +if owner then + if not in_mcpp_dir then + fail(string.format("a build plugin ('%s.%s') is a descriptor of pkgs/mcpp/ (docs/build-plugins.md)", ns, tostring(name))) + end + if not owner:match("^[a-z][a-z0-9_]*$") then + fail(string.format("owner '%s' of a build plugin is a lower-case identifier [a-z][a-z0-9_]*", owner)) + end + if type(name) ~= "string" or not name:match("^[a-z][a-z0-9_]*$") then + fail(string.format("name '%s' of a build plugin is a lower-case identifier [a-z][a-z0-9_]* (use _, not -)", tostring(name))) + end +elseif in_mcpp_dir then + if ns ~= "mcpp" then + fail(string.format("pkgs/mcpp/ holds packages of namespace 'mcpp' and build plugins '.mplugin', not '%s'", ns)) + end +end +os.exit(0) diff --git a/tests/check_reserved_namespace.lua b/tests/check_reserved_namespace.lua index ce19663b..fc343a1f 100644 --- a/tests/check_reserved_namespace.lua +++ b/tests/check_reserved_namespace.lua @@ -27,6 +27,20 @@ local ns = p.namespace if type(ns) ~= "string" then os.exit(0) end local reserved = { core = true, plugins = true, deps = true, rules = true, dist = true, tools = true } +-- A build plugin `.mplugin.` (docs/build-plugins.md) has its owner as the +-- first segment of its namespace. The owner is not `mcpp`, a name of the mcpp project's +-- (the reserved second segments, and its own packages: `platforms`) or a kind segment. +local owner = ns:match("^([^.]+)%.mplugin$") +if owner then + local barred = { mcpp = true, platforms = true, mwrap = true, mplugin = true } + if reserved[owner] or barred[owner] then + io.stderr:write(string.format( + "::error file=%s::owner '%s' of a build plugin is reserved (the mcpp project's names, or a kind segment); " .. + "an owner is who maintains the package (docs/build-plugins.md)\n", path, owner)) + os.exit(1) + end +end + local first = ns:match("^([^.]+)") if first and reserved[first] then io.stderr:write(string.format( diff --git a/tests/mwrap/slint-rule/build.mcpp b/tests/mwrap/slint-rule/build.mcpp new file mode 100644 index 00000000..ba3eabeb --- /dev/null +++ b/tests/mwrap/slint-rule/build.mcpp @@ -0,0 +1,12 @@ +// A build plugin is tested by what build.mcpp can do with it: the rule is run on one +// `.slint` file, which registers the action that writes the header and the include +// directory the test compiles against. How Slint behaves at run time is the wrapper's +// member (tests/mwrap/slint-ui), not this one. +import mcpp; +import mcpplibs.mplugin.slint; + +int main() { + mcpplibs::mplugin::slint::options o; + o.sources = {"ui/t.slint"}; + return mcpplibs::mplugin::slint::compile(o) ? 0 : 1; +} diff --git a/tests/mwrap/slint-rule/mcpp.toml b/tests/mwrap/slint-rule/mcpp.toml new file mode 100644 index 00000000..bcc24292 --- /dev/null +++ b/tests/mwrap/slint-rule/mcpp.toml @@ -0,0 +1,20 @@ +[package] +name = "slint-rule" +version = "1.19.0" +description = "Resolve the indexed build plugin mcpplibs.mplugin.slint (pkgs/mcpp/) and run it from build.mcpp on one .slint file" + +[language] +standard = "c++23" +modules = true +import_std = false + +[indices] +# Use the complete candidate built-in index prepared by tests/run_members.sh. +# An explicit empty table overrides the legacy workspace redirect. + +[dependencies] +# The SDK the rule drives: slint-compiler comes with it. +compat.slint = "1.19.0" + +[build-dependencies] +mcpplibs.mplugin.slint = { version = "1.19.0", host-module = true } diff --git a/tests/mwrap/slint-rule/tests/generated.cpp b/tests/mwrap/slint-rule/tests/generated.cpp new file mode 100644 index 00000000..371b6417 --- /dev/null +++ b/tests/mwrap/slint-rule/tests/generated.cpp @@ -0,0 +1,9 @@ +// t.h is what mcpplibs.mplugin.slint wrote for ui/t.slint; the program compiles against it. +#include "t.h" +#include + +int main() { + static_assert(sizeof(Tiny) > 0); + std::puts("mcpplibs.mplugin.slint: ui/t.slint became t.h, and Tiny compiles"); + return 0; +} diff --git a/tests/mwrap/slint-rule/ui/t.slint b/tests/mwrap/slint-rule/ui/t.slint new file mode 100644 index 00000000..1a869725 --- /dev/null +++ b/tests/mwrap/slint-rule/ui/t.slint @@ -0,0 +1,3 @@ +export component Tiny inherits Window { + in-out property counter: 1; +} diff --git a/tests/mwrap/slint-ui/build.mcpp b/tests/mwrap/slint-ui/build.mcpp index 76e6cadf..70565154 100644 --- a/tests/mwrap/slint-ui/build.mcpp +++ b/tests/mwrap/slint-ui/build.mcpp @@ -1,13 +1,13 @@ -// ui/app.slint reaches mcpp.mcpplibs.slintgen as `options::sources`; the module +// ui/app.slint reaches mcpplibs.mplugin.slint as `options::sources`; the module // `app.ui` exports what the file exports and slint-compiler generates. The SDK // is compat.slint, reached through mcpplibs.mwrap.slint. import mcpp; -import mcpp.mcpplibs.slintgen; +import mcpplibs.mplugin.slint; int main() { - mcpp::mcpplibs::slintgen::options o; + mcpplibs::mplugin::slint::options o; o.sources = {"ui/app.slint"}; o.module = "app.ui"; o.style = "fluent"; - return mcpp::mcpplibs::slintgen::compile(o) ? 0 : 1; + return mcpplibs::mplugin::slint::compile(o) ? 0 : 1; } diff --git a/tests/mwrap/slint-ui/mcpp.toml b/tests/mwrap/slint-ui/mcpp.toml index 86d7ac25..1bc03d33 100644 --- a/tests/mwrap/slint-ui/mcpp.toml +++ b/tests/mwrap/slint-ui/mcpp.toml @@ -1,7 +1,7 @@ [package] name = "slint-ui" -version = "1.19.0.2" -description = "Consume the immutable Slint wrapper: the runtime types and the interpreter through the modules, a .slint file compiled by mcpp.mcpplibs.slintgen into the module app.ui, a component driven headless, the features as constants" +version = "1.19.0.3" +description = "Consume the immutable Slint wrapper: the runtime types and the interpreter through the modules, a .slint file compiled by mcpplibs.mplugin.slint into the module app.ui, a component driven headless, the features as constants" [language] standard = "c++23" @@ -13,9 +13,9 @@ import_std = false # An explicit empty table overrides the legacy workspace redirect. [dependencies] -# The wrapper re-exports the build rule (module mcpp.mcpplibs.slintgen) and the +# The wrapper re-exports the build rule (module mcpplibs.mplugin.slint) and the # SDK: this is the whole dependency list. -mcpplibs.mwrap.slint = "1.19.0.2" +mcpplibs.mwrap.slint = "1.19.0.3" [build] sources = ["src/*.cpp"] diff --git a/tests/test_check_mplugin.py b/tests/test_check_mplugin.py new file mode 100644 index 00000000..f41f77bb --- /dev/null +++ b/tests/test_check_mplugin.py @@ -0,0 +1,77 @@ +"""The two lints of docs/build-plugins.md, run on small descriptors in a temporary tree. + + python3 tests/test_check_mplugin.py +""" +import subprocess +import tempfile +import unittest +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] + + +def descriptor(namespace, name): + return f'package = {{ spec = "1", namespace = "{namespace}", name = "{name}", type = "package" }}\n' + + +def lint(script, directory, filename, namespace, name): + with tempfile.TemporaryDirectory() as tmp: + target = Path(tmp) / directory + target.mkdir(parents=True) + path = target / filename + path.write_text(descriptor(namespace, name)) + result = subprocess.run(["lua5.4", str(ROOT / "tests" / script), str(path)], capture_output=True, text=True) + return result.returncode + + +class MpluginLayout(unittest.TestCase): + def layout(self, directory, namespace, name, filename=None): + return lint("check_mplugin_layout.lua", directory, filename or f"{namespace}.{name}.lua", namespace, name) + + def test_plugin_in_mcpp_dir_passes(self): + self.assertEqual(self.layout("pkgs/mcpp", "mcpplibs.mplugin", "slint"), 0) + + def test_underscores_pass(self): + self.assertEqual(self.layout("pkgs/mcpp", "mcpplibs.mplugin", "openkal_bind"), 0) + + def test_plugin_outside_mcpp_dir_fails(self): + self.assertEqual(self.layout("pkgs/s", "mcpplibs.mplugin", "slint"), 1) + + def test_hyphen_in_name_fails(self): + self.assertEqual(self.layout("pkgs/mcpp", "mcpplibs.mplugin", "openkal-bind"), 1) + + def test_upper_case_owner_fails(self): + self.assertEqual(self.layout("pkgs/mcpp", "Acme.mplugin", "foo"), 1) + + def test_official_package_in_mcpp_dir_passes(self): + self.assertEqual(self.layout("pkgs/mcpp", "mcpp", "plugins"), 0) + + def test_other_namespace_in_mcpp_dir_fails(self): + self.assertEqual(self.layout("pkgs/mcpp", "mcpplibs", "slintgen"), 1) + + def test_wrapper_elsewhere_passes(self): + self.assertEqual(self.layout("pkgs/mwrap", "mcpplibs.mwrap", "slint"), 0) + + +class ReservedOwner(unittest.TestCase): + def reserved(self, namespace, name="x"): + return lint("check_reserved_namespace.lua", "pkgs/mcpp", "x.lua", namespace, name) + + def test_ordinary_owners_pass(self): + for owner in ("mcpplibs", "acme", "d2learn"): + self.assertEqual(self.reserved(owner + ".mplugin"), 0, owner) + + def test_reserved_owners_fail(self): + for owner in ("mcpp", "core", "plugins", "deps", "rules", "dist", "tools", "platforms", "mwrap", "mplugin"): + self.assertEqual(self.reserved(owner + ".mplugin"), 1, owner) + + def test_reserved_first_segment_still_fails(self): + self.assertEqual(self.reserved("plugins"), 1) + + def test_other_namespaces_unaffected(self): + for ns in ("mcpplibs", "compat", "mcpplibs.mwrap", "mcpp"): + self.assertEqual(self.reserved(ns), 0, ns) + + +if __name__ == "__main__": + unittest.main()