fix(build,toolchain): make the llvm-musl path actually reach the target

Four defects the first end-to-end run surfaced, all found by building a
module TU against the llvm-musl-libcxx payload:

- pin override: the target vocabulary pin silently replaced --toolchain
  (it arrives via the env side channel, which the pin guard never read),
  so `--toolchain llvm --target x86_64-linux-musl` resolved gcc. The
  flag now blocks the pin on its own, regardless of target origin.
- triple propagation: the target-triple correction was scoped to
  freestanding only, but llvm-on-musl is the same one-binary case — the
  clang frontend's -dumpmachine answers with the host while the build
  targets musl, leaving the output dir, cache key and flags on the host
  triple (E1 for a hosted target). Freestanding-only side effects
  (hasImportStd off, the picolibc sysroot lookup) stay scoped.
- std module over the wrong libc: the std precompile used the shared
  host-flags producer (host libc++ headers + glibc), which fails on the
  payload's std.cppm with __config_site / bits/alltypes.h not found.
  llvm-musl now builds the std BMI from the payload headers over the
  musl-gcc sysroot (both payload naming shapes, with the xim- prefix).
- payload C runtime leak: the clangWithCfg PayloadFirst link flags name
  the HOST's glibc, whose loader became a static binary's PT_INTERP.
  Excluded for llvm-musl; its branch already assembles the target C
  runtime (musl sysroot, crt via --gcc-toolchain).

Verified end to end: mcpp build --toolchain llvm@22.1.8 --target
x86_64-linux-musl on a hello-module project produces a fully static
x86_64 musl ELF (no PT_INTERP, not a dynamic executable) that runs.
Unit suite 91 passed; the 1 test_elf_runtime failure is the known
environmental one (host /lib64/libtinfo.so.6 symlink chain), unchanged.

Refs #491

Author: yspbwx2010

src/build/flags.cppm

