feat(dist-apple): the closure's dylibs in the framework directory, the link-time rpath, ad-hoc signing, the app runner and --format dmg (mcpp#634)

The dylibs the engine stages beside a Mach-O program (2026.9.14.2+),
named by the stage manifest's `needs` lines, are copied into
Contents/Frameworks/ (Frameworks/ on iOS) and kept out of the resource
directory. generate() adds -Wl,-rpath,@executable_path/../Frameworks on
macOS and @executable_path/Frameworks on iOS through mcpp::link_flag, on
every pass, because the link happens before the pass that learns
--format; no load command is edited after the link. A macOS bundle
without an identity is signed ad hoc, frameworks first and the bundle
second; the iOS device row signs only with an identity and the simulator
row never. An incomplete closure is a warning naming the unresolved
libraries, and every refusal is a mcpp::warning.

On macOS the member supplies the runner named `app` (macapp-run) and
declares xim:macapp-run 0.1.0 with when = "run". --format dmg stages the
bundle beside an Applications link and runs hdiutil create -format UDZO;
it is refused on iOS.

tests/app-framework-consumer: a program whose dependency is shared and
which exits 7. check-apple-plan.sh passes locally against the new member
and fails against 0.9.3 ("no framework step for the staged dylib");
check-apple-bundle.sh is the macOS half (load command, codesign --verify
--deep --strict, the program with and without its framework, mcpp run
--format app with and without --runner app, hdiutil verify and attach).

Author: Sunrisepeak

dist/apple.cppm

@@ -391,9 +391,18 @@ implies           = ["surface"]
 [target.windows.feature-xlings.dist-wix]
 "xim:wix" = "5.0.2"
 
-# `dist-apple` declares no payload for `codesign`: it is part of Xcode, which is
-# not redistributable, so the member locates it and says where it looked. The
-# open-source `rcodesign` is the package that would replace that lookup.
+# `dist-apple` declares no payload for `codesign`, `ditto` or `hdiutil`: they are
+# part of macOS and Xcode, which are not redistributable, so the member runs the
+# system's. The open-source `rcodesign` is the package that would replace the
+# `codesign` lookup.
+#
+# THE RUNNER IS A PAYLOAD, AND ONLY `mcpp run` NEEDS IT. `mcpp run --format app`
+# on macOS reaches the bundle through the runner named `app` this member
+# supplies, `macapp-run`, which executes the bundle's executable in the
+# foreground so that its output and exit status are the program's. `when =
+# "run"` keeps a build or a pack from installing it.
+[target.'cfg(os = "macos")'.feature-xlings.dist-apple]
+"xim:macapp-run" = { version = "0.1.0", when = "run" }
 
 # ── The environment `dist-apk` needs ───────────────────────────────────────
 #

mcpp.toml

@@ -0,0 +1,13 @@
+// No `identity`: the bundle is signed ad hoc on macOS, and the fixture
+// declares no runner, so `mcpp run --format app` reaches the bundle through the
+// runner `dist-apple` supplies.
+import std;
+import mcpp;
+import mcpp.dist.apple;
+
+int main() {
+    mcpp::dist::apple::options opt;
+    opt.target   = "app-framework-consumer";
+    opt.app_name = "AppFrameworkConsumer";
+    return mcpp::dist::apple::generate(opt) ? 0 : 1;
+}

