vercel-labs / vercel-labs/native
ios: `native dev --target ios` fails to link — zig-built archive members not 8-byte aligned for Apple ld
Nobody has claimed this yet.
- Dominant language
- Zig
- Stars
- 7.7k
- Forks
- 314
- Avg merge
- 5h
- Merged PRs (30d)
- 13
Description
An embed static library built by the iOS dev loop is rejected by Xcode's linker before the app can ever run: native dev --target ios fails on every TypeScript-core app at the host-compile step, with a low-level ld error about archive member alignment. The zig build lib step itself succeeds; the failure happens when the toolkit-owned UIKit host is linked against the archive it just produced.
Repro
native init demo && cd demo
native dev --target ios
Expected: the embed library builds, the UIKit host compiles and links, the app installs and launches in the simulator.
Actual:
native dev (ios): compiling the toolkit UIKit host
ld: 64-bit mach-o member 'libIdfon_zcu.o' not 8-byte aligned in '.native/embed/aarch64-ios-simulator/lib/libIdfon.a'
clang: error: linker command failed with exit code 1 (use -v to see invocation)
native (ios): `xcrun` step failed
Modern ld64 requires 64-bit mach-o archive members to be 8-byte aligned; the archive zig emits doesn't guarantee that. Xcode 26.6's ld enforces it.
Workaround
Extract the members and repack with libtool before the link:
mkdir repack && cd repack
xcrun ar x ../libIdfon.a
chmod 644 *.o # members extract with mode 000
rm -f __.SYMDEF*
xcrun libtool -static -o ../libIdfon-aligned.a *.o
Gotcha for the fix: repacking from the archive directly (libtool -static -o out.a in.a) is not equivalent — it silently drops members, and the linked app then fails with all 48 _native_sdk_app_* C-API symbols undefined. Members must be extracted first, then repacked from the individual .o files. Worth an assertion after any repack (nm -g still finds _native_sdk_app_create).
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
- Fix lives in
src/tooling/ios.zig(and the xcodeproj packaging path): repack the embed archive afterbuildEmbedLib, before the clang link. Cheap relative to the build. - The alignment failure and the UBSan failure (sibling issue) are independent — fixing one does not unblock
native dev --target ios; both must be fixed for the dev loop to complete.
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 src/tooling/ios.zig at buildEmbedLib and follow the xcodeproj packaging path into the clang link. Reproduce with native init demo && cd demo && native dev --target ios, then verify the extracted-and-repacked archive retains _native_sdk_app_create with nm. Done means the UIKit host links, installs, and launches in the simulator.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- zig
- Domain
- build-system, mobile-dev
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100