@@ -0,0 +1,167 @@
+# 依赖库归档链接（dependency `lib` → static archive）设计方案
+
+> mcpp 0.0.63 → 0.0.64 — 修复 `mcpp test` 的 `duplicate symbol: main`,并把
+> 「依赖库」从「散对象内联」升级为「静态归档按需链接」。
+>
+> 关联：[2026-06-25-cdb-test-coverage-design.md](2026-06-25-cdb-test-coverage-design.md)
+>（同一轮 test 体验修复链的第三环）。
+>
+> **状态：设计定稿，进入实施。** 实施进度见 §8（动态更新）。
+
+## 1. 问题
+
+含 `[dev-dependencies] gtest` 的项目，若测试文件自带 `int main()`（脚手架默认模板
+就是），`mcpp test` 链接失败：
+
+```
+ld.lld: error: duplicate symbol: main
+>>> obj/test_smoke.o:(main)         ← 测试自己的 main()
+>>> obj/gtest_main.o:(.text+0x0)    ← gtest_main.cc 自带的 main()
+```
+
+测试二进制同时链接了测试自身的 `main` 与 gtest 的 `gtest_main.o`（也含 `main`）。
+
+需优雅支持的**交叉组合**（用户尽量无感）：
+
+| 用 gtest? | 自带 main? | 期望 |
+|---|---|---|
+| 否 | 是 | 链接测试自己的 main（今天 fresh 项目即此，正常）|
+| 是 | 是（调用 `InitGoogleTest`/`RUN_ALL_TESTS`）| 用测试的 main，**不要** gtest_main |
+| 是 | 否（只写 `TEST(...)`）| 用 gtest_main 提供的 main |
+| 否 | 否 | 无入口——**清晰报错**，非崩溃 |
+
+## 2. 根因
+
+`compat.gtest` 描述符（`mcpplibs/mcpp-index/pkgs/c/compat.gtest.lua`）**已声明**：
+
+```lua
+mcpp = {
+    sources = { "*/googletest/src/gtest-all.cc", "*/googletest/src/gtest_main.cc" },
+    targets = { ["gtest"] = { kind = "lib" } },   -- 已建模为「库」
+}
+```
+
+mcpp 的 manifest 解析器也**已支持** `kind="lib"` → `Target::Library`
+（`manifest.cppm:637`）。**但 mcpp 的依赖链接模型没有兑现它**：
+
+- `plan.cppm` 的 link-unit 循环只为**根包**的 `[targets.*]` 建 LinkUnit；
+- 依赖包（含 dev-dep）的对象通过 `append_package_objects` / compileUnit 循环
+  **直接内联**进消费者二进制（`plan.cppm:486–575`）；
+- 于是 `gtest-all.o`、`gtest_main.o` 作为**散对象**被无条件灌入测试二进制 →
+  `gtest_main.o` 的 `main` 与测试自身 `main` 冲突。
+
+**这不是 gtest 的缺陷,也不是描述符的缺陷,而是 mcpp 核心 link 模型的缺口。**
+
+## 3. 架构决策：修复归属（回答「改 mcpp-index 还是 mcpp」）
+
+| 候选 | 评价 |
+|---|---|
+| ❌ mcpp 里给 gtest 加特判（跳过 gtest_main.o） | 把第三方库名硬编进构建核心,污染架构,未来每个框架都要再特判。否决。 |
+| ❌ 改 gtest 描述符拆出 `gtest_main` 单独目标 | 描述符**已**声明 `kind="lib"`,够用;拆分增加每个库包的作者负担,且仍需 mcpp 支持「按归档链接」。非必要。 |
+| ✅ **mcpp 核心:兑现依赖的 `kind="lib"` → 建静态归档 `.a` → 按归档链接** | 通用、由**既有**描述符元数据驱动、零 gtest 特例、未来框架自动适配。**采用。** |
+
+**职责分层(干净):**
+- **描述符(mcpp-index)**:声明「我是什么」——`kind="lib"`。gtest 已声明,**不改**。
+- **mcpp 核心**:实现「怎么链」——依赖的 lib 包 → 归档 → 按归档链接。**通用 HOW。**
+
+**未来演进**:mcpplibs 生态测试框架 / mcpp 原生测试框架,只要在各自描述符里声明
+`kind="lib"`(并可选地提供一个含 `main` 的入口对象),就**自动**获得「带 main 用
+自己的、不带 main 用框架的」正确行为,mcpp 无需任何该框架的知识。
+
+## 4. 核心设计：依赖库 → 静态归档 → 条件链接
+
+### 4.1 原理（标准链接器语义）
+静态归档 `.a` 的成员对象**仅在其提供的符号当前未定义时**才被拉入。于是单个
+`libgtest.a = { gtest-all.o, gtest_main.o }` 即同时正确处理「带/不带 main」：
+
+- 测试自带 `main` → 链接器处理归档时 `main` 已定义 → **不拉** `gtest_main.o`;
+  测试引用的 gtest 符号 → 拉 `gtest-all.o`。✓
+- 测试不带 `main` → `main` 未定义 → 拉 `gtest_main.o`(它提供 main + 调
+  `RUN_ALL_TESTS`)+ `gtest-all.o`。✓
+- 测试自带 main 且**不用** gtest(但 gtest 是 dev-dep)→ 归档**零贡献**(无未定义
+  符号引用它)→ 不再撞 main。✓(今天的失败用例)
+- 测试不带 main 且不用框架 → 无入口 → 链接器报 undefined `main`。mcpp 捕获并给出
+  清晰提示(见 §6)。✓
+
+> 单归档即可,**无需**把 gtest_main 拆成独立 target——归档的「按成员对象解析」已
+> 天然实现条件链接。
+
+### 4.2 BuildPlan 变更（`plan.cppm`）
+对每个 `kind="lib"` 的**依赖**包(非根包),由其**非模块**实现对象(`.cc/.cpp/.c`)
+合成一个 `StaticLibrary` LinkUnit → 产 `lib<pkg>.a`:
+
+- 新增 LinkUnit:`{ kind=StaticLibrary, output="lib<mangled-pkg>.a", objects=<dep 的非模块对象> }`。
+- 消费者(Binary/TestBinary/SharedLibrary)**不再内联**该 dep 的非模块对象,改为:
+  - 把 `lib<pkg>.a` 路径追加到**链接命令、对象之后**(符号解析顺序正确);
+  - 把 `.a` 加入 `implicitInputs`(ninja 重建追踪)。
+- **模块对象(`.cppm` 的 `.o`)仍直接内联**:它们承载模块全局初始化、且从不提供
+  `main`,放进归档可能因「无未定义符号引用」被丢弃 → 破坏全局初始化。故模块对象
+  不归档(mcpplibs.cmdline 等纯模块依赖 → 无非模块对象 → 无归档 → **行为不变**)。
+
+### 4.3 链接顺序与 ninja（`ninja_backend.cppm`）
+- 当前链接行:`build <out> : cxx_link <objects> | <implicitInputs>`。`implicitInputs`
+  在 `|` 之后是 ninja 的**order-only/隐式依赖,不进命令行**。归档要真正参与链接,
+  其路径必须进**命令行、且在对象之后**。
+- 方案:LinkUnit 新增 `std::vector<std::filesystem::path> archiveInputs`;ninja 发射
+  时把它们拼在 `objects`(及 std.o)**之后**、作为命令行实参,同时也加入 `| implicit`
+  做重建追踪。
+
+### 4.4 复用既有基建
+mcpp 已有 `cxx_archive` 规则(`ninja_backend.cppm:378`)、`archive_tool`(ar/llvm-ar,
+`flags.cppm:253`)、`StaticLibrary` LinkUnit。本设计复用之,无需新工具。
+
+## 5. 不破坏既有行为(回归边界)
+- **纯模块依赖**(mcpplibs.cmdline,`.cppm`)→ 无非模块对象 → 不生成归档 →
+  链接与今天**逐字节一致**。
+- **根包自身**对象 → 不归档(它就是要被链接的主体)。
+- **shared 依赖**(SharedLibrary)→ 走既有 `append_direct_shared_deps`,不变。
+- 仅「依赖包含有非模块实现对象且 `kind=lib`」(gtest、未来 C/C++ 库)行为改变:
+  由内联改为归档链接——这正是修复点。
+
+## 6. 边界用例
+- **无 main 且无框架的测试**:链接报 undefined `main`。mcpp 捕获 lld/ld 的该错误,
+  转成可读提示:`test '<name>' 无入口:请写 int main(),或依赖一个提供 main 的测试
+  框架(如 gtest,不写 main 时由 gtest_main 提供)`。(P2,可后续增强;P0 至少不崩。)
+- **多个 lib 依赖**:每个一个 `.a`,按依赖顺序排在对象之后;若库间有相互依赖,
+  保持拓扑序(已有 `directPackageDeps` 拓扑信息可复用)。
+- **静态库目标的根包**(`mcpp build` 产 `.a`)→ 不受影响(那是根包 target,非依赖)。
+
+## 7. 验证策略(TDD)
+- **单元**(`tests/unit/test_ninja_backend.cpp` / 新增):给定一个 `kind=lib` 依赖 +
+  含非模块对象的 plan,断言:(a)生成 `StaticLibrary` LinkUnit;(b)消费者链接行含
+  该 `.a` 且**位于对象之后**;(c)纯模块依赖**不**生成归档。
+- **e2e**(新增 `78_test_main_combinations.sh`,三平台):一个含 `gtest` dev-dep 的
+  项目,覆盖四种交叉组合各一个 `tests/*.cpp`,断言 `mcpp test` 全绿:
+  1. 自带 main + 用 gtest;2. 不带 main + 用 gtest(TEST 宏);3. 自带 main + 不用
+  gtest;4.(可选)无 main 无框架 → 期望清晰错误。
+- **回归**:既有 15/16/17(test pass/fail/no-tests)、18(devdeps isolation)、
+  31(transitive deps)、07/08(static/shared lib)必须仍绿。
+
+## 8. 实施计划(动态更新)
+
+- [x] **P1 plan 模型**:`LinkUnit` 加 `archiveInputs`;为 `kind=lib` 依赖合成
+  `StaticLibrary` LinkUnit(`lib<pkg>.a`);消费者改为引用 `.a` 而非内联其非模块对象。
+  (`plan.cppm`:staticDep 检测 + 消费者排除内联 + `archiveInputs` 注入)
+- [x] **P2 ninja 发射**:链接行把 `archiveInputs` 经 `$in` 排在对象之后(既上命令行又
+  被 ninja 依赖追踪)。(`ninja_backend.cppm`)
+- [x] **P3 单元测试**:`NinjaBackend.ArchiveInputsLinkedAfterObjects`(归档在对象后);
+  全量 24 单测绿。
+- [x] **P4 e2e**:`78_test_main_combinations.sh` 四组合 `mcpp test` 全绿 + 断言生成
+  `cxx_archive`。本机验证:3 passed;`build libcompat_gtest.a : cxx_archive
+  obj/gtest_main.o obj/gtest-all.o`,测试链接行 `…objects… libcompat_gtest.a`。
+- [x] **P5 回归**:24 单测 + e2e 15/16/17/18/31/07/08 全绿。
+- [x] **P6 版本 + 文档**:bump 0.0.63→0.0.64;CHANGELOG;本文件勾选。
+- [ ] **P7 发布闭环**:PR → CI 全平台 → squash --admin 合入 → tag v0.0.64 →
+  release → 镜像 xlings-res(gh+gtc,4 平台)→ xim-pkgindex mcpp.lua bump(PR)→
+  索引产物自动发布 → `xlings install mcpp@0.0.64` 验证 → bootstrap pin bump。
+  （mcpp-index/gtest 描述符**不改** → 无需重发 mcpp-index。）
+
+## 9. 决策备注
+1. **由既有元数据驱动,而非新增特例**:`kind="lib"` 早在描述符里;本设计只是让
+   mcpp 兑现它。符合「约定优于配置 / 用户无感」。
+2. **单归档 + 链接器语义** 已覆盖全部 main 交叉组合,无需拆 `gtest_main`、无需让
+   用户选链接哪个目标——最大化「无感」。
+3. **模块对象不归档** 是关键安全边界:避免全局初始化被归档式丢弃,且让纯模块依赖
+   零回归。
+4. **面向未来框架**:任何测试框架在其描述符声明 `kind="lib"` 即自动获得正确入口
+   语义;mcpp 永不需要认识具体框架。
@@ -3,6 +3,26 @@
 > 本文件追踪 `mcpp-community/mcpp` 公开仓的版本演进。
 > 格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [0.0.64] — 2026-06-25
