2026.9.26.2: the version, and the CHANGELOG entry

Author: speak-agent

CHANGELOG.md

@@ -3,6 +3,85 @@
 > 本文件追踪 `mcpp-community/mcpp` 公开仓的版本演进。
 > 格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [2026.9.26.2] - 2026-09-26
+
+### 编译数据库:一个配置一个数据库(#699 的报告;#397 C-1、#677 B1)
+
+`compile_commands.json` 此前是一份跨命令、跨工具链合并的文件:删除后的下一次构建不再写回它,
+另一个工具写入的条目与上一个工具链的条目都被保留,`directory` 写的是工程根目录而编译器在输出目录
+中运行。现在:
+
+- 每个配置一份数据库,位于 `target/<triple>/<fingerprint>/compile_commands.json`,只在本配置之内
+  合并,因此 `mcpp test` 之后的 `mcpp build` 保留测试单元的条目。工程根目录的文件是当前配置数据库
+  的副本,整体替换、从不合并,内容相同时不写;切换工具链或 profile 就切换整个文件,切回时恢复该
+  配置的条目。根目录的符号链接照旧按其指向写入。
+- 根文件被删除后,下一次构建从配置数据库恢复它,快路径也是如此,不需要规划。
+- 被替换的根文件含有 mcpp 没有写的条目时(条目的 `output` 不在本工程的 `target/` 或 mcpp 主目录
+  之下),构建以一条警告说明其数量。
+- `directory` 与 S1 的 `work-directory` 是编译器运行的输出目录,与 JSON Compilation Database 格式、
+  S1-8-2 以及 CMake、ninja 的写法一致;从 `directory` 重放 GCC 的条目不再在源码树中写出
+  `gcm.cache/`。
+- 提供模块的单元在 `-c` 之前带上接口语言 flag(clang 为 `-x c++-module`,GCC 为 `-x c++`),
+  clangd 因此能处理 `.ixx` 接口;MSVC 的写法待 Windows 实测后再加。
+- 导入 `std` 的构建在 `compile_commands.json` 与 `emit --spec compile-commands` 中列出标准库单元
+  (S1-12-1),另一个版本的 clangd 因此能自己构建 `std`。S1 文档中标准库单元的 `provides` 指向
+  共享 std 缓存中的 BMI,工具链带 `build-id`,版本与构建身份完全一致的读者可以直接复用。
+- `mcpp new` 写出的 `.gitignore` 包含 `compile_commands.json`。
+
+### `emit build-database` 按成员规划(#699)
+
+`emit build-database --workspace` 此前在第一个规划失败的成员处停止,已规划成员的集合全部丢失。
+现在每个选中的成员独立规划:规划失败的成员不贡献集合,贡献一条 `error` 诊断,`path` 为它的
+`mcpp.toml`;至少一个成员规划成功时文档带 `data`,`watch` 也列出失败成员的 `mcpp.toml` 与
+`build.mcpp`;有任何错误时退出码为 1。在 `emit` 下,构建失败的宿主工具是警告
+`MCPP_BUILD_DATABASE_HOST_TOOL_UNBUILT`,规划继续,构建程序得到该工具将被发布的路径;构建程序失败
+的包不带该程序的指令地被描述,并得到一条 `MCPP_BUILD_DATABASE_PROGRAM_FAILED` 错误,`path` 为它的
+`build.mcpp`。`mcpp build` 的行为不变。带错误诊断的 `data` 是 S2 0.3.0 的部分回答
+(Sunrisepeak/mcpp-language-server#25)。
+
+### 构建程序:`runtime_search_dir`、`prepare` 角色与 stamp 规则(#701、#702)
+
+- `mcpp::runtime_search_dir(dir)`(`mcpp:runtime-search-dir=`,协议 12)是 `[runtime]
+  runtime_search_dirs` 的构建程序形态,并入同一个字段:ELF 与 Mach-O 的运行路径、`mcpp run` 的加载
+  路径、`mcpp pack` 的闭包搜索与运行时校验都照常读取它,依赖的声明到达消费方的可执行文件。目录在
+  构建程序运行时不必存在。保留字段 `[runtime] library_dirs` 不获得指令。
+- 新角色 `prepare` 用于文件名在构建程序运行时未知的施工(安装一个前缀、解开一个 SDK):命令填充
+  用 `a.output_dir(dir)` 声明的目录,引擎写 stamp。命令成功而目录不存在或除 stamp 外不含文件时,
+  这条边失败并点名目录。声明包的每条编译边与计划中的每条链接边等待它,构建输出以 `PREPARE`
+  标注。构建程序的重新运行依据落在某个 `prepare` 目录内时,构建给出警告。
+- 角色以常量书写:`mcpp::roles::{source, check, object, artifact, prepare}`。引擎拒绝这五个之外的
+  角色字符串并列出它们;此前未知的字符串被静默读作 `source`。
+- `check` 与 `prepare` 的命令成功后,引擎创建缺失的 stamp,并把已存在的 stamp 更新到当前时间;
+  此前已存在的 stamp 不被更新,一个输入改变一次之后,该 action 在此后每次构建中都会重新运行。
+
+### Windows 程序的 DLL 在链接后放到程序旁
+
+PE 映像没有运行路径,运行时搜索目录中的 DLL 此前只服务于 `mcpp run` 与 `mcpp pack`,从构建目录直接
+启动的程序找不到它。现在计划中带运行时搜索目录的 PE 程序在链接后多一条边 `mcpp place-dlls`:按
+`mcpp pack` 的闭包求解与系统规则,把程序直接或间接导入、且在这些目录中解析到的 DLL 放到程序旁,
+字节不同时才写;DLL 在其目录中被替换(包括被 `prepare` action 替换)后,同一次构建会再次放置它。
+部署到程序旁的 DLL 从链接边的隐式输入改为 order-only 输入,DLL 变化不再使程序重新链接。
+
+### 链接 flag 按词读取(#703)
+
+`[build] ldflags`、`mcpp::link_flag` 与依赖传播的链接 flag 此前只为 ninja 转义,Linux 与 macOS 的
+`sh` 展开其中的 `$ORIGIN`,程序的运行路径因此含有 `/../lib`,即宿主的 `/lib`。SPEC-004 §8 的词读法
+现在同样适用于链接 flag:每个词原样到达链接器;依赖的链接 flag 按词传播;`link_search`、`link_lib`、
+`link_script` 由路径构成的值是一个词,含空格的目录不再被拆开。为 shell 或 ninja 手工转义的写法
+(`\$ORIGIN`、`'$$ORIGIN'`)现在按写法读取,首次规划以 `build/flag-words` 指出这样的元素;
+索引中没有这样的写法。
+
+### 构建插件规范 SPEC-007
+
+新增 `docs/specs/build-plugins.md`(草案 0.2):插件的配置、施工与校验各用一种机制,环境不完整时
+警告而不失败,配置不依赖施工结果,运行时库以 `runtime_search_dir` 声明,构建期的网络访问在离线
+构建中不发生。mcpp 只提供通用机制,某一个工具的知识只属于它的插件。
+
+### 兼容性
+
+- 构建程序缓存的 epoch 升到 3,升级后每个构建程序重新运行一次。
+- 构建程序协议升到 12;使用新指令、新角色或角色常量的构建程序在旧引擎上编译失败并指出名字。
+
 ## [2026.9.26.1] - 2026-09-26
 
 ### 路径与文本统一为 UTF-8(#693)

docs/04-mcpp-toml.md

@@ -423,7 +423,7 @@ bmi_schedule = "auto"             # Module-edge scheduling: auto (= off) | on |
 
 An element of `cflags`, `cxxflags` or `asmflags` stands for one or more compiler
 arguments ("words"), and an element of `ldflags` for one or more linker
-arguments (mcpp 2026.9.27.1+). The syntax is the same on every host, wherever
+arguments (mcpp 2026.9.26.2+). The syntax is the same on every host, wherever
 the list is written: `[build]`, `[targets.<name>]`, a `flags` glob entry, a
 feature, a `[target.<selector>.build]` section, an xpkg descriptor, and the
 `mcpp:cflag=` / `mcpp:cxxflag=` / `mcpp:link-flag=` directives of a build
@@ -458,7 +458,7 @@ A `defines` entry is one value and is not read by this syntax: `defines =
 ["NAME=\"text\""]` passes the single word `-DNAME="text"`. `dialect_cxxflags`
 and `std-module-flags` are not covered by this section.
 
-`ldflags` follows the syntax from mcpp 2026.9.27.1 (#703). Before, a link-flag
+`ldflags` follows the syntax from mcpp 2026.9.26.2 (#703). Before, a link-flag
 element was escaped for ninja and not quoted for the shell, so on Linux and
 macOS a `$ORIGIN` reached the program's run path as `/../lib`. A `-L` or
 `-Wl,-rpath,` word with a package-relative path resolves against the package
@@ -1458,7 +1458,7 @@ Link intent keeps discovery stages separate:
 |---|---|---|---|
 | `link_library_dirs` | `-L` | `-L` | `-L` or `/LIBPATH:` |
 | `transitive_needed_dirs` | `-Wl,-rpath-link` | no flag | no flag |
-| `runtime_search_dirs` | RUNPATH/rpath only, never `-L` | rpath only | no flag; after the link, the DLLs the program imports from these directories are placed beside it *(2026.9.27.1+)* |
+| `runtime_search_dirs` | RUNPATH/rpath only, never `-L` | rpath only | no flag; after the link, the DLLs the program imports from these directories are placed beside it *(2026.9.26.2+)* |
 | `frameworks` | no flag | `-framework` | no flag |
 | `deploy_files` | copy edge | copy edge | copy beside the output; never a linker flag |
 | `deploy` *(2026.9.12.2+)* | copy edge into `bin/<to>/` | copy edge into `bin/<to>/` | copy edge into `bin/<to>/`; never a linker flag |
@@ -1494,7 +1494,7 @@ action may populate it later, at build time.
 
 A PE image has no run path, so on Windows a runtime search directory serves
 `mcpp run`, which puts it on `PATH`, and `mcpp pack`, which stages the closure.
-From 2026.9.27.1 the link of a PE program whose plan has runtime search
+From 2026.9.26.2 the link of a PE program whose plan has runtime search
 directories is followed by one more edge, `mcpp place-dlls`, which reads the
 program's import closure as `mcpp pack` does and places beside the program
 every DLL it imports, directly or through another DLL, that resolves in one of

docs/specs/README.md

@@ -33,10 +33,10 @@
 | [SPEC-001](package-identity.md) | 包身份(`package.namespace` / `package.name`)、`[dependencies]` 选择器与匹配机制 | 评审中 v1.1 | 2026-08-03 | mcpp >= 0.0.106 |
 | [SPEC-002](target-side.md) | 目标侧模型与能力声明(`mcpp:` 保留命名空间、五层、三条规则) | 评审中 v1.0 | 2026-08-24 | mcpp >= 2026.8.24.2 |
 | [SPEC-003](exit-codes.md) | 退出码契约(分类、语义、稳定性承诺) | 评审中 v1.0 | 2026-09-01 | mcpp >= 2026.9.1.1 |
-| [SPEC-004](manifest-semantics.md) | `mcpp.toml` 的平面划分、条件化形状、解析轴与命名规约 | 草案 v1.7 | 2026-09-26 | 条件化形状 mcpp >= 2026.8.29.1;目标轴 mcpp >= 2026.9.6.4;`linkage` 默认值 mcpp >= 2026.9.15.2;链接 flag 的词读法 mcpp >= 2026.9.27.1 |
-| [SPEC-005](build-database.md) | 构建数据库:`mcpp emit build-database` 的内容、取值规则与不写工程目录的保证 | 评审中 v1.3 | 2026-09-26 | mcpp >= 2026.9.15.1;v1.3 条款 mcpp >= 2026.9.27.1 |
+| [SPEC-004](manifest-semantics.md) | `mcpp.toml` 的平面划分、条件化形状、解析轴与命名规约 | 草案 v1.7 | 2026-09-26 | 条件化形状 mcpp >= 2026.8.29.1;目标轴 mcpp >= 2026.9.6.4;`linkage` 默认值 mcpp >= 2026.9.15.2;链接 flag 的词读法 mcpp >= 2026.9.26.2 |
+| [SPEC-005](build-database.md) | 构建数据库:`mcpp emit build-database` 的内容、取值规则与不写工程目录的保证 | 评审中 v1.3 | 2026-09-26 | mcpp >= 2026.9.15.1;v1.3 条款 mcpp >= 2026.9.26.2 |
 | [SPEC-006](toolchain-management.md) | 工具链管理:身份、来源、选择与载荷契约 | 草案 v0.2 | 2026-09-24 | 逐条标注;已实现条款 mcpp >= 2026.9.24.1 |
-| [SPEC-007](build-plugins.md) | 构建插件:配置、施工与校验的分工,运行时与规划期的义务 | 草案 v0.2 | 2026-09-26 | 逐条标注;mcpp >= 2026.9.27.1 |
+| [SPEC-007](build-plugins.md) | 构建插件:配置、施工与校验的分工,运行时与规划期的义务 | 草案 v0.2 | 2026-09-26 | 逐条标注;mcpp >= 2026.9.26.2 |
 
 ## 文档约定
 

docs/specs/build-database.md

@@ -7,7 +7,7 @@
 | 状态 | 评审中 v1.3 |
 | 版本 | 1.3 |
 | 最后修改 | 2026-09-26 |
-| 对应实现 | mcpp >= 2026.9.15.1;v1.3 修改的 R2.5、R3.7、R3.8、R4.1、R5.2 为 mcpp >= 2026.9.27.1 |
+| 对应实现 | mcpp >= 2026.9.15.1;v1.3 修改的 R2.5、R3.7、R3.8、R4.1、R5.2 为 mcpp >= 2026.9.26.2 |
 | 相关设计文档 | `.agents/docs/2026-09-14-636-build-database-and-the-latest-xlings.md`<br>`.agents/docs/2026-09-26-compile-database-and-issue-699-design.md` |
 | 相关 issue | #636, #648, #655, #699, #702 |
 | 依据的外部规范 | S1「C++ Build Database: IDE Profile」profile 0.2.0 与 S2 0.2.0 §3.4,取自 https://github.com/Sunrisepeak/lsp-mcpp-private 提交 `b82859d`(schema 自提交 `28ecd6e` 起未变);S2 0.3.0 §3.4 的部分回答(S2-3.4-12、S2-3.4-13,Sunrisepeak/mcpp-language-server#25);JSON Compilation Database |
@@ -170,7 +170,7 @@ mcpp 输出的 S1 文档满足 S1 等级 2,不输出 `ide.options`。等级 3 
   `MCPP_BUILD_DATABASE_PROGRAM_FAILED`,`path` 为该包的 `build.mcpp`;后续失败若是
   由缺失的指令引起,则按前一条规则使整个成员失败。只要 `diagnostics` 中有一条
   `error`,退出码就是 1,无论 `data` 是否出现。**已实现**(离线诊断码:
-  mcpp >= 2026.9.16.1;成员独立规划、`path` 与构建程序失败的描述:mcpp >= 2026.9.27.1)
+  mcpp >= 2026.9.16.1;成员独立规划、`path` 与构建程序失败的描述:mcpp >= 2026.9.26.2)
 - **R5.3** 信封的 `effects` 为 `read-project` 与 `write-global-cache`,运行了构建程序时
   另有 `exec-build-script`,本次运行启动过网络子进程(索引刷新、安装、git 远程操作,
   失败或超时的也算)时另有 `network`。**已实现**(`network`:mcpp >= 2026.9.16.1)

docs/specs/build-plugins.md

@@ -7,7 +7,7 @@
 | 状态 | 草案 v0.2 |
 | 版本 | 0.2 |
 | 最后修改 | 2026-09-26 |
-| 对应实现 | 逐条标注。未注明版本的「已实现」条款对应 mcpp >= 2026.9.26.1;注明 mcpp#702 的条款对应 mcpp >= 2026.9.27.1 |
+| 对应实现 | 逐条标注。未注明版本的「已实现」条款对应 mcpp >= 2026.9.26.1;注明 mcpp#702 的条款对应 mcpp >= 2026.9.26.2 |
 | 相关设计文档 | `.agents/docs/2026-09-26-compile-database-and-issue-699-design.md`(§5) |
 | 相关 issue | mcpp#699、mcpp#701、mcpp#702、mcpp#703 |
 | 使用文档 | [docs/30 - build.mcpp](../30-build-mcpp.md)、[docs/31 - 编写规则包](../31-authoring-a-rule-package.md) |
@@ -182,4 +182,4 @@
 | 版本 | 日期 | 变更 |
 |---|---|---|
 | 0.1 | 2026-09-26 | 首版草案(mcpp#699、#701、#702、#703)。 |
-| 0.2 | 2026-09-26 | 随 mcpp 2026.9.27.1 落地:R1.3 的警告、R2.1 的 `runtime_search_dir`、R2.4、R3.3 的 `prepare`(目录须含文件;链接边等待所有 `prepare`)、R3.5、R3.6、R4.1、R4.3、R5.2、R5.3 标为已实现。 |
+| 0.2 | 2026-09-26 | 随 mcpp 2026.9.26.2 落地:R1.3 的警告、R2.1 的 `runtime_search_dir`、R2.4、R3.3 的 `prepare`(目录须含文件;链接边等待所有 `prepare`)、R3.5、R3.6、R4.1、R4.3、R5.2、R5.3 标为已实现。 |

docs/specs/manifest-semantics.md

@@ -399,7 +399,7 @@ feature-deps          feature-xlings         ← 限定词是门
 `dialect_cxxflags` 与 `std-module-flags` 不在本节范围内。
 
 **状态:已实现(mcpp 2026.9.17.1;`defines` 的集合语义 mcpp 2026.9.25.1;`ldflags` 与链接指令
-mcpp 2026.9.27.1,#703)。**
+mcpp 2026.9.26.2,#703)。**
 
 ## 9. 工作空间继承与构建需求的作用域
 
@@ -435,4 +435,4 @@ mcpp 2026.9.27.1,#703)。**
 | 1.4 | 2026-09-15 | 库目标的默认链接形态 `linkage`(mcpp 2026.9.15.2):§3.1.1 补默认值的语义、优先顺序与拒绝条件;§7 补第 9 条判据。 |
 | 1.5 | 2026-09-17 | 编译 flag 列表元素的读法(mcpp 2026.9.17.1,#655):新增 §8 与 §7 第 10 条判据。 |
 | 1.6 | 2026-09-25 | 工作空间继承与构建需求的作用域(mcpp 2026.9.25.1,#690):§8 补 `defines` 的集合语义;新增 §9 与 §7 第 11 至 14 条判据。 |
-| 1.7 | 2026-09-26 | §8 的读法扩展到 `ldflags` 与构建程序的链接指令(mcpp 2026.9.27.1,#703):`$ORIGIN` 原样到达链接器;§7 补第 15 条判据。 |
+| 1.7 | 2026-09-26 | §8 的读法扩展到 `ldflags` 与构建程序的链接指令(mcpp 2026.9.26.2,#703):`$ORIGIN` 原样到达链接器;§7 补第 15 条判据。 |

docs/zh/04-mcpp-toml.md

@@ -425,7 +425,7 @@ bmi_schedule = "auto"             # Module-edge scheduling: auto (= off) | on |
 
 `cflags`、`cxxflags` 或 `asmflags` 里的一个元素代表一个或多个编译器
 参数（「词」），`ldflags` 里的一个元素代表一个或多个链接器参数
-（mcpp 2026.9.27.1+）。这套语法在每个宿主上都相同，无论写在哪张表里：
+（mcpp 2026.9.26.2+）。这套语法在每个宿主上都相同，无论写在哪张表里：
 `[build]`、`[targets.<name>]`、`flags` glob 条目、feature、
 `[target.<selector>.build]` 小节、xpkg 描述符，以及构建程序的
 `mcpp:cflag=` / `mcpp:cxxflag=` / `mcpp:link-flag=` 指令。
@@ -458,7 +458,7 @@ bmi_schedule = "auto"             # Module-edge scheduling: auto (= off) | on |
 ["NAME=\"text\""]` 传出单独一个词 `-DNAME="text"`。`dialect_cxxflags` 与
 `std-module-flags` 不受本节约束。
 
-`ldflags` 自 mcpp 2026.9.27.1 起遵循这套语法（#703）。此前链接 flag 的元素只为
+`ldflags` 自 mcpp 2026.9.26.2 起遵循这套语法（#703）。此前链接 flag 的元素只为
 ninja 转义、没有为 shell 加引号，所以在 Linux 与 macOS 上 `$ORIGIN` 以 `/../lib`
 进入程序的运行路径。带包内相对路径的 `-L` 或 `-Wl,-rpath,` 词相对包根解析，依赖的
 `ldflags` 按词传给消费者。为 ninja 或 shell 手工转义的元素（`\$ORIGIN`、
@@ -1389,7 +1389,7 @@ Link intent 把各个发现阶段分开处理：
 |---|---|---|---|
 | `link_library_dirs` | `-L` | `-L` | `-L` 或 `/LIBPATH:` |
 | `transitive_needed_dirs` | `-Wl,-rpath-link` | 无旗标 | 无旗标 |
-| `runtime_search_dirs` | 仅 RUNPATH/rpath，从不是 `-L` | 仅 rpath | 无旗标；链接之后，程序从这些目录导入的 DLL 被放到程序旁 *(2026.9.27.1+)* |
+| `runtime_search_dirs` | 仅 RUNPATH/rpath，从不是 `-L` | 仅 rpath | 无旗标；链接之后，程序从这些目录导入的 DLL 被放到程序旁 *(2026.9.26.2+)* |
 | `frameworks` | 无旗标 | `-framework` | 无旗标 |
 | `deploy_files` | 拷贝边 | 拷贝边 | 拷贝到输出旁边；从不是链接器旗标 |
 | `deploy` *（2026.9.12.2+）* | 拷贝边，进 `bin/<to>/` | 拷贝边，进 `bin/<to>/` | 拷贝边，进 `bin/<to>/`；从不是链接器旗标 |
@@ -1421,7 +1421,7 @@ Link intent 把各个发现阶段分开处理：
 存在；一个 `prepare` action 可能在构建期之后才把它填充起来。
 
 PE 映像没有运行路径，所以在 Windows 上运行时搜索目录服务于 `mcpp run`（把它放进
-`PATH`）与 `mcpp pack`（暂存闭包）。自 2026.9.27.1 起，计划中带运行时搜索目录的
+`PATH`）与 `mcpp pack`（暂存闭包）。自 2026.9.26.2 起，计划中带运行时搜索目录的
 PE 程序在链接之后多一条边 `mcpp place-dlls`：它按 `mcpp pack` 的方式读取程序的
 导入闭包，把程序直接或经另一个 DLL 间接导入、且在这些目录之一中解析到的每个 DLL
 放到程序旁。系统 DLL 与 API set 从不复制，副本只在字节不同时写入，某个 DLL 在

mcpp.toml

@@ -1,6 +1,6 @@
 [package]
 name        = "mcpp"
-version     = "2026.9.27.1"
+version = "2026.9.26.2"
 description = "Modern C++ build & package management tool"
 license     = "Apache-2.0"
 authors     = ["mcpp-community"]

modules/versioning/src/version.cppm

@@ -31,6 +31,6 @@ import std;
 
 export namespace mcpp {
 
-inline constexpr std::string_view MCPP_VERSION = "2026.9.27.1";
+inline constexpr std::string_view MCPP_VERSION = "2026.9.26.2";
 
 } // namespace mcpp

src/build/prepare.cppm

@@ -619,7 +619,7 @@ void report_flag_words_changes(const mcpp::manifest::Manifest& m) {
         }
     };
     // THE SAME QUESTION FOR THE LINK FLAGS, which take the reading from
-    // 2026.9.27.1 (#703). Before, a `-L` or `-Wl,-rpath,` element was escaped
+    // 2026.9.26.2 (#703). Before, a `-L` or `-Wl,-rpath,` element was escaped
     // for ninja, so its text reached the host's reader as written, and any
     // other element was pasted into the ninja rule, so ninja replaced its `$`
     // sequences first. `$ORIGIN` written plainly reads the same under both
@@ -634,7 +634,7 @@ void report_flag_words_changes(const mcpp::manifest::Manifest& m) {
             if (now == before) continue;
             note_change(std::format(
                 "{}: {} element '{}' reaches the linker as {}; mcpp before "
-                "2026.9.27.1 passed {} on this host",
+                "2026.9.26.2 passed {} on this host",
                 who, where, e, show(now), show(before)),
                 std::string(
                 "a link-flag element is read by the compile-flag syntax, so `$ORIGIN` "