build: pin explicit per-variant macOS deployment targets

The MLX build and NIF link set no deployment target, so MLX's objects
inherited the build host's OS (CMake "build for host") while the NIF
linked at the SDK-major .0 — producing `ld` version-mismatch warnings
and a shipped floor that drifts with the runner OS. An aot build done on
a macOS-26 host silently linked the macOS-26 libSystem `_Float16` helpers
(`__fmaxf16`/`__fminf16`) as hard imports, so it would fail to dyld-load
on the older macOS the aot variant is meant to support.

Pin an explicit per-variant floor (aot 14.0; jit 26.2, since its NAX
kernels and JACCL are gated on macOS SDK >= 26.2) and thread it through
both the MLX CMake build (CMAKE_OSX_DEPLOYMENT_TARGET) and the NIF
compile/link (MACOSX_DEPLOYMENT_TARGET) from one source of truth in
mix.exs. The floor is folded into the MLX cache dir name so a change
can't reuse a stale build. scripts/verify-nif-floor.sh asserts the built
NIF's LC_BUILD_VERSION and that a sub-26 floor imports no macOS-26
symbols; CI and the release workflow run it per variant.

Closes #202.

Author: ausimian

.github/workflows/ci.yml

@@ -38,8 +38,10 @@ jobs:
         include:
           - os: macos-14
             variant: aot
+            min: "14.0"
           - os: macos-26
             variant: jit
+            min: "26.2"
     env:
       MIX_ENV: test
       EMILY_MLX_VARIANT: ${{ matrix.variant }}
@@ -79,7 +81,7 @@ jobs:
         uses: actions/cache@v5
         with:
           path: ~/Library/Caches/emily
-          key: mlx-${{ runner.os }}-${{ matrix.variant }}-${{ hashFiles('c_src/**', 'Makefile', 'mix.exs') }}
+          key: mlx-${{ runner.os }}-${{ matrix.variant }}-${{ hashFiles('c_src/**', 'Makefile', 'mix.exs', 'scripts/build-mlx.sh') }}
           restore-keys: mlx-${{ runner.os }}-${{ matrix.variant }}-
 
       # The Bumblebee cache holds tiny-random HuggingFace fixtures
@@ -97,6 +99,12 @@ jobs:
 
       - run: mix precommit
 
+      # Assert the built NIF declares the pinned macOS floor for this variant
+      # and imports no above-floor libSystem symbols (see the script). Catches
+      # a variant that silently requires a newer macOS than it targets.
+      - name: Verify NIF macOS floor
+        run: bash scripts/verify-nif-floor.sh _build/test/lib/emily/priv/libemily.so "${{ matrix.min }}"
+
       # Conformance tests are excluded from the default suite because
       # they require network access on a cold cache (see
       # test/test_helper.exs). In CI we always want them green — a
@@ -120,8 +128,10 @@ jobs:
         include:
           - os: macos-14
             variant: aot
+            min: "14.0"
           - os: macos-26
             variant: jit
+            min: "26.2"
     env:
       MIX_ENV: test
       EMILY_MLX_VARIANT: ${{ matrix.variant }}
@@ -158,7 +168,7 @@ jobs:
         uses: actions/cache@v5
         with:
           path: ~/Library/Caches/emily
-          key: mlx-${{ runner.os }}-${{ matrix.variant }}-${{ hashFiles('c_src/**', 'Makefile', 'mix.exs') }}
+          key: mlx-${{ runner.os }}-${{ matrix.variant }}-${{ hashFiles('c_src/**', 'Makefile', 'mix.exs', 'scripts/build-mlx.sh') }}
           restore-keys: mlx-${{ runner.os }}-${{ matrix.variant }}-
 
       # Full checkpoints land here (Bumblebee + scidata MNIST).

.github/workflows/release-nif.yml

@@ -78,8 +78,8 @@ jobs:
           # sources transitively include
           # <MetalPerformancePrimitives/MetalPerformancePrimitives.h>,
           # first shipped in the macOS 26.2 SDK.
-          - { variant: aot, target: macos-arm64, runs-on: macos-14 }
-          - { variant: jit, target: macos-arm64, runs-on: macos-26 }
+          - { variant: aot, target: macos-arm64, runs-on: macos-14, min: "14.0" }
+          - { variant: jit, target: macos-arm64, runs-on: macos-26, min: "26.2" }
     runs-on: ${{ matrix.runs-on }}
     env:
       MIX_ENV: dev
