vercel-labs / vercel-labs/native
ios: Debug builds fail to link — core archive references UBSan runtime the host link never provides
Nobody has claimed this yet.
- Dominant language
- Zig
- Stars
- 7.7k
- Forks
- 314
- Avg merge
- 5h
- Merged PRs (30d)
- 13
Description
With the archive-alignment failure worked around (sibling issue), native dev --target ios in Debug still fails at the same clang link: the scriptc runtime objects inside the Debug core archive reference ___ubsan_handle_*, but the toolkit's host link command provides no sanitizer runtime. ReleaseFast builds are unaffected (no UBSan references), which is presumably why the dev loop was never exercised against this.
Repro
Same as the sibling issue: any app, native dev --target ios, after working around the archive alignment. The link then fails with ~13 undefined-symbol families, e.g.:
Undefined symbols for architecture arm64:
"___ubsan_handle_add_overflow", referenced from:
_scr_bytes_from_str in libIdfon.a[8](scr_bytes.o)
"___ubsan_handle_type_mismatch_v1", referenced from:
_scr_arr_new in libIdfon.a[6](scr_array.o)
... (shift_out_of_bounds, mul/sub/negate_overflow, out_of_bounds,
pointer_overflow, load_invalid_value, builtin_unreachable, ...)
Control
native build for the same app in ReleaseFast links fine — the UBSan references are Debug-only.
Workaround (verified)
Link the simulator ubsan runtime into the app and bundle it:
UB=/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/clang/21/lib/darwin/libclang_rt.ubsan_iossim_dynamic.dylib
xcrun lipo -thin arm64 "$UB" -output "$APP/libclang_rt.ubsan_iossim_dynamic.dylib"
# add to the host clang command:
# $APP/libclang_rt.ubsan_iossim_dynamic.dylib -rpath @executable_path
# then codesign both the dylib and the .app
Environment
- native 0.10.1 (
064ca98), CLI reportsnative 0.10.1 (commit 064ca98, automation protocol 0x51f7889bbe3305e7) - macOS 26.6.2 (arm64), Xcode 26.6
- Zig 0.16.0, Node v24.20.0
Notes
Suggested fixes, either works:
- (a) link the ubsan runtime for Debug builds (the bundle assembly is already in
ios.zig, so embedding the dylib +-rpath @executable_pathfits the existing flow), or - (b) compile the scriptc runtime objects without sanitizers so Debug archives carry no UBSan references — simpler, removes the dylib dependency entirely.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in ios.zig and trace the host clang command used by native dev --target ios for Debug builds, then compare it with the working ReleaseFast path and the scriptc objects in the core archive. Done means the same Debug iOS app links successfully without the listed UBSan errors, with the runtime bundled and signed if that approach is chosen, or without UBSan references if the runtime objects are rebuilt.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- ios, zig
- Domain
- build-system, mobile
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100