+
+### 修复
+
+- **`mcpp test` 在自带 `main()` 的测试 + gtest dev-dep 下 `duplicate symbol: main`**:
+  gtest 的 `gtest_main.cc` 自带 `main()`,而 mcpp 此前把依赖的**全部对象内联**进每个
+  测试二进制,于是测试自己的 `main()` 与 `gtest_main.o` 撞符号。修复:**兑现依赖
+  描述符里已声明的 `kind="lib"`**——把这类依赖编译成静态归档 `lib<pkg>.a`,链接在
+  测试对象**之后**;标准归档语义只在符号未定义时拉成员,故 `gtest_main.o` 的 `main`
+  只在测试不自带 `main` 时才被拉入。`{自带/框架 main} × {用/不用 gtest}` 全部组合
+  皆正确,用户无感。纯模块依赖(如 mcpplibs.cmdline,无非模块对象)行为不变。
+  这是**通用** link-model 改进、由既有描述符 `kind` 驱动,**无 gtest 特例**,未来
+  测试框架声明 `kind="lib"` 即自动适配。详见
+  `.agents/docs/2026-06-25-dependency-archive-linking-design.md`。
+
+### 测试
+
+- 新增单测 `NinjaBackend.ArchiveInputsLinkedAfterObjects`(归档须排在对象之后)与
+  跨平台 e2e `78_test_main_combinations.sh`(四种 main×gtest 组合 `mcpp test` 全绿)。
+
 ## [0.0.63] — 2026-06-25
 
 ### 修复
 