tests/app-framework-consumer/build.mcpp

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# dist-apple on macOS, measured on the bundle and the image (mcpp#634, B1 to B3).
+#
+# The plan-level half is `check-apple-plan.sh`; this half needs the tools only
+# a Mac has (`otool`, `codesign`, `hdiutil`) and runs the program.
+#
+#   1. The program is linked with the rpath `@executable_path/../Frameworks`,
+#      as written: the engine anchors no rpath that begins with a loader token
+#      (mcpp 2026.9.14.2+), and the member adds it through `mcpp::link_flag`.
+#   2. The bundle carries the dependency's dylib in `Contents/Frameworks/` and
+#      not among the resources, keeps the deployed file under
+#      `Contents/Resources/`, and is signed ad hoc so that `codesign --verify
+#      --deep --strict` accepts it.
+#   3. The bundled program loads the framework copy and exits 7 with its
+#      output; a copy of the bundle without the framework stops with "Library
+#      not loaded".
+#   4. `mcpp run --format app`, with no runner in the manifest, runs the bundle
+#      through `macapp-run` and returns the program's 7 with its output and
+#      arguments; `--runner app` does the same.
+#   5. `mcpp pack --format dmg` writes an image `hdiutil verify` accepts, which
+#      attaches read-only holding the bundle and an `Applications` link.
+#
+# Usage: MCPP=<mcpp 2026.9.14.2+> ./check-apple-bundle.sh   (run from this directory)
+set -eu
+
+MCPP="${MCPP:-mcpp}"
+NAME=AppFrameworkConsumer
+EXE=app-framework-consumer
+DYLIB=libapp-framework-dep.dylib
+fail() { echo "FAIL: $1"; shift; for f in "$@"; do echo "--- $f ---"; cat "$f" 2>/dev/null; done; exit 1; }
+reading() { printf 'READING %s: %s\n' "$1" "$2"; }
+packed() { sed -n 's/^ *Packed //p' "$1" | tail -1; }
+work=$(mktemp -d)
+
+# ── 1. the rpath, at link time ─────────────────────────────────────────────
+echo "== 1. the program's rpath =="
+rm -rf target
+"$MCPP" build > bundle-build.log 2>&1 || fail "mcpp build failed" bundle-build.log
+if find target -name '*.app' | grep -q .; then fail "a plain build produced a bundle"; fi
+programs=$(find target -type f -name "$EXE" ! -path '*/.build-mcpp/*')
+[ "$(printf '%s\n' "$programs" | grep -c .)" = 1 ] \
+    || fail "expected one linked $EXE under target/, found: $(echo $programs)" bundle-build.log
+otool -l "$programs" > bundle-loadcommands.log
+rpaths=$(awk '/cmd LC_RPATH/ { getline; getline; print $2 }' bundle-loadcommands.log)
+reading rpaths "$(echo $rpaths)"
+printf '%s\n' "$rpaths" | grep -qxF '@executable_path/../Frameworks' \
+    || fail "the program has no LC_RPATH @executable_path/../Frameworks" bundle-loadcommands.log
+if printf '%s\n' "$rpaths" | grep -q '.@executable_path'; then
+    fail "an rpath carries @executable_path after a directory, anchored" bundle-loadcommands.log
+fi
+otool -L "$programs" > bundle-needed.log
+grep -q "@rpath/$DYLIB" bundle-needed.log || fail "the program does not load @rpath/$DYLIB" bundle-needed.log
+echo "ok: LC_RPATH @executable_path/../Frameworks, as written, and the dependency is @rpath/$DYLIB"
+
+# ── 2. the bundle ──────────────────────────────────────────────────────────
+echo "== 2. the bundle carries the framework and is signed ad hoc =="
+"$MCPP" pack --format app > bundle-pack.log 2>&1 || fail "mcpp pack --format app failed" bundle-pack.log
+app=$(packed bundle-pack.log)
+case "$app" in *"/$NAME.app") ;; *) fail "the pack reported '$app', not $NAME.app" bundle-pack.log ;; esac
+[ -d "$app" ] || fail "the reported bundle $app is not a directory" bundle-pack.log
+[ -f "$app/Contents/Frameworks/$DYLIB" ] || { find "$app" | sort; fail "no Contents/Frameworks/$DYLIB"; }
+if find "$app/Contents/Resources" "$app/Contents/MacOS" -name '*.dylib' 2>/dev/null | grep -q .; then
+    find "$app" | sort; fail "a dylib is under Contents/Resources or Contents/MacOS"
+fi
+[ -f "$app/Contents/Resources/data/greeting.txt" ] || { find "$app" | sort; fail "the deployed file is not under Contents/Resources"; }
+codesign --verify --deep --strict --verbose=2 "$app" > bundle-codesign.log 2>&1 \
+    || fail "codesign --verify --deep --strict refused the bundle" bundle-codesign.log
+reading codesign-verify "$(tr '\n' ' ' < bundle-codesign.log)"
+# A linked arm64 program is already signed ad hoc by the linker, so the bundle's
+# own signature is read from its sealed resources, and the framework's from
+# the absence of the linker's flag.
+codesign -dv "$app" > bundle-signature.log 2>&1 || true
+reading bundle-signature "$(grep -E '^(Signature|CodeDirectory|Sealed Resources)' bundle-signature.log | tr '\n' ' ')"
+grep -q '^Signature=adhoc' bundle-signature.log || fail "the bundle's signature is not ad hoc" bundle-signature.log
+grep -q '^Sealed Resources' bundle-signature.log || fail "the bundle's resources are not sealed" bundle-signature.log
+codesign -dv "$app/Contents/Frameworks/$DYLIB" > bundle-framework-signature.log 2>&1 || true
+reading framework-signature "$(grep -E '^(Signature|CodeDirectory)' bundle-framework-signature.log | tr '\n' ' ')"
+grep -q '^Signature=adhoc' bundle-framework-signature.log \
+    || fail "the framework is not signed" bundle-framework-signature.log
+if grep -q 'linker-signed' bundle-framework-signature.log; then
+    fail "the framework carries the linker's signature, not one of its own" bundle-framework-signature.log
+fi
+echo "ok: Contents/Frameworks/$DYLIB, nothing loadable among the resources, and codesign --verify --deep --strict passes"
+
+# ── 3. the bundled program ─────────────────────────────────────────────────
+echo "== 3. the bundled program loads the framework =="
+rc=0
+DYLD_PRINT_LIBRARIES=1 "$app/Contents/MacOS/$EXE" > bundle-run.out 2> bundle-run.err || rc=$?
+reading bundle-run "exit=$rc $(cat bundle-run.out)"
+[ "$rc" -eq 7 ] || fail "the bundled program exited $rc, not 7" bundle-run.out bundle-run.err
+grep -qx 'framework-1-2-3 argc=1' bundle-run.out || fail "the bundled program's output is missing" bundle-run.out
+loaded=$(grep "$DYLIB" bundle-run.err | head -1)
+reading loaded "$loaded"
+case "$loaded" in *"/$NAME.app/Contents/Frameworks/$DYLIB") ;;
+    *) fail "the program did not load the framework copy" bundle-run.err ;; esac
+cp -R "$app" "$work/"
+rm "$work/$NAME.app/Contents/Frameworks/$DYLIB"
+rc=0
+"$work/$NAME.app/Contents/MacOS/$EXE" > bundle-noframework.out 2>&1 || rc=$?
+reading without-framework "exit=$rc $(head -2 bundle-noframework.out | tr '\n' ' ')"
+[ "$rc" -ne 0 ] || fail "the program ran without its framework" bundle-noframework.out
+grep -q 'Library not loaded' bundle-noframework.out || fail "the failure is not 'Library not loaded'" bundle-noframework.out
+echo "ok: exit 7 through the framework copy; without it, exit $rc and 'Library not loaded'"
+
+# ── 4. mcpp run --format app ───────────────────────────────────────────────
+echo "== 4. mcpp run --format app, through the runner dist-apple supplies =="
+if grep -q 'runner' mcpp.toml; then fail "the fixture's manifest names a runner" mcpp.toml; fi
+# mcpp_run <variant> <mcpp run arguments...>
+mcpp_run() {
+    local variant="$1"; shift
+    rc=0
+    "$MCPP" run "$@" > "bundle-mcpp-run-$variant.log" 2>&1 || rc=$?
+    reading "mcpp-run-$variant" "exit=$rc $(grep -m1 'Running' "bundle-mcpp-run-$variant.log" || echo 'no Running line')"
+    [ "$rc" -eq 7 ] || fail "mcpp run $* exited $rc, not 7" "bundle-mcpp-run-$variant.log"
+    grep -q 'Running `.*macapp-run' "bundle-mcpp-run-$variant.log" \
+        || fail "the status line does not name macapp-run" "bundle-mcpp-run-$variant.log"
+    grep -qx 'framework-1-2-3 argc=2' "bundle-mcpp-run-$variant.log" \
+        || fail "the program's output with one argument is missing" "bundle-mcpp-run-$variant.log"
+}
+mcpp_run format --format app -- extra
+mcpp_run runner --format app --runner app -- extra
+echo "ok: mcpp run --format app, and with --runner app, return 7 with the program's output and argument"
+
+# ── 5. the disk image ──────────────────────────────────────────────────────
+echo "== 5. mcpp pack --format dmg =="
+"$MCPP" pack --format dmg > bundle-dmg.log 2>&1 || fail "mcpp pack --format dmg failed" bundle-dmg.log
+dmg=$(packed bundle-dmg.log)
+case "$dmg" in *"/$NAME.dmg") ;; *) fail "the pack reported '$dmg', not $NAME.dmg" bundle-dmg.log ;; esac
+[ -f "$dmg" ] || fail "the reported image $dmg does not exist" bundle-dmg.log
+hdiutil verify "$dmg" > bundle-hdiutil-verify.log 2>&1 || fail "hdiutil verify refused the image" bundle-hdiutil-verify.log
+reading hdiutil-verify "$(grep -i 'checksum' bundle-hdiutil-verify.log | tail -1)"
+mnt="$work/mnt"
+mkdir -p "$mnt"
+hdiutil attach -nobrowse -readonly -mountpoint "$mnt" "$dmg" > bundle-attach.log 2>&1 \
+    || fail "hdiutil attach failed" bundle-attach.log
+detach() { hdiutil detach "$mnt" > /dev/null 2>&1 || hdiutil detach -force "$mnt" > /dev/null 2>&1 || true; }
+trap detach EXIT
+reading image-root "$(ls -1 "$mnt" | tr '\n' ' ')"
+[ -x "$mnt/$NAME.app/Contents/MacOS/$EXE" ] || fail "the image does not hold the bundle's program"
+[ -f "$mnt/$NAME.app/Contents/Frameworks/$DYLIB" ] || fail "the image's bundle lacks the framework"
+[ -L "$mnt/Applications" ] || fail "the image holds no Applications link"
+[ "$(readlink "$mnt/Applications")" = /Applications ] || fail "the Applications link points to $(readlink "$mnt/Applications")"
+codesign --verify --deep --strict "$mnt/$NAME.app" > bundle-image-codesign.log 2>&1 \
+    || fail "the bundle inside the image does not verify" bundle-image-codesign.log
+detach
+trap - EXIT
+echo "ok: the image verifies and attaches read-only with the signed bundle and Applications -> /Applications"
+
+echo "PASS: dist-apple's framework, rpath, ad-hoc signature, app runner and disk image, on the bundle"

