feat(ios): embed ggml-metal source into framework binary

[kiyohken2000]

Summary

Fixes #348 by switching from the runtime .metal file load (introduced in #252) to the embedded-source pattern that upstream llama.cpp uses behind GGML_METAL_EMBED_LIBRARY. The merged Metal source is baked into the framework binary as a __DATA symbol range and consumed directly by ggml-metal-device.m's embedded code path.

This addresses the maintenance concern from #252 (no per-target .metallib to ship or precompile) while removing the runtime NSBundle resource lookup that #348 reported as failing on iPhone A15 with XPC_ERROR_CONNECTION_INTERRUPTED.

cpp/ggml-metal/ggml-metal-device.m itself is unchanged — its #if GGML_METAL_EMBED_LIBRARY branch already supports this path; we only define the macro, generate the asm wrapper, and link it.

Changes

• scripts/bootstrap.sh — after the LM_ prefix sed pass, emit cpp/ggml-metal/ggml-metal-embed.s with the merged metal source as .byte directives between _lm_ggml_metallib_start and _lm_ggml_metallib_end symbols.
• ios/CMakeLists.txt — add ASM to project(... LANGUAGES ...) so the Xcode generator registers a build rule for .s sources, define LM_GGML_METAL_EMBED_LIBRARY=1, glob *.s from ggml-metal/ into the rnllama target, and set_source_files_properties(... LANGUAGE ASM).
• llama-rn.podspec — extend RNLLAMA_BUILD_FROM_SOURCE=1 source glob to include *.s, drop cpp/ggml-metal/ggml-metal.metal from s.resources, define the macro alongside LM_GGML_USE_METAL whenever Metal is enabled.
• scripts/build-ios.sh — stop copying ggml-metal.metal into the framework root in copy_framework_support_files.
• AGENTS.md — describe the new bootstrap step.
• cpp/ggml-metal/ggml-metal-embed.s — checked-in bootstrap output (mirrors how cpp/ggml-metal/ggml-metal.metal is already checked in).

Cross-platform porting notes (worth a quick look)

• od -An -vtx1 -w16 works on Linux/Git-Bash but macOS BSD od rejects -w16 with illegal option. The script omits -w16; both GNU and BSD od default to 16 bytes per line.
• The Mach-O section name is __ggml_metallib (15 chars), not __lm_ggml_metallib (18 chars). Mach-O caps section specifiers at 16 characters, so this had to drop the LM_ prefix. Only the exported symbols (_lm_ggml_metallib_start / _end) carry the LM_ prefix.
• Without LANGUAGES ASM on project(), the Xcode generator silently drops .s files from the build phase. The simulator x86_64 link step is the first to fail with Undefined symbols: _lm_ggml_metallib_start/_end. With LANGUAGES ASM + set_source_files_properties(... LANGUAGE ASM), all four xcframework slices compile and link cleanly.

Testing

• iPhone 13 mini (A15, iOS 26.5) — repro from [Bug] iOS: "Failed to load model" — default.metallib not bundled, runtime Metal source compilation fails with XPC_ERROR_CONNECTION_INTERRUPTED #348 with gemma-3-4B-it-Q4_K_M. initLlama succeeds and the native log shows:

  lm_ggml_metal_library_init: using embedded metal library
  lm_ggml_metal_library_init: loaded in 9.690 sec
  

  instead of the default.metallib not found … XPC_ERROR_CONNECTION_INTERRUPTED chain reported in the issue. (The 4B model itself then hits A15 Metal working-set limits — current allocated size is greater than the recommended max working set size — but that's an independent memory-pressure issue, not the [Bug] iOS: "Failed to load model" — default.metallib not bundled, runtime Metal source compilation fails with XPC_ERROR_CONNECTION_INTERRUPTED #348 XPC failure.)
• nm verification — _lm_ggml_metallib_start and _lm_ggml_metallib_end are present as data section symbols (S) in all four xcframework slices: ios-arm64, ios-arm64_x86_64-simulator, tvos-arm64, tvos-arm64_x86_64-simulator. No U (undefined) entries.
• npm run typecheck — clean.
• I did not run the macOS example smoke test from feat(ios): load ggml-metal.metal instead of prebuilt metallib #252 in this session; happy to add that pass and amend if you'd like the macOS path explicitly covered before merge.

Open questions

• Flag-gate? I kept the embed path unconditional rather than gating it behind an env var (e.g. LLAMA_METAL_EMBED=0 to fall back to the file-based path). Happy to add a flag if you'd prefer keeping the file-based path available as a fallback — let me know.
• Android scope — these changes are iOS-only. Android doesn't use Metal so it's a non-issue; not touching android/build.gradle.

🤖 Generated with Claude Code

[jhen0409]

Thanks! I also removed ggml-metal-embed.s and ignore it because it is not worth to track and it's also unreadable for diff.

• The latest CI failure looks not related to this PR.