feat(port): 差异放一个目录 —— libc++ 按 OS 宏选后端,而 openkal 按「配置的是哪个 C 库」

⭐ 形态先说:`port/include` 是**覆盖目录**,不是对 vendored 树的修改。
openkal-musl 的 `port/` 把与上游 musl 的每一处差异收在一个目录里、靠 include
顺序遮蔽它;这里是 libc++ 的同一套安排 —— vendored 树与上游逐字节相同,
`git diff` 对一份新 checkout 为空,而全部差异就是 port/include 下的这几个文件。

## locale 后端

upstream 的选择链问的是「这是哪个操作系统」,并在每个答案上假定那个系统的 C 库:

    #if defined(__APPLE__)    → support/apple.h
    #elif defined(__linux__)  → support/linux.h

这在 libc++ 正常被构建的每个地方都成立,因为 OS 和它的 C 库是一起来的。

⚠️ 在这里它们不是一起来的。openkal 的安排是 C 库是一个**包**,而下面的平台是一个
48 个函数的接口的实现。为 Apple 目标格式构建的程序定义了 `__APPLE__`,因为那是
关于**格式和 ABI** 的陈述 —— 而底下是 musl。upstream 的第一问于是对着错的问题
给出了正确答案:

    bsd_like.h:203: no member named 'asprintf_l' in the global namespace

⚠️ 这条**不能**用 `__config_site` 表达,而那是先试的:libc++ 那条链是写死的
`#if defined(__APPLE__)`,没有覆盖点;唯一相关的旋钮 `_LIBCPP_HAS_LOCALIZATION 0`
是**整个去掉 `<locale>`**,不是换后端。砍掉一个能用的设施去绕过一个口味问题,
比遮蔽一个头文件更差。

## 三个 Apple SDK 桩

libunwind 与 libc++ 的源码在 `__APPLE__` 下 include Apple SDK 的头。整棵树里
一共 5 处、4 个头 —— 数出来的,不是估的。桩里只有**被读到**的那些名字,和
openkal-macos 那份只有两个名字的 `libSystem.tbd` 同一种做法。

⚠️ `mach-o/dyld.h` 不是编译期的桩:refstring 与 UnwindCursor 在**运行期**调它。
openkal 没有动态加载器,一个这样构建的程序就是一个镜像,没有东西可枚举 —— 所以
诚实的答案是零个镜像,而两个调用者本来就处理这个情况。⚠️ 答零个和让符号未定义
不是一回事:后者是一个从没想要加载器的程序链接失败在 Apple 的加载器上。

## std.compat

`[package] std-compat-module`:提供一个模块的包提供两个。理由见 mcpp#486。

⚠️ 未完成:libc++abi 的 guard 实现(`mach_port_t` / `syscall`)与 libc++ 的
locale 后端(`vasprintf` / `strtof_l`)各自按平台宏选实现,而「Mach-O 上的 musl」
两份都不是。CI 不跑这条,所以没有回归面。

Author: speak-agent

mcpp.toml

@@ -25,6 +25,16 @@ provides = ["hosted-standard-library"]
 # knows nothing about, and its configuration is in llvm-generated/ rather than
 # beside the compiler.
 std-module = "llvm-generated/std.cppm"