@@ -118,6 +118,11 @@ jobs:
 
       - run: mix compile
 
+      # Guard the shipped artifact: assert it declares the pinned macOS floor
+      # and imports no above-floor libSystem symbols before it's packaged.
+      - name: Verify NIF macOS floor
+        run: bash scripts/verify-nif-floor.sh _build/dev/lib/emily/priv/libemily.so "${{ matrix.min }}"
+
       - name: Package NIF tarball
         id: pack
         env:

RELEASE.md

@@ -1,5 +1,10 @@
 ### Changed
 
+- The precompiled NIF now declares an explicit minimum macOS per variant —
+  macOS 14 for the AOT build, macOS 26.2 for the JIT build — instead of
+  inheriting whatever macOS the release runner happened to be on. Published
+  artifacts now have a deterministic macOS compatibility floor, and CI
+  asserts it on every build.
 - Updated the pinned MLX to 0.32.0. This is a maintenance bump that also
   picks up faster small-batch quantized matvec (`qmv_wide`) — accelerating
   the fused quantized path — and broader fused SDPA coverage (asymmetric

mix.exs

@@ -348,7 +348,14 @@ defmodule Emily.MixProject do
       "MLX_DIR" => dir,
       "MLX_INCLUDE_DIR" => Path.join(dir, "include"),
       "MLX_LIB_DIR" => Path.join(dir, "lib"),
-      "FINE_INCLUDE_DIR" => Fine.include_dir()
+      "FINE_INCLUDE_DIR" => Fine.include_dir(),
+      # Compile + link the NIF at the same macOS floor the vendored libmlx.a
+      # was built for (see `macos_deployment_target/0`). clang honours this
+      # env var for both the object compiles and the final link, so the NIF
+      # and the static MLX objects agree on `LC_BUILD_VERSION` — no `ld`
+      # version-mismatch warnings — and the shipped .so declares a
+      # deterministic minimum rather than inheriting the build host's OS.
+      "MACOSX_DEPLOYMENT_TARGET" => macos_deployment_target()
     }
   end
 
@@ -426,7 +433,31 @@ defmodule Emily.MixProject do
   end
 
   defp mlx_install_dir,
-    do: Path.join(cache_dir(), "mlx-#{@mlx_version}-#{mlx_variant()}")
+    do:
+      Path.join(
+        cache_dir(),
+        "mlx-#{@mlx_version}-#{mlx_variant()}-min#{macos_deployment_target()}"
+      )
+
+  # Minimum macOS each MLX variant targets, pinned explicitly rather than
+  # inheriting the build host's OS version. Threaded into both halves of the
+  # build — the MLX source build via `CMAKE_OSX_DEPLOYMENT_TARGET`
+  # (see scripts/build-mlx.sh) and the NIF compile/link via
+  # `MACOSX_DEPLOYMENT_TARGET` (see make_env/0) — and folded into the cache
+  # dir name above so changing a floor can't silently reuse a stale MLX build.
+  #
+  #   * aot — the older-macOS-compatible path (built on macOS 14 in CI).
+  #     MLX's own hard floor is 14.0.
+  #   * jit — 26.2: its NAX kernels and the JACCL backend are gated on macOS
+  #     SDK >= 26.2 (deps/mlx_src/CMakeLists.txt), and the macOS-26 libSystem
+  #     `_Float16` helpers (`__fmaxf16`/`__fminf16`) it links aren't present on
+  #     earlier releases, so it isn't portable below 26.2.
+  defp macos_deployment_target do
+    case mlx_variant() do
+      "jit" -> "26.2"
+      _ -> "14.0"
+    end
+  end
 
   defp arch_tag do
     case {:os.type(), :erlang.system_info(:system_architecture) |> to_string()} do
@@ -495,7 +526,7 @@ defmodule Emily.MixProject do
       :binary,
       :exit_status,
       :stderr_to_stdout,
-      {:args, [mlx_src, @mlx_version, jit_flag, install_dir]}
+      {:args, [mlx_src, @mlx_version, jit_flag, install_dir, macos_deployment_target()]}
     ]
 
     port = Port.open({:spawn_executable, String.to_charlist(script)}, port_opts)

scripts/build-mlx.sh

@@ -4,7 +4,7 @@
 # `compile.emily_mlx` compiler step; not intended for direct use.
 #
 # Usage:
