feat(port): C++ 运行时不再关心后端是谁 —— macOS 交叉构建打通

⭐⭐ 在 Linux 上,`mcpp build --target aarch64-macos` 现在产出:

  Mach-O 64-bit arm64 executable
  /usr/lib/libSystem.B.dylib          ← 唯一依赖
  _clock_gettime_nsec_np              ← 借的名字,仍然是那两个
  _pthread_create_from_mach_thread
  dyld_stub_binder                    ← 第三个属于格式,不属于本包

带着 import std、容器、算法、异常与展开期析构 —— 全部来自 openkal 生态,
没有一个字节来自 Apple 的 SDK。

## 一个谓词,而不是每个平台一遍

`_LIBCPP_HAS_MUSL_LIBC` 现在是 locale 后端的第一问。⚠️ 第一版写成
「musl **且在 Apple 上**」,第二个目标 Windows 立刻以同样形状失败(`_locale_t`)
—— 收窄到一个平台就意味着每个平台再写一遍。

## 三条搬出了「按目标」的块,因为它们是关于 openkal 的事实

- `_LIBUNWIND_USE_DLADDR=0` —— openkal 在**任何**目标上都没有动态加载器。
  ⚠️ 它原来在 cfg(os="none") 里,macOS 目标于是以 `unknown type name 'Dl_info'`
  重新发现了同一件事。
- `_GNU_SOURCE` —— musl 的非标准名字住在它后面(vasprintf/strtof_l/syscall)。
  同样的搬迁,同样的理由。
- compiler-rt builtins —— ⚠️ 这条**不能**搬成包级:宿主链接里驱动仍然链载荷自己的
  归档,实测重复定义 __muloti4。改为按目标格式各一份,并记下清单表达不了
  「驱动的运行时选择被替换过」这件事。

## 覆盖目录里的新增

`port/include/__thread/support.h` —— libc++abi 的 guard 问 `__APPLE__` 要 Mach 的
线程标识。⚠️ 三个分支里只有第一个不适合 openkal,而它正是命中的那个;第二个
(SYS_gettid)会经 musl 的系统调用垫片走到 kal_task_*,第三个是合法答案。
⚠️ 而它关不掉:_LIBCPP_HAS_THREAD_API_PTHREAD 是我们的,清掉它是为了绕开一个
标识函数而拿掉整个线程层。

`mach-o/dyld.h` 加上卸载钩子 —— 这里没有东西会被卸载。

## Mach-O 的 thread_local 走模拟 TLS

⚠️ `undefined symbol: _tlv_bootstrap`:这个格式经加载器 bootstrap 的描述符访问
thread_local,而这里没有加载器。`-femulated-tls` 让每次访问改走
`__emutls_get_address`。⭐ 机制不是新的 —— 生态设计的实验 A 验证过这条路
(32 项断言 0 failures),而那次也记下了这个 flag 是 LLVM 专有的,
这正是它能写在这里的原因:这个目标的编译器按构造就是 clang。

⚠️ 而 `emutls.c` 要从排除表里拿掉,并且**顺序不决定这件事** —— 列表里任何位置的
排除都压过任何位置的包含。实测:加了包含而排除还在,产物没有那个对象。

Author: speak-agent

mcpp.toml