@@ -1183,7 +1183,12 @@ CompileFlags compute_flags(const BuildPlan& plan) {
     // but the link line has a hard 128KiB ceiling (MAX_ARG_STRLEN) that real
     // workspaces already spend 43% of.
     std::string payload_ld;
-    if (isClangWithCfg
+    // llvm-musl excluded: the clangWithCfg PayloadFirst flags here name the
+    // HOST's glibc (its loader ends up as a static binary's PT_INTERP), while
+    // the isLlvmMusl branch above already assembled the target's complete C
+    // runtime (musl sysroot + crt via --gcc-toolchain).
+    if (!isLlvmMusl
+     && isClangWithCfg
      && lm.mode == mcpp::toolchain::CLibMode::PayloadFirst)
         payload_ld = lm.link_flags(ninjaEsc);
     // GCC: replace the payload's patched `*link:` with the pristine one, so

src/build/prepare.cppm

@@ -1253,9 +1253,11 @@ prepare_build(bool print_fingerprint,
     // costs nobody anything and needs no coordination.
     //
     // It counts as user-explicit, so mcpp will not quietly revise it.
+    bool toolchainFromFlag = false;
     if (const char* tcEnv = std::getenv("MCPP_TOOLCHAIN"); tcEnv && *tcEnv) {
         tcSpec   = std::string(tcEnv);
         tcOrigin = TcOrigin::ManifestToolchain;
+        toolchainFromFlag = true;
     }
     if (!tcSpec.has_value()) {
         auto cfg = get_cfg();
@@ -1436,8 +1438,17 @@ prepare_build(bool print_fingerprint,
         // which is exactly the promise the fallback is built on ("mcpp
         // revises its own defaults, never yours"). A target the user asked
         // for (--target, or [build] target) still wins, as it always has.
+        // `hasToolchainOverride` above covers the manifest's [target.X]
+        // section. `--toolchain` must stop the pin on its own, regardless of
+        // where the target came from: the flag form of the promise
+        // `pinWouldOverruleUser` keeps for remembered targets ("mcpp revises
+        // its own defaults, never yours") — measured, `--toolchain llvm
+        // --target x86_64-linux-musl` used to resolve gcc@16.1.0 because the
+        // musl row's pin silently replaced the flag.
         const bool pinWouldOverruleUser =
-            targetFromGlobalDefault && tc_origin_is_user_explicit(tcOrigin);
+            toolchainFromFlag
+            || (targetFromGlobalDefault
+                && tc_origin_is_user_explicit(tcOrigin));
         if (known && !hasToolchainOverride && !known->pin.empty()
             && !pinWouldOverruleUser) {
             tcSpec = std::string(known->pin);
@@ -1823,15 +1834,22 @@ prepare_build(bool print_fingerprint,
     // `tc.targetTriple`, so correcting it here corrects all of them at once —
     // which is the point of there being one field rather than five answers.
     //
-    // ⚠️ Scoped to freestanding on purpose. The hosted cross targets already
-    // resolve a per-target binary, and overwriting their probed triple would
-    // replace a measured fact with an assumed one for no gain.
+    // ⚠️ Scoped to freestanding AND the llvm-musl family on purpose. The
+    // other hosted cross targets already resolve a per-target binary, and
+    // overwriting their probed triple would replace a measured fact with an
+    // assumed one for no gain. llvm-musl is the same one-binary case as
+    // freestanding: the clang frontend's -dumpmachine answers with the host
+    // while the build targets musl, so without this the output dir, cache key
+    // and flag layer all stay on the host triple (E1 for a hosted target).
     if (!overrides.target_triple.empty()) {
-        if (auto want = mcpp::toolchain::triple::parse(overrides.target_triple);
-            want && want->is_freestanding())
+        auto want = mcpp::toolchain::triple::parse(overrides.target_triple);
+        const bool llvmMuslTarget = want && want->is_musl()
+            && mcpp::toolchain::is_clang(*tc);
+        if (want && (want->is_freestanding() || llvmMuslTarget))
         {
             tc->targetTriple = want->str();
 
+            if (want->is_freestanding()) {
             // `import std` is structurally hosted, and turning it off is the
             // SAME fact as the line above, not a second policy: libc++'s
             // std.cppm is one module over the whole library, including the
@@ -1852,9 +1870,14 @@ prepare_build(bool print_fingerprint,
             tc->hasImportStd = false;
             tc->stdModuleSource.clear();
             tc->stdCompatSource.clear();
+            }
 
             // ── The target's C library, resolved like its compiler ─────────
             //
+            // (freestanding only: the C library column names picolibc, whose
+            // payload layout a freestanding spec describes. llvm-musl resolves
+            // its libc++ one block below instead.)
+            if (want->is_freestanding())
             // The row in kKnownTargets names it, exactly as it names the
             // toolchain pin, and it is installed through the same channel a
             // project's `[xlings] deps` use (see the materialization above).

src/toolchain/stdmod.cppm

@@ -34,12 +34,14 @@ import std;
 import mcpp.home;
 import mcpp.libs.json;
 import mcpp.platform;
+import mcpp.platform.xlings;
 import mcpp.toolchain.clang;
 import mcpp.toolchain.detect;
 import mcpp.toolchain.fingerprint;
 import mcpp.toolchain.gcc;
 import mcpp.toolchain.hostflags;
 import mcpp.toolchain.linkmodel;
+import mcpp.toolchain.model;
 import mcpp.toolchain.msvc;
 
 export namespace mcpp::toolchain {
@@ -249,8 +251,46 @@ std::expected<StdModule, StdModError> ensure_built(
     HostFlagOptions hopt;
     hopt.cfgBypass = HostFlagOptions::CfgBypass::Always;
     hopt.clangStdlibSelect = true;
-    std::string sysroot_flag =
+    std::string sysroot_flag;
+    // llvm-musl: the shared producer reconstructs the HOST's header world,
+    // which is wrong for the target whose std.cppm this is — the failure is
+    // the freestanding doc's `__config_site not found` one layer up. The
+    // target's musl libc++ headers and C library come from the payload
+    // prepare resolved (targetSysroot*) plus the musl-gcc sysroot.
+    if (is_clang(tc) && is_musl_target(tc)
+        && !tc.targetSysrootInclude.empty())
+    {
+        // The musl C headers come from the musl-gcc payload's sysroot; the
+        // frontend locates it the same way the link side does (a
+        // triple-named sibling of the llvm payload under xpkgs).
+        auto xpkgs = mcpp::xlings::paths::xpkgs_from_compiler(tc.binaryPath);
+        std::string sysroot;
+        if (xpkgs) {
+            // Two payload shapes, matching the registry's naming: the
+            // triple-named cross package and the host-native musl-gcc one
+            // (whose sysroot still lives under <triple>/).
+            const std::string shapes[] = {
+                std::format("xim-x-{}-gcc", tc.targetTriple), "xim-x-musl-gcc"};
+            for (auto const& shape : shapes) {
+                auto gccRoot = *xpkgs / shape;
+                std::error_code ec;
+                if (!std::filesystem::is_directory(gccRoot, ec)) continue;
+                for (auto& e : std::filesystem::directory_iterator(gccRoot, ec))
+                    if (e.is_directory()) {
+                        sysroot = (e.path() / tc.targetTriple).string();
+                        break;
+                    }
+                if (!sysroot.empty()) break;
+            }
+        }
+        sysroot_flag = std::format(
+            " --no-default-config --target={} -nostdinc++ -stdlib=libc++"
+            " --sysroot={} -isystem'{}'",
+            tc.targetTriple, sysroot, tc.targetSysrootInclude.string());
+    } else {
+    sysroot_flag =
         render_tokens(host_compile_tokens(tc, hopt, shellEsc));
+    }
 
     // Deployment target appended here rather than passed to the producer
     // ONLY to keep this command string byte-identical to what earlier