tests/app-framework-consumer/check-apple-bundle.sh

@@ -0,0 +1,168 @@
+#!/usr/bin/env bash
+# Plan-level check for dist-apple's closure, signing, runner and disk image on
+# the macOS row (mcpp#634, B1 to B3).
+#
+# The real bundle is measured on the macOS runner. This script measures, on any
+# host, what the compiled build program PLANS under the environment the engine
+# sets for `mcpp pack --format app` and `--format dmg` on macOS: the build
+# program's target accessors read that environment and nothing else, so a
+# process given the same variables takes the branches a real pack takes. The
+# staged tree and its stage manifest are fabricated in the shape the engine
+# writes (mcpp's docs/50, "The stage manifest").
+#
+# Usage: MCPP=<mcpp> ./check-apple-plan.sh   (run from this directory)
+set -e
+
+MCPP="${MCPP:-mcpp}"
+fail() { echo "FAIL: $1"; shift; for f in "$@"; do echo "--- $f ---"; cat "$f" 2>/dev/null; done; exit 1; }
+command -v python3 >/dev/null || fail "python3 is required to read the planned actions"
+
+rm -rf target
+"$MCPP" build > build.log 2>&1 || fail "the host build failed to compile build.mcpp" build.log
+BIN=target/.build-mcpp/build.mcpp.bin
+[ -x "$BIN" ] || fail "no compiled build.mcpp.bin at $BIN" build.log
+
+# stage_tree <closure> : a staged tree with the program, its dylib and a
+# deployed resource, and the stage manifest the engine writes for it.
+stage_tree() {
+    local stage
+    stage=$(mktemp -d)
+    mkdir -p "$stage/bin/data"
+    head -c 5000 /dev/urandom > "$stage/bin/app-framework-consumer"
+    head -c 4000 /dev/urandom > "$stage/bin/libapp-framework-dep.dylib"
+    echo hello > "$stage/bin/data/greeting.txt"
+    {
+        printf 'closure = %s\n' "$1"
+        if [ "$1" = not-walked ]; then
+            printf 'reason = the loader finds no file for @rpath/libmissing.dylib\n'
+        fi
+        printf 'needs\t/usr/lib/libSystem.B.dylib\tplatform\n'
+        printf 'needs\t@rpath/libapp-framework-dep.dylib\tbin/libapp-framework-dep.dylib\n'
+        if [ "$1" = not-walked ]; then
+            printf 'needs\t@rpath/libmissing.dylib\tunresolved\n'
+        fi
+        printf '5000 bin/app-framework-consumer\n'
+        printf '4000 bin/libapp-framework-dep.dylib\n'
+    } > "$stage.stage-manifest"
+    echo "$stage"
+}
+
+# run_program <format> <os> <env> <stage> <log>
+run_program() {
+    local out
+    out=$(mktemp -d)
+    env -i PATH="$PATH" \
+        MCPP_PACK_FORMAT="$1" MCPP_TARGET_OS="$2" MCPP_TARGET_ENV="$3" \
+        MCPP_PACK_STAGE_DIR="$4" MCPP_MANIFEST_DIR="$PWD" \
+        MCPP_PKG_NAME=app-framework-consumer MCPP_PKG_VERSION=0.1.0 \
+        MCPP_OUT_DIR="$out" \
+        "$BIN" > "$5" 2>&1 || true
+}
+
+# check <log> <python assertions reading `actions` (id -> action) and `lines`>
+check() {
+    python3 - "$1" "$2" <<'PY' || exit 1
+import json, sys
+log, code = sys.argv[1], sys.argv[2]
+lines = open(log).read().splitlines()
+actions = {}
+for l in lines:
+    if l.startswith("mcpp:action="):
+        a = json.loads(l[len("mcpp:action="):])
+        actions[a["id"]] = a
+def fail(msg):
+    print("FAIL: " + msg)
+    print("--- " + log + " ---")
+    print("\n".join(lines))
+    sys.exit(1)
+exec(code)
+PY
+}
+
+echo "== --format app on macOS, with a staged dylib =="
+stage=$(stage_tree walked)
+run_program app macos "" "$stage" /tmp/apple-plan-app.log
+check /tmp/apple-plan-app.log '
+fw = actions.get("mcpp.dist.apple.framework.libapp-framework-dep.dylib")
+if not fw: fail("no framework step for the staged dylib")
+if not fw["outputs"] or not fw["outputs"][0].endswith("/AppFrameworkConsumer.app/Contents/Frameworks/libapp-framework-dep.dylib"):
+    fail("the framework step does not write Contents/Frameworks/libapp-framework-dep.dylib")
+if fw["command"][-2:] != ["sign", "-"]:
+    fail("the framework step does not sign ad hoc: " + repr(fw["command"]))
+if any(i.startswith("mcpp.dist.apple.resource.libapp") for i in actions):
+    fail("the staged dylib is also planned as a resource")
+if "mcpp.dist.apple.resource.data" not in actions:
+    fail("the deployed resource is not planned")
+sign = actions.get("mcpp.dist.apple.codesign")
+if not sign: fail("no codesign step on macOS without an identity")
+if sign["command"][:4] != ["codesign", "--force", "--sign", "-"] or "--timestamp" in sign["command"]:
+    fail("the bundle is not signed ad hoc: " + repr(sign["command"]))
+if fw["outputs"][0] not in sign["inputs"]:
+    fail("the bundle signature does not follow the framework")
+bundle = actions.get("mcpp.dist.apple.bundle")
+if not bundle or sign["outputs"][0] not in bundle["inputs"]:
+    fail("the bundle step does not follow the signature")
+if any(k.startswith("mcpp.dist.apple.dmg") for k in actions):
+    fail("--format app planned a disk image")
+if "mcpp:link-flag=-Wl,-rpath,@executable_path/../Frameworks" not in lines:
+    fail("no framework rpath was emitted for the link")
+if "mcpp:runner-named=app:macapp-run" not in lines:
+    fail("the app runner was not supplied")
+'
+echo "ok: the dylib is a framework signed ad hoc, not a resource; the bundle is signed after it; the rpath and the runner are declared"
+
+echo "== --format dmg on macOS =="
+run_program dmg macos "" "$stage" /tmp/apple-plan-dmg.log
+check /tmp/apple-plan-dmg.log '
+bundle = actions.get("mcpp.dist.apple.bundle")
+st = actions.get("mcpp.dist.apple.dmg-stage")
+img = actions.get("mcpp.dist.apple.dmg")
+if not (bundle and st and img): fail("the disk image steps are not planned")
+if bundle["outputs"][0] not in st["inputs"]: fail("the image staging does not take the bundle")
+if st["outputs"][0] not in img["inputs"]: fail("hdiutil does not take the staging directory")
+cmd = img["command"]
+if cmd[:2] != ["hdiutil", "create"] or "UDZO" not in cmd or not cmd[-1].endswith("/AppFrameworkConsumer.dmg"):
+    fail("the image command is not hdiutil create -format UDZO ... AppFrameworkConsumer.dmg: " + repr(cmd))
+consumed = set(i for a in actions.values() for i in a["inputs"])
+terminals = [a["id"] for a in actions.values() if not set(a["outputs"]) & consumed]
+if terminals != ["mcpp.dist.apple.dmg"]:
+    fail("the image is not the sole terminal artifact: " + repr(terminals))
+'
+echo "ok: the bundle is staged beside the link and the .dmg is the sole terminal artifact"
+
+echo "== an incomplete closure is reported =="
+stage2=$(stage_tree not-walked)
+run_program app macos "" "$stage2" /tmp/apple-plan-notwalked.log
+check /tmp/apple-plan-notwalked.log '
+if not any(l.startswith("mcpp:warning=") and "libmissing.dylib" in l and "closure is incomplete" in l for l in lines):
+    fail("the incomplete closure is not reported, naming the unresolved library")
+if "mcpp.dist.apple.bundle" not in actions:
+    fail("an incomplete closure stopped the bundle")
+'
+echo "ok: an incomplete closure is a warning naming the library, and the bundle is still planned"
+
+echo "== --format dmg on iOS is refused =="
+run_program dmg ios sim "$stage" /tmp/apple-plan-dmg-ios.log
+check /tmp/apple-plan-dmg-ios.log '
+if actions: fail("an iOS disk image planned actions")
+if not any(l.startswith("mcpp:warning=") and "a .dmg is a macOS disk image" in l for l in lines):
+    fail("the refusal is not a warning")
+'
+echo "ok: an iOS disk image is refused, as a warning"
+
+echo "== the iOS simulator row =="
+run_program app ios sim "$stage" /tmp/apple-plan-ios.log
+check /tmp/apple-plan-ios.log '
+fw = actions.get("mcpp.dist.apple.framework.libapp-framework-dep.dylib")
+if not fw or not fw["outputs"][0].endswith("/AppFrameworkConsumer.app/Frameworks/libapp-framework-dep.dylib"):
+    fail("the simulator bundle does not carry the dylib in Frameworks/")
+if fw["command"][-1] != "nosign": fail("the simulator framework is signed")
+if "mcpp.dist.apple.codesign" in actions: fail("the simulator bundle is signed")
+if "mcpp:link-flag=-Wl,-rpath,@executable_path/Frameworks" not in lines:
+    fail("no iOS framework rpath was emitted")
+if any(l.startswith("mcpp:runner-named=app:") for l in lines):
+    fail("the macOS runner was supplied on iOS")
+'
+echo "ok: the simulator bundle carries Frameworks/, unsigned, with the iOS rpath and no macOS runner"
+
+echo "PASS: dist-apple's closure, signing, runner and disk image, at the plan level"

tests/app-framework-consumer/check-apple-plan.sh

@@ -0,0 +1,3 @@
+#pragma once
+
+const char* app_framework_dep_marker();