feat(build): materialize package generated files

Author: Sunrisepeak

.agents/docs/2026-05-30-package-owned-build-flags-plan.md

@@ -24,6 +24,7 @@ xlings 现在可以用 `mcpp 0.0.34` 构建，但工程文件里有大量 C 库
 - [x] 依赖包描述中的 `mcpp.cflags` / `mcpp.cxxflags` 能作用到该包自己的 compile units。
 - [x] 包级 include dirs 在编译该包源码时优先于全局 include dirs。
 - [x] build fingerprint / cache key 包含包级 flags，避免 flags 变化后误用缓存。
+- [x] Form B 描述支持 `generated_files`，让官方索引包可以生成少量包私有配置头。
 - [x] 保持现有项目级 flags 兼容，不破坏已有 manifest。
 - [x] 用 xlings 当前项目验证 `mcpp build` 和 `mcpp build --target x86_64-linux-musl`。
 
@@ -32,6 +33,7 @@ xlings 现在可以用 `mcpp 0.0.34` 构建，但工程文件里有大量 C 库
 - `src/manifest.cppm`
   - 保持现有解析入口。
   - 若缺少字段，不改变默认行为。
+  - 解析 `mcpp.generated_files = { ["path"] = "content" }`。
 - `src/build/plan*.cppm` 或当前 build plan 生成位置
   - 在 compile unit 上记录 origin package 或直接保存 package-owned flags。
 - `src/build/flags.cppm`
@@ -41,6 +43,7 @@ xlings 现在可以用 `mcpp 0.0.34` 构建，但工程文件里有大量 C 库
   - 加入 package build metadata hash。
 - `tests/*`
   - 增加一个最小包级 cflags 测试: 依赖包源码必须依赖包内宏才能编译通过，主项目不声明该宏。
+  - 增加一个最小 Form B `generated_files` 测试: 依赖包源码包含生成头，消费者不声明该头。
 
 ## 验证命令
 
@@ -59,9 +62,12 @@ cd /home/speak/workspace/github/openxlings/xlings
 - [x] 文档 checkpoint commit: `9047604`.
 - [x] failing test added: `tests/e2e/50_package_owned_build_flags.sh`.
 - [x] package-owned flags implementation.
+- [x] package-owned generated support files implementation:
+  - `tests/unit/test_manifest.cpp` 覆盖 Form B `generated_files` 解析。
+  - `tests/e2e/51_package_generated_files.sh` 覆盖生成文件参与依赖包编译。
 - [x] xlings local validation:
   - `mcpp build` -> `target/x86_64-linux-gnu/ff952c89919589bb/bin/xlings --version` = `xlings 0.4.45`.
   - `mcpp build --target x86_64-linux-musl` -> `target/x86_64-linux-musl/7e48a312cd4dbb49/bin/xlings` static ELF.
-- [ ] PR draft 创建。
+- [x] PR draft 创建: https://github.com/mcpp-community/mcpp/pull/88
 - [ ] CI 每 120s 检查一次直到完成。
 - [ ] 设计确认后 bump `0.0.35` 并发布。

src/cli.cppm

@@ -623,10 +623,59 @@ std::string canonical_package_build_metadata(
             s += " cxxflag:";
             s += flag;
         }
+        for (auto const& [path, content] : pkg.manifest.buildConfig.generatedFiles) {
+            s += " genfile:";
+            s += path.generic_string();
+            s += "=";
+            s += content;
+        }
     }
     return s;
 }
 
