fix(pack,prepare): the neutral link form only where it says the same thing

e2e 257 caught a regression the previous commit introduced, and the reason is
worth keeping: a leg's link line is not always just a library reference.

A PE/MinGW shared leg links with `-L… -Wl,-Bdynamic -lmathkit`, and
`-Wl,-Bdynamic` only works IMMEDIATELY BEFORE the `-l` it enables — mcpp gives PE
executables `-static`, which otherwise leaves ld in static-only mode where it
refuses an import library and says `have you installed the static version of the
mathkit library?`, naming neither the DLL nor `-static`.

The first attempt cleared the leg's ldflags wholesale and lost the flag. The
second kept it but rendered the library reference through the neutral channel,
which puts it in a different slot on the command line — so the flag and its
argument were separated and the same failure came back. Both are the same
mistake: treating a hand-tuned link line as if it were a two-field record.

So the neutral form is emitted only for legs where it is EQUIVALENT, and the
PE/MinGW shared leg keeps the spelling that works. It costs nothing — a PE/GNU
leg is not an MSVC-ABI leg, and cl.exe, the reason the neutral form exists, never
reads it. On the consuming side only the library references are replaced, never
the whole list.

Author: speak-agent

docs/12-binary-distribution.md

@@ -329,11 +329,19 @@ target, so a `cl.exe` consumer links the package. They are not new vocabulary 
 `[runtime]` has had both keys at the top level all along; this makes them
 per-target.
 
-**Both spellings are emitted, and a newer mcpp ignores the `ldflags` rather than
-adding to them.** An older mcpp reads only the `ldflags` and silently ignores the
-`runtime` block, so dropping the `ldflags` would leave every older client with no
-link line at all; adding both would put `-L` back on the `cl` command line, which
-is the thing being avoided.
+**Both spellings are emitted, and a newer mcpp drops the leg's library
+references rather than adding to them.** An older mcpp reads only the `ldflags`
+and silently ignores the `runtime` block, so dropping the `ldflags` would leave
+every older client with no link line at all; adding both would put `-L` back on
+the `cl` command line, which is the thing being avoided.
+
+One leg is deliberately left out of this: a **PE/MinGW shared** leg links with
+`-L… -Wl,-Bdynamic -lmathkit`, and `-Wl,-Bdynamic` only works immediately before
+the `-l` it enables — mcpp gives PE executables `-static`, which otherwise leaves
+the linker in static-only mode where it refuses an import library. The neutral
+form cannot say "switch link mode first", so that leg keeps the spelling that
+works. It costs nothing: a PE/MinGW leg is not an MSVC-ABI leg, and `cl.exe`
+never reads it.
 
 Naming the file by path instead (`lib/<triple>/mathkit.lib`) is the spelling
 every driver takes, and it does not work either: ninja runs link commands with

docs/zh/12-binary-distribution.md

@@ -295,11 +295,17 @@ mcpp 会按 target 把它们渲染成 `/LIBPATH:` + `<name>.lib` 或 `-L` + `-l<
 于是 `cl.exe` 的消费者也能链上。这两个键不是新词表 —— `[runtime]` 顶层一直就有,
 这里只是让它们可以按 target 给。
 
-**两种拼写都会写出来,而新版 mcpp 读到中立形式时会忽略同一条腿的 `ldflags`,
+**两种拼写都会写出来,而新版 mcpp 读到中立形式时会丢掉同一条腿的库引用,
 而不是叠加。** 旧版 mcpp 只读 `ldflags` 并静默忽略 `runtime` 段,所以去掉
 `ldflags` 会让所有旧客户端一个链接 flag 都拿不到;而两者都应用又会把 `-L` 送回
 `cl` 的命令行 —— 那正是要避免的事。
 
+有一条腿被刻意排除在外:**PE/MinGW 的动态库腿**链接行是
+`-L… -Wl,-Bdynamic -lmathkit`,而 `-Wl,-Bdynamic` 只有**紧邻它所启用的那个 `-l`**
+时才有效 —— mcpp 给 PE 可执行文件加 `-static`,否则链接器停在纯静态模式并拒绝
+导入库。中立形式没法表达「先切换链接模式」,所以那条腿保留能用的拼写。
+这不付出任何代价:PE/MinGW 的腿不是 MSVC ABI 的腿,`cl.exe` 永远读不到它。
+
 **改成直接写文件路径也不行**(`lib/<triple>/mathkit.lib` 才是每个 driver 都吃的
 拼写):ninja 执行链接命令时 cwd 是**输出目录**,而只有 include 家族前缀
 (`-I`、`-L` …)会被 `normalize_include_flags` 相对包根绝对化 —— 没有前缀的 token

src/build/prepare.cppm

@@ -232,8 +232,22 @@ void merge_conditional_config(mcpp::manifest::Manifest& m,
         // a broader unconditional one under GNU last-wins — which is what
         // makes an off-OS REMOVAL expressible (`-U` after the base `-D`).
         if (neutralWins) {
+            // ⚠️ Drop the LIBRARY REFERENCES, not the whole ldflags list.
+            //
+            // Clearing it outright was a measured regression: a PE/MinGW shared
+            // leg's ldflags also carry `-Wl,-Bdynamic`, without which `-static`
+            // leaves ld in static-only mode and it refuses the import library
+            // with `have you installed the static version of the mathkit
+            // library?`. e2e 257 caught it.
+            //
+            // The neutral form replaces exactly what it can express — a library
+            // and where to find it. Anything else in that block says something
+            // it cannot say, and must survive.
             auto inputs = cc.inputs;
