feat: [build] macos_deployment_target manifest field

First-class manifest support for the macOS minimum supported OS version
of produced binaries (LC_BUILD_VERSION minos), following ecosystem
conventions: the MACOSX_DEPLOYMENT_TARGET env var (which cargo/rustc and
the cc crate honor) stays as the explicit per-invocation override, the
new [build] macos_deployment_target field provides the project default
(SwiftPM platforms: style), and the toolchain/SDK default applies when
neither is set.

The resolved value feeds the same paths the env var already did:
explicit -mmacosx-version-min on compile+link command lines and the BMI
fingerprint (switching targets rebuilds the module cache). No effect off
macOS. Unit tests + docs/05-mcpp-toml.md.

Author: Sunrisepeak

docs/05-mcpp-toml.md

@@ -91,8 +91,16 @@ cflags       = ["-DFOO=1"]        # 额外 C 编译参数
 cxxflags     = ["-DBAR=2"]        # 额外 C++ 编译参数(不要放 -std=...)
 ldflags      = ["-lfoo"]          # 额外链接参数
 static_stdlib = true               # 静态链接 libstdc++(默认 true)
+macos_deployment_target = "11.0"   # macOS 产物的最低支持系统版本(仅 macOS 生效)
 ```
 
+`macos_deployment_target` 设定产物 Mach-O 头里的最低系统版本
+(`LC_BUILD_VERSION minos`),即二进制能运行的最老 macOS。优先级与各生态
+惯例一致:环境变量 `MACOSX_DEPLOYMENT_TARGET`(单次调用的显式覆盖,
+cargo/rustc、cc 等同样尊重该变量)> 本字段(项目默认,类似 SwiftPM 的
+`platforms:`)> 工具链/SDK 默认。该值会进入 BMI 指纹——切换 target 会
+自动重建模块缓存。
+
 C++ 标准不要通过 `build.cxxflags = ["-std=..."]` 配置。请使用:
 
 ```toml

src/build/flags.cppm

