Add LLVM toolchain support and mirror config

Adds LLVM/Clang toolchain provider support, import std handling, self mirror config, xlings index migration, and bumps release metadata to 0.0.14.

Author: Sunrisepeak

.agents/docs/2026-05-13-llvm-clang-toolchain-support-design.md

@@ -109,6 +109,12 @@ jobs:
           # above so they don't have to reinstall the sandbox.
           export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
           test -x "$MCPP_VENDORED_XLINGS"
+          # GitHub-hosted runners are outside CN; keep CI toolchain downloads on
+          # the global mirror while mcpp's default remains CN for fresh local
+          # sandboxes. E2E tests with their own MCPP_HOME read this variable.
+          export MCPP_E2E_TOOLCHAIN_MIRROR=GLOBAL
+          "$MCPP" self config --mirror "$MCPP_E2E_TOOLCHAIN_MIRROR"
+          "$MCPP" self config
           # Pin the global default so test 28 (which exercises the
           # default-toolchain path) gets a deterministic GNU answer
           # instead of whatever auto-install picks on a fresh sandbox.

.github/workflows/ci.yml

@@ -3,6 +3,27 @@
 > 本文件追踪 `mcpp-community/mcpp` 公开仓的版本演进。
 > 格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [0.0.14] — 2026-05-13
+
+LLVM / Clang 工具链支持与 xlings 镜像配置完善。
+
+### 新增
+
+- ✅ **LLVM / Clang 工具链支持** —— 新增基于 `clang++`、`clang-scan-deps`、
+  `llvm-ar`、`lld` 的工具链探测与构建路径，支持 xlings `llvm` 包提供的
+  自包含 Linux LLVM 工具链。
+- ✅ **`import std` 支持** —— LLVM libc++ 模块标准库可用时，自动发现
+  `std.cppm` / `std.compat.cppm`，并接入标准库 BMI 预构建流程。
+- ✅ **`mcpp self config --mirror`** —— 通过 xlings 抽象层配置 sandbox
+  镜像，默认初始化为 `CN`，CI 可显式切换为 `GLOBAL`。
+
+### 改进
+
+- 🔧 **工具链 provider 拆分** —— 将通用模型、探测逻辑、GCC、Clang、LLVM
+  provider 与 registry 分离到独立模块，为后续更多工具链扩展预留入口。
+- 🔧 **xlings 索引兼容迁移** —— 自动将历史 `mcpp-index` 索引名迁移到
+  `mcpplibs`，避免旧 sandbox 状态影响新流程。
+
 ## [0.0.4] — 2026-05-10
 
 构建 / 环境体验优化三件套。

CHANGELOG.md

@@ -1,6 +1,6 @@
 [package]
 name        = "mcpp"
-version     = "0.0.13"
+version     = "0.0.14"
 description = "Modern C++ build & package management tool"
 license     = "Apache-2.0"
 authors     = ["mcpp-community"]

mcpp.toml

@@ -10,7 +10,8 @@ export module mcpp.build.flags;
 
 import std;
 import mcpp.build.plan;