@@ -1,6 +1,6 @@
 [package]
 name        = "mcpp"
-version     = "0.0.63"
+version     = "0.0.64"
 description = "Modern C++ build & package management tool"
 license     = "Apache-2.0"
 authors     = ["mcpp-community"]
 
@@ -629,6 +629,14 @@ std::string emit_ninja_string(const BuildPlan& plan) {
                 rule = "cxx_shared";
                 break;
         }
+        // Dependency static archives (kind="lib" deps, e.g. gtest): linked
+        // AFTER the objects so the linker pulls members (e.g. gtest_main.o's
+        // own main) only when a symbol is still undefined. Explicit inputs →
+        // placed on the command line via $in AND dep-tracked for relink.
+        for (auto& a : lu.archiveInputs) {
+            ins += " " + escape_ninja_path(a);
+        }
+
         std::string implicit;
         for (auto& input : lu.implicitInputs) {
             implicit += " " + escape_ninja_path(input);
 
@@ -30,6 +30,7 @@ struct LinkUnit {
     std::string                     targetName;
     enum Kind { Binary, StaticLibrary, SharedLibrary, TestBinary } kind = Binary;
     std::vector<std::filesystem::path> objects;        // relative to plan.outputDir
+    std::vector<std::filesystem::path> archiveInputs;  // dep static libs (.a), linked AFTER objects
     std::vector<std::filesystem::path> implicitInputs; // relative to plan.outputDir
     std::vector<std::string>        linkFlags;          // per-link edge flags
     std::filesystem::path           output;            // relative to plan.outputDir
@@ -380,6 +381,50 @@ BuildPlan make_plan(const mcpp::manifest::Manifest&         manifest,
         }
     }
 
+    // Static-library dependencies (kind="lib", e.g. gtest): build a per-package
+    // archive lib<pkg>.a from the package's non-module objects and link it into
+    // consumers AFTER their own objects. Standard archive semantics then pull
+    // only the members a symbol still needs — notably gtest_main.o's own main()
+    // is pulled ONLY when the consumer test defines none — which fixes
+    // "duplicate symbol: main" across the {own-main, framework-main} ×
+    // {uses-framework, doesn't} combinations. Module (.cppm) objects are NOT
+    // archived: they carry global init and must always be linked directly.
+    // Driven purely by the dependency's declared `kind` — no per-framework
+    // special-casing, so a future test framework just declares kind="lib".
+    struct StaticDepArchive {
+        std::string           packageName;   // qualified
+        std::filesystem::path output;        // lib<pkg>.a, relative to outputDir
+    };
+    std::vector<StaticDepArchive> staticDepArchives;
+    std::set<std::string> staticDepPackages;   // qualified names linked via .a
+    for (std::size_t i = 1; i < packages.size(); ++i) {
+        auto const& p = packages[i];
+        auto qname = qualified_package_name(p.manifest);
+        if (sharedDepPackages.contains(qname)) continue;   // shared takes precedence
+        bool isLib = false;
+        for (auto const& t : p.manifest.targets) {
+            if (t.kind == mcpp::manifest::Target::Library) { isLib = true; break; }
+        }
+        if (!isLib) continue;
+        std::vector<std::filesystem::path> archiveObjs;
+        for (auto& cu : plan.compileUnits) {
+            if (cu.packageName != qname) continue;
+            if (cu.source.extension() == ".cppm") continue;          // modules stay loose
+            if (!is_implementation_source(cu.source)) continue;
+            if (entryFilesAcrossTargets.contains(cu.source)) continue;
+            archiveObjs.push_back(cu.object);
+        }
+        if (archiveObjs.empty()) continue;   // header-only / pure-module lib → nothing to archive
+        LinkUnit ar;
+        ar.targetName = qname;
+        ar.kind       = LinkUnit::StaticLibrary;
+        ar.output     = std::filesystem::path("lib" + sanitize(qname) + ".a");
+        ar.objects    = std::move(archiveObjs);
+        staticDepPackages.insert(qname);
+        staticDepArchives.push_back({qname, ar.output});
+        plan.linkUnits.push_back(std::move(ar));
+    }
+
     std::map<std::size_t, std::vector<std::size_t>> directPackageDeps;
     for (std::size_t i = 0; i < packages.size(); ++i) {
         for (auto const& [depName, spec] : packages[i].manifest.dependencies) {
@@ -568,6 +613,7 @@ BuildPlan make_plan(const mcpp::manifest::Manifest&         manifest,
         // is exclusive to that binary).
         for (auto& cu : plan.compileUnits) {
             if (sharedDepPackages.contains(cu.packageName)) continue;
+            if (staticDepPackages.contains(cu.packageName)) continue;    // archived → linked as .a
             if (!is_implementation_source(cu.source)) continue;
             if (lu.entryMain && cu.source == *lu.entryMain) continue;     // own entry: already added above
             if (entryFilesAcrossTargets.contains(cu.source)) continue;     // foreign entry: skip
@@ -577,6 +623,12 @@ BuildPlan make_plan(const mcpp::manifest::Manifest&         manifest,
         if (lu.kind == LinkUnit::Binary || lu.kind == LinkUnit::TestBinary
             || lu.kind == LinkUnit::SharedLibrary) {
             append_shared_deps_for_linked_objects(lu);
+            // Link each kind="lib" dependency archive AFTER this unit's objects.
+            // Harmless when unused: archive members are pulled on demand, so a
+            // binary that references no symbols from the lib pulls nothing.
+            for (auto const& sa : staticDepArchives) {
+                lu.archiveInputs.push_back(sa.output);
+            }
         }
 
         plan.linkUnits.push_back(std::move(lu));
 
@@ -18,7 +18,7 @@ import mcpp.toolchain.detect;
 
 export namespace mcpp::toolchain {
 
-inline constexpr std::string_view MCPP_VERSION = "0.0.63";
+inline constexpr std::string_view MCPP_VERSION = "0.0.64";
 
 struct FingerprintInputs {
     Toolchain                       toolchain;
 
@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# requires:
+# 78_test_main_combinations.sh — `mcpp test` must handle every combination of
+# {test defines its own main, test relies on the framework's main} ×
+# {test uses gtest, test doesn't} when gtest is a dev-dependency.
+#
+# Regression for `ld.lld: duplicate symbol: main`: gtest's gtest_main.cc carries
+# its own main(), and mcpp used to inline ALL of a dev-dep's objects into every
+# test binary — so a test that defined its own main() collided with gtest_main.
+# The fix links kind="lib" dependencies as a static archive (lib<pkg>.a) placed
+# AFTER the test's objects, so the linker pulls gtest_main.o ONLY when main is
+# still undefined. Driven by the dep's declared kind — no gtest special-casing.
+#
+# No `requires:` capability → runs on all three CI platforms (mirrors 15/16/17).
+set -e
+
+TMP=$(mktemp -d)
+trap "rm -rf $TMP" EXIT
+
+cd "$TMP"
+"$MCPP" new combo > /dev/null
+cd combo
+
+cat >> mcpp.toml <<'EOF'
+
+[dev-dependencies]
+gtest = "1.15.2"
+EOF
+
+rm -f tests/test_smoke.cpp
+
+# (1) own main + uses gtest → gtest_main.o must NOT be pulled (no dup main)
+cat > tests/t_own_main_gtest.cpp <<'EOF'
+#include <gtest/gtest.h>
+import std;
+TEST(A, ok) { EXPECT_EQ(1 + 1, 2); }
+int main(int argc, char** argv) {
+    ::testing::InitGoogleTest(&argc, argv);
+    return RUN_ALL_TESTS();
+}
+EOF
+
+# (2) no main + uses gtest macros → gtest_main.o provides main
+cat > tests/t_framework_main.cpp <<'EOF'
+#include <gtest/gtest.h>
+TEST(B, ok) { EXPECT_TRUE(true); }
+EOF
+
+# (3) own main + does NOT use gtest (but gtest is still a dev-dep) → archive
+#     contributes nothing; previously this collided with gtest_main's main.
+cat > tests/t_own_main_no_gtest.cpp <<'EOF'
+import std;
+int main() { std::println("ok"); return 0; }
+EOF
+
+out=$("$MCPP" test 2>&1) || { echo "FAIL: mcpp test exited non-zero"; echo "$out"; exit 1; }
+
+for t in t_own_main_gtest t_framework_main t_own_main_no_gtest; do
+    echo "$out" | grep -q "$t ... ok" || { echo "FAIL: $t did not pass"; echo "$out"; exit 1; }
+done
+echo "$out" | grep -q '3 passed; 0 failed' || { echo "FAIL: summary mismatch"; echo "$out"; exit 1; }
+
+# The dev-dep must be linked as an archive, not inlined object-by-object.
+nj=$(find target -name build.ninja | head -1)
+grep -q 'cxx_archive' "$nj" || { echo "FAIL: no static archive built for kind=lib dep"; exit 1; }
+
+echo "OK"