-#   scripts/build-mlx.sh <mlx-src-dir> <mlx-version> <jit 0|1> <install-prefix>
+#   scripts/build-mlx.sh <mlx-src-dir> <mlx-version> <jit 0|1> <install-prefix> <macos-min>
 #
 # <install-prefix> ends up with an {include,lib} layout that mix.exs
 # exports to the NIF build via `MLX_INCLUDE_DIR` / `MLX_LIB_DIR`.
@@ -17,15 +17,20 @@ set -euo pipefail
 # ninja) still resolve.
 export PATH="/usr/bin:/bin:/usr/sbin:/sbin:${PATH}"
 
-if [[ $# -ne 4 ]]; then
-  echo "usage: $0 <mlx-src-dir> <mlx-version> <jit 0|1> <install-prefix>" >&2
+if [[ $# -ne 5 ]]; then
+  echo "usage: $0 <mlx-src-dir> <mlx-version> <jit 0|1> <install-prefix> <macos-min>" >&2
   exit 2
 fi
 
 MLX_SRC_DIR="$1"
 VERSION="$2"
 JIT="$3"
 PREFIX="$4"
+# Explicit macOS deployment target (e.g. 14.0 for aot, 26.2 for jit). Pins the
+# floor for MLX's objects instead of MLX's default "build for the host" (its
+# CMakeLists sets CMAKE_OSX_DEPLOYMENT_TARGET to the builder's OS otherwise),
+# so the artifacts don't drift with the runner and match the NIF link target.
+MACOS_MIN="$5"
 
 case "$JIT" in
   0) VARIANT="aot"; METAL_JIT="OFF" ;;
@@ -178,6 +183,7 @@ CMAKE_BUILD_PARALLEL_LEVEL=1 cmake \
   -S "$MLX_SRC_DIR" \
   -B "$BUILD_DIR" \
   -DCMAKE_BUILD_TYPE=Release \
+  -DCMAKE_OSX_DEPLOYMENT_TARGET="$MACOS_MIN" \
   -DCMAKE_INSTALL_PREFIX="$STAGING" \
   -DBUILD_SHARED_LIBS=OFF \
   -DMLX_BUILD_TESTS=OFF \

scripts/verify-nif-floor.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Assert a built NIF's macOS floor matches the pinned deployment target, and
+# that it imports no libSystem symbols newer than that floor. Run by CI after
+# `mix compile` (and usable locally) so the shipped precompiled NIF's minimum
+# macOS is a checked invariant rather than an accident of the build host.
+#
+# Guards specifically against the failure mode that motivated the pin: an aot
+# build done on a macOS-26 host silently linking the 26.0 `_Float16` helpers
+# `__fmaxf16`/`__fminf16` (hard, non-weak imports from libSystem), which would
+# fail to dyld-load on the older macOS the aot variant is supposed to support.
+#
+# Usage: scripts/verify-nif-floor.sh <libemily.so> <expected-min>
+#   e.g. scripts/verify-nif-floor.sh _build/test/lib/emily/priv/libemily.so 14.0
+
+set -euo pipefail
+
+if [[ $# -ne 2 ]]; then
+  echo "usage: $0 <libemily.so> <expected-min>" >&2
+  exit 2
+fi
+
+SO="$1"
+EXPECTED="$2"
+
+[[ -f "$SO" ]] || { echo "error: NIF not found: $SO" >&2; exit 2; }
+
+# 1) Declared minimum — LC_BUILD_VERSION's `minos`.
+minos=$(otool -l "$SO" | awk '/LC_BUILD_VERSION/{f=1} f && /^ *minos/{print $2; exit}')
+if [[ "$minos" != "$EXPECTED" ]]; then
+  echo "error: $SO declares minos '${minos:-<none>}', expected '$EXPECTED'" >&2
+  exit 1
+fi
+echo "ok: $SO declares minos $EXPECTED"
+
+# 2) No above-floor libSystem symbols. macOS 26 added the `_Float16` helpers
+#    __fmaxf16/__fminf16; a sub-26 floor must not import them (they resolve
+#    from libSystem at load and are absent on earlier macOS).
+major=${EXPECTED%%.*}
+if (( major < 26 )); then
+  if nm -u "$SO" 2>/dev/null | grep -qE '___(fmaxf16|fminf16)'; then
+    echo "error: $SO (floor $EXPECTED) imports macOS-26 _Float16 symbols:" >&2
+    nm -u "$SO" | grep -E '___(fmaxf16|fminf16)' >&2
+    exit 1
+  fi
+  echo "ok: $SO imports no macOS-26 _Float16 symbols"
+fi
+
+echo "NIF floor verified: $SO -> macOS $EXPECTED"