feat(platform): iOS support through cdylib

[Guikingone]

Closes #662.

Makes iOS a real compilation target. Compiled PHP runs on the iOS Simulator:

==> running inside booted simulator 9A3F533A-…
    42 hi iOS 6

iPhone 17 Pro, iOS 26.5, arm64. spike_add(40, 2) returned 42, spike_greet("iOS", 3) returned "hi iOS" with length 6, and elephc_free released the buffer — the int export, the string export and the ownership contract, end to end on device-class arm64.

The architecture decision

iOS is a variant on Target, not a fourth Platform.

Every syscall number, struct offset, errno, open flag and Mach-O convention is identical between macOS and iOS on arm64 — they share XNU. A new Platform would have grown ~181 match arms across 54 files that all return exactly what macOS already returns, and turned every future OS constant into a four-way match.

The evidence that this was right: Target::supports_current_backend() needed no change at all. The arm64 Darwin backend serves iOS unchanged, and the central gate at pipeline.rs never had to open.

What genuinely differs turned out to be four things:

SDK selection	linker/sdk.rs now always passes --sdk explicitly. Relying on xcrun's default resolves whatever the selected developer directory offers, silently handing back the macOS SDK when the requested iOS one is missing
-platform_version	iOS records a 13.0 deployment floor; macOS keeps its report-the-SDK-version behaviour, untouched
Compiler triple	native_deps/toolchain.rs matched a fixed darwin and therefore rejected every iOS toolchain outright
Sandbox rules	six builtins depend on fork and cannot work — see below

Target::as_str() encodes the variant because three persisted keys derive from it: the runtime object cache filename, the native-dependency ArtifactReceipt JSON, and the package catalog. A macOS and an iOS build sharing a string would silently reuse each other's artifacts. A test pins that macOS, device and simulator cannot collide and that each string round-trips.

A missing iOS SDK no longer suggests xcode-select --install — the Command Line Tools that installs ship no iOS SDK, so the advice loops.

What's in it

String returns from #[Export] — the gate everything else waited on

is_v1_return_type accepted Int | Float | Bool | Void and no Str, so an embedded elephc library could only ever return a number. Every realistic payload — a serialized view tree, a JSON result, a domain object — is a string.

Ownership. Strings are move-semantics, not refcounted: __rt_decref_any sends kind 1 straight to __rt_heap_free_safe, which frees rather than decrements. An exported string return must therefore be exactly one owned heap block. Lowering now persists it unconditionally, and that persist replaces the borrow acquire rather than stacking on it — Str is lifetime-tracked, so acquiring and then copying would strand the acquired reference as a leak. Without the forced persist, return $param; hands the host back its own pointer and return "literal"; a .rodata address, neither of which elephc_free may legitimately release.

Two register contracts, both silent failure modes:

• AAPCS64 returns a 16-byte aggregate in x0/x1 while elephc produces the pair in x1/x2. The trampoline shifts it down and can no longer tail-branch. x86_64 needs no shift — rax/rdx already is the SysV two-INTEGER struct return.
• elephc_free receives its argument in rdi under SysV, but __rt_heap_free_safe reads rax. x86_64 bridges the register; AArch64 passes it in x0 and tail-branches unchanged.

Neither side is covered by the other's tests. Left alone this would have shipped as silent corruption on precisely the arm64 path iOS depends on.

The in-band NULL_SENTINEL is translated to a real C NULL with a zero length at the boundary, branchlessly.

--emit staticlib

lib<stem>.a with the user object, the runtime object and a symbol index. A C host links it directly — no dlopen — and runs. This is the delivery form an Xcode project consumes; a .a also avoids the embedded-framework signing dance a .dylib in an app bundle requires.

It is deliberately not the PIC path. Emitter::new_pic exists for dynamic loading, where the loader resolves cross-object references at dlopen time; its GOT indirection is unrelated to position independence as such. An archive is merged once into the host's final binary by the host's own linker, exactly like the executable path — whose non-PIC output is already PC-relative and already yields PIE binaries. The test proves it: the archive links into a PIE host and works.

An Emit::is_library() predicate replaces the scattered matches!(emit, Emit::Cdylib) checks the two library kinds share. The one Cdylib-only check stays Cdylib-only: ELF dynamic-symbol visibility is meaningless for a .a. Both linker command renderers get explicit unreachable! arms rather than a catch-all, so a future emit kind cannot silently inherit link behaviour. Archiving bypasses the link plan: bridges and managed native packages stay separate .a files for the consuming project, as a C library leaves its dependencies to its consumer.

