Merge branch 'feat/eight-t4' into feat/eight-reports

Author: speak-agent

docs/04-mcpp-toml.md

@@ -1471,9 +1471,11 @@ is a table of exactly two strings. `from` is relative to the declaring package's
 root, and `to` is relative to the executable's directory, where `"."` means that
 directory itself. Both are separated by `/` on every host, and neither may be
 absolute, name a drive, or contain an empty, `.` or `..` component; an entry
-that does is refused, and the refusal names its index. Two sources for one
-destination are refused naming the destination, while one file name in two
-directories is not a collision. `deploy` is a key of its own rather than a table
+that does is refused, and the refusal names its index. Two or more sources for
+one destination merge into a single copy, placed once every source is
+byte-identical (mcpp#723); they are refused at build time, naming every source
+and the destination, when they are not. One file name in two directories is
+not a collision. `deploy` is a key of its own rather than a table
 form of `deploy_files`, because a descriptor reader that predates it meets `{`
 inside `deploy_files` and does not terminate, whereas it skips a `runtime` key it
 does not know. `mcpp pack` stages the files of both keys at the same relative

docs/specs/build-plugins.md

@@ -140,12 +140,19 @@
   从不作为 `-L`)、`mcpp run` 的加载路径、`mcpp pack` 的闭包搜索与运行时校验,并把依赖包的
   声明传到消费方的可执行文件。(**已实现**,mcpp#702)
 - **R4.2** 一个在配置时已知的文件需要位于程序旁的某个相对位置时(Qt 的平台插件、Vulkan 的
-  ICD 清单),插件用 `deploy`。(**已实现**,协议 11)
+  ICD 清单),插件用 `deploy`。(**已实现**,协议 11)两个或更多来源为同一目的地各自声明
+  `deploy` 时,规划期不再把它当作错误拒绝:被声明的来源此时可能尚未生成,其内容无法比较。
+  引擎把它们合并为一条施工边,将每个来源都列为该边的输入;施工时(`mcpp stage`)逐字节核对
+  这些来源,字节相同则放置,不同则该边失败,消息点名每一个来源与该目的地。(**已实现**,
+  mcpp#723)
 - **R4.3** Windows 的可执行文件没有运行路径。`mcpp run` 通过 `PATH` 使用运行时搜索目录,
   `mcpp pack` 把闭包需要的 DLL 放到程序旁(**已实现**)。链接之后,引擎把程序直接或间接导入的、
   位于其运行时搜索目录中的非系统 DLL 放到程序旁,使从构建目录直接启动的程序同样能找到它们;
   闭包的求解与 `mcpp pack` 相同,DLL 在其目录中被替换后下一次构建再次放置。(**已实现**,
-  mcpp#702)
+  mcpp#702)一个目的地只有一个写者:本条的放置以 R4.2 与工具链耦合运行时 DLL(`toolchain-
+  coupled`)合并而成的部署清单为唯一权威,**禁止**写入该清单已经放置的名字。遇到清单已放置
+  的名字时,本条只比较该名字现有文件与运行时搜索目录中同名文件的字节,相同则不作声张,不同
+  则以警告点名这一差异,**禁止**覆盖清单已放置的文件。(**已实现**,mcpp#723)
 - **R4.4** 插件**禁止**在 `link_flag` 中写运行路径(`-Wl,-rpath,...`),**必须**使用 R4.1。
   (作者义务)
 

docs/zh/04-mcpp-toml.md

@@ -1401,9 +1401,10 @@ Link intent 把各个发现阶段分开处理：
 两个字符串组成的表。`from` 相对声明它的包根目录，`to` 相对可执行
 文件所在目录，`"."` 意味着那个目录本身。两者在每个宿主上都以 `/`
 分隔，都不能是绝对路径、不能命名一个驱动器、不能含有空、`.` 或 `..`
-组成部分；不满足的条目会被拒绝，拒绝信息点名它的索引。两个来源指向
-同一个目的地会被拒绝并点名那个目的地，而一个文件名出现在两个不同
-目录下不算冲突。`deploy` 是一个独立的键，而不是 `deploy_files` 的
+组成部分；不满足的条目会被拒绝，拒绝信息点名它的索引。两个或更多
+来源指向同一个目的地会合并为一次拷贝，字节相同则放置（mcpp#723）；
+不同则在施工时失败，点名每一个来源与该目的地。一个文件名出现在两个
+不同目录下不算冲突。`deploy` 是一个独立的键，而不是 `deploy_files` 的
 表格形式，因为一个早于它出现的描述符读取器，遇到 `deploy_files` 里的
 `{` 会无法终止，而它会跳过一个不认识的 `runtime` 键。`mcpp pack` 把
 这两个键指向的文件，以打包出的可执行文件为参照，拷贝到同样的相对

src/build/flags.cppm

@@ -1547,16 +1547,19 @@ CompileFlags compute_flags(const BuildPlan& plan) {
                     auto clash = std::ranges::find_if(plan.runtimeDeployFiles,
                         [&](auto const& d) { return d.dest == dest; });
                     if (clash != plan.runtimeDeployFiles.end()) {
-                        if (clash->source.lexically_normal()
-                            != src.lexically_normal())
+                        if (std::ranges::none_of(clash->sources,
+                                [&](auto const& s) {
+                                    return s.lexically_normal()
+                                        == src.lexically_normal();
+                                }))
                             f.diagnostics.push_back(std::format(
                                 "toolchain-coupled would stage '{}' beside the "
                                 "artifact, but this project already deploys "
                                 "'{}' there; keeping the project's file",
-                                src.string(), clash->source.string()));
+                                src.string(), clash->sources.front().string()));
                         continue;
                     }
-                    f.toolchainRuntimeDeploy.push_back({src, dest});
+                    f.toolchainRuntimeDeploy.push_back({{src}, dest});
                 }
             }
         }

src/build/ninja_backend.cppm

@@ -1935,7 +1935,16 @@ std::string emit_ninja_string(const BuildPlan& plan) {
         for (auto const& d : plan.linkIntent.runtimeSearchDirs)
             dirs += " " + ninja_command_word(d.string());
         append("rule place_dlls\n");
-        append("  command = $mcpp place-dlls --output $out --depfile $out.d $in" + dirs + "\n");
+        // `$placed` (SPEC-007 R4.2/R4.3, #723 self-review: one destination,
+        // one writer) names, per edge, the DLLs the merged deploy list
+        // already places directly beside THIS program. `place-dlls` skips
+        // them — that list is the authority for its own destinations, and
+        // this mechanism only compares and warns instead of racing it. It is
+        // always exactly one shell word, comma-joining the names (never
+        // empty in the ninja_command_word sense: `''`/`""` when there is
+        // nothing to say) so it can never absorb `$in` or the directories
+        // that follow it, whatever it lists.
+        append("  command = $mcpp place-dlls --output $out --depfile $out.d $in $placed" + dirs + "\n");
         append("  depfile = $out.d\n");
         append("  deps = gcc\n");
         append("  description = DLLS $in\n\n");
@@ -2958,6 +2967,18 @@ std::string emit_ninja_string(const BuildPlan& plan) {
             append("build " + exe + ".dlls: place_dlls " + exe
                    + (prepareStamps.empty() ? std::string{} : " |" + prepareStamps)
                    + "\n");
+            // One destination, one writer (SPEC-007 R4.2/R4.3, #723 self-
+            // review): the names the merged deploy list already places in
+            // THIS program's own directory. `place-dlls` must not place a
+            // second, competing copy of one of these — see the `$placed`
+            // comment above, and `place_runtime_dlls` in mcpp.pack.
+            std::string placedHere;
+            for (auto const& d : deployFiles) {
+                if (d.dest.parent_path() != lu.output.parent_path()) continue;
+                if (!placedHere.empty()) placedHere += ',';
+                placedHere += d.dest.filename().string();
+            }
+            append("  placed = " + ninja_command_word(placedHere) + "\n");
             append("default " + exe + ".dlls\n\n");
         }
 
@@ -2975,10 +2996,20 @@ std::string emit_ninja_string(const BuildPlan& plan) {
     // previous `mcpp run` gets the skip-if-equivalent treatment instead of a
     // hard "cannot copy" failure.
     // Inert on RPATH platforms where the merged deploy list is empty.
+    //
+    // SPEC-007 R4.2 (#723): a destination with more than one source (two
+    // packages of this graph each generated the same file) becomes ONE edge
+    // with every source as an input, not one edge per source. `mcpp stage`
+    // is where they are checked against each other's bytes — planning cannot,
+    // because a generated source may not exist yet. A destination with
+    // exactly one source (every project before this feature, and most
+    // packages after it) emits the exact same line as always: the loop below
+    // reduces to the one-word case with no change in spelling.
     for (auto const& d : deployFiles) {
-        append(std::format("build {} : stage_file {}\n",
-            escape_ninja_path(d.dest),
-            escape_ninja_path(d.source)));
+        std::string ins;
+        for (auto const& s : d.sources) ins += " " + escape_ninja_path(s);
+        append(std::format("build {} : stage_file{}\n",
+            escape_ninja_path(d.dest), ins));
     }
     if (!deployFiles.empty())
         append("\n");

src/build/plan.cppm

@@ -437,7 +437,15 @@ struct BuildPlan {
     // byte-for-byte unchanged; only a Windows prebuilt-DLL package (or a test
     // that ships a .dll) populates it. dest is relative to outputDir.
     struct DeployFile {
-        std::filesystem::path source;   // absolute source DLL
+        // Absolute source paths. Usually one; more than one means two or more
+        // packages of this graph each generate a file for this destination
+        // (SPEC-007 R4.2) — an `artifacts` dependency and its consumer asking
+        // one plugin for the same translation catalog is the case #723 was
+        // filed for. Planning no longer refuses this: at planning time a
+        // generated source may not exist yet, so its content cannot be
+        // compared. `mcpp stage` (mcpp.build.stage) is where the sources are
+        // actually checked, at build time, against each other's bytes.
+        std::vector<std::filesystem::path> sources;
         std::filesystem::path dest;     // relative to outputDir, e.g. bin/libopenblas.dll
     };
     std::vector<DeployFile>            runtimeDeployFiles;
@@ -1430,38 +1438,41 @@ make_plan(const mcpp::manifest::Manifest&         manifest,
 
     // `toDir` is a `runtime.deploy` destination, relative to the executable's
     // directory; empty and "." both mean that directory itself, which is where
-    // every `deploy_files` entry goes. The collision check keys on the full
-    // relative destination, so two files of one name in two directories do not
-    // collide, and two sources for one destination still do.
+    // every `deploy_files` entry goes. The check keys on the full relative
+    // destination, so two files of one name in two directories do not
+    // collide.
+    //
+    // Two sources for one destination are no longer refused HERE (SPEC-007
+    // R4.2, #723): at planning time a generated source may not exist yet, so
+    // its content cannot be compared. Both stay as inputs of the one
+    // `stage_file` edge this destination becomes (ninja_backend.cppm), and
+    // `mcpp stage` (mcpp.build.stage) is where the invariant — one
+    // destination, one content — is actually checked, once the sources exist.
+    // A source already listed for this destination (the ordinary case: the
+    // same file reached through two graph edges) is not duplicated.
     auto add_deploy = [&](const std::filesystem::path& source,
-                          std::string_view toDir = {})
-        -> std::optional<std::string> {
+                          std::string_view toDir = {}) {
         const auto normalized = source.lexically_normal();
         auto destDir = std::filesystem::path("bin");
         if (!toDir.empty() && toDir != ".") destDir /= std::filesystem::path(toDir);
         const auto dest = destDir / source.filename();
         auto existing = std::ranges::find_if(plan.runtimeDeployFiles,
             [&](auto const& value) { return value.dest == dest; });
         if (existing != plan.runtimeDeployFiles.end()) {
-            if (existing->source.lexically_normal() != normalized) {
-                return std::format(
-                    "runtime deploy collision: '{}' and '{}' both target '{}'",
-                    existing->source.string(), normalized.string(), dest.string());
-            }
-            return std::nullopt;
+            if (std::ranges::find(existing->sources, normalized)
+                == existing->sources.end())
+                existing->sources.push_back(normalized);
+            return;
         }
-        plan.runtimeDeployFiles.push_back({normalized, dest});
-        return std::nullopt;
+        plan.runtimeDeployFiles.push_back({{normalized}, dest});
     };
     // Structured deploy files are explicit and platform-neutral.  Legacy
     // library_dirs keeps its one-train DLL discovery behavior below.
     for (auto const& source : plan.linkIntent.deployFiles) {
-        if (auto collision = add_deploy(source))
-            return std::unexpected(std::move(*collision));
+        add_deploy(source);
     }
     for (auto const& entry : plan.linkIntent.deploy) {
-        if (auto collision = add_deploy(entry.from, entry.to))
-            return std::unexpected(std::move(*collision));
+        add_deploy(entry.from, entry.to);
     }
     for (auto const& dir : plan.linkIntent.runtimeSearchDirs) {
         std::error_code dirEc;
@@ -1472,8 +1483,7 @@ make_plan(const mcpp::manifest::Manifest&         manifest,
             std::ranges::transform(ext, ext.begin(),
                 [](unsigned char c){ return std::tolower(c); });
             if (ext != ".dll") continue;
-            if (auto collision = add_deploy(entry.path()))
-                return std::unexpected(std::move(*collision));
+            add_deploy(entry.path());
         }
     }
     // The same private runtime directories embedded as executable RUNPATH are

src/build/stage.cppm

@@ -75,6 +75,30 @@ std::expected<StageOutcome, StageError> stage_file(const std::filesystem::path&
                                                    const std::filesystem::path& dst,
                                                    const StageOptions& opts = {});
 
+// Publish one destination that may have more than one source (SPEC-007 R4.2,
+// mcpp#723): two or more packages of one graph can each generate a
+// byte-identical file and deploy it under the same name, and the plan no
+// longer refuses that at planning time — a generated source may not exist yet
+// when the plan is built, so its content cannot be compared there. This is
+// where the invariant is actually checked, because by build time every source
+// exists: every source is compared against the first by content
+// (`same_content`, never masking the way `bmi_equivalent` does — a deploy
+// target is an ordinary file, not a BMI with a compiler-embedded clock), and
+// the first is staged when they all agree. Disagreement is refused, naming
+// every source and the destination, so the message points at every producer
+// instead of an arbitrary pair.
+//
+// `srcs.size() == 1` is not a special case bolted on top: it takes the same
+// path as every other count, with the comparison loop simply empty, and ends
+// up calling `stage_file` on that one source exactly as before this function
+// existed. This is what keeps a project with one source per destination —
+// every project before this feature — emitting the same `mcpp stage`
+// invocation it always has.
+std::expected<StageOutcome, StageError> stage_files(
+    const std::vector<std::filesystem::path>& srcs,
+    const std::filesystem::path& dst,
+    const StageOptions& opts = {});
+
 // Byte-for-byte comparison (exported for tests). False when either file is
 // unreadable or the sizes differ.
 bool same_content(const std::filesystem::path& a, const std::filesystem::path& b);
@@ -337,4 +361,27 @@ std::expected<StageOutcome, StageError> stage_file(const std::filesystem::path&
     return std::unexpected(StageError{failure_message(src, dst, last)});
 }
 
+std::expected<StageOutcome, StageError> stage_files(
+    const std::vector<std::filesystem::path>& srcs,
+    const std::filesystem::path& dst,
+    const StageOptions& opts)
+{
+    if (srcs.empty()) {
+        return std::unexpected(StageError{
+            std::format("staging '{}' requires at least one source", dst.string())});
+    }
+    for (std::size_t i = 1; i < srcs.size(); ++i) {
+        if (!same_content(srcs.front(), srcs[i])) {
+            std::string list;
+            for (auto const& s : srcs) list += std::format("\n  {}", s.string());
+            return std::unexpected(StageError{std::format(
+                "two or more sources disagree for one destination\n"
+                "  destination: {}\n"
+                "  sources:{}",
+                dst.string(), list)});
+        }
+    }
+    return stage_file(srcs.front(), dst, opts);
+}
+
 } // namespace mcpp::build::stage

src/cli/cmd_build.cppm

@@ -914,19 +914,25 @@ export int cmd_dyndep(const mcpplibs::cmdline::ParsedArgs& parsed) {
 }
 
 // Invoked by ninja during build (stage_file rule):
-//   mcpp stage --output <dst> <src>
+//   mcpp stage --output <dst> <src>...
 //
 // Publishes a cache-owned artifact (std BMI, std.o, runtime DLL) into the
 // build directory. See mcpp.build.stage for the semantics — in particular why
 // an already-equivalent destination is left untouched (#311).
+//
+// More than one source (SPEC-007 R4.2, mcpp#723) means two or more packages
+// of this graph deploy the same destination; `stage_files` places it when
+// every source is byte-identical and otherwise fails, naming every source
+// and the destination. One source — every invocation before this feature —
+// takes the exact path it always has.
 export int cmd_stage(const mcpplibs::cmdline::ParsedArgs& parsed) {
     std::filesystem::path outPath = parsed.option_or_empty("output").value();
     if (outPath.empty()) {
         std::println(stderr, "error: --output <path> required");
         return 2;
     }
-    if (parsed.positional_count() != 1) {
-        std::println(stderr, "error: stage requires exactly one source path");
+    if (parsed.positional_count() < 1) {
+        std::println(stderr, "error: stage requires at least one source path");
         return 2;
     }
 
@@ -939,9 +945,13 @@ export int cmd_stage(const mcpplibs::cmdline::ParsedArgs& parsed) {
     if (!verify.empty())
         opts.verify = mcpp::build::stage::parse_verify(verify);
 
-    auto r = mcpp::build::stage::stage_file(
-        mcpp::platform::fs::extended_length(std::filesystem::path{parsed.positional(0)}),
-        mcpp::platform::fs::extended_length(outPath), opts);
+    std::vector<std::filesystem::path> sources;
+    for (std::size_t i = 0; i < parsed.positional_count(); ++i)
+        sources.push_back(mcpp::platform::fs::extended_length(
+            std::filesystem::path{parsed.positional(i)}));
+
+    auto r = mcpp::build::stage::stage_files(
+        sources, mcpp::platform::fs::extended_length(outPath), opts);
     if (!r) {
         std::println(stderr, "error: {}", r.error().message);
         return 1;