Skip to content

Commit aab319d

Browse files
fix: cl.exe objects carry their own debug information (/Z7)
The shared PDB of /Zi /FS is written through mspdbsrv.exe, which outlives the compile that started it; retiring that compile's process unit ended the server under concurrent compiles (C1090, PDB API error 23, e2e 258). /Zi, /ZI and /FS in a package's flags are refused on cl.exe (e2e 1023). Co-authored-by: speak-agent <248744407+speak-agent@users.noreply.github.com>
1 parent a2daca7 commit aab319d

9 files changed

Lines changed: 161 additions & 11 deletions

File tree

‎.agents/docs/2026-11-07-ecosystem-885-closeout-design.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -252,6 +252,11 @@ status: active
252252
遇到。现在接管时删除这些记录;准入时遇到其他目录的证书(目录被移动或在别处恢复)视为无记录,重新编译该对象。
253253
回归 e2e 1022。
254254
- `mcpp test` 的依赖横幅显示约束(`v^0.3.1`),而不是解析出的版本。回归 e2e 196。
255+
- cl.exe 的调试构建以 `/Zi /FS` 把一个目录全部编译的调试信息写入同一个 PDB,写入经由 mspdbsrv.exe;该服务由
256+
第一个 cl.exe 启动,并在它结束后继续存在。C2 的执行器在每个编译结束时回收它的进程单元,回收持有该服务的单元
257+
即结束了仍在写入的其他编译(C1090,PDB API 错误 23;e2e 258 在 Windows 上间歇失败)。现在调试信息写入各自的
258+
对象(`/Z7`),对象缓存与目录接管也以对象自足为前提;包的标志中的 `/Zi`、`/ZI`、`/FS` 在 cl.exe 上于编译前
259+
被拒绝。回归 e2e 1023 与单元测试 CheckSharedPdbWord。
255260
- 清单外新发现、按 D11 建议题的问题:mcpp#898(图中提供 C 库却不提供 C++ ABI 时,错误在 std 模块预编译阶段才出现,
256261
规划阶段没有拒绝)。
257262
- #896、#897(D17):两者都是 mcpp 的缺陷,在本轮修复。