@@ -149,6 +149,97 @@ include_dirs = [
 # So the freestanding configuration states it, and states the two facilities
 # that environment does not have. Nothing else differs: the C library beneath is
 # the same one.
+# ⚠️ THE COMPILER'S OWN RUNTIME, ON EVERY TARGET WHOSE DRIVER SELECTION WE
+# REPLACED — WHICH IS EVERY CROSS, AND NOT THE HOST.
+#
+# `__udivti3` and its relatives are what the compiler decided to call; no source
+# here mentions them. A native link gets them from the toolchain's own
+# `libclang_rt.builtins`, which the driver adds. A cross does not — the target
+# side comes from this graph — so this package has to supply them.
+#
+# ⚠️ AND IT MUST NOT SUPPLY THEM NATIVELY. Measured 2026-08-23: adding them to
+# the package-wide source list broke the HOST build with duplicate definitions
+# of `__muloti4` and its neighbours, against the archive the driver had already
+# linked. The fact is "the driver's runtime selection was replaced", and the
+# nearest thing a manifest can say today is "this target is not the host of this
+# repository's builds" — stated per format rather than once, which is the cost
+# of the manifest not being able to say it directly.
+[target.'cfg(os = "macos")'.build]
+# ⚠️ AND compiler-rt's emutls, WHICH THE EXCLUSION LIST OTHERWISE DROPS.
+#
+# The package-wide exclusions leave `emutls.c` out because it needs an
+# environment — pthread keys and an allocator. This target has both, from
+# openkal-musl, and `-femulated-tls` below makes every thread-local access call
+# into it. Measured: without it, `undefined symbol: __emutls_get_address`.
+#
+# ⭐ EMULATED THREAD-LOCAL STORAGE, WHICH THIS OBJECT FORMAT NEEDS AND openkal
+# ALREADY VALIDATED.
+#
+# Mach-O reaches a `thread_local` through a descriptor the dynamic loader
+# bootstraps — `_tlv_bootstrap`. There is no dynamic loader here, so the symbol
+# is undefined and the program does not link. `-femulated-tls` makes the
+# compiler route every access through `__emutls_get_address` instead, which is
+# an ordinary function call resolved by compiler-rt against a key the C library
+# owns.
+#
+# ⚠️ Measured 2026-08-23: `undefined symbol: _tlv_bootstrap`, after everything
+# else on this target linked. And the mechanism is not new — the ecosystem
+# design's experiment A validated exactly this route (32 assertions, 0
+# failures); ⚠️ that experiment also recorded that the flag is LLVM-only, which
+# is why it can be stated here at all: this target's compiler is clang by
+# construction.
+cxxflags = ["-femulated-tls"]
+cflags   = ["-femulated-tls"]
+# ⚠️ libc++ carries its OWN copy of the 128-bit multiply-overflow helper, for
+# platforms where compiler-rt is not linked. Supplying compiler-rt's makes them
+# a pair: `duplicate symbol: __muloti4`. The freestanding block never hit it
+# because it excludes the whole filesystem directory for a different reason.
+sources = [
+  "!llvm/libcxx/src/filesystem/int128_builtins.cpp",
+  "llvm/compiler-rt/lib/builtins/*.c",
+  "llvm/compiler-rt/lib/builtins/emutls.c",
+  "!llvm/compiler-rt/lib/builtins/atomic*.c",
+  "!llvm/compiler-rt/lib/builtins/clear_cache.c",
+  # ⚠️ `emutls.c` IS NOT EXCLUDED HERE, AND THE ORDER DOES NOT DECIDE THAT —
+  # AN EXCLUSION ANYWHERE IN A LIST BEATS AN INCLUSION ANYWHERE ELSE IN IT.
+  # Measured: adding the include above while leaving the exclusion below it
+  # produced no object and `undefined symbol: __emutls_get_address`. So the
+  # line is simply absent from this target rather than re-added.
+  "!llvm/compiler-rt/lib/builtins/enable_execute_stack.c",
+  "!llvm/compiler-rt/lib/builtins/eprintf.c",
+  "!llvm/compiler-rt/lib/builtins/gcc_personality_v0.c",
+  "!llvm/compiler-rt/lib/builtins/crtbegin.c",
+  "!llvm/compiler-rt/lib/builtins/crtend.c",
+  # ⚠️ Darwin's own: it asks Apple's SDK which OS version is running, so that a
+  # weakly-linked symbol can be probed. openkal is not that OS, and nothing here
+  # weak-links against it. (`apple_versioning.c` is already outside the
+  # architecture's list; this one is inside it and still Darwin's.)
+  "!llvm/compiler-rt/lib/builtins/os_version_check.c",
+  "!llvm/compiler-rt/lib/builtins/*xf*.c",
+  "!llvm/compiler-rt/lib/builtins/*xc3.c",
+]
+
+[target.'cfg(windows)'.build]
+sources = [
+  "!llvm/libcxx/src/filesystem/int128_builtins.cpp",
+  "llvm/compiler-rt/lib/builtins/*.c",
+  "!llvm/compiler-rt/lib/builtins/atomic*.c",
+  "!llvm/compiler-rt/lib/builtins/clear_cache.c",
+  "!llvm/compiler-rt/lib/builtins/emutls.c",
+  "!llvm/compiler-rt/lib/builtins/enable_execute_stack.c",
+  "!llvm/compiler-rt/lib/builtins/eprintf.c",
+  "!llvm/compiler-rt/lib/builtins/gcc_personality_v0.c",
+  "!llvm/compiler-rt/lib/builtins/crtbegin.c",
+  "!llvm/compiler-rt/lib/builtins/crtend.c",
+  # ⚠️ Darwin's own: it asks Apple's SDK which OS version is running, so that a
+  # weakly-linked symbol can be probed. openkal is not that OS, and nothing here
+  # weak-links against it. (`apple_versioning.c` is already outside the
+  # architecture's list; this one is inside it and still Darwin's.)
+  "!llvm/compiler-rt/lib/builtins/os_version_check.c",
+  "!llvm/compiler-rt/lib/builtins/*xf*.c",
+  "!llvm/compiler-rt/lib/builtins/*xc3.c",
+]
+
 [target.'cfg(not(os = "none"))'.build]
 include_dirs = ["llvm-generated/generic"]
 
@@ -157,12 +248,9 @@ include_dirs = ["llvm-generated/freestanding"]
 # Two switches that a hosted target answers by recognising the system and this
 # one cannot.
 #
-#   the unwinder's use of dladdr --- there is no dynamic loader here, and the
-#   type its interface names does not exist;
-#   _GNU_SOURCE --- libc++abi reaches `syscall' for a thread identity, and musl
-#   declares that name only under this macro. LLVM's own runtimes build defines
-#   it for the same reason; a hosted build here gets it from elsewhere and the
-#   difference was invisible until this target asked.
+#   (dladdr and _GNU_SOURCE moved to the package-wide list above: both are
+#   facts about openkal rather than about this target, and leaving them here
+#   meant every new object format rediscovered them.)
 #   _LIBUNWIND_IS_BAREMETAL — ⭐ the unwinder finds its tables through symbols
 #   the linker script defines rather than through the program headers. Both
 #   routes exist upstream and this target must take the second: the headers are
@@ -176,8 +264,7 @@ include_dirs = ["llvm-generated/freestanding"]
 #   The symbols are `__eh_frame_start` / `__eh_frame_end` (and the `_hdr_`
 #   pair), and AddressSpace.hpp carries the linker script fragment that defines
 #   them. examples/same-source/link.ld is that fragment.
-cxxflags = ["-D_LIBUNWIND_USE_DLADDR=0", "-D_GNU_SOURCE",
-            "-D_LIBUNWIND_IS_BAREMETAL=1"]
+cxxflags = ["-D_LIBUNWIND_IS_BAREMETAL=1"]
 # ⚠️ THE FLAG BELONGS TO THIS PACKAGE AND LANDS ON THE CONSUMER'S LINK.
 #
 # `_LIBUNWIND_IS_BAREMETAL` above makes the unwinder read `__eh_frame_hdr_start`
@@ -225,9 +312,7 @@ ldflags = ["-Wl,--eh-frame-hdr"]
 #   two halves of an initialisation array that a linker script places here.
 sources = [
   "!llvm/libcxx/src/filesystem/*.cpp",
-
   "llvm/compiler-rt/lib/builtins/*.c",
-
   "!llvm/compiler-rt/lib/builtins/atomic*.c",
   "!llvm/compiler-rt/lib/builtins/clear_cache.c",
   "!llvm/compiler-rt/lib/builtins/emutls.c",
@@ -236,9 +321,14 @@ sources = [
   "!llvm/compiler-rt/lib/builtins/gcc_personality_v0.c",
   "!llvm/compiler-rt/lib/builtins/crtbegin.c",
   "!llvm/compiler-rt/lib/builtins/crtend.c",
-
+  # ⚠️ Darwin's own: it asks Apple's SDK which OS version is running, so that a
+  # weakly-linked symbol can be probed. openkal is not that OS, and nothing here
+  # weak-links against it. (`apple_versioning.c` is already outside the
+  # architecture's list; this one is inside it and still Darwin's.)
+  "!llvm/compiler-rt/lib/builtins/os_version_check.c",
   "!llvm/compiler-rt/lib/builtins/*xf*.c",
   "!llvm/compiler-rt/lib/builtins/*xc3.c",
+
   "!llvm/compiler-rt/lib/builtins/*bf*.c",
 ]
 
@@ -251,6 +341,31 @@ cxxflags = [
   # it takes. The C sources had it and the C++ ones did not, which is the kind of
   # split a single flags list does not have.
   "-D_LIBUNWIND_IS_NATIVE_ONLY",
+  # ⭐ NO `dladdr`, ON ANY TARGET — WHICH IS A FACT ABOUT openkal, NOT ABOUT ONE
+  # PLATFORM.
+  #
+  # libunwind uses it to put a FUNCTION NAME on a frame, which is a convenience
+  # for `_Unwind_FindEnclosingFunction` and for printing a backtrace; nothing in
+  # unwinding needs it. It reaches for it whenever the platform "has a dynamic
+  # loader", and decides that by the OS.
+  #
+  # openkal has no dynamic loader on any target: a program built this way is one
+  # image. So the answer is the same everywhere, and it is stated once here
+  # rather than per target — which is what stops the next object format from
+  # rediscovering it. ⚠️ It was in the `cfg(os = "none")` block before, and the
+  # macOS target then failed on `unknown type name 'Dl_info'` — the same fact,
+  # asked again, at a place that had not been told.
+  "-D_LIBUNWIND_USE_DLADDR=0",
+  # ⭐ musl's non-standard names live behind this, and they are not optional for
+  # libc++: the locale backend calls `vasprintf`, `strtof_l`, `strtod_l`,
+  # `strtold_l`, and libc++abi's guard reaches `syscall`. All of them are musl's
+  # to declare, and musl declares them here.
+  #
+  # ⚠️ It was in the `cfg(os = "none")` block, where it happened to be needed
+  # first. Measured on the macOS cross: `no member named 'strtof_l' in the
+  # global namespace`, from a header the freestanding block never applied to.
+  # The fact is about the C LIBRARY, so it is stated once for the package.
+  "-D_GNU_SOURCE",
   "-D_LIBCXXABI_BUILDING_LIBRARY",
   "-D_LIBCPP_DISABLE_VISIBILITY_ANNOTATIONS",
   "-D_LIBCXXABI_DISABLE_VISIBILITY_ANNOTATIONS",

port/include/__thread/support.h

@@ -0,0 +1,54 @@
+// The threading support header, plus the two PLATFORM names libc++abi looks for
+// at this point and that openkal answers differently.
+//
+// ⭐ WHY HERE. `cxa_guard_impl.h` includes this unconditionally and then asks
+//
+//     #if defined(__APPLE__) && _LIBCPP_HAS_THREAD_API_PTHREAD
+//       ... pthread_mach_thread_np(...)  → mach_port_t
+//     #elif defined(SYS_gettid) && _LIBCPP_HAS_THREAD_API_PTHREAD
+//       ... syscall(SYS_gettid)
+//     #else
+//       constexpr uint32_t (*PlatformThreadID)() = nullptr;
+//
+// ⚠️ ALL THREE BRANCHES ARE FINE FOR openkal EXCEPT THE FIRST, WHICH IS THE ONE
+// THAT MATCHES. The second routes through musl's system-call shim, which this
+// ecosystem answers with `kal_task_*`; the third is a legal answer that the
+// guard implementations already handle. The first names Apple's Mach kernel,
+// and there is no Mach here — the platform is `openkal-macos`, and `__APPLE__`
+// is a statement about the OBJECT FORMAT.
+//
+// ⚠️ AND IT CANNOT BE SWITCHED OFF. `_LIBCPP_HAS_THREAD_API_PTHREAD` is ours to
+// set, and clearing it would remove the whole threading layer to route around
+// one identity function. `_LIBCXXABI_USE_FUTEX` selects a different
+// IMPLEMENTATION but does not stop this function from being DEFINED, so it
+// still has to compile.
+//
+// ⇒ So the two names are supplied, as the platform, exactly as
+// `AvailabilityMacros.h` and `mach-o/dyld.h` beside this file are. The rule the
+// overlay follows throughout: replace the PLATFORM, never the library.
+#ifndef OPENKAL_LIBCXX_THREAD_SUPPORT_OVERLAY
+#define OPENKAL_LIBCXX_THREAD_SUPPORT_OVERLAY
+
+#include_next <__thread/support.h>
+
+#if defined(__APPLE__) && !defined(OPENKAL_NO_MACH_SHIM)
+#  include <cstdint>
+#  include <pthread.h>
+
+// Apple's own width, which `cxa_guard_impl.h` static_asserts against.
+typedef std::uint32_t mach_port_t;
+
+// A value that is the same for one execution context and different between two.
+//
+// ⚠️ THAT IS THE WHOLE CONTRACT AT THIS CALL SITE. The identity is used to
+// notice that a guarded initialisation has re-entered itself — it is compared
+// for equality and never for anything else, never published, and never handed
+// to the system. Apple's answer is a Mach port name because Mach is what
+// identifies a thread there; here the descriptor's own address serves, and it
+// is unique for the same reason a descriptor is.
+inline mach_port_t pthread_mach_thread_np(pthread_t __p) {
+    return static_cast<mach_port_t>(reinterpret_cast<std::uintptr_t>(__p));
+}
+#endif
+
+#endif  // OPENKAL_LIBCXX_THREAD_SUPPORT_OVERLAY

port/include/mach-o/dyld.h

@@ -35,6 +35,21 @@ static inline const struct mach_header* _dyld_get_image_header(uint32_t) { retur
 static inline intptr_t _dyld_get_image_vmaddr_slide(uint32_t) { return 0; }
 static inline const char* _dyld_get_image_name(uint32_t) { return 0; }
 
+// ⚠️ AND THE UNLOAD HOOK, WHICH IS WHY THIS FILE IS NOT ONLY ENQUIRIES.
+//
+// libunwind's frame-description cache registers a callback so that entries can
+// be dropped when an image is unloaded. Nothing is ever unloaded here — there
+// is one image and no loader to unload it — so registering is complete when it
+// does nothing, and the callback would never be called even if it were kept.
+//
+// ⭐ Stubbing it here rather than shadowing UnwindCursor.hpp keeps the whole of
+// this package's difference from upstream in headers upstream does not own.
+// The rule the overlay follows: replace the PLATFORM, never the library.
+static inline void _dyld_register_func_for_remove_image(
+    void (*)(const struct mach_header*, intptr_t)) {}
+static inline void _dyld_register_func_for_add_image(
+    void (*)(const struct mach_header*, intptr_t)) {}
+
 #ifdef __cplusplus
 }
 #endif