Merge pull request #203 from ausimian/build/pin-macos-deployment-target

build: pin explicit per-variant macOS deployment targets

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"