‎CHANGELOG.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,12 @@
4343
two seconds (macOS CI, a scan of a two-configuration workspace: "compiler
4444
registration channel closed or timed out") is asked again, and an owner that
4545
accepts no connection has ended, so the compiler ends at once (e2e 840, 1016).
46+
- cl.exe writes a debug build's debug information into each object (`/Z7`), not
47+
into a PDB shared through mspdbsrv.exe (`/Zi /FS`). The server outlived the
48+
compile that started it, and retiring that compile's process unit ended it
49+
under the concurrent compiles, one of which failed with C1090, PDB API error
50+
23 (e2e 258, intermittently on Windows). `/Zi`, `/ZI` and `/FS` in a
51+
package's flags are refused on cl.exe before anything compiles (e2e 1023).
4652

4753
- A finished detached compiler is recognized when its final status appears
4854
between status and liveness checks. Recovery still validates its output proof.

‎docs/04-mcpp-toml.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1632,7 +1632,7 @@ where it would become a BMI path that nothing reports.
16321632
```toml
16331633
[profile.dist]
16341634
opt = 3 # -O level (a number, or the string "s"/"z")
1635-
debug = false # -g
1635+
debug = false # -g; /Z7 on cl.exe
16361636
lto = true # -flto; /GL + /LTCG on cl.exe (note: some packaged gcc builds ship without the LTO plugin)
16371637
strip = true # -s at link time
16381638
ndebug = true # -DNDEBUG for every unit of the graph (default: on for release/dist)
@@ -1644,6 +1644,13 @@ cxxflags = ["-fno-plt"]
16441644
ldflags = []
16451645
```
16461646

1647+
**Debug information on cl.exe (2026.11.7.1+).** `debug = true` compiles with
1648+
`/Z7`: each object carries its own debug information. `/Zi` and `/ZI` write
1649+
the debug information of every compile into one PDB through mspdbsrv.exe, a
1650+
server that outlives the compile that started it and ends with that compile's
1651+
process unit; `/Zi`, `/ZI` and `/FS` in a package's flags are refused before
1652+
anything compiles.
1653+
16471654
- Selection & default: a bare `mcpp build` uses the **`dev`** profile (`-O0 -g`) — the
16481655
mainstream convention (cf. Cargo/Meson/CMake/Zig/Bazel). **Release is opt-in:**
16491656
`mcpp build --release` (shorthand) or `--profile release`. `--dev` is the explicit

‎docs/zh/04-mcpp-toml.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1504,7 +1504,7 @@ GCC 16.1 报告 `sorry, unimplemented: private module fragment`,mcpp
15041504
```toml
15051505
[profile.dist]
15061506
opt = 3 # -O level (a number, or the string "s"/"z")
1507-
debug = false # -g
1507+
debug = false # -g;cl.exe 上为 /Z7
15081508
lto = true # -flto; /GL + /LTCG on cl.exe (note: some packaged gcc builds ship without the LTO plugin)
15091509
strip = true # -s at link time
15101510
ndebug = true # 整个图的每个单元 -DNDEBUG(release/dist 默认开)
@@ -1516,6 +1516,10 @@ cxxflags = ["-fno-plt"]
15161516
ldflags = []
15171517
```
15181518

1519+
**cl.exe 上的调试信息(2026.11.7.1+)。**`debug = true` 以 `/Z7` 编译:每个对象携带自己的调试信息。
1520+
`/Zi` 与 `/ZI` 把全部编译的调试信息经由 mspdbsrv.exe 写入同一个 PDB;该服务在启动它的编译结束后继续存在,
1521+
并随那个编译的进程单元一同结束。包的标志中的 `/Zi`、`/ZI`、`/FS` 在编译开始前被拒绝。
1522+
15191523
- 选择与默认值:一条裸的 `mcpp build` 使用 **`dev`** profile
15201524
(`-O0 -g`)——这是主流约定(参见 Cargo/Meson/CMake/Zig/Bazel)。
15211525
**Release 需要显式选择:**`mcpp build --release`(简写)或

‎modules/toolchain-model/src/dialect.cppm‎

Lines changed: 37 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ struct CommandDialect {
3030
std::string_view compileOnly; // "-c" | "/c"
3131
std::string_view outputObjPrefix; // "-o " | "/Fo:"
3232
std::string_view optPrefix; // "-O" | "/O"
33-
std::string_view debugFlags; // "-g" | "/Zi /FS"
33+
std::string_view debugFlags; // "-g" | "/Z7"
3434
std::string_view alwaysFlags; // "" | "/nologo /EHsc /utf-8"
3535
// Same rationale as forceCxxLangArgv: the argv consumer gets tokens, not
3636
// a string it has to split. Both spans point at static arrays below.
@@ -205,6 +205,18 @@ std::optional<CrtWordVerdict> check_crt_word(std::string_view word,
205205
bool staticCrt,
206206
std::string_view key);
207207

208+
// A SHARED-PDB WORD IS REFUSED ON cl.exe (2026.11.7.1). `/Zi` and `/ZI`
209+
// write a compile's debug information into a PDB that every compile of a
210+
// directory shares, through mspdbsrv.exe, a server the first cl.exe starts and
211+
// that outlives it; `/FS` serialises those writes through it. Each compile
212+
// runs in a process unit that retires with the compile, and the server is a
213+
// member of the unit that started it: retiring that unit ends the server under
214+
// every other compile writing through it. `[profile.<name>] debug = true`
215+
// gives each object its own debug information (`/Z7`). Returns the refusal
216+
// for such a word, either dash, and nullopt for any other word.
217+
std::optional<std::string> check_shared_pdb_word(std::string_view word,
218+
std::string_view key);
219+
208220
// The two dialect rows, reachable without a Toolchain. Exposed so the MSVC
209221
// row — which no build reaches until the cl.exe backend lands — can still be
210222
// unit-tested, and so callers that already know the shape they want (the
@@ -273,7 +285,15 @@ constexpr CommandDialect kMsvcDialect{
273285
.compileOnly = "/c",
274286
.outputObjPrefix = "/Fo:",
275287
.optPrefix = "/O",
276-
.debugFlags = "/Zi /FS",
288+
// DEBUG INFORMATION IN EACH OBJECT (/Z7), not in a PDB that every compile
289+
// of a directory shares (/Zi /FS). The shared PDB is written through
290+
// mspdbsrv.exe, which the first cl.exe starts and which outlives it by
291+
// seconds; the compiler executor retires each compile's process unit, and
292+
// retiring the unit that holds the server ended the server under the
293+
// concurrent compiles writing through it (C1090, PDB API error 23). An
294+
// object that carries its own debug information is also complete on its
295+
// own, which the object cache and a taken-over build directory assume.
296+
.debugFlags = "/Z7",
277297
.alwaysFlags = "/nologo /EHsc /utf-8",
278298
.alwaysFlagsArgv = kMsvcAlwaysArgv,
279299
.libFlag = "{}.lib",
@@ -333,6 +353,21 @@ std::string std_flag_for(const CommandDialect& d,
333353
return std::format("{}{}", d.stdPrefix, canonical);
334354
}
335355

356+
std::optional<std::string> check_shared_pdb_word(std::string_view word,
357+
std::string_view key) {
358+
if (word.size() != 3 || (word[0] != '/' && word[0] != '-'))
359+
return std::nullopt;
360+
const auto spelling = word.substr(1);
361+
if (spelling != "Zi" && spelling != "ZI" && spelling != "FS")
362+
return std::nullopt;
363+
return std::format(
364+
"`{}` in {} writes debug information through mspdbsrv.exe, a PDB server "
365+
"shared by every compile and ended with the compile that started it. "
366+
"Remove the flag: `[profile.<name>] debug = true` gives each object its "
367+
"own debug information (/Z7)",
368+
word, key);
369+
}
370+
336371
std::optional<CrtWordVerdict> check_crt_word(std::string_view word,
337372
bool staticCrt,
338373
std::string_view key) {

‎src/build/prepare/scan.cpp‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -440,6 +440,10 @@ step11_msvc_crt_word_check(PrepareState& state) {
440440
// NOT gated on `needsStdModule`: the CRT model is a link-time fact for
441441
// every MSVC-ABI build, with or without `import std`.
442442
//
443+
// On cl.exe the same pass refuses a shared-PDB word (`/Zi`, `/ZI`, `/FS`):
444+
// its server outlives the compile that started it, and retiring that
445+
// compile's unit ends it under the others (`check_shared_pdb_word`).
446+
//
443447
// EVERY PACKAGE'S `cxxflags`, because each reaches its own package's
444448
// units after the graph's flags and would compile them against another
445449
// CRT: one image, two CRTs. `dialect_cxxflags` is the root's alone (a
@@ -450,6 +454,9 @@ step11_msvc_crt_word_check(PrepareState& state) {
450454
if (mcpp::toolchain::is_msvc_target(*state.tc)) {
451455
const bool wantsStatic = mcpp::toolchain::msvc_wants_static_crt(
452456
state.m->buildConfig.linkage, state.m->buildConfig.cxxRuntime);
457+
// cl.exe alone writes a shared PDB through mspdbsrv.exe; clang on the
458+
// MSVC ABI writes its debug information into each object.
459+
const bool clExe = mcpp::toolchain::dialect_for(*state.tc).id == "msvc";
453460
for (std::size_t i = 0; i < state.packages.size(); ++i) {
454461
auto const& pkg = state.packages[i];
455462
// A selected workspace member is the project being developed and
@@ -473,8 +480,12 @@ step11_msvc_crt_word_check(PrepareState& state) {
473480
for (auto const& w : list) {
474481
const bool inherited =
475482
std::ranges::find(fromWorkspace, w) != fromWorkspace.end();
476-
auto verdict = mcpp::toolchain::check_crt_word(
477-
w, wantsStatic, inherited ? std::string_view(workspaceKey) : key);
483+
const std::string_view at =
484+
inherited ? std::string_view(workspaceKey) : key;
485+
if (clExe)
486+
if (auto refusal = mcpp::toolchain::check_shared_pdb_word(w, at))
487+
return std::unexpected(*refusal);
488+
auto verdict = mcpp::toolchain::check_crt_word(w, wantsStatic, at);
478489
if (!verdict) continue;
479490
if (verdict->contradicts)
480491
return std::unexpected(verdict->message);

‎src/toolchain/lifecycle.cppm‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -208,8 +208,8 @@ void msvc_print_detected(const mcpp::toolchain::msvc::MsvcInstallation& inst,
208208
// read-only files — payloads are unpacked from .vsix/.msi, and archive
209209
// entries carry the attribute through. POSIX only needs the DIRECTORY
210210
// writable to unlink a child, so this never shows up on Linux or macOS.
211-
// a lingering handle — a build with /Zi leaves mspdbsrv.exe running for a
212-
// few seconds after cl.exe exits, and it lives inside the payload.
211+
// a lingering handle — a build that writes a PDB leaves mspdbsrv.exe
212+
// running for a few seconds after it ends, and it lives inside the payload.
213213
//
214214
// Both surface as the same "Access is denied", which is why this handles both
215215
// rather than picking one: clear the attribute, then give a live process a
@@ -263,8 +263,8 @@ export bool remove_payload_tree(const std::filesystem::path& root,
263263
// even while open, same volume, the handle follows the file)
264264
// then delete the payload tree, which now holds only directories
265265
//
266-
// This is what makes `remove` mean something after a /Zi build with the
267-
// toolset being removed: mspdbsrv.exe lives INSIDE the payload and
266+
// This is what makes `remove` mean something after a build that wrote a
267+
// PDB with the toolset being removed: mspdbsrv.exe lives INSIDE the payload and
268268
// outlives cl.exe by tens of seconds, so "wait for it" is a guess and a
269269
// CLI that hangs on a guess is worse than the failure. The bytes are
270270
// swept by the next lifecycle command, when nothing holds them.
@@ -307,7 +307,8 @@ export bool remove_payload_tree(const std::filesystem::path& root,
307307
// The files are gone and an empty directory skeleton would not die. That
308308
// is a sharing violation on a DIRECTORY, which on Windows means some
309309
// process has one of them as its current directory -- mspdbsrv.exe is
310-
// launched inside the payload, so this is the normal tail of a /Zi build.
310+
// launched inside the payload, so this is the normal tail of a build that
311+
// wrote a PDB.
311312
//
312313
// A toolchain with no files in it is not installed, which is what
313314
// `remove` promises. Reporting failure here would be reporting the
Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
#!/usr/bin/env bash
2+
# requires: msvc
3+
# cl.exe OBJECTS CARRY THEIR OWN DEBUG INFORMATION (2026.11.7.1).
4+
# A dev build compiled with `/Zi /FS`: every compile of a directory wrote one
5+
# PDB through mspdbsrv.exe, which the first cl.exe started and which outlives
6+
# it. Each compile runs in a process unit that retires with it, so retiring
7+
# the unit that held the server ended it under the concurrent compiles, and
8+
# one failed with C1090, PDB API error 23 (258, intermittently). Debug
9+
# information is now `/Z7`, in each object, and a shared-PDB word in the
10+
# manifest is refused before anything compiles.
11+
set -e
12+
source "$(dirname "$0")/_host_path.sh"
13+
14+
TMP=$(mktemp -d)
15+
trap "rm -rf $TMP" EXIT
16+
mkdir -p "$TMP/many/src"
17+
cd "$TMP/many"
18+
cat > mcpp.toml <<'EOF2'
19+
[package]
20+
name = "many"
21+
version = "0.1.0"
22+
[toolchain]
23+
windows = "msvc@system"
24+
EOF2
25+
# Enough units that compiles overlap, each with debug information.
26+
for k in $(seq 1 16); do
27+
printf 'int part%d(int v) { return v + %d; }\n' "$k" "$k" > "src/part$k.cpp"
28+
done
29+
{
30+
for k in $(seq 1 16); do printf 'int part%d(int);\n' "$k"; done
31+
printf 'int main() { int s = 0;\n'
32+
for k in $(seq 1 16); do printf ' s += part%d(0);\n' "$k"; done
33+
printf ' return s == 136 ? 0 : 1; }\n'
34+
} > src/main.cpp
35+
36+
"$MCPP" build > build.log 2>&1 || {
37+
cat build.log
38+
echo "FAIL: a dev build of overlapping cl.exe compiles did not build"; exit 1; }
39+
nj="$(find target -name build.ninja -not -path '*/.build-mcpp/*' | head -1)"
40+
grep -q '/Z7' "$nj" || {
41+
grep -n 'cxxflags\|/Z' "$nj" | head
42+
echo "FAIL: the dev profile's cl.exe compile does not write /Z7 debug information"; exit 1; }
43+
if grep -qE '(^| )/(Zi|FS)( |$)' "$nj"; then
44+
grep -nE '/(Zi|FS)' "$nj" | head
45+
echo "FAIL: a cl.exe compile still writes a shared PDB"; exit 1
46+
fi
47+
"$MCPP" run > run.log 2>&1 || {
48+
cat run.log; echo "FAIL: the program of the dev build did not run"; exit 1; }
49+
50+
# A shared-PDB word in the manifest is refused before anything compiles.
51+
cat >> mcpp.toml <<'EOF2'
52+
[build]
53+
cxxflags = ["/Zi"]
54+
EOF2
55+
if "$MCPP" build > refused.log 2>&1; then
56+
cat refused.log
57+
echo "FAIL: [build] cxxflags = [\"/Zi\"] built on cl.exe"; exit 1
58+
fi
59+
grep -q 'mspdbsrv' refused.log && grep -q '/Z7' refused.log || {
60+
cat refused.log
61+
echo "FAIL: the refusal does not say why /Zi is refused and what to write"; exit 1; }
62+
if grep -q 'Compiling' refused.log; then
63+
cat refused.log; echo "FAIL: the refusal came after compiling began"; exit 1
64+
fi
65+
echo "PASS: cl.exe objects carry their own debug information; /Zi is refused"

‎tests/unit/test_toolchain_dialect.cpp‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,9 @@ TEST(CommandDialect, MsvcSpellings) {
4040
EXPECT_EQ(d.stdPrefix, "/std:");
4141
EXPECT_EQ(d.outputObjPrefix, "/Fo:");
4242
EXPECT_EQ(d.objExt, ".obj");
43+
// Each object carries its debug information: no compile writes through
44+
// the shared PDB server another compile's unit holds.
45+
EXPECT_EQ(d.debugFlags, "/Z7");
4346
EXPECT_TRUE(d.rspfileLink);
4447
EXPECT_EQ(d.linkStyle, CommandDialect::LinkStyle::SeparateLinker);
4548
}
@@ -227,6 +230,19 @@ TEST(MsvcAbiCrtWord, EveryContractResolvesToExactlyOneWordPerRow) {
227230
}
228231
}
229232

233+
// A shared-PDB word is refused on cl.exe, either dash; other words pass.
234+
TEST(CheckSharedPdbWord, ZiZIAndFSAreRefusedOtherWordsPass) {
235+
for (auto* word : {"/Zi", "-Zi", "/ZI", "-ZI", "/FS", "-FS"}) {
236+
auto refusal = check_shared_pdb_word(word, "[build] cxxflags");
237+
ASSERT_TRUE(refusal.has_value()) << word;
238+
EXPECT_NE(refusal->find(word), std::string::npos) << *refusal;
239+
EXPECT_NE(refusal->find("[build] cxxflags"), std::string::npos) << *refusal;
240+
EXPECT_NE(refusal->find("/Z7"), std::string::npos) << *refusal;
241+
}
242+
for (auto* word : {"/Z7", "-Z7", "/Zc:__cplusplus", "/Zp8", "/FSx", "/MT", "-g"})
243+
EXPECT_FALSE(check_shared_pdb_word(word, "[build] cxxflags").has_value()) << word;
244+
}
245+
230246
// D3: a free-form CRT word is always a second statement once the model is
231247
// resolved for every MSVC-ABI row.
232248
TEST(CheckCrtWord, AgreeingWordIsRedundantContradictingWordIsRefused) {

0 commit comments

Comments
 (0)