Capability gating

system, passthru, exec, shell_exec, popen and pclose are refused at compile time for iOS targets:

error[1:7]: shell_exec() cannot be compiled for ios-arm64: that sandbox forbids
spawning a process, so the call would always fail at run time

The same source still compiles for the host — this is a target capability gate, not a removal of the builtin.

The gate lives in each builtin's check: hook rather than in a backend audit, because a hook has the call's exact span. An exhaustive-match audit would guarantee no builtin is forgotten, but the WASM equivalent shows the price: its errors can only cite block and instruction indices, having no wiring to CompileError/Span. proc_open and its family are absent because they do not exist in the compiler at all; the guard's doc comment records that they must adopt it when added.

Assembling for the right platform

Running Lot 0 against a real SDK found the one thing that could not be predicted from the macOS side:

ld: building for 'iOS-simulator', but linking in object file built for 'macOS'

A Mach-O object records the platform it was assembled for. as -arch arm64 stamps macOS and cannot say otherwise, so relinking against the iOS SDK was never going to be enough — an earlier note in this PR claiming only -syslibroot and -platform_version remained untested was wrong.

Non-macOS Apple targets now assemble through clang with -target and -isysroot. The user object and the cached runtime object built that command in two separate places and would have drifted; they now share one linker::assembler_command, because they must agree or the link fails on whichever one disagrees. APPLE_IOS_MIN_OS is a single constant for the same reason: the assembler writes it into each object's LC_BUILD_VERSION and the linker into the image's -platform_version, and a mismatch between those is itself a link error.

macOS is byte-unchanged — its objects still report platform MACOS and a statically linked host still runs.

Native dependencies

pcre2 and zlib are catalogued for ios-arm64 and ios-sim-arm64, so any PHP program reaching PCRE or zlib can build them for iOS. Both are plain autoconf/make projects with no host assumptions beyond a C compiler, so neither needed a per-package caveat. resolve_toolchain already refuses any cross target without explicit ELEPHC_NATIVE_CC/AR/RANLIB; for iOS those must carry -target and -isysroot or configure silently probes the host.

Adding the entries exposed two correctness bugs:

• validate_tuple accepted a simulator compiler for a device target, and vice versa. The two triples differ only by a trailing -simulator, so the substring match let incompatible objects through. The accepted spellings are measured, not assumed: clang -dumpmachine reports arm64-apple-ios13.0 under -target arm64-apple-ios13.0, and arm64-apple-darwin25.5.0 with no target flag.
• resolve_toolchain hardcoded --sdk macosx when reading the SDK version into the toolchain fingerprint, so an iOS build recorded the host SDK — and bumping the iOS SDK never invalidated the cache.

Device and simulator artifacts do not collide despite sharing an abi string: ArtifactKey carries target.as_str() as its own path component, which the Apple variant already distinguishes.

The lockfile test asserted a hardcoded count of three target plans. It now derives the expectation from the catalog and checks the target names, so adding a target is not a chore and the assertion says what it means.

Exercising the entries against a real SDK found a third bug, and it would have made the catalog claim hollow. The recipes passed toolchain.target_tuple — whatever clang -dumpmachine prints — as --host/CHOST. autoconf feeds those through config.sub, which parses an Apple cross triple as kernel ios13.0 plus OS simulator and rejects it outright:

Invalid configuration 'arm64-apple-ios13.0-simulator':
Kernel 'ios13.0' not known to work with OS 'simulator'.

toolchain.abi is elephc's normalized identity and is exactly what config.sub wants. Measured against a real one: arm64-apple-ios13.0-simulator rejected, aarch64-apple-ios and aarch64-apple-darwin accepted. Linux is unaffected in substance — its abi is the canonical <arch>-unknown-linux-<gnu|musl> form of the same information.

pcre2 and zlib now build for ios-sim-arm64, with archive members reporting platform IOSSIMULATOR, arch arm64, cached under ios-sim-arm64/aarch64-apple-ios. The host macOS build still produces MACOS members.

One note for consumers: ELEPHC_NATIVE_CC_* takes a command path, not a command line, so an iOS toolchain needs a small wrapper script carrying -target and -isysroot.

scripts/ios-relink-spike.sh

Answers the platform question in one command once Xcode is installed: emit assembly, assemble, relink against the iOS SDK, build a C host for the simulator triple and run it through simctl spawn — no Xcode project involved.