-import mcpp.xlings;
+import mcpp.toolchain.detect;
+import mcpp.toolchain.registry;
 
 export namespace mcpp::build {
 
@@ -23,6 +24,7 @@ struct CompileFlags {
     std::filesystem::path arBinary;   // ar path (may be empty → use PATH)
     std::string sysroot;              // --sysroot=... (for ninja ldflags)
     std::string bFlag;                // -B<binutils> (for ninja ldflags)
+    std::string toolEnv;              // env prefix for private toolchain executables
     bool staticStdlib = true;
     std::string linkage;  // "static" or ""
 };
@@ -35,23 +37,8 @@ namespace mcpp::build {
 
 namespace {
 
-std::filesystem::path derive_c_compiler(const std::filesystem::path& cxxPath) {
-    auto stem = cxxPath.stem().string();
-    auto parent = cxxPath.parent_path();
-    auto ext = cxxPath.extension();
-
-    // g++ → gcc, clang++ → clang, x86_64-linux-musl-g++ → x86_64-linux-musl-gcc
-    std::string cc_stem;
-    if (stem.ends_with("++")) {
-        cc_stem = stem.substr(0, stem.size() - 2);
-        // g++ → gcc; clang++ → clang
-        if (cc_stem.ends_with("g"))
-            cc_stem += "cc";  // g → gcc
-        // else clang++ → clang (already correct after stripping ++)
-    } else {
-        cc_stem = stem;  // fallback: same as cxx
-    }
-    return parent / (cc_stem + ext.string());
+std::filesystem::path staged_std_bmi_path(const BuildPlan& plan) {
+    return mcpp::toolchain::staged_std_bmi_path(plan.toolchain, plan.outputDir);
 }
 
 // Escape a path for embedding in ninja rule strings.
@@ -72,7 +59,8 @@ std::string escape_path(const std::filesystem::path& p) {
 CompileFlags compute_flags(const BuildPlan& plan) {
     CompileFlags f;
     f.cxxBinary = plan.toolchain.binaryPath;
-    f.ccBinary = derive_c_compiler(plan.toolchain.binaryPath);
+    f.ccBinary = mcpp::toolchain::derive_c_compiler(plan.toolchain);
+    f.toolEnv = mcpp::toolchain::compiler_env_prefix(plan.toolchain);
 
     // PIC?
     bool need_pic = false;
@@ -99,13 +87,13 @@ CompileFlags compute_flags(const BuildPlan& plan) {
     }
 
     // Binutils -B flag
-    bool isMuslTc = plan.toolchain.targetTriple.find("-musl") != std::string::npos;
+    bool isMuslTc = mcpp::toolchain::is_musl_target(plan.toolchain);
+    bool isClang = mcpp::toolchain::is_clang(plan.toolchain);
     std::filesystem::path binutilsBin;
-    if (!isMuslTc) {
-        if (auto ar = mcpp::xlings::paths::find_sibling_binary(
-                plan.toolchain.binaryPath, "binutils", "bin/ar")) {
-            binutilsBin = ar->parent_path();  // bin/ar → bin/
-        }
+    if (!isMuslTc && !isClang) {
+        auto ar = mcpp::toolchain::archive_tool(plan.toolchain);
+        if (!ar.empty())
+            binutilsBin = ar.parent_path();
     }
     std::string b_flag;
     if (!binutilsBin.empty()) {
@@ -114,13 +102,7 @@ CompileFlags compute_flags(const BuildPlan& plan) {
     }
 
     // AR binary
-    if (!binutilsBin.empty()) {
-        f.arBinary = binutilsBin / "ar";
-    } else if (isMuslTc) {
-        auto muslAr = plan.toolchain.binaryPath.parent_path() / "x86_64-linux-musl-ar";
-        if (std::filesystem::exists(muslAr))
-            f.arBinary = muslAr;
-    }
+    f.arBinary = mcpp::toolchain::archive_tool(plan.toolchain);
 
     // Opt level (musl ICE workaround)
     std::string opt_flag = isMuslTc ? " -Og" : " -O2";
@@ -142,17 +124,28 @@ CompileFlags compute_flags(const BuildPlan& plan) {
         plan.manifest.buildConfig.cStandard.empty() ? "c11" : plan.manifest.buildConfig.cStandard;
 
     // Assemble
-    f.cxx = std::format("-std=c++23 -fmodules{}{}{}{}{}{}", opt_flag, pic_flag, sysroot_flag,
-                        b_flag, include_flags, user_cxxflags);
+    std::string module_flag = isClang ? "" : " -fmodules";
+    std::string std_module_flag;
+    if (isClang && !plan.stdBmiPath.empty()) {
+        std_module_flag = " -fmodule-file=std=" + escape_path(staged_std_bmi_path(plan));
+    }
+    f.cxx = std::format("-std=c++23{}{}{}{}{}{}{}{}", module_flag, std_module_flag,
+                        opt_flag, pic_flag, sysroot_flag, b_flag, include_flags, user_cxxflags);
     f.cc = std::format("-std={}{}{}{}{}{}{}", c_std, opt_flag, pic_flag, sysroot_flag, b_flag,
                        include_flags, user_cflags);
 
     // Link flags
     f.staticStdlib = plan.manifest.buildConfig.staticStdlib;
     f.linkage = plan.manifest.buildConfig.linkage;
     std::string full_static = (f.linkage == "static") ? " -static" : "";
-    std::string static_stdlib = f.staticStdlib ? " -static-libstdc++" : "";
-    f.ld = std::format("{}{}{}{}", full_static, static_stdlib, sysroot_flag, b_flag);
+    std::string static_stdlib = (f.staticStdlib && !isClang) ? " -static-libstdc++" : "";
+    std::string runtime_dirs;
+    for (auto& dir : plan.toolchain.linkRuntimeDirs) {
+        runtime_dirs += " -L" + escape_path(dir);
+        runtime_dirs += " -Wl,-rpath," + escape_path(dir);
+    }
+    f.ld = std::format("{}{}{}{}{}", full_static, static_stdlib, sysroot_flag, b_flag,
+                       runtime_dirs);
 
     return f;
 }

src/build/flags.cppm

@@ -23,6 +23,8 @@ import mcpp.build.plan;
 import mcpp.build.flags;
 import mcpp.build.compile_commands;
 import mcpp.dyndep;
+import mcpp.toolchain.detect;
+import mcpp.toolchain.registry;
 import mcpp.xlings;
 
 export namespace mcpp::build {
@@ -67,6 +69,16 @@ std::string escape_ninja_path(const std::filesystem::path& p) {
     return out;
 }
 
+std::string escape_ninja_variable_value(std::string_view s) {
+    std::string out;
+    out.reserve(s.size());
+    for (char c : s) {
+        if (c == '$') out += "$$";
+        else          out.push_back(c);
+    }
+    return out;
+}
+
 void write_file(const std::filesystem::path& p, std::string_view content) {
     std::filesystem::create_directories(p.parent_path());
     std::ofstream os(p);
@@ -107,47 +119,15 @@ std::filesystem::path mcpp_exe_path() {
     return "mcpp";  // fall back to PATH lookup
 }
 
-// Derive a sibling C compiler from a C++ compiler binary path. Used so .c
-// sources can be compiled by the actual C frontend (cc1), not g++ which
-// rejects implicit `void*` conversions and `restrict` etc.
-//   .../bin/g++                       → .../bin/gcc
-//   .../bin/x86_64-linux-musl-g++     → .../bin/x86_64-linux-musl-gcc
-//   .../bin/clang++                   → .../bin/clang
-//   .../bin/c++                       → .../bin/cc
-// If no sibling exists, return "gcc" so PATH lookup is the final fallback
-// (this also keeps unit tests that don't touch a real toolchain happy).
-std::filesystem::path derive_c_compiler(const std::filesystem::path& cxx) {
-    auto fname = cxx.filename().string();
-    auto try_replace = [&](std::string_view from,
-                           std::string_view to) -> std::optional<std::filesystem::path> {
-        auto pos = fname.rfind(from);
-        if (pos == std::string::npos)
-            return std::nullopt;
-        std::string repl = fname;
-        repl.replace(pos, from.size(), to);
-        auto p = cxx.parent_path() / repl;
-        std::error_code ec;
-        if (std::filesystem::exists(p, ec))
-            return p;
-        return std::nullopt;
-    };
-    if (auto p = try_replace("clang++", "clang"))
-        return *p;
-    if (auto p = try_replace("g++", "gcc"))
-        return *p;
-    if (auto p = try_replace("c++", "cc"))
-        return *p;
-    return "gcc";
-}
-
 bool is_c_source(const std::filesystem::path& src) {
     return src.extension() == ".c";
 }
 
 }  // namespace
 
 std::string emit_ninja_string(const BuildPlan& plan) {
-    bool dyndep = dyndep_mode_enabled();
+    bool dyndep = dyndep_mode_enabled()
+               && mcpp::toolchain::is_gcc(plan.toolchain);
     std::string out;
     auto append = [&](std::string s) { out += std::move(s); };
 
@@ -167,6 +147,7 @@ std::string emit_ninja_string(const BuildPlan& plan) {
 
     append(std::format("cxx       = {}\n", escape_ninja_path(flags.cxxBinary)));
     append(std::format("cxxflags  = {}\n", flags.cxx));
+    append(std::format("toolenv   = {}\n", escape_ninja_variable_value(flags.toolEnv)));
     if (need_c_rule) {
         append(std::format("cc        = {}\n", escape_ninja_path(flags.ccBinary)));
         append(std::format("cflags    = {}\n", flags.cc));
@@ -208,7 +189,7 @@ std::string emit_ninja_string(const BuildPlan& plan) {
            "if [ -n \"$bmi_out\" ] && [ -f \"$bmi_out\" ]; then "
              "cp -p \"$bmi_out\" \"$bmi_out.bak\"; "
            "fi && "
-           "$cxx $cxxflags -c $in -o $out && "
+           "$toolenv $cxx $cxxflags -c $in -o $out && "
            "if [ -n \"$bmi_out\" ] && [ -f \"$bmi_out.bak\" ] && "
               "cmp -s \"$bmi_out\" \"$bmi_out.bak\"; then "
              "mv \"$bmi_out.bak\" \"$bmi_out\"; "
@@ -221,38 +202,38 @@ std::string emit_ninja_string(const BuildPlan& plan) {
     append("\n");
 
     append("rule cxx_object\n");
-    append("  command = $cxx $cxxflags -c $in -o $out\n");
+    append("  command = $toolenv $cxx $cxxflags -c $in -o $out\n");
     append("  description = OBJ $out\n");
     if (dyndep)
         append("  restat = 1\n");
     append("\n");
 
     if (need_c_rule) {
         append("rule c_object\n");
-        append("  command = $cc $cflags -c $in -o $out\n");
+        append("  command = $toolenv $cc $cflags -c $in -o $out\n");
         append("  description = CC $out\n");
         if (dyndep)
             append("  restat = 1\n");
         append("\n");
     }
 
     append("rule cxx_link\n");
-    append("  command = $cxx $in -o $out $ldflags\n");
+    append("  command = $toolenv $cxx $in -o $out $ldflags\n");
     append("  description = LINK $out\n\n");
 
     append("rule cxx_archive\n");
-    append("  command = $ar rcs $out $in\n");
+    append("  command = $toolenv $ar rcs $out $in\n");
     append("  description = AR $out\n\n");
 
     append("rule cxx_shared\n");
-    append("  command = $cxx -shared $in -o $out $ldflags\n");
+    append("  command = $toolenv $cxx -shared $in -o $out $ldflags\n");
     append("  description = SHARED $out\n\n");
 
     if (dyndep) {
         // Scan rule: produce P1689 .ddi for one TU.
         // -E -M -MM -MF gives us the dep file; -fdeps-* gives us the .ddi.
         append("rule cxx_scan\n");
-        append("  command = $cxx $cxxflags -fdeps-format=p1689r5 "
+        append("  command = $toolenv $cxx $cxxflags -fdeps-format=p1689r5 "
                "-fdeps-file=$out -fdeps-target=$compile_target "
                "-M -MM -MF $out.dep -E $in -o $compile_target\n");
         append("  description = SCAN $out\n\n");
@@ -264,14 +245,17 @@ std::string emit_ninja_string(const BuildPlan& plan) {
         append("  restat = 1\n\n");
     }
 
-    // Stage prebuilt std artifacts into our gcm.cache/
-    auto std_bmi_dst = std::filesystem::path("gcm.cache") / "std.gcm";
+    // Stage prebuilt std artifacts into the compiler-specific BMI cache.
+    auto std_bmi_dst = mcpp::toolchain::staged_std_bmi_path(plan.toolchain, {});
     auto std_o_dst = std::filesystem::path("obj") / "std.o";
 
-    append(std::format("build {} : cp_bmi {}\n", escape_ninja_path(std_bmi_dst),
-                       escape_ninja_path(plan.stdBmiPath)));
-    append(std::format("build {} : cp_bmi {}\n\n", escape_ninja_path(std_o_dst),
-                       escape_ninja_path(plan.stdObjectPath)));
+    bool has_std_artifacts = !plan.stdBmiPath.empty() && !plan.stdObjectPath.empty();
+    if (has_std_artifacts) {
+        append(std::format("build {} : cp_bmi {}\n", escape_ninja_path(std_bmi_dst),
+                           escape_ninja_path(plan.stdBmiPath)));
+        append(std::format("build {} : cp_bmi {}\n\n", escape_ninja_path(std_o_dst),
+                           escape_ninja_path(plan.stdObjectPath)));
+    }
 
     auto bmi_path = [](std::string_view name) {
         std::string s = "gcm.cache/";
@@ -366,7 +350,8 @@ std::string emit_ninja_string(const BuildPlan& plan) {
             if (rule != "c_object") {
                 for (auto& imp : cu.imports) {
                     if (imp == "std" || imp == "std.compat") {
-                        implicit += " gcm.cache/std.gcm";
+                        if (has_std_artifacts)
+                            implicit += " " + escape_ninja_path(std_bmi_dst);
                         continue;
                     }
                     implicit += " " + bmi_path(imp);
@@ -397,14 +382,16 @@ std::string emit_ninja_string(const BuildPlan& plan) {
         switch (lu.kind) {
             case LinkUnit::Binary:
             case LinkUnit::TestBinary:
-                ins += " " + escape_ninja_path(std_o_dst);
+                if (has_std_artifacts)
+                    ins += " " + escape_ninja_path(std_o_dst);
                 rule = "cxx_link";
                 break;
             case LinkUnit::StaticLibrary:
                 rule = "cxx_archive";
                 break;
             case LinkUnit::SharedLibrary:
-                ins += " " + escape_ninja_path(std_o_dst);
+                if (has_std_artifacts)
+                    ins += " " + escape_ninja_path(std_o_dst);
                 rule = "cxx_shared";
                 break;
         }