Skip to content

Commit 351ee54

Browse files
[MLX] Isolate submodule build with ExternalProject
MLX was pulled into ExecuTorch's build via add_subdirectory, dropping MLX's whole CMake project into ET's target/option namespace. That shared scope collides with deps MLX fetches (today nlohmann_json), worked around by patching MLX's own CMakeLists.txt at configure time. Patching a submodule is fragile: the patch is pinned to specific lines and silently stops applying when an MLX bump touches that region, at which point the json collision returns with no clear signal. It also dirties the submodule and leaks MLX's MLX_BUILD_* options into ET's cache. Build MLX in its own isolated CMake scope via ExternalProject and consume it as a prebuilt static lib + metallib through an imported `mlx` target. MLX then runs its FetchContent in its own namespace, so the json collision cannot happen and the patch is deleted. The imported target re-adds the Metal/Foundation/ QuartzCore frameworks a static libmlx.a does not carry (matching the imported mlx target already in tools/cmake/executorch-config.cmake), and mlxdelegate depends on mlx_external directly since add_dependencies on an imported target does not order the build. The ExternalProject BINARY_DIR is kept at the same location add_subdirectory used, so libmlx.a and mlx.metallib land at their existing paths; downstream consumers (package config, metallib copy helper, the pybindings wheel in setup.py) need no changes. - Replace MLX_BUILD_* options + patch loop + add_subdirectory with ExternalProject_Add(mlx_external) and an imported `mlx` target. - install(TARGETS mlx) -> install(FILES ${_mlx_static_lib}), since an imported target cannot be installed via install(TARGETS). - Point the metallib install and MLX_METALLIB_PATH at ${_mlx_metallib}. - Delete backends/mlx/patches/mlx_json.patch and the patch-apply loop. Verified: cmake --preset mlx-release configures, builds, and installs; libmlx.a, libmlxdelegate.a, and mlx.metallib land in cmake-out/lib/; the MLX submodule stays pristine through configure/build/install; the delegate tests (op_test_runner, multi_thread_test_runner, mlx_mutable_state_test) build and link mlx directly, and mlx_mutable_state_test passes. Fixes #20556. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
1 parent 55a71e6 commit 351ee54

2 files changed

Lines changed: 80 additions & 113 deletions

File tree

‎backends/mlx/CMakeLists.txt‎

Lines changed: 80 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -162,83 +162,72 @@ if(NOT _mlx_deployment_target_ok)
162162
)
163163
endif()
164164