+std::expected<void, std::string>
+materialize_generated_files(const std::filesystem::path& root,
+                            const mcpp::manifest::Manifest& manifest)
+{
+    for (auto const& [relPath, content] : manifest.buildConfig.generatedFiles) {
+        if (relPath.empty()) {
+            return std::unexpected("generated_files contains an empty path");
+        }
+        if (relPath.is_absolute()) {
+            return std::unexpected(std::format(
+                "generated_files path '{}' must be relative", relPath.generic_string()));
+        }
+        for (auto const& part : relPath) {
+            if (part == "..") {
+                return std::unexpected(std::format(
+                    "generated_files path '{}' must not escape the package root",
+                    relPath.generic_string()));
+            }
+        }
+
+        auto out = root / relPath.lexically_normal();
+        std::error_code ec;
+        std::filesystem::create_directories(out.parent_path(), ec);
+        if (ec) {
+            return std::unexpected(std::format(
+                "cannot create directory for generated file '{}': {}",
+                out.string(), ec.message()));
+        }
+
+        std::ofstream os(out, std::ios::binary);
+        if (!os) {
+            return std::unexpected(std::format(
+                "cannot write generated file '{}'", out.string()));
+        }
+        os << content;
+        if (!os) {
+            return std::unexpected(std::format(
+                "failed while writing generated file '{}'", out.string()));
+        }
+    }
+    return {};
+}
+
 bool is_std_module(std::string_view name) {
     return name == "std" || name == "std.compat";
 }
@@ -1714,6 +1763,11 @@ prepare_build(bool print_fingerprint,
             }
         }
 
+        if (auto r = materialize_generated_files(effRoot, *manifest); !r) {
+            return std::unexpected(std::format(
+                "dependency '{}': {}", depName, r.error()));
+        }
+
         return std::pair{effRoot, std::move(*manifest)};
     };
 

src/manifest.cppm

