Skip to content

Commit e7e1d04

Browse files
authored
mcpp 2026.9.28.3, mcpp.plugins 0.17.0, and the build-plugin naming rule as an admission rule (mcpp#734) (#484)
- docs/package-types.md (both languages) gains section I, build-plugin packages: modules named mcpp.<namespace>.*, the reserved second segments of mcpp. (core, plugins, deps, rules, dist, tools), the plugins-core manifest form and the engine floor. - The lint refuses a namespace spelled like a reserved segment (tests/check_reserved_namespace.lua); tests/run_members.sh fails a member whose build prints the engine's reserved-name warning. docs/repository-and-schema.md (both languages) and the add-package skill state both. - tests/examples/mcpp-plugins builds a program with mcpp.plugins 0.17.0 on every platform: tools-embed and mcpp.plugins.fs in one build program. - mcpp.plugins 0.17.0 is registered (GitHub archive and GitCode mirror, one sha256). - validate.yml runs every member with mcpp 2026.9.28.3; latest_mcpp moves to it; min_mcpp does not move.
1 parent e9b80c5 commit e7e1d04

15 files changed

Lines changed: 217 additions & 9 deletions

File tree

‎.agents/skills/add-mcpp-index-package/SKILL.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -139,5 +139,6 @@ rm -rf "tests/examples/<member>/target" "tests/examples/<member>/.mcpp" # 冷
139139
| 声称实现了 feature 却未做负向验证 | 验证默认构建确实不含该组件 |
140140
| 未对齐 CI 的 mcpp 版本,本地通过而 CI 失败 | 读取 `MCPP_VERSION` 并使用同一版本 |
141141
| 直接推送 `main` | 切出分支并提交 PR |
142+
| 构建插件把模块命名为 `mcpp.rules.*`、`mcpp.plugins.*` 等保留名,或把命名空间取作 `rules`、`tools` 等 | 模块命名为 `mcpp.<自身命名空间>.*`;保留第二段属于 mcpp 项目(docs/zh/package-types.md §I),成员构建出现引擎的保留名警告即失败 |
142143

143144
完成前应遵循 `verification-before-completion`:在声明“通过/完成”之前,须给出真实命令输出作为证据。

‎.github/workflows/validate.yml‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -371,7 +371,13 @@ env:
371371
# that never match one target (linux, macos), so no descriptor's flags move.
372372
#
373373
# `index.toml` min_mcpp does not move: no descriptor grammar changed.
374-
MCPP_VERSION: "2026.9.28.2"
374+
#
375+
# 2026.9.28.3 (mcpp-community/mcpp#734): build programs speak protocol 14,
376+
# so every member's build program re-runs once; mcpp.plugins 0.17.0 states it
377+
# as its floor, and tests/examples/mcpp-plugins builds against it. Engine
378+
# warnings the members may newly print: W1 to W3 of SPEC-008 (the library
379+
# interface), warnings only.
380+
MCPP_VERSION: "2026.9.28.3"
375381

376382
jobs:
377383
lint:
@@ -422,6 +428,14 @@ jobs:
422428
if ! lua5.4 tests/check_package_name.lua "$f"; then
423429
fail=1
424430
fi
431+
# 5b. The build-plugin naming rule (mcpp#734): a namespace may not be
432+
# one of the reserved second segments of `mcpp.` (core, plugins,
433+
# deps, rules, dist, tools), which name the mcpp project's own
434+
# modules. The module names themselves are checked where members
435+
# build (tests/run_members.sh), by the engine's own warning.
436+
if ! lua5.4 tests/check_reserved_namespace.lua "$f"; then
437+
fail=1
438+
fi
425439
# 6. c++fly admission policy (mcpp design 2026-07-14 §11-Q2, v1):
426440
# c++fly means "toolchain's latest level + every experimental
427441
# gate" — deliberately toolchain-dependent, so a published

‎docs/package-types.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -294,6 +294,38 @@ Four things to get right:
294294
The matching member is `tests/examples/protobuf-protoc`, and it is the complement of `tests/examples/protobuf`: that
295295
one deliberately uses no generated code, this one is generated code end to end.
296296

297+
## I. Build-plugin package (`mcpp.plugins`)
298+
299+
A build plugin is a package whose modules a consumer's `build.mcpp` imports: its
300+
units import `mcpp.core` (also spelled `mcpp`) and reach a consumer through a
301+
`[build-dependencies]` edge with `host-module = true`. Three rules admit one to
302+
this index (mcpp#734):
303+
304+
- **Module names.** A plugin names its build-program modules
305+
`mcpp.<namespace>.*` after its own namespace (`mcpp.acme.protobuf`). The second
306+
segments `core`, `plugins`, `deps`, `rules`, `dist` and `tools` belong to the
307+
mcpp project. The engine warns when another package uses them (mcpp SPEC-007
308+
§9); a member whose build prints that warning fails `tests/run_members.sh`,
309+
and the lint refuses a namespace spelled like one of them
310+
(`tests/check_reserved_namespace.lua`). Modules the package also offers to
311+
programs follow the library rule, `<namespace>.<name>.*` (mcpp SPEC-008 I3).
312+
- **The manifest.** The official general library is reached through the feature
313+
`plugins-core`. A plugin built on it depends on `mcpp.plugins` with
314+
`host-module = true` and `features = ["plugins-core"]`, and adds
315+
`reexport = true` when its consumers' build programs import the library
316+
themselves:
317+
318+
```toml
319+
[build-dependencies.mcpp]
320+
plugins = { version = "0.17.0", features = ["plugins-core"], host-module = true, reexport = true }
321+
```
322+
- **The engine floor.** The package states the first mcpp release it needs,
323+
`[package] mcpp = ">=<release>"`; an older engine stops and names the upgrade.
324+
A plugin that reads the build information (the resolved tools, `mcpp::report`)
325+
needs 2026.9.28.3.
326+
327+
The matching member is `tests/examples/mcpp-plugins`.
328+
297329
---
298330

299331
## The minimal project (`tests/examples/<short>/`)

‎docs/repository-and-schema.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ tests/examples/<member>/ one test project per library (a workspace member; <
1818
tests/*.cpp behavioral assertions (standalone main; a non-zero exit code is a failure)
1919
tests/check_mirror_urls.lua lint: GLOBAL+CN table completeness, and that CN points at mcpp-res
2020
tests/check_package_name.lua lint: identity shape (name is a single atomic segment, hierarchy belongs to namespace)
21+
tests/check_reserved_namespace.lua lint: a namespace is not a reserved second segment of `mcpp.` (core, plugins, deps, rules, dist, tools)
2122
tests/list_cn_urls.lua extracts the CN urls for mirror-cn-reachable
2223
tests/run_members.sh runs workspace members one at a time and times each. The entry point used both by CI
2324
and locally; see "Running workspace members locally" below
@@ -164,7 +165,7 @@ locally with `mcpp xpkg parse pkgs/<x>/<name>.lua`.
164165
- `env.MCPP_VERSION` is the mcpp version every job uses; local verification should match it.
165166
- `lint` (always runs): lua syntax via `loadfile(f,'t')`; `spec=`/`name=`/`xpm=` must be present; leading-v versions
166167
are rejected; runs `check_mirror_urls.lua`; runs `check_package_name.lua` (identity shape, see "Package identity"
167-
above); then runs `mcpp xpkg parse` over every descriptor with the mcpp version CI pins (strict — an unknown key
168+
above); runs `check_reserved_namespace.lua` (the build-plugin naming rule, docs/package-types.md §I); then runs `mcpp xpkg parse` over every descriptor with the mcpp version CI pins (strict — an unknown key
168169
fails). `xpkg parse` in mcpp >= 0.0.106 enforces the identity shape itself, which makes the lua lint an earlier and
169170
cheaper redundant gate.
170171
- `mirror-cn-reachable` (always runs): `curl`s each CN url; all must return 200.
@@ -227,6 +228,7 @@ for f in pkgs/*/*.lua; do
227228
grep -nqE '\["v[0-9]+|\["[^"]+"\][[:space:]]*=[[:space:]]*"v[0-9]+' "$f" && { echo "LEADING-V $f"; fail=1; }
228229
lua5.4 tests/check_mirror_urls.lua "$f" >/dev/null 2>&1 || { echo "MIRROR $f"; fail=1; }
229230
lua5.4 tests/check_package_name.lua "$f" || fail=1
231+
lua5.4 tests/check_reserved_namespace.lua "$f" || fail=1
230232
done
231233
[ $fail -eq 0 ] && echo "ALL LINT PASS"
232234
```

‎docs/zh/package-types.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -272,6 +272,30 @@ protobuf 最经典的坑——在这里**语法上无法表达**。`mcpp build -
272272
对应的成员是 `tests/examples/protobuf-protoc`,它与 `tests/examples/protobuf` 互为补集:那个刻意**不用**
273273
任何生成代码,这个从头到尾都是生成代码。
274274

275+
## I. 构建插件包(`mcpp.plugins`)
276+
277+
构建插件是其模块由消费方 `build.mcpp` 导入的包:它的单元导入 `mcpp.core`(也写作 `mcpp`),
278+
经带 `host-module = true` 的 `[build-dependencies]` 边到达消费方。进入本索引需满足三条规则
279+
(mcpp#734):
280+
281+
- **模块名。** 插件以自身命名空间为其构建程序模块命名:`mcpp.<namespace>.*`(例如
282+
`mcpp.acme.protobuf`)。第二段 `core`、`plugins`、`deps`、`rules`、`dist`、`tools` 属于 mcpp
283+
项目。其他包使用它们时引擎给出警告(mcpp SPEC-007 §9);构建输出含该警告的成员在
284+
`tests/run_members.sh` 中失败,lint 拒绝与之同名的命名空间(`tests/check_reserved_namespace.lua`)。
285+
包同时提供给程序的模块遵循库的规则 `<namespace>.<name>.*`(mcpp SPEC-008 I3)。
286+
- **清单。** 官方通用库经 feature `plugins-core` 提供。基于它的插件以 `host-module = true` 与
287+
`features = ["plugins-core"]` 依赖 `mcpp.plugins`;其消费方的构建程序也直接导入该库时,再加
288+
`reexport = true`:
289+
290+
```toml
291+
[build-dependencies.mcpp]
292+
plugins = { version = "0.17.0", features = ["plugins-core"], host-module = true, reexport = true }
293+
```
294+
- **引擎下限。** 包以 `[package] mcpp = ">=<release>"` 写明所需的最早 mcpp 版本;更旧的引擎停止并
295+
写出升级方式。读取构建信息(解析出的工具、`mcpp::report`)的插件需要 2026.9.28.3。
296+
297+
对应的成员是 `tests/examples/mcpp-plugins`。
298+
275299
---
276300

277301
## 最小工程(`tests/examples/<short>/`)

‎docs/zh/repository-and-schema.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ tests/examples/<member>/ 每库测试工程(workspace 成员;<member> 为包
1717
tests/*.cpp 行为断言(独立 main,退出码非 0 即失败)
1818
tests/check_mirror_urls.lua lint:GLOBAL+CN 表完整性,以及 CN 指向 mcpp-res
1919
tests/check_package_name.lua lint:身份形态(name 为单一原子段,层级归 namespace)
20+
tests/check_reserved_namespace.lua lint:命名空间不得是 `mcpp.` 的保留第二段(core、plugins、deps、rules、dist、tools)
2021
tests/list_cn_urls.lua 抽取 CN url,供 mirror-cn-reachable 使用
2122
tests/run_members.sh 逐个运行 workspace 成员并计时。CI 与本地共用的入口,见下文「本地运行 workspace 成员」
2223
tests/plan_shards.lua 依实测耗时将成员分配到各分片。由 `select` job 调用一次,`run_members.sh --shard`
@@ -125,7 +126,7 @@ mcpp 跑 `xpkg parse`(strict:未知键即失败),所以需要更新文法/键的
125126
条件下比较,代价是显著更慢。
126127
- `env.MCPP_VERSION` 为全部 job 使用的 mcpp 版本,本地验证应与之对齐。
127128
- `lint`(始终运行):lua 语法 `loadfile(f,'t')`;须含 `spec=`/`name=`/`xpm=`;禁止前导 v 版本;执行
128-
`check_mirror_urls.lua`;执行 `check_package_name.lua`(身份形态,见上文「包身份」);再用 CI pin 的
129+
`check_mirror_urls.lua`;执行 `check_package_name.lua`(身份形态,见上文「包身份」);执行 `check_reserved_namespace.lua`(构建插件命名规则,见 package-types §I);再用 CI pin 的
129130
mcpp 对每个描述符跑 `mcpp xpkg parse`(strict,未知键即失败)。mcpp ≥ 0.0.106 的 `xpkg parse` 自身
130131
也强制身份形态,lua lint 因此是更早、更便宜的冗余闸门。
131132
- `mirror-cn-reachable`(始终运行):逐个 `curl` CN url,均须返回 200。
@@ -179,6 +180,7 @@ for f in pkgs/*/*.lua; do
179180
grep -nqE '\["v[0-9]+|\["[^"]+"\][[:space:]]*=[[:space:]]*"v[0-9]+' "$f" && { echo "LEADING-V $f"; fail=1; }
180181
lua5.4 tests/check_mirror_urls.lua "$f" >/dev/null 2>&1 || { echo "MIRROR $f"; fail=1; }
181182
lua5.4 tests/check_package_name.lua "$f" || fail=1
183+
lua5.4 tests/check_reserved_namespace.lua "$f" || fail=1
182184
done
183185
[ $fail -eq 0 ] && echo "ALL LINT PASS"
184186
```

‎index.toml‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,13 @@
120120
# Moved in the pull request that moves validate.yml's pin to 2026.9.28.2,
121121
# which runs every member on every platform with it. The release changes no
122122
# descriptor grammar.
123+
# ── 2026-09-28: latest_mcpp -> 2026.9.28.3, min_mcpp unchanged ─────────────
124+
#
125+
# Moved in the pull request that moves validate.yml's pin to 2026.9.28.3 and
126+
# registers mcpp.plugins 0.17.0, whose package floor it is. The release changes
127+
# no descriptor grammar; its `[package] mcpp` key is manifest vocabulary, which
128+
# an older engine reports as unsupported and ignores.
123129
[index]
124130
spec = "1"
125131
min_mcpp = "2026.9.18.3"
126-
latest_mcpp = "2026.9.28.2"
132+
latest_mcpp = "2026.9.28.3"

‎mcpp.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@ members = [
7171
"tests/examples/imgui-window",
7272
"tests/examples/jwt-cpp",
7373
"tests/examples/marzer.tomlplusplus",
74+
"tests/examples/mcpp-plugins",
7475
"tests/examples/mio",
7576
"tests/examples/libmysqlclient",
7677
"tests/examples/mysql-connector-cpp",

‎pkgs/m/mcpp.plugins.lua‎

Lines changed: 36 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,23 @@
22
-- each member selected by a feature.
33
--
44
-- [dependencies.mcpp]
5-
-- plugins = { version = "0.16.0", features = ["rules-spirv"], host-module = true }
5+
-- plugins = { version = "0.17.0", features = ["rules-spirv"], host-module = true }
66
--
77
-- // build.mcpp
88
-- import mcpp;
99
-- import mcpp.rules.spirv;
1010
--
11+
-- 0.17.0 (package floor 2026.9.28.3, `[package] mcpp`): the general library
12+
-- for build programs behind `plugins-core` (renamed from `surface`, kept as an
13+
-- alias until 2027-03-28) -- `mcpp.plugins.toolset`, `mcpp.plugins.fs` -- and
14+
-- the test kit `mcpp.plugins.testing` behind `plugins-testing`. deps-vcpkg and
15+
-- deps-cmake build with the toolset mcpp resolved: a Visual Studio instance is
16+
-- selected with VCPKG_VISUAL_STUDIO_PATH (the ABI hash is unchanged), a managed
17+
-- MSVC toolset and the clang rows are named in a derived triplet
18+
-- `<base>-mcpp-<hash>`, and the Linux GCC row keeps vcpkg's detection; the C
19+
-- runtime follows the program's contract. mcpp-community/mcpp#734,
20+
-- mcpp-community/mcpp-plugins#37.
21+
--
1122
-- 0.16.0 (mcpp floor 2026.9.27.1 for `rules-qt`): the Linux C++ runtime a
1223
-- Qt program needs is stated in the host rows `[target.x86_64-linux-gnu]` and
1324
-- `[target.aarch64-linux-gnu]`, which a plain `mcpp build` now applies
@@ -608,6 +619,13 @@ package = {
608619

609620
xpm = {
610621
linux = {
622+
["0.17.0"] = {
623+
url = {
624+
GLOBAL = "https://github.com/mcpp-community/mcpp-plugins/archive/refs/tags/v0.17.0.tar.gz",
625+
CN = "https://gitcode.com/mcpp-res/mcpp-plugins/releases/download/0.17.0/mcpp-plugins-0.17.0.tar.gz",
626+
},
627+
sha256 = "20e9fc467c83dce33fbb706f5373eeb14eb0880c1e08e9c2c30594147875c57e",
628+
},
611629
["0.16.0"] = {
612630
url = {
613631
GLOBAL = "https://github.com/mcpp-community/mcpp-plugins/archive/refs/tags/v0.16.0.tar.gz",
@@ -846,9 +864,16 @@ package = {
846864
},
847865
sha256 = "adf1f9d6691a5d05a8a4a94e83c733ea39caee1510ce2c9af4cb23bebabea9f5",
848866
},
849-
["latest"] = { ref = "0.16.0" },
867+
["latest"] = { ref = "0.17.0" },
850868
},
851869
macosx = {
870+
["0.17.0"] = {
871+
url = {
872+
GLOBAL = "https://github.com/mcpp-community/mcpp-plugins/archive/refs/tags/v0.17.0.tar.gz",
873+
CN = "https://gitcode.com/mcpp-res/mcpp-plugins/releases/download/0.17.0/mcpp-plugins-0.17.0.tar.gz",
874+
},
875+
sha256 = "20e9fc467c83dce33fbb706f5373eeb14eb0880c1e08e9c2c30594147875c57e",
876+
},
852877
["0.16.0"] = {
853878
url = {
854879
GLOBAL = "https://github.com/mcpp-community/mcpp-plugins/archive/refs/tags/v0.16.0.tar.gz",
@@ -1087,9 +1112,16 @@ package = {
10871112
},
10881113
sha256 = "adf1f9d6691a5d05a8a4a94e83c733ea39caee1510ce2c9af4cb23bebabea9f5",
10891114
},
1090-
["latest"] = { ref = "0.16.0" },
1115+
["latest"] = { ref = "0.17.0" },
10911116
},
10921117
windows = {
1118+
["0.17.0"] = {
1119+
url = {
1120+
GLOBAL = "https://github.com/mcpp-community/mcpp-plugins/archive/refs/tags/v0.17.0.tar.gz",
1121+
CN = "https://gitcode.com/mcpp-res/mcpp-plugins/releases/download/0.17.0/mcpp-plugins-0.17.0.tar.gz",
1122+
},
1123+
sha256 = "20e9fc467c83dce33fbb706f5373eeb14eb0880c1e08e9c2c30594147875c57e",
1124+
},
10931125
["0.16.0"] = {
10941126
url = {
10951127
GLOBAL = "https://github.com/mcpp-community/mcpp-plugins/archive/refs/tags/v0.16.0.tar.gz",
@@ -1328,7 +1360,7 @@ package = {
13281360
},
13291361
sha256 = "adf1f9d6691a5d05a8a4a94e83c733ea39caee1510ce2c9af4cb23bebabea9f5",
13301362
},
1331-
["latest"] = { ref = "0.16.0" },
1363+
["latest"] = { ref = "0.17.0" },
13321364
},
13331365
},
13341366

‎tests/check_reserved_namespace.lua‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
-- Lint `package.namespace` against the build-plugin naming rule (mcpp#734;
2+
-- mcpp SPEC-007 §9, "plugin names").
3+
--
4+
-- A build plugin names its modules `mcpp.<namespace>.*` after its own
5+
-- package's namespace, and the second segments `core`, `plugins`, `deps`,
6+
-- `rules`, `dist` and `tools` of `mcpp.` belong to the mcpp project: `mcpp.core`
7+
-- is the engine's interface, the others are the families of mcpp-plugins. A
8+
-- namespace spelled like one of them would make a third party's
9+
-- `mcpp.<namespace>.*` indistinguishable from an official family, so the index
10+
-- refuses such a namespace. The engine warns on the module names themselves;
11+
-- the index can refuse, because it knows which namespaces are registered.
12+
--
13+
-- Usage: lua5.4 tests/check_reserved_namespace.lua <file.lua>
14+
15+
function import(...)
16+
return setmetatable({}, {__index = function() return function() end end})
17+
end
18+
19+
local path = assert(arg[1], "usage: check_reserved_namespace.lua <file>")
20+
package = nil
21+
local chunk = assert(loadfile(path, "t"))
22+
chunk()
23+
24+
local p = package
25+
if type(p) ~= "table" then os.exit(0) end
26+
local ns = p.namespace
27+
if type(ns) ~= "string" then os.exit(0) end
28+
29+
local reserved = { core = true, plugins = true, deps = true, rules = true, dist = true, tools = true }
30+
local first = ns:match("^([^.]+)")
31+
if first and reserved[first] then
32+
io.stderr:write(string.format(
33+
"::error file=%s::namespace '%s' is reserved: `mcpp.%s.*` names modules of the mcpp project " ..
34+
"(mcpp SPEC-007 §9), so a plugin of this namespace could not be told from an official one\n",
35+
path, ns, first))
36+
os.exit(1)
37+
end
38+
os.exit(0)

0 commit comments

Comments
 (0)