The chain minus the SDK swap is already verified: run against the macOS SDK it returns 42 hi iOS 6, exercising the int export, the string export and elephc_free. Only -syslibroot and -platform_version remain untested. It isolates XDG_CACHE_HOME deliberately — the runtime object's cache key encodes the program's feature set, so the shared cache holds several candidates and a newest-match glob would link the wrong one.

examples/swiftui-view-protocol/

A native app whose entire interface is decided by compiled PHP: render_view() returns a serialized view tree, dispatch() returns the next one after an event, and the Swift host understands four node types and nothing else.

It runs on macOS and iOS from the same view.php and the same Swift. run-ios.sh builds a real iOS app, installs it on a booted simulator, launches it and screenshots the result — no .xcodeproj involved, swiftc and the simulator SDK are enough. The library is linked statically, the delivery form an Xcode project consumes; that is also what lets one Swift source serve both platforms, dlopen being the wrong shape for iOS.

This is the shape that fits ahead-of-time compilation: a template engine must evaluate itself on the device and so needs a runtime there, while a tree generator compiles once and ships as machine code. It is the one corner of the UI problem where being AOT costs nothing.

Two constraints any Swift host will hit, documented in its README so the iOS host does not rediscover them: ElephcStr must be declared in C (Swift rejects a Swift-declared struct in a @convention(c) signature — only a C type carries the guarantee that the value rides the aggregate-return registers), @main requires -parse-as-library, and -sdk does not reach the link step — swiftc drives clang to link with the host sysroot unless -Xclang-linker -isysroot passes the SDK through, which an iOS build otherwise reports as "using sysroot for 'MacOSX' but targeting 'iPhone'".

Verification

Focused, per AGENTS.md; CI owns the matrix.

suite
cdylib_tests	6/6 — string-return ownership, staticlib link-and-run, iOS capability gating
native_deps	56 / 0
error_tests	1139 / 0
codegen::oop	585 / 0
ir_backend_smoke_test	255 / 0 — catches compilation errors
codegen::strings	186 / 0
--bins	1060 / 0
--lib	990 / 0

Build warning-free.

The ownership test asserts the returned pointer is not the caller's own buffer — ownership, not string contents. The emitter tests pin both register contracts on both architectures. The view-protocol example self-tests headlessly:

initial=nothing yet after++=2 items after-=one item reset=nothing yet
PASS: the view tree, the string ABI and PHP-side state all round-trip

examples/ios-device-probe/ — what the simulator did not prove

An iOS Simulator app is a native macOS process loading the iOS frameworks, so elephc's raw syscalls hit the macOS table — exactly the one they were written against. The simulator validates codegen, the C ABI, marshaling, ownership, Mach-O and linking. It does not touch the device sandbox.

This probe measures the difference: it runs compiled PHP inside the app and reports which operations succeed — container file I/O, paths outside the container, getcwd/tmp/env, the clock, DNS. Nothing aborts on failure, so one run measures everything instead of stopping at the first denial. Its own simulator output makes the case:

OK   outside./tmp write         permitted
OK   outside./etc/hosts stat    readable
OK   env.getenv HOME            /Users/…/CoreSimulator/Devices/…/data

run.sh builds, bundles, signs, installs through devicectl and launches with --console. Device mode stops at the signature — only an Apple ID can issue the certificate and profile — with everything up to that point assembled and verified as platform IOS, arm64.

It also surfaces a constraint consumers should not discover the hard way: an elephc static library is not self-contained. Filesystem PHP reaches __rt_fopen_maybe_phar, which pulls in the elephc-phar bridge, which pulls in bzip2. Emit::Staticlib leaves bridges and native packages to the consuming project by design — as a C library leaves its dependencies to its consumer — so an Xcode target also links the bridges it uses, cross-compiled for the same target (rustup target add aarch64-apple-ios), plus their system libraries. Which bridges depends on which PHP surface you use; the view-protocol example needs none.

Verified against a real iOS SDK

Both targets build and link:

	device	simulator
archive members	platform IOS	platform IOSSIMULATOR
host executable	links	links
runs	needs provisioning + signed bundle	42 hi iOS 6

./scripts/ios-relink-spike.sh drives it, in either mode.

Not verified

Execution on a physical device. Needs provisioning and a signed app bundle — app packaging rather than a compiler concern. The device archive and executable build and link identically to the simulator's.

x86_64 at run time. Its code paths are asserted at the emitted-assembly level only — macOS cannot assemble the ELF x86_64 runtime. CI covers it.