@@ -79,6 +79,7 @@ struct Toolchain {
 struct BuildConfig {
     std::vector<std::string>           sources;        // glob patterns
     std::vector<std::filesystem::path> includeDirs;    // relative to package root
+    std::map<std::filesystem::path, std::string> generatedFiles; // Form B package-owned support files
     bool                                staticStdlib = true;
     // "" (default = dynamic), "static", "dynamic" — chosen at resolve
     // time from --static / --target / [target.<triple>].linkage. Wired
@@ -1296,6 +1297,27 @@ synthesize_from_xpkg_lua(std::string_view luaContent,
             }
             cur.consume('}');
         }
+        else if (key == "generated_files") {
+            // `{ ["relative/path"] = "contents", ... }`
+            if (!cur.consume('{')) {
+                return std::unexpected(ManifestError{
+                    "expected '{' after `generated_files =`", m.sourcePath, 0, 0});
+            }
+            cur.skip_ws_and_comments();
+            while (!cur.eof() && cur.peek() != '}') {
+                auto path = cur.read_key();
+                if (path.empty()) break;
+                cur.skip_ws_and_comments();
+                if (!cur.consume('=')) {
+                    return std::unexpected(ManifestError{
+                        "expected '=' in `generated_files` entry", m.sourcePath, 0, 0});
+                }
+                auto content = cur.read_string();
+                m.buildConfig.generatedFiles.emplace(path, std::move(content));
+                cur.skip_ws_and_comments();
+            }
+            cur.consume('}');
+        }
         else if (key == "targets") {
             // `{ ["name"] = { kind = "lib" }, ... }`
             if (!cur.consume('{')) {

tests/e2e/51_package_generated_files.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# requires: gcc fresh-sandbox
+# Form B package descriptors can materialize small package-owned support
+# files before scanning and compiling the package.
+set -e
+
+TMP=$(mktemp -d)
+trap "rm -rf $TMP" EXIT
+
+export MCPP_HOME="$TMP/mcpp-home"
+source "$(dirname "$0")/_inherit_toolchain.sh"
+
+INDEX_DIR="$TMP/local-index"
+mkdir -p "$INDEX_DIR/pkgs/t"
+cat > "$INDEX_DIR/pkgs/t/tinycfg.lua" <<'EOF'
+package = {
+    spec = "1",
+    name = "tinycfg",
+    description = "Generated config header package",
+    licenses = {"MIT"},
+    type = "package",
+    xpm = {
+        linux = {
+            ["1.0.0"] = {
+                url = "https://example.invalid/tinycfg-1.0.0.tar.gz",
+                sha256 = "0000000000000000000000000000000000000000000000000000000000000000",
+            },
+        },
+    },
+    mcpp = {
+        language = "c++23",
+        import_std = false,
+        sources = { "src/*.c" },
+        include_dirs = { "mcpp_generated/include" },
+        generated_files = {
+            ["mcpp_generated/include/generated_config.h"] = "#pragma once\n#define TINYCFG_VALUE 42\n",
+        },
+        targets = { ["tinycfg"] = { kind = "lib" } },
+        deps = {},
+    },
+}
+EOF
+
+mkdir -p "$TMP/project/app/src" \
+         "$TMP/project/app/.mcpp/.xlings/data/xpkgs/local-dev.tinycfg/1.0.0/src"
+cd "$TMP/project/app"
+
+cat > .mcpp/.xlings/data/xpkgs/local-dev.tinycfg/1.0.0/src/tinycfg.c <<'EOF'
+#include "generated_config.h"
+int tinycfg_value(void) {
+    return TINYCFG_VALUE;
+}
+EOF
+
+cat > src/main.cpp <<'EOF'
+extern "C" int tinycfg_value(void);
+int main() {
+    return tinycfg_value() == 42 ? 0 : 1;
+}
+EOF
+
+cat > mcpp.toml <<EOF
+[package]
+name = "app"
+version = "0.1.0"
+
+[indices]
+local-dev = { path = "$INDEX_DIR" }
+
+[dependencies]
+"local-dev.tinycfg" = "1.0.0"
+
+[targets.app]
+kind = "bin"
+main = "src/main.cpp"
+EOF
+
+"$MCPP" build > build.log 2>&1 || {
+    cat build.log
+    exit 1
+}
+
+generated=".mcpp/.xlings/data/xpkgs/local-dev.tinycfg/1.0.0/mcpp_generated/include/generated_config.h"
+[[ -f "$generated" ]] || {
+    echo "FAIL: generated file was not materialized"
+    find .mcpp/.xlings/data/xpkgs/local-dev.tinycfg/1.0.0 -maxdepth 4 -type f | sort
+    exit 1
+}
+
+grep -q "TINYCFG_VALUE 42" "$generated" || {
+    echo "FAIL: generated file content mismatch"
+    cat "$generated"
+    exit 1
+}
+
+"$MCPP" run > run.log 2>&1 || {
+    cat run.log
+    exit 1
+}
+
+echo "OK"

tests/unit/test_manifest.cpp

@@ -194,6 +194,30 @@ package = {
     EXPECT_EQ(m->modules.sources[0], "*/src/*.c");
 }
 
+TEST(SynthesizeFromXpkgLua, GeneratedFiles) {
+    constexpr auto src = R"(
+package = {
+    spec = "1",
+    name = "tinyc",
+    xpm  = { linux = { ["1.0.0"] = { url = "u", sha256 = "h" } } },
+    mcpp = {
+        sources = { "*/src/*.c" },
+        generated_files = {
+            ["mcpp_generated/include/config.h"] = "#pragma once\n#define TINYC_OK 1\n",
+        },
+        include_dirs = { "mcpp_generated/include" },
+        targets = { ["tinyc"] = { kind = "lib" } },
+    },
+}
+)";
+    auto m = mcpp::manifest::synthesize_from_xpkg_lua(src, "tinyc", "1.0.0");
+    ASSERT_TRUE(m.has_value()) << m.error().format();
+    ASSERT_EQ(m->buildConfig.generatedFiles.size(), 1u);
+    auto it = m->buildConfig.generatedFiles.find("mcpp_generated/include/config.h");
+    ASSERT_NE(it, m->buildConfig.generatedFiles.end());
+    EXPECT_EQ(it->second, "#pragma once\n#define TINYC_OK 1\n");
+}
+
 TEST(Manifest, DependenciesFlatDefaultNamespace) {
     constexpr auto src = R"(
 [package]