Gate NAX JIT sources by macOS SDK version#3426
Open
ausimian wants to merge 1 commit intoml-explore:mainfrom
Open
Gate NAX JIT sources by macOS SDK version#3426ausimian wants to merge 1 commit intoml-explore:mainfrom
ausimian wants to merge 1 commit intoml-explore:mainfrom
Conversation
MLX's JIT branch in backend/metal/CMakeLists.txt unconditionally runs
make_jit_source() on the NAX kernel sources. Those headers
transitively include <MetalPerformancePrimitives/...>, which only
ships with the macOS 26.2+ SDK, so MLX_METAL_JIT=ON currently fails
to build on older SDKs (e.g. Xcode 15.x on GitHub-hosted macos-14
runners), stopping at:
fatal error: 'MetalPerformancePrimitives/MetalPerformancePrimitives.h'
file not found
Mirror the same SDK gate the AOT branch already applies in
kernels/CMakeLists.txt (MLX_METAL_VERSION >= 400 AND
MACOS_SDK_VERSION >= 26.2). When the gate fails, define
MLX_METAL_NO_NAX so is_nax_available() returns false at runtime, and
emit a small generated .cpp with empty-string stubs for the NAX JIT
source providers (metal::gemm_nax, metal::quantized_nax, ...) so
jit_kernels.cpp still links. The stubs are never exercised because
the callers are guarded by is_nax_available().
No behavioural change on macOS 26.2+ SDK builds (gate passes; NAX JIT
sources are emitted as before). On older SDKs, JIT=ON now builds a
binary without NAX support, exactly mirroring how JIT=OFF already
behaves on the same SDK.
2251c30 to
1089f64
Compare
6 tasks
ausimian
added a commit
to ausimian/emily
that referenced
this pull request
Apr 19, 2026
Note the MetalPerformancePrimitives SDK gap on older Xcodes (e.g. GitHub's macos-14 runner) and point to the upstream fix at ml-explore/mlx#3426 so the patches/ directory can be retired once the submodule is bumped past it.
2 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Proposed changes
When
MLX_METAL_JIT=ON,backend/metal/CMakeLists.txtunconditionally invokesmake_jit_source()on the NAX kernel sources. Those headers transitively#include <MetalPerformancePrimitives/MetalPerformancePrimitives.h>, which only ships with the macOS 26.2+ SDK, so JIT builds currently fail on older SDKs (e.g. Xcode 15.x on GitHub-hostedmacos-14runners):The AOT branch in
kernels/CMakeLists.txtalready gates NAX by the same SDK check (MLX_METAL_VERSION GREATER_EQUAL 400 AND MACOS_SDK_VERSION GREATER_EQUAL 26.2). This PR mirrors that gate in the JIT branch:MLX_METAL_NO_NAX(sois_nax_available()returnsfalseat runtime) and emit a tiny generatednax_stubs.cppwith empty-string stubs for the NAX JIT source providers (metal::gemm_nax,metal::quantized_nax, …). The stubs are needed only sojit_kernels.cppstill links; they are never exercised at runtime because the NAX code paths are guarded byis_nax_available().On older SDKs,
MLX_METAL_JIT=ONnow produces the same no-NAX binary thatMLX_METAL_JIT=OFFalready does — it just uses the JIT path for the non-NAX kernels.Context
Discovered while plumbing
MLX_METAL_JIT=ONthrough a downstream consumer's CI (GitHub-hostedmacos-14/ Xcode 15.x). MLX's own CI builds JIT on a self-hosted runner with Xcode 26, so the upstream CI does not currently exercise the JIT path on older SDKs.Tested
MLX_METAL_JIT=ONon GitHub-hostedmacos-14— previously broken at thenax.hpreprocess step, now links and passes after this patch.Checklist
pre-commit run --all-filesto format my code / installed pre-commit prior to committing changes — CMake-only change; happy to runcmake-formatif the maintainers prefer a specific output.