165-
# MLX build options - we only need the C++ library with Metal
166-
set(MLX_BUILD_PYTHON_BINDINGS
167-
OFF
168-
CACHE BOOL "" FORCE
165+
# Build MLX in its own isolated CMake scope via ExternalProject, then consume it
166+
# as a prebuilt static lib through an imported target (see below). Building MLX
167+
# with add_subdirectory would drop its whole project into ExecuTorch's
168+
# target/option namespace, which collides with shared deps MLX fetches (e.g.
169+
# nlohmann_json) and leaks MLX's MLX_BUILD_* options into our cache. The
170+
# isolated scope runs MLX's FetchContent in its own namespace, so no collision
171+
# and no submodule patching are needed.
172+
include(ExternalProject)
173+
174+
set(_mlx_binary_dir ${CMAKE_CURRENT_BINARY_DIR}/mlx)
175+
set(_mlx_static_lib ${_mlx_binary_dir}/libmlx.a)
176+
# With MLX_METAL_JIT=ON, MLX does not install the metallib; it is produced in
177+
# the build tree at this path.
178+
set(_mlx_metallib ${_mlx_binary_dir}/mlx/backend/metal/kernels/mlx.metallib)
179+
180+
message(
181+
STATUS "Building MLX from submodule (ExternalProject): ${MLX_SOURCE_DIR}"
169182
)
170-
set(MLX_BUILD_TESTS
171-
OFF
172-
CACHE BOOL "" FORCE
183+
ExternalProject_Add(
184+
mlx_external
185+
SOURCE_DIR ${MLX_SOURCE_DIR}
186+
BINARY_DIR ${_mlx_binary_dir}
187+
CMAKE_ARGS -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}
188+
-DCMAKE_CXX_STANDARD=${CMAKE_CXX_STANDARD}
189+
-DCMAKE_OSX_DEPLOYMENT_TARGET=${CMAKE_OSX_DEPLOYMENT_TARGET}
190+
-DCMAKE_TOOLCHAIN_FILE=${CMAKE_TOOLCHAIN_FILE}
191+
-DPLATFORM=${PLATFORM}
192+
-DDEPLOYMENT_TARGET=${DEPLOYMENT_TARGET}
193+
# We only need the static Metal C++ library.
194+
-DMLX_BUILD_METAL=ON
195+
-DMLX_BUILD_CPU=OFF
196+
-DMLX_BUILD_CUDA=OFF
197+
-DMLX_BUILD_SHARED_LIBS=OFF
198+
-DMLX_BUILD_PYTHON_BINDINGS=OFF
199+
-DMLX_BUILD_PYTHON_STUBS=OFF
200+
-DMLX_BUILD_TESTS=OFF
201+
-DMLX_BUILD_EXAMPLES=OFF
202+
-DMLX_BUILD_BENCHMARKS=OFF
203+
-DMLX_BUILD_GGUF=OFF
204+
-DMLX_BUILD_SAFETENSORS=OFF
205+
-DMLX_METAL_JIT=ON
206+
# MLX's own install() does not emit libmlx.a where we consume it or the
207+
# metallib at all, so skip the install step and read both from the build tree.
208+
INSTALL_COMMAND ""
209+
# Required so Ninja knows these are produced by the external build.
210+
BUILD_BYPRODUCTS ${_mlx_static_lib} ${_mlx_metallib}
173211
)
174-
set(MLX_BUILD_EXAMPLES
175-
OFF
176-
CACHE BOOL "" FORCE
177-
)
178-
set(MLX_BUILD_BENCHMARKS
179-
OFF
180-
CACHE BOOL "" FORCE
181-
)
182-
set(MLX_BUILD_PYTHON_STUBS
183-
OFF
184-
CACHE BOOL "" FORCE
185-
)
186-
set(MLX_BUILD_CUDA
187-
OFF
188-
CACHE BOOL "" FORCE
189-
)
190-
set(MLX_BUILD_CPU
191-
OFF
192-
CACHE BOOL "" FORCE
193-
)
194-
set(MLX_BUILD_METAL
195-
ON
196-
CACHE BOOL "" FORCE
197-
)
198-
set(MLX_BUILD_SHARED_LIBS
199-
OFF
200-
CACHE BOOL "" FORCE
201-
)
202-
set(MLX_BUILD_GGUF
203-
OFF
204-
CACHE BOOL "" FORCE
205-
)
206-
set(MLX_BUILD_SAFETENSORS
207-
OFF
208-
CACHE BOOL "" FORCE
209-
)
210-
set(MLX_METAL_JIT
211-
ON
212-
CACHE BOOL "Use JIT compiled Metal kernels"
213-
)
214-
215-
# Auto-apply patches to MLX submodule. Each patch is applied idempotently: `git
216-
# apply --check` tests whether the patch is still applicable (i.e. not yet
217-
# applied), and only then applies it.
218-
set(_mlx_patches "${CMAKE_CURRENT_SOURCE_DIR}/patches/mlx_json.patch")
219-
foreach(_patch IN LISTS _mlx_patches)
220-
if(EXISTS "${_patch}" AND EXISTS "${MLX_SOURCE_DIR}")
221-
get_filename_component(_patch_name "${_patch}" NAME)
222-
execute_process(
223-
COMMAND git apply --check "${_patch}"
224-
WORKING_DIRECTORY ${MLX_SOURCE_DIR}
225-
RESULT_VARIABLE _patch_check
226-
OUTPUT_QUIET ERROR_QUIET
227-
)
228-
if(_patch_check EQUAL 0)
229-
execute_process(
230-
COMMAND git apply "${_patch}" WORKING_DIRECTORY ${MLX_SOURCE_DIR}
231-
)
232-
message(STATUS "Applied ${_patch_name} to MLX submodule")
233-
else()
234-
message(STATUS "${_patch_name} already applied or not applicable")
235-
endif()
236-
endif()
237-
endforeach()
238212

239-
# Add MLX subdirectory
240-
message(STATUS "Adding MLX from submodule: ${MLX_SOURCE_DIR}")
241-
add_subdirectory(${MLX_SOURCE_DIR} ${CMAKE_CURRENT_BINARY_DIR}/mlx)
213+
# Imported target for the MLX static library produced by mlx_external. A static
214+
# libmlx.a carries no transitive link deps, so re-add the frameworks MLX itself
215+
# links (mirrors third-party/mlx/CMakeLists.txt:209). CPU is OFF, so Accelerate
216+
# is not needed.
217+
add_library(mlx STATIC IMPORTED GLOBAL)
218+
set_target_properties(mlx PROPERTIES IMPORTED_LOCATION ${_mlx_static_lib})
219+
# Headers come from the submodule source tree (always present), not the build
220+
# dir, so mlxdelegate compilation cannot race the external build.
221+
target_include_directories(mlx INTERFACE ${MLX_SOURCE_DIR})
222+
find_library(METAL_FRAMEWORK Metal)
223+
find_library(FOUNDATION_FRAMEWORK Foundation)
224+
find_library(QUARTZ_FRAMEWORK QuartzCore)
225+
set_target_properties(
226+
mlx
227+
PROPERTIES INTERFACE_LINK_LIBRARIES
228+
"${METAL_FRAMEWORK};${FOUNDATION_FRAMEWORK};${QUARTZ_FRAMEWORK}"
229+
)
230+
add_dependencies(mlx mlx_external)
242231

243232
# -----------------------------------------------------------------------------
244233
# MLX Backend library
@@ -266,6 +255,11 @@ add_library(mlxdelegate ${_mlx_backend__srcs})
266255
# Ensure schema is generated before compiling
267256
add_dependencies(mlxdelegate mlx_schema)
268257

258+
# mlx is an imported target, so add_dependencies(mlx mlx_external) above does
259+
# not order the build. Depend on mlx_external directly so libmlx.a exists before
260+
# mlxdelegate links.
261+
add_dependencies(mlxdelegate mlx_external)
262+
269263
# Add logging flag if enabled
270264
if(ET_MLX_ENABLE_OP_LOGGING)
271265
target_compile_definitions(mlxdelegate PRIVATE ET_MLX_ENABLE_OP_LOGGING=1)
@@ -283,8 +277,9 @@ target_include_directories(
283277
mlxdelegate PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/runtime
284278
)
285279

286-
# Link against MLX and executorch mlx is only available at BUILD_INTERFACE -
287-
# consumers must link to mlx separately
280+
# Link against MLX and executorch. mlx is an imported static lib (built by
281+
# mlx_external); it is only consumed at build time here, not re-exported, so
282+
# downstream consumers must link to mlx separately via the package config.
288283
target_link_libraries(
289284
mlxdelegate PRIVATE mlx_schema executorch_core $<BUILD_INTERFACE:mlx>
290285
)
@@ -301,8 +296,10 @@ install(
301296
DESTINATION ${CMAKE_INSTALL_LIBDIR}
302297
)
303298

304-
# Install mlx library for downstream consumers
305-
install(TARGETS mlx DESTINATION ${CMAKE_INSTALL_LIBDIR})
299+
# Install mlx library for downstream consumers. mlx is an imported target (built
300+
# by mlx_external), so install the static lib file directly rather than via
301+
# install(TARGETS ...), which only accepts built targets.
302+
install(FILES ${_mlx_static_lib} DESTINATION ${CMAKE_INSTALL_LIBDIR})
306303

307304
# Install mlx headers for downstream consumers that may need mlx types
308305
install(
@@ -325,16 +322,15 @@ install(
325322
# containing MLX code. When MLX is statically linked into _portable_lib.so, this
326323
# is the directory containing _portable_lib.so.
327324
#
328-
# For the installed library, we put metallib in lib/ alongside libmlx.a
329-
install(
330-
FILES ${CMAKE_CURRENT_BINARY_DIR}/mlx/mlx/backend/metal/kernels/mlx.metallib
331-
DESTINATION ${CMAKE_INSTALL_LIBDIR}
332-
)
325+
# For the installed library, we put metallib in lib/ alongside libmlx.a. The
326+
# metallib is produced in the mlx_external build tree (MLX_METAL_JIT=ON does not
327+
# install it); _mlx_metallib points there.
328+
install(FILES ${_mlx_metallib} DESTINATION ${CMAKE_INSTALL_LIBDIR})
333329

334330
# Cache the metallib path for pybindings to copy it next to _portable_lib.so
335331
# This enables editable installs to work correctly
336332
set(MLX_METALLIB_PATH
337-
"${CMAKE_CURRENT_BINARY_DIR}/mlx/mlx/backend/metal/kernels/mlx.metallib"
333+
"${_mlx_metallib}"
338334
CACHE INTERNAL "Path to mlx.metallib for pybindings"
339335
)
340336

‎backends/mlx/patches/mlx_json.patch‎

Lines changed: 0 additions & 29 deletions
This file was deleted.

0 commit comments

Comments
 (0)