Skip to content

build : use umbrella Headers directory for XCFramework module map#23974

Merged
danbev merged 1 commit into
ggml-org:masterfrom
gmarzjr:fix-xcframework-modulemap
Jun 4, 2026
Merged

build : use umbrella Headers directory for XCFramework module map#23974
danbev merged 1 commit into
ggml-org:masterfrom
gmarzjr:fix-xcframework-modulemap

Conversation

@gmarzjr
Copy link
Copy Markdown
Contributor

@gmarzjr gmarzjr commented Jun 1, 2026

Overview

The XCFramework generated by build-xcframework.sh creates a module map that manually lists public headers.

That list can fall out of sync with the framework's Headers directory. The module map is currently missing ggml-opt.h, which is present in the framework headers. This can cause downstream Apple builds to fail with:

Include of non-modular header inside framework module 'llama'

Use the framework's Headers directory itself as the module map umbrella instead of maintaining a manual header list. This makes all public headers under the generated framework's Headers directory part of the llama module.

Additional information

The generated llama.xcframework contains a llama.framework bundle. Inside that framework, the public headers are copied into llama.framework/Headers, and llama.framework/Modules/module.modulemap tells Clang which of those headers belong to the importable llama module.

This issue shows up when a downstream Apple build imports the generated framework as a module. In that case, Clang expects headers included by llama.h to also be declared by the framework's module map. Since ggml-opt.h is present in llama.framework/Headers but missing from module.modulemap, the import can fail as a non-modular include.

Projects that build llama.cpp directly from source, or consume the headers without importing the generated framework module, may not hit this error.

Verification:

  • Built the XCFramework before this change and consumed it from a downstream iOS build.
  • The build failed because llama.h includes ggml-opt.h, but ggml-opt.h was not listed in the generated module map.
  • Rebuilt the XCFramework after this change.
  • The same build succeeded.

Requirements

  • I have read and agree with the contributing guidelines
  • AI usage disclosure: Yes - I wrote and reviewed the code change. AI was used to analyze before/after build logs and review commit/PR wording.

The XCFramework generated by build-xcframework.sh creates a module map
that manually lists public headers.

That list can fall out of sync with the framework's Headers directory.
The module map is currently missing ggml-opt.h, which is present in the
framework headers. This can cause downstream Apple builds to fail with:

    Include of non-modular header inside framework module 'llama'

Use the framework's Headers directory itself as the module map umbrella
instead of maintaining a manual header list. This makes all public headers
under the generated framework's Headers directory part of the llama module.
@gmarzjr gmarzjr requested a review from danbev as a code owner June 1, 2026 14:03
@danbev danbev requested a review from ggerganov June 4, 2026 10:47
@danbev danbev merged commit 4d74287 into ggml-org:master Jun 4, 2026
3 checks passed
gabe-l-hart added a commit to gabe-l-hart/llama.cpp that referenced this pull request Jun 4, 2026
* origin/master: (57 commits)
server : disable on-device spec checkpoints (ggml-org#24108)
arg: fix double mtp downloads (ggml-org#24128)
webui: [a11y] fix keyboard navigation issues in chat interface and sidebar (ggml-org#23132)
Move duplicated imatrix code into single common imatrix-loader.cpp (ggml-org#22445)
ui: Fixed packages (ggml-org#24119)
ui: added single line reasoning preview (ggml-org#23601)
return filter to save memory (ggml-org#24125)
convert: Fix Gemma 4 Unified conversion (ggml-org#24118)
ggml: vectorize ggml_vec_dot_q4_1_q8_1 with WASM SIMD128 (ggml-org#22209)
server: avoid unnecessary checkpoint restore when new tokens are present (ggml-org#24110)
agents: refactor, include more guidelines (ggml-org#24111)
webui: fix tool selector toggle/counter, key tools by stable identity (ggml-org#24065)
build : use umbrella Headers directory for XCFramework module map (ggml-org#23974)
server : add header to tools/server/server-http.h (ggml-org#24089)
cmake: skip cvector-generator and export-lora when CPU backend is disabled (ggml-org#24053)
fix(mtmd): handle Gemma 4 audio projector embedding size (ggml-org#24091)
readme : add status badges (ggml-org#24104)
tests : refactor test-save-load-state to accept token input (ggml-org#24073)
metal : reduce rset heartbeat from 500ms -> 5ms (ggml-org#24074)
ggml-webgpu: FlashAttention refactor + standardize quantization support (ggml-org#23834)
...
jimbothigpen pushed a commit to jimbothigpen/llama.cpp that referenced this pull request Jun 6, 2026
…ml-org#23974)

The XCFramework generated by build-xcframework.sh creates a module map
that manually lists public headers.

That list can fall out of sync with the framework's Headers directory.
The module map is currently missing ggml-opt.h, which is present in the
framework headers. This can cause downstream Apple builds to fail with:

    Include of non-modular header inside framework module 'llama'

Use the framework's Headers directory itself as the module map umbrella
instead of maintaining a manual header list. This makes all public headers
under the generated framework's Headers directory part of the llama module.

(cherry picked from commit 4d74287)
jimbothigpen pushed a commit to jimbothigpen/llama.cpp that referenced this pull request Jun 6, 2026
…ml-org#23974)

The XCFramework generated by build-xcframework.sh creates a module map
that manually lists public headers.

That list can fall out of sync with the framework's Headers directory.
The module map is currently missing ggml-opt.h, which is present in the
framework headers. This can cause downstream Apple builds to fail with:

    Include of non-modular header inside framework module 'llama'

Use the framework's Headers directory itself as the module map umbrella
instead of maintaining a manual header list. This makes all public headers
under the generated framework's Headers directory part of the llama module.

(cherry picked from commit 4d74287)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants