vercel-labs / vercel-labs/native

ios: `native dev --target ios` fails to link — zig-built archive members not 8-byte aligned for Apple ld

Open
#428 0 comments 0 reactions 0 assignees View on GitHub

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 reports native 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 after buildEmbedLib, 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.