-            inputs.ldflags.clear();
+            std::erase_if(inputs.ldflags, [](std::string_view f) {
+                return f.starts_with("-L") || f.starts_with("-l")
+                    || f.starts_with("/LIBPATH:");
+            });
             mcpp::manifest::append(m.buildConfig, inputs);
         } else {
             mcpp::manifest::append(m.buildConfig, cc.inputs);

src/pack/manifest_emit.cppm

@@ -243,19 +243,32 @@ std::string emit_package_manifest(const PackageDoc& doc) {
                          peGnuShared ? "\"-Wl,-Bdynamic\", " : "",
                          leg.linkName);
 
-        // …and the same statement without a dialect. mcpp renders these as
-        // `/LIBPATH:` + `<n>.lib` or `-L` + `-l<n>` from the target, which is
-        // what lets a consumer driven by native `cl.exe` link this package at
-        // all — cl rejects `-L`.
+        // …and, where it says the SAME thing, the dialect-neutral form. mcpp
+        // renders these as `/LIBPATH:` + `<n>.lib` or `-L` + `-l<n>` from the
+        // target, which is what lets a consumer driven by native `cl.exe` link
+        // this package at all — cl rejects `-L`.
         //
         // BOTH are emitted, deliberately. An older mcpp reads only the ldflags
         // above and silently ignores this block (measured), so dropping the
         // ldflags would leave every older client with no link line at all. A
-        // newer mcpp seeing this block ignores that leg's ldflags rather than
-        // adding to them — see merge_conditional_config.
-        o += std::format("[target.'{}'.runtime]\n", cfg_predicate_for(leg.triple));
-        o += std::format("link_library_dirs = [\"lib/{}\"]\n", leg.triple);
-        o += std::format("libraries         = [\"{}\"]\n\n", leg.linkName);
+        // newer mcpp seeing this block drops that leg's library references and
+        // uses these instead — see merge_conditional_config.
+        //
+        // ⚠️ NOT FOR A PE/MinGW SHARED LEG, and this was measured rather than
+        // reasoned. That leg's line is `-L… -Wl,-Bdynamic -lmathkit`, and
+        // `-Wl,-Bdynamic` only works IMMEDIATELY BEFORE the `-l` it enables:
+        // mcpp gives PE executables `-static`, which leaves ld in static-only
+        // mode where it refuses an import library. The neutral form has no way
+        // to say "and switch link mode first", and rendering the two halves
+        // through different slots separates the flag from its argument — e2e
+        // 257 fails with `have you installed the static version of the mathkit
+        // library?`. So that one leg keeps the spelling that works, and cl.exe
+        // never sees it: a PE/GNU leg is not an MSVC-ABI leg.
+        if (!peGnuShared) {
+            o += std::format("[target.'{}'.runtime]\n", cfg_predicate_for(leg.triple));
+            o += std::format("link_library_dirs = [\"lib/{}\"]\n", leg.triple);
+            o += std::format("libraries         = [\"{}\"]\n\n", leg.linkName);
+        }
     }
     // A shared library has to be FOUND at run time as well as linked, and the
     // two are different search paths — `link_library_dirs` is not rpath.