mcpplibs
diff --git a/‎.github/workflows/ci.yml‎
Lines changed: 121 additions & 0 deletions b/‎.github/workflows/ci.yml‎
Lines changed: 121 additions & 0 deletions
diff --git a/‎build.mcpp‎
Lines changed: 93 additions & 0 deletions b/‎build.mcpp‎
Lines changed: 93 additions & 0 deletions
diff --git a/‎examples/cross-hello/mcpp.toml‎
Lines changed: 21 additions & 0 deletions b/‎examples/cross-hello/mcpp.toml‎
Lines changed: 21 additions & 0 deletions
diff --git a/‎examples/cross-hello/src/main.c‎
Lines changed: 70 additions & 0 deletions b/‎examples/cross-hello/src/main.c‎
Lines changed: 70 additions & 0 deletions
@@ -152,6 +152,31 @@ jobs:
           grep -qE '^-- failures: 0 --$' run.log
           ! grep -q '^FAIL:' run.log
 
+      - name: The same program, built the ordinary way, as a control
+        run: |
+          # ⚠️ THIS STEP EXISTS BECAUSE IT ALREADY EARNED ITS PLACE.
+          #
+          # The cross-built copy failed on a machine of the other system, and the
+          # obvious reading was a defect in this port or in the way it was
+          # cross-built. A native build of the SAME source reproduced it here ---
+          # which said it was neither, and the defect was in the program's own
+          # assertion macro, which evaluated its condition twice and so closed a
+          # stream that was already closed.
+          #
+          # Two failures that look alike are told apart by building the same
+          # source two ways, and that is cheap enough to do every time.
+          # ⚠️ The target has to be named here as it is everywhere else in this
+          # job: one system needs it, and a step that omitted it built for that
+          # system's other toolchain and failed at the link with names kernel32
+          # supplies. Measured, on the first run of this step.
+          extra=''
+          [ -n '${{ matrix.target }}' ] && extra='--target ${{ matrix.target }}'
+          cd examples/cross-hello
+          mcpp build $extra
+          binary="$(find target -type f \( -name 'cross-hello' -o -name 'cross-hello.exe' \) | head -1)"
+          "./$binary" 2>&1 | tee out.log
+          grep -q -- '-- failures: 0 --' out.log
+
       - name: The counts agree with the system's own
         working-directory: examples/wordcount
         run: |
@@ -171,3 +196,99 @@ jobs:
 
           # The variable was consulted, and the interval was measured.
           grep -q 'elapsed .* nanoseconds' run.log
