update: unlock native Linux build for CMake and CPU backend only

.gitignore

@@ -90,3 +90,6 @@ fastlane/test_output
 
 iOSInjectionProject/
 .swiftpm
+
+# VS Code
+.vscode/

CMakeLists.txt

@@ -1,6 +1,25 @@
 cmake_minimum_required(VERSION 3.16)
 project(MLXSwift LANGUAGES C CXX Swift)
 
+# ----------------------------- Setup -----------------------------
+# note: 1:1 mirror of MLX configs
+
+set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake")
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+set(CMAKE_INSTALL_MESSAGE NEVER)
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+
+# ----------------------------- Configuration -----------------------------
+# note: mirrors a subset of MLX options exactly (1:1 mapping)
+
+option(MLX_BUILD_EXAMPLES "Build examples for mlx" ON)
+option(MLX_BUILD_METAL "Build metal backend" ON)
+# option(MLX_BUILD_CUDA "Build cuda backend" OFF)
+
+# ----------------------------- Lib -----------------------------
+
 include(FetchContent)
 # Avoid warning about DOWNLOAD_EXTRACT_TIMESTAMP in CMake 3.24:
 if(POLICY CMP0135)
@@ -26,6 +45,13 @@ FetchContent_MakeAvailable(swift-numerics)
 
 # MLX package
 file(GLOB MLX-src ${CMAKE_CURRENT_LIST_DIR}/Source/MLX/*.swift)
+
+# todo: add conditional logic for MLX_BUILD_CUDA (once implemented)
+if(NOT MLX_BUILD_METAL)
+  list(REMOVE_ITEM MLX-src ${CMAKE_CURRENT_LIST_DIR}/Source/MLX/GPU.swift
+       ${CMAKE_CURRENT_LIST_DIR}/Source/MLX/MLXArray+Metal.swift)
+endif()
+
 add_library(MLX STATIC ${MLX-src})
 target_include_directories(MLX
                            PUBLIC ${CMAKE_CURRENT_LIST_DIR}/Source/Cmlx/include)
@@ -65,12 +91,14 @@ add_library(MLXLinalg STATIC ${MLXLinalg-src})
 target_link_libraries(MLXLinalg PRIVATE MLX)
 
 # Examples
-add_executable(example1
-               ${CMAKE_CURRENT_LIST_DIR}/Source/Examples/Example1.swift)
-target_link_libraries(example1 PRIVATE MLX)
-target_compile_options(example1 PRIVATE -parse-as-library)
-
-add_executable(tutorial
-               ${CMAKE_CURRENT_LIST_DIR}/Source/Examples/Tutorial.swift)
-target_link_libraries(tutorial PRIVATE MLX)
-target_compile_options(tutorial PRIVATE -parse-as-library)
+if(MLX_BUILD_EXAMPLES)
+  add_executable(example1
+                 ${CMAKE_CURRENT_LIST_DIR}/Source/Examples/Example1.swift)
+  target_link_libraries(example1 PRIVATE MLX)
+  target_compile_options(example1 PRIVATE -parse-as-library)
+
+  add_executable(tutorial
+                 ${CMAKE_CURRENT_LIST_DIR}/Source/Examples/Tutorial.swift)
+  target_link_libraries(tutorial PRIVATE MLX)
+  target_compile_options(tutorial PRIVATE -parse-as-library)
+endif()

README.md

@@ -38,7 +38,7 @@ from MLX Python.
 
 ## Installation
 
-The ``MLX`` Swift package can be built and run from Xcode or SwiftPM. A CMake install is also provided.
+The ``MLX`` Swift package can be built and run from Xcode or SwiftPM. A CMake installation is also provided, featuring a native Linux build option.
 
 More details are in the [documentation](https://swiftpackageindex.com/ml-explore/mlx-swift/main/documentation/mlx/install).
 
@@ -95,14 +95,57 @@ brew install ninja
 With CMake:
 
 ```shell
-mkdir build
+mkdir -p build
 cd build
 cmake .. -G Ninja
 ninja
 ./example1
 ./tutorial
 ```
 
+<details>
+  <summary>Expand Native Linux Build Instructions</summary>
+
+  #### (1) Install Dependencies
+
+  RHEL/Fedora:
+  ```shell
+  sudo dnf install -y blas-devel lapack-devel openblas-devel clang llvm cmake make ninja
+  # Then install Swift by following the instructions at https://swift.org
+  ```
+
+  Ubuntu/Debian:
+  ```shell
+  sudo apt update;
+  sudo apt install -y libblas-dev liblapack-dev libopenblas-dev clang llvm cmake make ninja;
+  # Then install Swift by following the instructions at https://swift.org
+  ```
+
+  Refer to [swift.org](https://www.swift.org/install/linux/) for installation options and instructions specific to your Linux distribution.
+
+
+  #### (2) Build + Run Examples
+
+  On Linux, the examples use the CPU backend by default.
+
+  Note: GPU+CUDA support is a work in progress for `mlx-swift` on Linux, but is available in the Python-based MLX.
+
+  Note: SwiftPM builds are not currently supported for native Linux targets.
+
+  ```shell
+  mkdir -p build
+  cd build
+  cmake -DMLX_BUILD_METAL=OFF .. -G Ninja
+  ninja
+  ./example1
+  ./tutorial
+  ```
+
+
+</details>
+
+</br>
+
 ## Contributing
 
 Check out the [contribution guidelines](CONTRIBUTING.md) for more information

Source/Examples/Example1.swift

@@ -6,19 +6,19 @@ import MLX
 @main
 struct Example1 {
     static func main() {
-        // create from stride (sequence of 2, 4, 6, 8)
-        let arr = MLXArray(stride(from: Int32(2), through: 8, by: 2), [2, 2])
+        let osName = ProcessInfo.processInfo.operatingSystemVersionString.lowercased()
+        let device: Device = osName.contains("linux") ? .cpu : .gpu
+        Stream.withNewDefaultStream(device: device) {
+            let arr = MLXArray(stride(from: Int32(2), through: 8, by: 2), [2, 2])
 
-        print(arr)
-        print(arr.dtype)
-        print(arr.shape)
-        print(arr.ndim)
-        print(arr.asType(.int64))
+            print(arr)
+            print(arr.dtype)
+            print(arr.shape)
+            print(arr.ndim)
+            print(arr.asType(.int64))
 
-        // print a row
-        print(arr[1])
-
-        // print a value
-        print(arr[0, 1].item(Int32.self))
+            print(arr[1])
+            print(arr[0, 1].item(Int32.self))
+        }
     }
 }

Source/Examples/Tutorial.swift

@@ -96,10 +96,14 @@ struct Tutorial {
 
         assert(df2dx2.item() == Float(2))
     }
-
     static func main() {
-        scalarBasics()
-        arrayBasics()
-        automaticDifferentiation()
+        let osName = ProcessInfo.processInfo.operatingSystemVersionString.lowercased()
+        let device: Device = osName.contains("linux") ? .cpu : .gpu
+
+        Stream.withNewDefaultStream(device: device) {
+            scalarBasics()
+            arrayBasics()
+            automaticDifferentiation()
+        }
     }
 }

Source/MLX/IO.swift

@@ -214,11 +214,11 @@ private func new_mlx_io_vtable_dataIO() -> mlx_io_vtable {
         default:
             break
         }
-
     } read: { ptr, data, n in
         let state = Unmanaged<IOState>.fromOpaque(ptr!).takeUnretainedValue()
 
         if n + state.offset <= state.data.count {
+            guard let data = data else { return }
             _ = state.data.withUnsafeBytes { buffer in
                 memcpy(data, buffer.baseAddress!.advanced(by: state.offset), n)
             }
@@ -229,6 +229,7 @@ private func new_mlx_io_vtable_dataIO() -> mlx_io_vtable {
         let state = Unmanaged<IOState>.fromOpaque(ptr!).takeUnretainedValue()
 
         if n + offset <= state.data.count {
+            guard let data = data else { return }
             _ = state.data.withUnsafeBytes { buffer in
                 memcpy(data, buffer.baseAddress!.advanced(by: offset), n)
             }

Source/MLX/MLXArray+Bytes.swift

@@ -2,7 +2,6 @@
 
 import Cmlx
 import Foundation
-import Metal
 
 // MARK: - Backing / Bytes
 
@@ -275,32 +274,6 @@ extension MLXArray {
             .data
     }
 
-    /// Return the contents as a Metal buffer in the native ``dtype``.
-    ///
-    /// > If you can guarantee the lifetime of the ``MLXArray`` will exceed the MTLBuffer and that
-    /// the array will not be mutated (e.g. using indexing or other means) it is possible to pass `noCopy: true`
-    /// to reference the backing bytes.
-    ///
-    /// ### See Also
-    /// - <doc:conversion>
-    /// - ``asArray(_:)``
-    /// - ``asData(access:)``
-    public func asMTLBuffer(device: any MTLDevice, noCopy: Bool = false) -> (any MTLBuffer)? {
-        self.eval()
-
-        if noCopy && self.contiguousToDimension() == 0 {
-            // the backing is contiguous, we can provide a wrapper
-            // for the contents without a copy (if requested)
-            let source = UnsafeMutableRawPointer(mutating: mlx_array_data_uint8(self.ctx))!
-            return device.makeBuffer(bytesNoCopy: source, length: self.nbytes)
-        } else {
-            let data = asDataCopy()
-            return data.data.withUnsafeBytes { ptr in
-                device.makeBuffer(bytes: ptr.baseAddress!, length: ptr.count)
-            }
-        }
-    }
-
 }
 
 /// Return the strides for contiguous memory

Source/MLX/MLXArray+Metal.swift

@@ -0,0 +1,37 @@
+// Copyright © 2025 Apple Inc.
+
+import Cmlx
+import Foundation
+import Metal
+
+// MARK: - Metal
+
+extension MLXArray {
+
+    /// Return the contents as a Metal buffer in the native ``dtype``.
+    ///
+    /// > If you can guarantee the lifetime of the ``MLXArray`` will exceed the MTLBuffer and that
+    /// the array will not be mutated (e.g. using indexing or other means) it is possible to pass `noCopy: true`
+    /// to reference the backing bytes.
+    ///
+    /// ### See Also
+    /// - <doc:conversion>
+    /// - ``asArray(_:)``
+    /// - ``asData(access:)``
+    public func asMTLBuffer(device: any MTLDevice, noCopy: Bool = false) -> (any MTLBuffer)? {
+        self.eval()
+
+        if noCopy && self.contiguousToDimension() == 0 {
+            // the backing is contiguous, we can provide a wrapper
+            // for the contents without a copy (if requested)
+            let source = UnsafeMutableRawPointer(mutating: mlx_array_data_uint8(self.ctx))!
+            return device.makeBuffer(bytesNoCopy: source, length: self.nbytes)
+        } else {
+            let data = asDataCopy()
+            return data.data.withUnsafeBytes { ptr in
+                device.makeBuffer(bytes: ptr.baseAddress!, length: ptr.count)
+            }
+        }
+    }
+
+}

Source/MLX/MLXArray.swift

@@ -2,7 +2,6 @@
 
 import Cmlx
 import Foundation
-import Metal
 import Numerics
 
 public final class MLXArray {

Source/MLX/State.swift

@@ -32,7 +32,7 @@ extension MLXRandom {
 
         /// Initialize the RandomState with a seed based on the current time.
         public init() {
-            let now = mach_approximate_time()
+            let now = DispatchTime.now().uptimeNanoseconds
             state = MLXRandom.key(now)
         }
 

Source/MLXNN/Module.swift

@@ -462,7 +462,7 @@ open class Module {
                 }
                 p._updateInternal(newArray)
 
-            case (.value(.parameters(let p)), .none):
+            case (.value(.parameters), .none):
                 if Self.parameterIsValid(key) {
                     throw UpdateError.keyNotFound(path: path, modules: modulePath)
                 } else {