fix: fold [build].defines into cflags/cxxflags before P1689 scan

[build].defines was parsed but never folded into the compile flags used
by the P1689 module scanner. When imports were guarded by a macro from
[build].defines, the scanner saw no imports while the planner (via
scan_overrides) expected them, causing module-graph divergence.

- Add defines to BuildConfig
- Parse [build].defines in TOML loader
- Fold defines into -D<x> on cflags/cxxflags before snapshot/fingerprint
- Add unit test and E2E regression test
- Update English and Chinese docs

Closes #296

Author: ZheFeng7110

docs/05-mcpp-toml.md

@@ -141,6 +141,7 @@ c_standard   = "c11"              # Standard for C source files (default c11)
 cflags       = ["-DFOO=1"]        # Extra C compile flags
 cxxflags     = ["-DBAR=2"]        # Extra C++ compile flags (do not put -std=... here)
 ldflags      = ["-lfoo"]          # Extra link flags
+defines      = ["BIZ=1", "QUX"]   # Preprocessor macros for every TU (desugars to -D; reaches module scans)
 static_stdlib = true               # Statically link libstdc++ (default true)
 target       = "x86_64-linux-musl" # Default build target when no --target is passed
                                    # (≙ cargo build.target; e.g. "ship fully-static")
@@ -182,6 +183,8 @@ then only guaranteed to run on the build machine's version and above). A lower
 floor (11–13) requires a self-built libc++ archive (already verified to work, a
 data-level switch, available on request).
 
+`defines` desugars each entry to `-D<x>` on both the C and C++ compile channels and reaches every TU in the package — including module interface units — so it affects the P1689 module scan. For macros that should only affect a single binary's entry source, use `[targets.<name>].defines` instead.
+
 Do not configure the C++ standard via `build.cxxflags = ["-std=..."]`. Instead use:
 
 ```toml

docs/zh/05-mcpp-toml.md

@@ -136,6 +136,7 @@ c_standard   = "c11"              # C 源文件的标准(默认 c11)
 cflags       = ["-DFOO=1"]        # 额外 C 编译参数
 cxxflags     = ["-DBAR=2"]        # 额外 C++ 编译参数(不要放 -std=...)
 ldflags      = ["-lfoo"]          # 额外链接参数
+defines      = ["BIZ=1", "QUX"]   # 作用于每个 TU 的预处理宏(脱糖为 -D;会进入模块扫描)
 static_stdlib = true               # 静态链接 libstdc++(默认 true)
 macos_deployment_target = "14.0"   # macOS 产物的最低支持系统版本(仅 macOS 生效)
 ```