+
+  # ---------------------------------------------------------------------------
+  # The measurement musl/PATCHES.md records, made from a machine that is not the
+  # system it is about.
+  #
+  # It is a job rather than a note because the claim it supports --- that a
+  # program for that system can be built, and linked, without any file that
+  # system supplies --- is one that a change to this port could silently undo.
+  # The two numbers it asserts are zero indirect symbols and exactly two names.
+  cross-macos:
+    name: cross-link for the other system, from this one
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: The implementation for that system
+        run: |
+          branch='${{ github.head_ref || github.ref_name }}'
+          git clone --quiet https://github.com/mcpplibs/openkal-macos.git ../openkal-macos
+          git -C ../openkal-macos checkout --quiet "origin/$branch" 2>/dev/null || true
+          git clone --quiet https://github.com/mcpplibs/openkal.git ../openkal
+          git -C ../openkal checkout --quiet "origin/$branch" 2>/dev/null || true
+
+      - name: Install LLVM
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y -qq clang lld llvm
+          # ld64.lld is the Mach-O driver of the same binary; Ubuntu's package
+          # installs it under a version suffix and without the plain name.
+          v=$(ls /usr/lib/llvm-*/bin/ld64.lld 2>/dev/null | sort -V | tail -1)
+          test -n "$v" || { echo "::error::this image has no ld64.lld"; exit 1; }
+          d=$(dirname "$v")
+          echo "LD64=$v" >> "$GITHUB_ENV"
+          # The tools are installed under a version suffix and the probe asks for
+          # them by their plain names, so the directory that has both spellings
+          # is named rather than assumed.
+          echo "NM=$d/llvm-nm" >> "$GITHUB_ENV"
+          echo "$d" >> "$GITHUB_PATH"
+          "$d/llvm-nm" --version | head -1
+          clang --version | head -1
+
+      - name: Zero indirect symbols, and two names
+        run: |
+          bash tools/probe-cross-macos.sh aarch64
+          bash tools/probe-cross-macos.sh x86_64
+
+      # ⚠️ LINKING IS NOT RUNNING, AND THIS IS WHERE THAT IS ADMITTED.
+      #
+      # Everything above happens on a machine that is not the system in
+      # question, and everything above is about the objects and the link. Whether
+      # the result STARTS is a different question, and it cannot be asked here:
+      # that system's 64-bit ARM variant refuses to start an image that is not
+      # signed, and the signature can only be made on a machine of that system.
+      #
+      # So the artifact is carried there. The job that receives it is the only
+      # place in this workflow where the claim becomes "a program built here
+      # runs there" rather than "a program built here links".
+      - name: A program for that system, built here
+        run: |
+          bash tools/cross-build-macos.sh aarch64 examples/cross-hello/src/main.c cross-hello-arm64
+          file cross-hello-arm64
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: cross-hello-arm64
+          path: cross-hello-arm64
+          retention-days: 1
+
+  # ---------------------------------------------------------------------------
+  # The other half of the claim, on a machine of that system.
+  cross-macos-run:
+    name: what was cross-built starts, on that system
+    needs: cross-macos
+    runs-on: macos-14
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: cross-hello-arm64
+
+      - name: Sign it, because this system will not start it otherwise
+        run: |
+          chmod +x cross-hello-arm64
+          # Ad hoc: the identity is `-', which asserts nothing about who made
+          # the program and is exactly what this system requires before it will
+          # start one on this architecture. A program that is distributed needs
+          # more; a program that is checked needs this.
+          codesign -s - --force cross-hello-arm64
+          codesign -dv cross-hello-arm64 2>&1 | head -3
+
+      - name: It starts, and the C library beneath it came up
+        run: |
+          ./cross-hello-arm64 | tee run.log
+          grep -q -- '-- failures: 0 --' run.log
@@ -0,0 +1,93 @@
+import mcpp;
+import std;
+
+// ⭐⭐ THE COMPILER'S OWN RUNTIME, NAMED ONLY WHEN IT HAS THAT NAME.
+//
+// A compiler emits calls to routines no C library defines — a 128-bit shift, a
+// stack probe, a complex multiply on `long double`. They live in `libgcc.a`
+// under GCC and in compiler-rt under clang, and the two are not
+// interchangeable names for one file: `-lgcc` on a clang link is a library that
+// does not exist.
+//
+// ⚠️ THE MANIFEST CANNOT SAY THIS, WHICH IS WHY THERE IS A PROGRAM. A
+// `[target.'cfg(windows)']` block describes the TARGET, and this is a question
+// about the toolchain that resolved. Both measurements arrived on 2026-08-22
+// from the same missing distinction:
+//
+//   naming it unconditionally    lld: error: unable to find library -lgcc
+//                                (a clean runner, clang, cross to PE)
+//   naming it never              undefined reference to `___chkstk_ms'
+//                                undefined reference to `__mulxc3'
+//                                (a Windows runner, GCC, no C++ runtime in the
+//                                 graph to supply compiler-rt instead)
+//
+// Each was the correct behaviour for the other configuration.
+//
+// ⚠️ PE ONLY, AND `gcc_eh` WITH IT. On this format a thread-local variable is
+// reached through a helper rather than through an address the processor
+// supplies, and that helper is in the second archive rather than the first.
+// Where the graph brings `openkal-llvm-runtime`, compiler-rt's `emutls.c` is
+// the same answer and neither archive is consulted.
+//
+// ⚠️ NOT ON ELF OR Mach-O. There the driver still links the compiler's runtime
+// even under `-nostdlib`, or the graph supplies it; adding a name here would be
+// a second source for something that already has one.
+
+// ⭐⭐ WHICH COMPILER FAMILY RESOLVED — AND WHAT AN ABSENT ANSWER MEANS.
+//
+// ⚠️ READ FROM THE ENVIRONMENT, NOT THROUGH A HELPER. A build program is
+// compiled against the `mcpp` module of whichever tool RUNS it, so naming a
+// helper newer than the released tool makes this package require an unreleased
+// one. Measured 2026-08-22, on every row of three repositories at once:
+//
+//     build.mcpp: error: no member named 'compiler' in namespace 'mcpp'
+//     build.mcpp: error: 'toolchain_dir' is not a member of 'mcpp'
+//
+// — and the second is the more useful of the two, because `toolchain_dir` was
+// the FALLBACK written for the first. The environment variables are the
+// contract and `std::getenv` reads them on every version.
+//
+// ⚠️ AND AN ABSENT VALUE IS NOT "NO COMPILER". Measured against mcpp 2026.8.19.1,
+// which is what CI installs: `MCPP_TARGET_OS`, `MCPP_HOST`, `MCPP_OUT_DIR`,
+// `MCPP_MANIFEST_DIR`, `MCPP_TARGET` and `MCPP_TARGET_ARCH` are all set, and
+// `MCPP_COMPILER` and `MCPP_TOOLCHAIN_DIR` are absent.
+//
+// ⭐ So absent means "a build tool from before the question could be asked" —
+// and such a tool cannot produce the configuration the answer would change. The
+// clang-over-openkal cross to PE arrives on the same release as the variable.
+// The one configuration a tool that predates it can produce is the GCC one, so
+// that is what absent is answered with, and it is a deduction rather than a
+// default.
+std::string compiler_family() {
+    if (const char* v = std::getenv("MCPP_COMPILER"); v && *v) return v;
+    return "gcc";
+}
+
+std::string env_or_empty(const char* name) {
+    const char* v = std::getenv(name);
+    return v ? v : "";
+}
+
+int main() {
+    const std::string os  = env_or_empty("MCPP_TARGET_OS");
+    const std::string fam = compiler_family();
+
+    if (fam != "gcc") return 0;
+
+    // ⚠️ ELF NEEDS IT TOO, AND FOR THE SAME REASON THE PE BLOCK DID. The Linux
+    // block of the manifest named `-lgcc` unconditionally, and that resolved on
+    // a Linux host because a payload with it happens to be installed there.
+    // Measured 2026-08-23, a macOS host cross-building for `x86_64-linux-gnu`:
+    //
+    //     ld.lld: error: unable to find library -lgcc
+    //
+    // ⇒ Under clang the answer is compiler-rt, which `openkal-llvm-runtime`
+    // builds for this target as it already did for the other three.
+    if (os == "linux") {
+        mcpp::link_lib("gcc");
+    } else if (os == "windows") {
+        mcpp::link_lib("gcc");
+        mcpp::link_lib("gcc_eh");
+    }
+    return 0;
+}
@@ -0,0 +1,21 @@
+# The same program, built the ordinary way.
+#
+# It exists as a control. The cross-built copy of this source is carried to a
+# machine of that system and run there; if it fails, the failure is either in
+# the port or in the way it was cross-built, and those are different things. A
+# native build of the same source on the same machine separates them --- which
+# is the step that, on the first failure of the C++ runtime, turned a day of
+# guessing into four measurements.
+[package]
+name    = "cross-hello"
+version = "0.1.0"
+
+[dependencies]
+openkal-musl = { path = "../.." }
+
+[targets.cross-hello]
+kind = "bin"
+main = "src/main.c"
+
+[build]
+cxx_runtime = "host-coupled"
@@ -0,0 +1,70 @@
+/* A program built on one system and started on another.
+ *
+ * It is deliberately not a "hello": what it prints has to be something the
+ * machine that runs it can check, and what is worth checking is that the C
+ * library came up --- that streams work, that the environment was received,
+ * that allocation works. A program that printed a constant would prove only
+ * that control reached its first statement. */
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+int main(int argc, char** argv)
+{
+	/* ⚠️ UNBUFFERED, AND THAT IS PART OF THE PROBE.
+	 *
+	 * Output to a pipe is fully buffered, so a program that dies part way
+	 * through loses everything it had printed --- and what the machine that
+	 * runs this reports is then not where the program got to. Measured: one run
+	 * showed a single line and stopped, and the line it showed was not the last
+	 * one it had executed. A probe whose report is buffered is a probe that
+	 * lies about where it stopped. */
+	setvbuf(stdout, NULL, _IONBF, 0);
+
+	int failures = 0;
+	/* ⚠️ THE CONDITION IS EVALUATED ONCE, AND THE FIRST VERSION DID NOT.
+	 *
+	 * It read `(ok) ? "ok" : "FAIL"' and then `if (!(ok))', so an argument with
+	 * an effect happened twice --- and one of the arguments below is
+	 * `fclose(f) == 0'. The second close was of a stream already closed, and
+	 * the program died at the NEXT fopen with a segmentation fault.
+	 *
+	 * It was measured on a machine of the other system first, where it looked
+	 * like a defect in this port, and it reproduced on this one --- which is
+	 * what said it was not. A probe that has an effect in its own condition is
+	 * a probe that tests itself as well as its subject. */
+	#define check(ok, what) do { \
+		const int okm_ok_ = !!(ok); \
+		printf("%s: %s\n", okm_ok_ ? "ok" : "FAIL", what); \
+		if (!okm_ok_) ++failures; } while (0)
+
+	check(argc >= 1 && argv[0] != NULL, "the program received its own name");
+
+	char* p = malloc(4096);
+	check(p != NULL, "an allocation succeeds");
+	if (p) { memset(p, 0x5a, 4096); check(p[4095] == 0x5a, "the whole of it is writable"); free(p); }
+
+	FILE* f = fopen("cross-hello.tmp", "w");
+	check(f != NULL, "a file is created");
+	if (f) {
+		check(fprintf(f, "%d", 12345) == 5, "it is written to");
+		check(fclose(f) == 0, "it closes");
+		f = fopen("cross-hello.tmp", "r");
+		check(f != NULL, "it opens again for reading");
+		if (f) {
+			/* Split, because a single assertion over three operations names
+			 * none of them when it fails --- which is what the first version
+			 * of this program did, on a machine this one cannot run. */
+			int v = 0;
+			int n = fscanf(f, "%d", &v);
+			printf("   (fscanf returned %d, value %d)\n", n, v);
+			check(n == 1, "a formatted read succeeds");
+			check(v == 12345, "it reads back what was written");
+			fclose(f);
+		}
+		remove("cross-hello.tmp");
+	}
+
+	printf("-- failures: %d --\n", failures);
+	return failures != 0;
+}