+# ⚠️ AND THE COMPAT MODULE, BECAUSE IT IS THE SAME LIBRARY.
+#
+# `std.compat` re-exports the C library's names into the global namespace over
+# the SAME libc++. Naming only the first leaves the second resolving to the
+# toolchain's copy, and the two are then a mixed pair — which does not fail
+# where they are chosen but inside the toolchain's headers, against a
+# configuration never generated for this target:
+#
+#   …/share/libc++/v1/std.compat.cppm → __config:13 '__config_site' not found
+std-compat-module = "llvm-generated/std.compat.cppm"
 std-module-flags = [
   # ⚠️ --no-default-config, and it is not tidiness.
   #
@@ -106,6 +116,13 @@ sources = [
 # build if it reaches a <ctype.h> that is not its own. The generated
 # configuration precedes both, because every header of the library includes it.
 include_dirs = [
+  # ⭐ THE OVERLAY, FIRST. Every difference from vendored libc++ lives in one
+  # directory that shadows it, exactly as openkal-musl's `port/` shadows
+  # vendored musl — so the vendored tree stays byte-identical to upstream and
+  # `git diff` against a fresh checkout of it is empty. port/include's own
+  # headers say what each one is for and why it could not be a `__config_site`
+  # switch instead.
+  "port/include",
   "llvm/libcxx/include",
   "llvm/libcxx/src",
   "llvm/libcxxabi/include",

port/include/Availability.h

@@ -0,0 +1,6 @@
+// See AvailabilityMacros.h beside this file. Same header, Apple's newer
+// spelling; libunwind includes whichever it finds first.
+#ifndef OPENKAL_AVAILABILITY_H
+#define OPENKAL_AVAILABILITY_H
+#include <AvailabilityMacros.h>
+#endif

port/include/AvailabilityMacros.h

@@ -0,0 +1,29 @@
+// A stub for a header openkal has no reason to have, providing exactly the one
+// macro that is read.
+//
+// ⭐ THE SAME MOVE AS openkal-macos's `libSystem.tbd`, WHICH IS TWO NAMES.
+//
+// libunwind's public header asks how old a deployment target may be before its
+// entry points become unavailable, and it asks Apple's SDK. There is no Apple
+// SDK here: the platform is `openkal-macos`, an implementation of a
+// 48-function interface, and the object format is Mach-O because that is what
+// the machine loads — those are two different statements, and upstream reads
+// the second as the first.
+//
+// The whole of what is read is below. It was obtained by grepping the vendored
+// runtimes for every `AVAILABLE_*` / `__OSX_AVAILABLE*` / `__IPHONE_*` name, not
+// by copying Apple's header, so a name that appears here appears because
+// something asks for it.
+//
+//     libunwind.h:  AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER
+//
+// ⚠️ EMPTY IS THE ANSWER, NOT A PLACEHOLDER. The macro's job upstream is to
+// attach an availability attribute, which describes when a symbol appeared in
+// Apple's shipping libSystem. Nothing here comes from Apple's libSystem, so
+// there is no version at which it appeared and nothing to attach.
+#ifndef OPENKAL_AVAILABILITY_MACROS_H
+#define OPENKAL_AVAILABILITY_MACROS_H
+
+#define AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER /* always available here */
+
+#endif

port/include/__locale_dir/locale_base_api.h

@@ -0,0 +1,64 @@
+// ⭐⭐ libc++ 的平台后端按 OS 宏选,而 openkal 的答案按「配置的是哪个 C 库」。
+//
+// THE OVERLAY, NOT AN EDIT. openkal-musl's `port/` carries every difference
+// from vendored musl in one directory that shadows it on the include path, and
+// this is that arrangement for libc++ — the vendored tree stays byte-identical
+// to upstream, and the whole of the difference is this file.
+//
+// WHAT UPSTREAM DOES, AND WHY IT IS RIGHT EVERYWHERE ELSE
+//
+// `__locale_dir/locale_base_api.h` selects a backend by asking which operating
+// system this is, and on each answer it assumes that system's C library:
+//
+//     #if defined(__APPLE__)      → support/apple.h
+//     #elif defined(__linux__)    → support/linux.h
+//     …
+//
+// That holds wherever libc++ is normally built, because the OS and its C
+// library travel together.
+//
+// WHY THEY DO NOT TRAVEL TOGETHER HERE
+//
+// openkal's arrangement is that the C library is a PACKAGE — openkal-musl — and
+// the platform beneath it is an implementation of a 48-function interface. A
+// program for Apple's object format built this way has `__APPLE__` defined,
+// because that is a statement about the FORMAT and the ABI, and has musl
+// underneath it. Upstream's first question then gets the right answer to the
+// wrong question:
+//
+//     bsd_like.h:203: no member named 'asprintf_l' in the global namespace
+//
+// — Apple's locale extensions, which musl does not have and never claimed to.
+//
+// ⚠️ WHY THIS IS NOT EXPRESSIBLE AS A `__config_site` SWITCH, WHICH WAS TRIED
+// FIRST. `__config_site` is where this package states every other decision
+// (which C library, whether there is a filesystem, whether there is a random
+// device), and it is the right place for anything libc++ offers a knob for.
+// libc++ offers none here: the chain is a fixed `#if defined(__APPLE__)` with
+// no override, and the only related knob — `_LIBCPP_HAS_LOCALIZATION 0` —
+// removes `<locale>` entirely rather than choosing a different backend.
+// Removing a working facility to route around a question of taste is a worse
+// trade than shadowing one header.
+//
+// ⇒ `_LIBCPP_HAS_MUSL_LIBC` comes from this package's own `__config_site`, so
+// it is a CONFIGURED FACT rather than a guess, and it is asked first. The
+// backend it selects is the one a musl build already uses on the other object
+// format — nothing new is written, the existing answer is merely reachable.
+//
+// Measured 2026-08-23: with this in place, libc++'s `std` module precompiles
+// for `arm64-apple-macos14.0` on a Linux host.
+#ifndef OPENKAL_LIBCXX_LOCALE_BASE_API_OVERLAY
+#define OPENKAL_LIBCXX_LOCALE_BASE_API_OVERLAY
+
+#include <__config>
+
+#if _LIBCPP_HAS_LOCALIZATION && _LIBCPP_HAS_MUSL_LIBC && defined(__APPLE__)
+// The one case upstream's chain answers wrongly for this configuration. Every
+// other target — including musl on ELF, where `__linux__` is defined and the
+// chain already reaches the same header — falls through to upstream below.
+#  include <__locale_dir/support/linux.h>
+#else
+#  include_next <__locale_dir/locale_base_api.h>
+#endif
+
+#endif  // OPENKAL_LIBCXX_LOCALE_BASE_API_OVERLAY

port/include/mach-o/dyld.h

@@ -0,0 +1,42 @@
+// The dynamic loader's enquiry interface — declared, and answering that there
+// is nothing loaded.
+//
+// ⚠️ THIS ONE IS NOT A COMPILE-TIME STUB. Two places call these at RUN time:
+//
+//   libcxx/src/include/refstring.h   — asks whether a string literal lies in a
+//                                      read-only segment, so that a copy can be
+//                                      skipped;
+//   libunwind/src/UnwindCursor.hpp   — asks which image a program counter is
+//                                      in, for the compact-unwind path.
+//
+// openkal has no dynamic loader. A program built this way is one image, loaded
+// by whatever started it, and there is nothing to enumerate — so the honest
+// answer is zero images, and both callers already handle it: refstring falls
+// back to copying, and the unwinder falls back to the DWARF tables it is
+// configured to use here anyway.
+//
+// ⚠️ Answering zero is NOT the same as leaving the symbols undefined. Undefined
+// would be a link error naming Apple's loader in a program that never wanted
+// one; zero is the state of a program that is not dynamically loaded, and it is
+// true rather than a simulation.
+#ifndef OPENKAL_MACH_O_DYLD_H
+#define OPENKAL_MACH_O_DYLD_H
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+struct mach_header;
+
+static inline uint32_t _dyld_image_count(void) { return 0; }
+static inline const struct mach_header* _dyld_get_image_header(uint32_t) { return 0; }
+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; }
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif