fix: consistent macOS deployment target for Metal compatibility

Ensure cmake, the C++ compiler, and the Rust linker all use the same
macOS deployment target. Mismatch between these components causes
___isPlatformVersionAtLeast linking errors.

Resolution priority:
  1. MACOSX_DEPLOYMENT_TARGET env var (user override)
  2. Current system macOS version (via sw_vers)
  3. MLX minimum (14.0) as final fallback

Enforces a floor of macOS 14.0 (MLX's minimum requirement) with a
cargo warning if a lower target is requested.

Fixes: ml-explore/mlx#1602

Author: nicholasjpaterno

mlx-sys/build.rs

@@ -3,6 +3,65 @@ extern crate cmake;
 use cmake::Config;
 use std::{env, path::PathBuf, process::Command};
 
+/// MLX requires macOS >= 14.0 (Sonoma).
+#[cfg(target_os = "macos")]
+const MLX_MIN_MACOS_VERSION: &str = "14.0";
+
+/// Query the current macOS version via `sw_vers -productVersion`.
+#[cfg(target_os = "macos")]
+fn detect_macos_version() -> Option<String> {
+    let output = Command::new("sw_vers")
+        .args(["-productVersion"])
+        .output()
+        .ok()?;
+    if !output.status.success() {
+        return None;
+    }
+    let version = String::from_utf8_lossy(&output.stdout).trim().to_string();
+    if version.is_empty() {
+        None
+    } else {
+        Some(version)
+    }
+}
+
+/// Resolve the macOS deployment target.
+///
+/// Priority:
+///   1. `MACOSX_DEPLOYMENT_TARGET` env var (user override)
+///   2. Current system macOS version (via `sw_vers`)
+///   3. MLX minimum (14.0) as final fallback
+///
+/// Ensures the resolved target is at least [`MLX_MIN_MACOS_VERSION`].
+#[cfg(target_os = "macos")]
+fn resolve_deployment_target() -> String {
+    let target = env::var("MACOSX_DEPLOYMENT_TARGET")
+        .ok()
+        .or_else(detect_macos_version)
+        .unwrap_or_else(|| MLX_MIN_MACOS_VERSION.to_string());
+
+    // Parse major version to enforce minimum
+    let major: u32 = target
+        .split('.')
+        .next()
+        .and_then(|s| s.parse().ok())
+        .unwrap_or(14);
+    let min_major: u32 = MLX_MIN_MACOS_VERSION
+        .split('.')
+        .next()
+        .and_then(|s| s.parse().ok())
+        .unwrap_or(14);
+
+    if major < min_major {
+        eprintln!(
+            "cargo:warning=MACOSX_DEPLOYMENT_TARGET={target} is below MLX minimum ({MLX_MIN_MACOS_VERSION}), using {MLX_MIN_MACOS_VERSION}"
+        );
+        MLX_MIN_MACOS_VERSION.to_string()
+    } else {
+        target
+    }
+}
+
 /// Find the clang runtime library path dynamically using xcrun
 fn find_clang_rt_path() -> Option<String> {
     // Use xcrun to find the active toolchain path
@@ -53,6 +112,18 @@ fn build_and_link_mlx_c() {
     config.define("CMAKE_C_COMPILER", "/usr/bin/cc");
     config.define("CMAKE_CXX_COMPILER", "/usr/bin/c++");
 
+    // Ensure consistent macOS deployment target across cmake, C++ compiler, and Rust linker.
+    // Mismatch causes ___isPlatformVersionAtLeast linking errors.
+    // See: https://github.com/ml-explore/mlx/issues/1602
+    #[cfg(target_os = "macos")]
+    let deployment_target = {
+        let target = resolve_deployment_target();
+        config.define("CMAKE_OSX_DEPLOYMENT_TARGET", &target);
+        env::set_var("MACOSX_DEPLOYMENT_TARGET", &target);
+        println!("cargo:rerun-if-env-changed=MACOSX_DEPLOYMENT_TARGET");
+        target
+    };
+
     #[cfg(debug_assertions)]
     {
         config.define("CMAKE_BUILD_TYPE", "Debug");
@@ -97,6 +168,13 @@ fn build_and_link_mlx_c() {
         println!("cargo:rustc-link-lib=framework=Accelerate");
     }
 
+    // Pass matching deployment target to the Rust linker so all components agree.
+    #[cfg(target_os = "macos")]
+    println!(
+        "cargo:rustc-link-arg=-mmacosx-version-min={}",
+        deployment_target
+    );
+
     // Link against Xcode's clang runtime for ___isPlatformVersionAtLeast symbol
     // This is needed on macOS 26+ where the bundled LLVM runtime may be outdated
     // See: https://github.com/conda-forge/llvmdev-feedstock/issues/244