@@ -89,6 +89,18 @@ CompileFlags compute_flags(const BuildPlan& plan) {
     // any new branching added to this function.
     auto caps = mcpp::toolchain::capabilities_for(plan.toolchain);
 
+    // macOS minimum supported OS version for produced binaries.
+    // Precedence: MACOSX_DEPLOYMENT_TARGET env (explicit per-invocation
+    // override, the convention cargo/rustc/cc honor) > the manifest's
+    // [build] macos_deployment_target (project default, SwiftPM-style) >
+    // empty (toolchain/SDK default).
+    std::string macosDeploymentTarget;
+    if (const char* dt = std::getenv("MACOSX_DEPLOYMENT_TARGET"); dt && *dt) {
+        macosDeploymentTarget = dt;
+    } else {
+        macosDeploymentTarget = plan.manifest.buildConfig.macosDeploymentTarget;
+    }
+
     f.cxxBinary = plan.toolchain.binaryPath;
     f.ccBinary = mcpp::toolchain::derive_c_compiler(plan.toolchain);
 
@@ -137,20 +149,17 @@ CompileFlags compute_flags(const BuildPlan& plan) {
         auto llvmRoot = plan.toolchain.binaryPath.parent_path().parent_path();
         auto libcxxInclude = llvmRoot / "include" / "c++" / "v1";
         compile_toolchain_flags = " --no-default-config -nostdinc++";
-        // macOS deployment target: make MACOSX_DEPLOYMENT_TARGET explicit
-        // on the command line so (a) the ninja commands don't depend on
-        // env propagation and (b) the value participates in the BMI
+        // macOS deployment target: make the resolved value explicit on
+        // the command line so (a) the ninja commands don't depend on env
+        // propagation and (b) the value participates in the BMI
         // fingerprint via canonical flags — mixing targets in one sandbox
         // otherwise reuses a std.pcm built for a different
         // arm64-apple-macosxNN triple and dies with a config mismatch
         // (observed on macos CI). The link side is added to f.ld below
         // (the macOS link path doesn't consume link_toolchain_flags).
-        if (mcpp::platform::is_macos) {
-            if (const char* dt = std::getenv("MACOSX_DEPLOYMENT_TARGET");
-                dt && *dt) {
-                compile_toolchain_flags +=
-                    std::string(" -mmacosx-version-min=") + dt;
-            }
+        if (mcpp::platform::is_macos && !macosDeploymentTarget.empty()) {
+            compile_toolchain_flags +=
+                " -mmacosx-version-min=" + macosDeploymentTarget;
         }
         llvmRootForStdlib = llvmRoot;
         // libc++ headers
@@ -363,8 +372,8 @@ CompileFlags compute_flags(const BuildPlan& plan) {
             }
         }
         std::string version_min;
-        if (const char* dt = std::getenv("MACOSX_DEPLOYMENT_TARGET"); dt && *dt) {
-            version_min = std::string(" -mmacosx-version-min=") + dt;
+        if (!macosDeploymentTarget.empty()) {
+            version_min = " -mmacosx-version-min=" + macosDeploymentTarget;
         }
         f.ld = std::format("{}{}{} -fuse-ld=lld{}{}{}{}", full_static, static_stdlib,
                            b_flag, version_min, stdlib_link, user_ldflags, link_extra);

src/cli.cppm

@@ -589,13 +589,20 @@ std::string canonical_compile_flags(const mcpp::manifest::Manifest& m) {
     s += " -fmodules";
     // macOS deployment target changes the effective compile triple
     // (arm64-apple-macosxNN) — a std.pcm built for one target cannot be
-    // loaded by a TU compiled for another. Fold it into the fingerprint
-    // so switching MACOSX_DEPLOYMENT_TARGET rebuilds the BMI cache
+    // loaded by a TU compiled for another. Fold the resolved value
+    // (env override > [build] macos_deployment_target manifest default)
+    // into the fingerprint so switching targets rebuilds the BMI cache
     // instead of dying with a module config mismatch.
     if constexpr (mcpp::platform::is_macos) {
+        std::string dtv;
         if (const char* dt = std::getenv("MACOSX_DEPLOYMENT_TARGET"); dt && *dt) {
+            dtv = dt;
+        } else {
+            dtv = m.buildConfig.macosDeploymentTarget;
+        }
+        if (!dtv.empty()) {
             s += " macos_deployment_target=";
-            s += dt;
+            s += dtv;
         }
     }
     if (!m.buildConfig.cStandard.empty()) {

src/manifest.cppm

@@ -104,6 +104,14 @@ struct BuildConfig {
     std::vector<std::string>           cxxflags;
     std::vector<std::string>           ldflags;
     std::string                         cStandard;
+    // macOS minimum supported OS version for produced binaries
+    // (LC_BUILD_VERSION minos), e.g. "11.0". Mirrors the ecosystem
+    // conventions around deployment targets (the MACOSX_DEPLOYMENT_TARGET
+    // env var that cargo/rustc/cc honor; SwiftPM's `platforms:` manifest
+    // field; CMAKE_OSX_DEPLOYMENT_TARGET). Precedence: the env var (an
+    // explicit per-invocation override) wins over this manifest default;
+    // empty + no env = toolchain/SDK default. No effect off macOS.
+    std::string                         macosDeploymentTarget;
     // Resolved build-profile knobs (from [profile.<name>] + built-in defaults).
     std::string                         optLevel = "2";  // -O level
     bool                                debug    = false; // -g
@@ -888,6 +896,8 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
     if (auto v = doc->get_string_array("build.cxxflags")) m.buildConfig.cxxflags = *v;
     if (auto v = doc->get_string_array("build.ldflags"))  m.buildConfig.ldflags  = *v;
     if (auto v = doc->get_string("build.c_standard"))     m.buildConfig.cStandard = *v;
+    if (auto v = doc->get_string("build.macos_deployment_target"))
+        m.buildConfig.macosDeploymentTarget = *v;
     for (auto const& flag : m.buildConfig.cxxflags) {
         if (starts_with_std_flag(flag)) {
             return std::unexpected(error(origin,

tests/unit/test_manifest.cpp

@@ -295,6 +295,34 @@ kind = "lib"
     EXPECT_EQ(m->buildConfig.cStandard, "c11");
 }
 
+TEST(Manifest, BuildMacosDeploymentTarget) {
+    constexpr auto src = R"(
+[package]
+name = "x"
+version = "0.1.0"
+[build]
+macos_deployment_target = "11.0"
+[targets.x]
+kind = "lib"
+)";
+    auto m = mcpp::manifest::parse_string(src);
+    ASSERT_TRUE(m.has_value()) << m.error().format();
+    EXPECT_EQ(m->buildConfig.macosDeploymentTarget, "11.0");
+}
+
+TEST(Manifest, BuildMacosDeploymentTargetDefaultsEmpty) {
+    constexpr auto src = R"(
+[package]
+name = "x"
+version = "0.1.0"
+[targets.x]
+kind = "lib"
+)";
+    auto m = mcpp::manifest::parse_string(src);
+    ASSERT_TRUE(m.has_value()) << m.error().format();
+    EXPECT_TRUE(m->buildConfig.macosDeploymentTarget.empty());
+}
+
 TEST(Manifest, RuntimeConfig) {
     constexpr auto src = R"(
 [package]