From 6efe6ae0c607a4437535a09a6eb94df9eb91408b Mon Sep 17 00:00:00 2001 From: Sunrisepeak Date: Sun, 11 Oct 2026 14:31:22 +0900 Subject: [PATCH] docs: a build plugin names the libraries its modules import in [dependencies] (mcpp 2026.10.11.1) From mcpp 2026.10.11.1 (mcpp-community/mcpp#797) a build plugin's [dependencies] are compiled with it for the build programs that use it, and reexport = true hands one on to their build.mcpp. A plugin built on mcpp.plugins' plugins-core names it there. The [build-dependencies] entry with host-module = true, the spelling before that release, is read as a dependency as well, reported as deprecated, and no longer read from mcpp 2027.1. A [build-dependencies] edge gives the build program the library without host-module = true. --- docs/package-types.md | 22 ++++++++++++++-------- docs/zh/package-types.md | 17 ++++++++++------- 2 files changed, 24 insertions(+), 15 deletions(-) diff --git a/docs/package-types.md b/docs/package-types.md index 9a514792..12fe3031 100644 --- a/docs/package-types.md +++ b/docs/package-types.md @@ -298,8 +298,9 @@ one deliberately uses no generated code, this one is generated code end to end. A build plugin is a package whose modules a consumer's `build.mcpp` imports: its units import `mcpp.core` (also spelled `mcpp`) and reach a consumer through a -`[build-dependencies]` edge with `host-module = true`. Three rules admit one to -this index (mcpp#734): +`[build-dependencies]` edge, which gives the build program the package's library +(`host-module = true` states it explicitly). Three rules admit one to this index +(mcpp#734): - **Module names.** A plugin names its build-program modules `mcpp..*` after its own namespace (`mcpp.acme.protobuf`). The second @@ -310,15 +311,20 @@ this index (mcpp#734): (`tests/check_reserved_namespace.lua`). Modules the package also offers to programs follow the library rule, `..*` (mcpp SPEC-008 I3). - **The manifest.** The official general library is reached through the feature - `plugins-core`. A plugin built on it depends on `mcpp.plugins` with - `host-module = true` and `features = ["plugins-core"]`, and adds - `reexport = true` when its consumers' build programs import the library - themselves: + `plugins-core`. What a plugin's own modules import is in its + `[dependencies]`: a plugin built on the library depends on `mcpp.plugins` + with `features = ["plugins-core"]`, and adds `reexport = true` when its + consumers' build programs import the library themselves (mcpp 2026.10.11.1+, + mcpp#797): ```toml - [build-dependencies.mcpp] - plugins = { version = "0.17.0", features = ["plugins-core"], host-module = true, reexport = true } + [dependencies.mcpp] + plugins = { version = "0.17.0", features = ["plugins-core"], reexport = true } ``` + + The same entry in `[build-dependencies]` with `host-module = true`, the + spelling before 2026.10.11.1, is read as a dependency of the plugin as well + and reported as deprecated; mcpp 2027.1 no longer reads it. - **The engine floor.** The package states the first mcpp release it needs, `[package] mcpp = ">="`; an older engine stops and names the upgrade. A plugin that reads the build information (the resolved tools, `mcpp::report`) diff --git a/docs/zh/package-types.md b/docs/zh/package-types.md index f2106b83..f4d00f4f 100644 --- a/docs/zh/package-types.md +++ b/docs/zh/package-types.md @@ -275,22 +275,25 @@ protobuf 最经典的坑——在这里**语法上无法表达**。`mcpp build - ## I. 构建插件包(`mcpp.plugins`) 构建插件是其模块由消费方 `build.mcpp` 导入的包:它的单元导入 `mcpp.core`(也写作 `mcpp`), -经带 `host-module = true` 的 `[build-dependencies]` 边到达消费方。进入本索引需满足三条规则 -(mcpp#734): +经 `[build-dependencies]` 边到达消费方,该边把包的库交给构建程序(`host-module = true` 显式写出 +这一点)。进入本索引需满足三条规则(mcpp#734): - **模块名。** 插件以自身命名空间为其构建程序模块命名:`mcpp..*`(例如 `mcpp.acme.protobuf`)。第二段 `core`、`plugins`、`deps`、`rules`、`dist`、`tools` 属于 mcpp 项目。其他包使用它们时引擎给出警告(mcpp SPEC-007 §9);构建输出含该警告的成员在 `tests/run_members.sh` 中失败,lint 拒绝与之同名的命名空间(`tests/check_reserved_namespace.lua`)。 包同时提供给程序的模块遵循库的规则 `..*`(mcpp SPEC-008 I3)。 -- **清单。** 官方通用库经 feature `plugins-core` 提供。基于它的插件以 `host-module = true` 与 - `features = ["plugins-core"]` 依赖 `mcpp.plugins`;其消费方的构建程序也直接导入该库时,再加 - `reexport = true`: +- **清单。** 官方通用库经 feature `plugins-core` 提供。插件自身模块导入的东西写在它的 + `[dependencies]` 中:基于该库的插件以 `features = ["plugins-core"]` 依赖 `mcpp.plugins`;其消费方 + 的构建程序也直接导入该库时,再加 `reexport = true`(mcpp 2026.10.11.1+,mcpp#797): ```toml - [build-dependencies.mcpp] - plugins = { version = "0.17.0", features = ["plugins-core"], host-module = true, reexport = true } + [dependencies.mcpp] + plugins = { version = "0.17.0", features = ["plugins-core"], reexport = true } ``` + + 2026.10.11.1 之前的写法,即在 `[build-dependencies]` 中写同一条目并带 `host-module = true`,也被读作 + 插件的依赖并报告为已弃用;mcpp 2027.1 起不再读取。 - **引擎下限。** 包以 `[package] mcpp = ">="` 写明所需的最早 mcpp 版本;更旧的引擎停止并 写出升级方式。读取构建信息(解析出的工具、`mcpp::report`)的插件需要 2026.9.28.3。