@@ -166,6 +167,8 @@ cargo/rustc、cc 等同样尊重该变量)> 本字段(项目默认,类似 SwiftP
 系统 libc++(产物只保证在构建机同版本及以上运行)。更低 floor(11–13)
 需自建 libc++ 归档(已验证可行,数据级切换,按需提供)。
 
+`defines` 把每个条目脱糖为 `-D<x>`,同时作用于 C 和 C++ 编译通道,并覆盖包内每个 TU(包括模块接口单元),因此会影响 P1689 模块扫描。若只想让某个二进制入口源读到宏,请改用 `[targets.<name>].defines`。
+
 C++ 标准不要通过 `build.cxxflags = ["-std=..."]` 配置。请使用:
 
 ```toml

src/build/prepare.cppm

@@ -442,6 +442,19 @@ void merge_conditional_build_inputs(mcpp::manifest::Manifest& m,
     }
 }
 
+// Desugar `[build].defines` into `-D<x>` on both C and C++ flag channels.
+// This must run AFTER conditional `[target.'cfg(...)'.build]` sections are
+// merged (so conditional defines land too) and BEFORE the manifest is
+// snapshotted into packages[] / fingerprinted. Idempotent: clearing the
+// `defines` vector after folding makes repeated calls harmless.
+void fold_build_defines_into_flags(mcpp::manifest::BuildConfig& bc) {
+    for (auto const& d : bc.defines) {
+        bc.cflags.push_back("-D" + d);
+        bc.cxxflags.push_back("-D" + d);
+    }
+    bc.defines.clear();
+}
+
 // Feature-activation closure — THE single implementation (build.mcpp env
 // contract, Stage 2a feature-deps, and the main feature pass all call this):
 // seed = [features].default ∪ requested, expanded transitively over implies;
@@ -943,6 +956,10 @@ prepare_build(bool print_fingerprint,
             m->buildDependencies.insert(cc.buildDependencies.begin(), cc.buildDependencies.end());
         }
     }
+    // `[build].defines` must reach the scanner (P1689) and the compile edge,
+    // and must participate in the fingerprint. Fold before dependency
+    // resolution / fingerprinting.
+    fold_build_defines_into_flags(m->buildConfig);
 
     // msvc@system: a *system* toolchain — located on the machine, never
     // resolved through xim packages. mcpp does not install MSVC.
@@ -2073,6 +2090,7 @@ prepare_build(bool print_fingerprint,
                                     cfgpred::context_for(overrides.target_triple),
                                     overrides.target_triple);
         }
+        fold_build_defines_into_flags(manifest->buildConfig);
 
         return std::pair{effRoot, std::move(*manifest)};
     };
@@ -2964,6 +2982,7 @@ prepare_build(bool print_fingerprint,
                     cfgpred::context_for(overrides.target_triple),
                     overrides.target_triple);
             }
+            fold_build_defines_into_flags(dep_manifest->buildConfig);
         } else {
             auto loaded = loadVersionDep(name, key.ns, key.shortName, spec.version);
             if (!loaded) return std::unexpected(loaded.error());

src/manifest/toml.cppm

@@ -841,6 +841,7 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
     if (auto v = doc->get_bool("build.allow_host_libs")) m.buildConfig.allowHostLibs = *v;
     if (auto v = doc->get_string_array("build.cflags"))   m.buildConfig.cflags   = *v;
     if (auto v = doc->get_string_array("build.cxxflags")) m.buildConfig.cxxflags = *v;
+    if (auto v = doc->get_string_array("build.defines"))  m.buildConfig.defines  = *v;
     // Module-graph-global dialect flags (issue #210) — see types.cppm
     // dialect_flags(); this key is the explicit escape hatch for flags the
     // known-list doesn't recognize yet.

src/manifest/types.cppm

@@ -203,6 +203,13 @@ inline void append(BuildInputs& dst, const BuildInputs& src) {
 // is read in ~150 places, and a BuildConfig genuinely IS a set of build
 // inputs plus the selection axis and resolved policy scalars.
 struct BuildConfig : BuildInputs {
+    // Package-level preprocessor defines. Unlike per-target `defines` (which
+    // only affect the binary's entry TU), these reach every TU in this
+    // package — including module interface units — so they participate in
+    // the P1689 module scan. Desugared to `-D<x>` on both C and C++ compiles
+    // before the manifest is snapshot into BuildPlan / fingerprint.
+    std::vector<std::string>           defines;
+
     // feature name → extra source globs gated by that feature. A glob listed
     // here is EXCLUDED from the default build and only compiled/linked when the
     // feature is active for this package (resolved in prepare_build). Lets a

tests/e2e/167_build_defines_module_scan.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# requires:
+# [build].defines must reach the P1689 module scan AND the compile command
+# for every TU (including module interfaces). Previously it was parsed but
+# silently dropped, causing plan-vs-scan divergence for conditional imports.
+set -e
+
+TMP=$(mktemp -d)
+trap "rm -rf $TMP" EXIT
+
+cd "$TMP"
+mkdir -p src
+
+cat > src/lib.cppm <<'EOF'
+#ifndef TEST_USE_MODULES
+module;
+#include <print>
+#endif
+
+export module lib;
+
+#ifdef TEST_USE_MODULES
+import std;
+#endif
+
+export void printHello(){
+    std::println("hello from lib");
+}
+EOF
+
+cat > src/main.cpp <<'EOF'
+#ifdef TEST_USE_MODULES
+import std;
+import lib;
+#else
+#include <print>
+#endif
+
+int main() {
+    std::println("hello from main");
+    printHello();
+    return 0;
+}
+EOF
+
+cat > mcpp.toml <<'EOF'
+[package]
+name        = "hello"
+version     = "0.1.0"
+description = "A modular C++23 package"
+license     = "Apache-2.0"
+
+[build]
+defines = ["TEST_USE_MODULES"]
+
+[scan_overrides."src/lib.cppm"]
+provides = ["lib"]
+imports = ["std"]
+
+[scan_overrides."src/main.cpp"]
+imports = ["std", "lib"]
+EOF
+
+"$MCPP" build > build.log 2>&1 || { cat build.log; echo "build failed"; exit 1; }
+out=$("$MCPP" run 2>&1 | tail -2 | tr '\n' ' ')
+[[ "$out" == *"hello from main"*"hello from lib"* ]] || {
+    echo "unexpected output: $out"; exit 1; }
+
+echo "OK"

tests/unit/test_manifest.cpp

@@ -341,6 +341,24 @@ kind = "lib"
     EXPECT_EQ(m->buildConfig.cStandard, "c11");
 }
 
+// [build].defines is sugar for `-D<x>` on both C and C++ channels; it must
+// parse into buildConfig.defines so prepare_build can fold it into flags
+// before the P1689 scan and fingerprint.
+TEST(Manifest, BuildDefinesParsesIntoSeparateVector) {
+    constexpr auto src = R"(
+[package]
+name = "x"
+version = "0.1.0"
+[build]
+defines = ["TEST_USE_MODULES", "VALUE=42"]
+)";
+    auto m = mcpp::manifest::parse_string(src);
+    ASSERT_TRUE(m.has_value()) << m.error().format();
+    ASSERT_EQ(m->buildConfig.defines.size(), 2u);
+    EXPECT_EQ(m->buildConfig.defines[0], "TEST_USE_MODULES");
+    EXPECT_EQ(m->buildConfig.defines[1], "VALUE=42");
+}
+
 // #249: `[build] include_dirs_after` parses into buildConfig.includeDirsAfter
 // — the -idirafter channel (searched AFTER the toolchain's system dirs), so
 // an extracted-tarball root containing a file named like a standard header