metal-linalg 2.2.0__tar.gz

metal_linalg-2.2.0/.gitignore

@@ -0,0 +1,24 @@
+# Build directories
+build*/
+cmake-build-*/
+.build/
+.swiftpm/
+Package.resolved
+
+# Compiled Metal shaders (generated by CMake from the .metal sources)
+*.air
+*.metallib
+!shaders/prebuilt/*.metallib
+
+# IDE
+.idea/
+.vscode/
+.DS_Store
+
+# Python bytecode
+__pycache__/
+
+# Written by tuning/tune_{qr,eigh,svd}.py (committed copies live in docs/results/)
+qr-tune-results/
+eigh-tune-results/
+svd-tune-results/

metal_linalg-2.2.0/CHANGELOG.md

@@ -0,0 +1,162 @@
+# Changes
+
+## 2.2.0 (2026-10-02)
+
+- **The Python package is on PyPI**: `pip install metal-linalg` installs a
+  prebuilt wheel (Apple Silicon, macOS 14+, Python 3.10 to 3.14) and the MLX
+  it was built against, which it pins exactly (`mlx==0.32.3`). Every release
+  builds, checks and tests the wheels and publishes them
+  ([wheels.yml](.github/workflows/wheels.yml)). Building from source no
+  longer needs `--no-build-isolation`: the build fetches the pinned MLX and
+  nanobind itself.
+- The Python build accepts nanobind 3's ABI, which the pip MLX uses from
+  0.32.3 (nanobind 3.0.1); it still builds against MLX built with nanobind
+  2.x, such as Homebrew's.
+- The Python tests check residuals with CPU matmuls: MLX 0.32.3 multiplies
+  float32 on the M5's GPU to only about 1e-2, which failed checks of results
+  that are accurate to 1e-6.
+
+## 2.1.0 (2026-10-02)
+
+- **QR has a CPU path**, like the eigensolver and the SVD: LAPACK's `sgeqrf`
+  and `sorgqr`, for lone and small-batch calls that do not pay for a GPU
+  launch (on an M5 Pro, 4 matrices of 64×64 take 0.13 ms on the CPU against
+  1.04 ms on the GPU). `QrPolicy` gains the GPU-or-CPU boundary
+  (`gpu_max_k`, `gpu_min_batch_times_k`, `gpu_min_batch`), with the
+  `QR_GPU_*` and `QR_DEVICE` environment overrides; `QrBackend::cpu`,
+  `qr_gpu_backend()`, `qr_uses_gpu()` and `detail::qr_cpu` are new, and the C,
+  Python and Swift APIs follow. The QR sweep times the CPU and the tuner fits
+  the boundary; a device measured before this keeps sending every QR call to
+  the GPU until it is measured again. See [docs/qr.md](docs/qr.md).
+- The QR guide documents the backends' sign conventions for R's diagonal,
+  which differ, and how to normalise them.
+
+## 2.0.1 (2026-10-01)
+
+- metal-linalg is licensed under the MIT licence ([LICENSE](LICENSE)).
+
+## 2.0.0 (2026-10-01)
+
+The project is renamed from `qr-apple-silicon` to **metal-linalg**, since it
+now covers three decompositions, and is packaged as a library.
+
+### New
+
+- **Symmetric eigensolver**: `eigh_accelerated`, `eigvalsh_accelerated`. Cyclic
+  Jacobi in two kernels, a whole-matrix kernel (simd and threadgroup modes)
+  and a block kernel that spreads one matrix over the GPU, with a per-device
+  route to MLX's CPU `eigh` where that is faster. See [docs/eigh.md](docs/eigh.md).
+- **Thin SVD**: `svd_accelerated`, `svdvals_accelerated`. One-sided Jacobi in a
+  whole-matrix and a block kernel, each optionally after this library's QR for
+  tall input, with a per-device route to the CPU. See [docs/svd.md](docs/svd.md).
+- **Per-device routing policies** for all three solvers, measured on an Apple
+  M1 (QR, eigh) and an Apple M5 Pro (all three), with environment and
+  programmatic overrides.
+- **Measuring a Mac is one command**, `python3 tuning/run.py`: it checks the
+  machine, builds, tests, measures all three decompositions and writes a
+  uniquely named submission (`docs/results/<device>/<date>-<random>/`), so any
+  number of people with the same Mac can contribute.
+  The library's per-device tables (`src/tuned/`) are generated from every
+  run submitted for each device, by `tuning/generate_tables.py`, which a
+  GitHub Action runs on each results pull request (to validate it and show the
+  effect) and after each merge (to apply it). See [docs/tuning.md](docs/tuning.md). For QR
+  this replaces the fixed rule of 1.0 with a crossover on the row count alone,
+  measured over square, tall, wide and near-square shapes
+  ([study](docs/studies/qr-routing-apple-m1.md)).
+- **Python package** `metal_linalg` (`python/`, `pyproject.toml`): `qr`, `eigh`,
+  `eigvalsh`, `svd`, `svdvals` on `mlx.core` arrays, the routing queries and
+  policies. Compiled against the installed MLX and sharing its arrays without
+  copying; see [python/README.md](python/README.md).
+- **A core without MLX**, on plain float buffers: `<metal_linalg/core.h>`
+  (`core::qr`, `core::eigh`, `core::svd` and every backend). The MLX API is
+  now a thin layer over it, with the same names and signatures as before.
+  `-DMETAL_LINALG_WITH_MLX=OFF` builds the core alone.
+- **A C API**, `<metal_linalg/c_api.h>`: the decompositions, routing queries
+  and policies behind C types, with status codes and per-thread error
+  messages. See [docs/c-api.md](docs/c-api.md).
+- **A Swift package**: `MetalLinalg` on `[Float]`, and `MetalLinalgMLX` on
+  mlx-swift's `MLXArray`, built on the C API; the shaders reach it through
+  C23 `#embed` of `shaders/prebuilt/`. See [docs/swift.md](docs/swift.md).
+- **Objective-C**: a guide, [docs/objective-c.md](docs/objective-c.md), and
+  `examples/objc_quickstart.mm`; Objective-C can use the MLX API from `.mm`
+  files or the C API from anywhere.
+- Every measurement run records the exact Mac (e.g. "MacBook Pro (16-inch, M5
+  Pro)"), and its power and thermal state after each part of the run; a
+  device's combined summary compares the runs by machine, to find outliers.
+- [CONTRIBUTING.md](CONTRIBUTING.md): measuring a Mac and sending the results as a
+  pull request (with the GitHub CLI, with git alone, or as a zip on an issue).
+- [docs/reading-reports.md](docs/reading-reports.md) explains every number in
+  a measurement report, with worked examples from the M5 Pro run.
+- `<metal_linalg/device.h>`: `device_name()`, `gpu_core_count()`.
+- `<metal_linalg/metal_linalg.h>`, which includes everything.
+- `qr_backend(m, n, batch)`, like `eigh_backend` and `svd_backend`.
+- `sweep_qr --policy`, like the other two sweeps.
+- `examples/`: five self-checking programs (a quick start, orthonormal bases
+  with QR, PCA with eigh, the nearest orthogonal matrix with the SVD, and the
+  routing queries), built with the tests and run by `ctest`.
+
+### Packaging
+
+- The compiled shaders are embedded in the library, so an installed
+  `libmetal_linalg` is self-contained: nothing is looked up on disk at run
+  time and consumers need no Metal compiler. Without the compiler the build
+  uses the metallibs committed under `shaders/prebuilt/`.
+- A CMake package: `find_package(MetalLinalg)` and
+  `metal_linalg::metal_linalg`. As a subproject (`add_subdirectory`,
+  `FetchContent`) it builds static and installs nothing.
+- A Homebrew formula, in its own tap, [c0rmac/homebrew-metal-linalg](https://github.com/c0rmac/homebrew-metal-linalg):
+  `brew tap c0rmac/metal-linalg`, `brew trust c0rmac/metal-linalg`, then `brew install metal-linalg`.
+- **Releases are automatic**: every update to `main` that changes the library
+  publishes the next version (a tag, a GitHub release with its source tarball)
+  and points the Homebrew formula at it. See CONTRIBUTING.md, "Releases".
+
+### Breaking changes
+
+| 1.x | 2.0 |
+|---|---|
+| namespace `custom_math` | `metal_linalg` |
+| `#include "qr.h"`, `"qr_detail.h"` | `#include <metal_linalg/qr.h>` (the `detail` backends are in it) |
+| `DispatchPolicy` | `QrPolicy` |
+| `dispatch_policy()`, `dispatch_policy_source()`, `set_dispatch_policy()` | `qr_policy()`, `qr_policy_source()`, `set_qr_policy()` |
+| `m_crossover_for_batch(p, batch)` | `qr_backend(m, n, batch)` |
+| CMake target `qr_metal` | `metal_linalg::metal_linalg` |
+
+### Changed
+
+- **The CPU paths call LAPACK directly**: `ssyevd` for eigh and `sgesdd` for
+  the SVD (Accelerate, after a thin QR for tall input), instead of MLX's CPU
+  `eigh` and `svd`. On an M5 Pro the eigensolver's CPU path is as fast as
+  before and the SVD's is as fast on square and wide shapes and 5-25% faster
+  on tall ones. Non-finite input gives NaN on the CPU too, for that matrix
+  alone, as on the GPU. The routing tables were measured against the old
+  paths and are due to be remeasured.
+- The eigensolver's tuning sweep times the library's own CPU path, as the
+  SVD's already did, rather than MLX's.
+
+### Fixes
+
+- **QR was not scale-invariant.** The kernels compare squared column norms
+  with an absolute threshold, so entries around 1e-3 lost accuracy, below 1e-5
+  the factorisation failed, and above 1e+18 it returned NaN. Every matrix is
+  now scaled by an exact power of two on the way in.
+- **QR discarded real data for nearly dependent columns**: the reflection
+  threshold (1e-7 on a squared norm) treated column tails shorter than 3e-4 of
+  the matrix's scale as zero. It is now 1e-30, which only guards the division.
+- **The streaming QR backends could write past their buffers.** Their cached
+  workspaces were keyed by the padded shape but sized by the exact one, so a
+  call whose shape padded like an earlier, smaller one (1000×1000, then
+  1024×1024) reused buffers too small for it. They are now keyed by the exact
+  shape.
+- **Every call leaked Metal objects**: the library was built without ARC and
+  without an autorelease pool, so each call kept its command buffers and a
+  buffer wrapper alive for the life of the thread, which mattered in long
+  loops. It is now built with ARC, and every GPU call drains its own pool.
+- **Transposed and other strided views were read as their untransposed
+  buffer**: an unevaluated MLX array reports itself contiguous, so contiguity
+  is now checked after evaluation.
+
+## 1.0.0
+
+`qr-apple-silicon`: batched QR on Apple GPUs (`custom_math::qr_accelerated`),
+with single-threadgroup and grid-parallel Householder backends and a fixed
+rule choosing between them.

metal_linalg-2.2.0/CMakeLists.txt

@@ -0,0 +1,327 @@
+cmake_minimum_required(VERSION 3.25)
+if (NOT CMAKE_HOST_SYSTEM_NAME STREQUAL "Darwin")
+    message(FATAL_ERROR "metal-linalg runs on Apple Silicon Macs only (Metal and Accelerate); "
+                        "it cannot be built on ${CMAKE_HOST_SYSTEM_NAME}.")
+endif ()
+project(metal_linalg VERSION 2.2.0 LANGUAGES CXX OBJCXX
+        DESCRIPTION "QR, symmetric eigendecomposition and SVD on Apple GPUs, for MLX")
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+# Standalone (top level) it is a shared library with install rules, which is
+# what Homebrew ships. As a subproject (add_subdirectory / FetchContent) it is
+# a static library folded into the parent's binary, with no install rules, so
+# a parent that builds it from source gets the shaders and routing tables of
+# that checkout and nothing else to ship.
+option(METAL_LINALG_SHARED      "Build libmetal_linalg as a shared library" ${PROJECT_IS_TOP_LEVEL})
+option(METAL_LINALG_INSTALL     "Generate install and CMake package rules" ${PROJECT_IS_TOP_LEVEL})
+option(METAL_LINALG_BUILD_TESTS "Build the tests, benchmarks and tuning harnesses" ${PROJECT_IS_TOP_LEVEL})
+option(METAL_LINALG_BUILD_EXAMPLES "Build the examples (run as tests)" ${METAL_LINALG_BUILD_TESTS})
+option(METAL_LINALG_BUILD_PYTHON "Build the Python extension (pyproject.toml turns this on)" OFF)
+option(METAL_LINALG_USE_PREBUILT_SHADERS
+       "Use shaders/prebuilt/*.metallib instead of compiling the .metal sources" OFF)
+# Without MLX the library is the buffer core alone (core.h, c_api.h): no MLX
+# API, and nothing that needs MLX (tests, benchmarks, examples, Python).
+option(METAL_LINALG_WITH_MLX "Build the MLX API over the core" ON)
+if (NOT METAL_LINALG_WITH_MLX)
+    foreach (_opt METAL_LINALG_BUILD_TESTS METAL_LINALG_BUILD_EXAMPLES METAL_LINALG_BUILD_PYTHON)
+        if (${_opt})
+            message(STATUS "metal-linalg: ${_opt} needs MLX; turned off")
+            set(${_opt} OFF CACHE BOOL "" FORCE)
+        endif ()
+    endforeach ()
+endif ()
+
+# The Python extension must use the very MLX the `mlx` Python package loads, so
+# look where that package says first: a pip-installed mlx carries its own, and
+# for Homebrew's the search falls through to the Homebrew prefix.
+if (METAL_LINALG_BUILD_PYTHON)
+    find_package(Python 3.10 REQUIRED COMPONENTS Interpreter Development.Module)
+    execute_process(COMMAND "${Python_EXECUTABLE}" -m mlx --cmake-dir
+                    OUTPUT_VARIABLE _mlx_py_root OUTPUT_STRIP_TRAILING_WHITESPACE
+                    RESULT_VARIABLE _mlx_py_rc ERROR_QUIET)
+    if (NOT _mlx_py_rc EQUAL 0)
+        message(FATAL_ERROR "metal-linalg: mlx is not installed for ${Python_EXECUTABLE}. "
+                            "See python/README.md.")
+    endif ()
+    list(PREPEND CMAKE_PREFIX_PATH "${_mlx_py_root}")
+endif ()
+
+if (METAL_LINALG_WITH_MLX)
+    find_package(MLX REQUIRED)
+endif ()
+include(GNUInstallDirs)
+
+# =============================================================================
+# Metal shaders
+# =============================================================================
+# Each .metal is compiled to a metallib and the metallib's bytes are compiled
+# into the library, so an installed libmetal_linalg is self-contained: nothing
+# is looked up on disk at run time and consumers need no Metal toolchain.
+#
+# Building from source needs the Metal shader compiler. From Xcode 26 it is a
+# separate download (xcodebuild -downloadComponent MetalToolchain); where it is
+# missing, the metallibs committed under shaders/prebuilt/ are used instead.
+# They are the same AIR whatever GPU compiled them. After editing a shader on
+# a machine that has the compiler, `cmake --build build --target
+# update_prebuilt_shaders` refreshes that directory.
+
+execute_process(COMMAND xcrun -sdk macosx metal --version
+                RESULT_VARIABLE _metal_rc OUTPUT_QUIET ERROR_QUIET)
+if (_metal_rc EQUAL 0)
+    set(METAL_LINALG_HAVE_METAL_COMPILER ON)
+else ()
+    set(METAL_LINALG_HAVE_METAL_COMPILER OFF)
+endif ()
+if (NOT METAL_LINALG_HAVE_METAL_COMPILER AND NOT METAL_LINALG_USE_PREBUILT_SHADERS)
+    message(STATUS "metal-linalg: no Metal shader compiler (xcodebuild -downloadComponent "
+                   "MetalToolchain installs it); using shaders/prebuilt")
+    set(METAL_LINALG_USE_PREBUILT_SHADERS ON)
+endif ()
+
+set(_ml_shader_dir "${CMAKE_CURRENT_BINARY_DIR}/shaders")
+file(MAKE_DIRECTORY "${_ml_shader_dir}")
+
+# metal_linalg_add_shader(<name> [FLAGS ...] [DEPENDS <header> ...])
+# Compiles shaders/<name>.metal (or copies the prebuilt metallib) and embeds
+# it as the C symbols metal_linalg_<name>_metallib / _len; see src/shaders.h.
+function(metal_linalg_add_shader name)
+    cmake_parse_arguments(_arg "" "" "FLAGS;DEPENDS" ${ARGN})
+    set(_src "${CMAKE_CURRENT_SOURCE_DIR}/shaders/${name}.metal")
+    set(_air "${_ml_shader_dir}/${name}.air")
+    set(_lib "${_ml_shader_dir}/${name}.metallib")
+    set(_cpp "${_ml_shader_dir}/${name}_metallib.cpp")
+
+    if (METAL_LINALG_USE_PREBUILT_SHADERS)
+        set(_pre "${CMAKE_CURRENT_SOURCE_DIR}/shaders/prebuilt/${name}.metallib")
+        if (NOT EXISTS "${_pre}")
+            message(FATAL_ERROR "metal-linalg: no Metal shader compiler and no prebuilt ${name}.metallib")
+        endif ()
+        add_custom_command(
+            OUTPUT "${_lib}"
+            COMMAND ${CMAKE_COMMAND} -E copy_if_different "${_pre}" "${_lib}"
+            DEPENDS "${_pre}"
+            COMMENT "Using prebuilt ${name}.metallib"
+            VERBATIM)
+    else ()
+        set(_deps "${_src}")
+        foreach (_d IN LISTS _arg_DEPENDS)
+            list(APPEND _deps "${CMAKE_CURRENT_SOURCE_DIR}/shaders/${_d}")
+        endforeach ()
+        # Re-runs whenever the source or a header it includes changes, so an
+        # edited shader can never be masked by a stale metallib.
+        add_custom_command(
+            OUTPUT "${_lib}"
+            COMMAND xcrun -sdk macosx metal ${_arg_FLAGS} -c "${_src}" -o "${_air}"
+            COMMAND xcrun -sdk macosx metallib "${_air}" -o "${_lib}"
+            DEPENDS ${_deps}
+            BYPRODUCTS "${_air}"
+            COMMENT "Compiling ${name}.metal -> ${name}.metallib"
+            VERBATIM)
+    endif ()
+
+    add_custom_command(
+        OUTPUT "${_cpp}"
+        COMMAND ${CMAKE_COMMAND} -DINPUT=${_lib} -DOUTPUT=${_cpp}
+                -DSYMBOL=metal_linalg_${name}_metallib
+                -P "${CMAKE_CURRENT_SOURCE_DIR}/cmake/EmbedMetallib.cmake"
+        DEPENDS "${_lib}" "${CMAKE_CURRENT_SOURCE_DIR}/cmake/EmbedMetallib.cmake"
+        COMMENT "Embedding ${name}.metallib"
+        VERBATIM)
+
+    set_property(GLOBAL APPEND PROPERTY METAL_LINALG_EMBEDDED_SOURCES "${_cpp}")
+    set_property(GLOBAL APPEND PROPERTY METAL_LINALG_METALLIBS "${_lib}")
+endfunction()
+
+metal_linalg_add_shader(QR_Unblocked)
+metal_linalg_add_shader(QR_Streaming_AMX_Reduced)
+metal_linalg_add_shader(QR_Streaming_AMX_Complete)
+
+# The Jacobi rotations need c^2 + s^2 == 1 to roundoff and the non-finite
+# check needs IEEE semantics, neither of which fast-math guarantees. The
+# kernels are barrier- and memory-bound, so precise arithmetic costs nothing
+# measurable.
+metal_linalg_add_shader(Eigh_Jacobi      FLAGS -fno-fast-math DEPENDS eigh_jacobi_common.h)
+metal_linalg_add_shader(Eigh_BlockJacobi FLAGS -fno-fast-math DEPENDS eigh_jacobi_common.h block_jacobi_common.h)
+metal_linalg_add_shader(Svd_Jacobi       FLAGS -fno-fast-math DEPENDS eigh_jacobi_common.h)
+metal_linalg_add_shader(Svd_BlockJacobi  FLAGS -fno-fast-math DEPENDS eigh_jacobi_common.h block_jacobi_common.h)
+
+get_property(_ml_embedded GLOBAL PROPERTY METAL_LINALG_EMBEDDED_SOURCES)
+get_property(_ml_metallibs GLOBAL PROPERTY METAL_LINALG_METALLIBS)
+
+if (NOT METAL_LINALG_USE_PREBUILT_SHADERS)
+    add_custom_target(update_prebuilt_shaders
+        COMMAND ${CMAKE_COMMAND} -E copy_if_different ${_ml_metallibs}
+                "${CMAKE_CURRENT_SOURCE_DIR}/shaders/prebuilt/"
+        DEPENDS ${_ml_metallibs}
+        COMMENT "Refreshing shaders/prebuilt/ from this build"
+        VERBATIM)
+endif ()
+
+# =============================================================================
+# The library
+# =============================================================================
+
+if (METAL_LINALG_SHARED)
+    set(_ml_kind SHARED)
+else ()
+    set(_ml_kind STATIC)
+endif ()
+add_library(metal_linalg ${_ml_kind}
+    src/device.mm
+    src/metal_runtime.mm
+    src/qr.mm
+    src/qr_unblocked.mm
+    src/qr_streaming_amx_reduced.mm
+    src/qr_streaming_amx_complete.mm
+    src/qr_cpu.mm
+    src/eigh.mm
+    src/eigh_block_jacobi.mm
+    src/svd.mm
+    src/svd_block_jacobi.mm
+    src/c_api.cpp
+    ${_ml_embedded}
+)
+if (METAL_LINALG_WITH_MLX)
+    target_sources(metal_linalg PRIVATE src/mlx_api.cpp)
+endif ()
+add_library(metal_linalg::metal_linalg ALIAS metal_linalg)
+
+# An absolute install name, so a consumer linked against the installed
+# library finds it without an rpath; Homebrew passes its opt path.
+set_target_properties(metal_linalg PROPERTIES
+    VERSION   ${PROJECT_VERSION}
+    SOVERSION ${PROJECT_VERSION_MAJOR}
+    EXPORT_NAME metal_linalg
+    INSTALL_NAME_DIR "${CMAKE_INSTALL_FULL_LIBDIR}"
+)
+target_compile_features(metal_linalg PUBLIC cxx_std_20)
+target_include_directories(metal_linalg
+    PUBLIC
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+        $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
+    PRIVATE
+        "${CMAKE_CURRENT_SOURCE_DIR}/src"
+)
+# The Objective-C++ sources are written for ARC: Metal objects are released
+# when their last reference goes, not leaked per call.
+target_compile_options(metal_linalg PRIVATE $<$<COMPILE_LANGUAGE:OBJCXX>:-fobjc-arc>)
+
+# The public headers only need MLX; the frameworks are the library's own, but
+# a static build hands them to the consumer's link line.
+set(_ml_frameworks "-framework Metal" "-framework MetalPerformanceShaders" "-framework Foundation"
+                   "-framework IOKit" "-framework Accelerate")
+target_link_libraries(metal_linalg PRIVATE ${_ml_frameworks})
+if (METAL_LINALG_WITH_MLX)
+    target_link_libraries(metal_linalg PUBLIC mlx)
+endif ()
+if (NOT METAL_LINALG_SHARED)
+    target_link_libraries(metal_linalg INTERFACE ${_ml_frameworks})
+endif ()
+
+# =============================================================================
+# Install and export: find_package(MetalLinalg) -> metal_linalg::metal_linalg
+# =============================================================================
+
+if (METAL_LINALG_INSTALL)
+install(TARGETS metal_linalg
+    EXPORT MetalLinalgTargets
+    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+)
+install(DIRECTORY include/ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
+
+set(_ml_cmake_dir "${CMAKE_INSTALL_LIBDIR}/cmake/MetalLinalg")
+install(EXPORT MetalLinalgTargets
+    FILE MetalLinalgTargets.cmake
+    NAMESPACE metal_linalg::
+    DESTINATION "${_ml_cmake_dir}"
+)
+include(CMakePackageConfigHelpers)
+configure_package_config_file(cmake/MetalLinalgConfig.cmake.in
+    "${CMAKE_CURRENT_BINARY_DIR}/MetalLinalgConfig.cmake"
+    INSTALL_DESTINATION "${_ml_cmake_dir}"
+)
+write_basic_package_version_file(
+    "${CMAKE_CURRENT_BINARY_DIR}/MetalLinalgConfigVersion.cmake"
+    VERSION ${PROJECT_VERSION}
+    COMPATIBILITY SameMajorVersion
+)
+install(FILES
+    "${CMAKE_CURRENT_BINARY_DIR}/MetalLinalgConfig.cmake"
+    "${CMAKE_CURRENT_BINARY_DIR}/MetalLinalgConfigVersion.cmake"
+    DESTINATION "${_ml_cmake_dir}"
+)
+endif ()
+
+# =============================================================================
+# Tests, benchmarks and tuning harnesses
+# =============================================================================
+
+if (METAL_LINALG_BUILD_TESTS)
+    include(CTest)
+
+    function(metal_linalg_add_tool name)
+        add_executable(${name} ${ARGN})
+        target_link_libraries(${name} PRIVATE metal_linalg mlx)
+    endfunction()
+
+    metal_linalg_add_tool(test_qr   tests/test_qr.cpp)
+    metal_linalg_add_tool(test_eigh tests/test_eigh.cpp)
+    metal_linalg_add_tool(test_svd  tests/test_svd.cpp)
+    add_test(NAME qr_correctness   COMMAND test_qr)
+    add_test(NAME eigh_correctness COMMAND test_eigh)
+    add_test(NAME svd_correctness  COMMAND test_svd)
+
+    # The buffer core on its own, without MLX, and the C API compiled as C.
+    add_executable(test_core tests/test_core.cpp)
+    target_link_libraries(test_core PRIVATE metal_linalg)
+    add_test(NAME core_correctness COMMAND test_core)
+    enable_language(C)
+    add_executable(test_c_api tests/test_c_api.c)
+    set_target_properties(test_c_api PROPERTIES C_STANDARD 99 C_STANDARD_REQUIRED ON)
+    target_link_libraries(test_c_api PRIVATE metal_linalg)
+    add_test(NAME c_api COMMAND test_c_api)
+
+    metal_linalg_add_tool(benchmark_qr   benchmarks/benchmark_qr.cpp)
+    metal_linalg_add_tool(benchmark_eigh benchmarks/benchmark_eigh.cpp)
+    metal_linalg_add_tool(benchmark_svd  benchmarks/benchmark_svd.cpp)
+
+    # Tuning harnesses: run these when porting to a different Apple GPU, since
+    # core count and per-core throughput set every routing crossover; see
+    # docs/tuning.md.
+    metal_linalg_add_tool(sweep_qr   tuning/sweep_qr.cpp)
+    metal_linalg_add_tool(sweep_eigh tuning/sweep_eigh.cpp)
+    metal_linalg_add_tool(sweep_svd  tuning/sweep_svd.cpp)
+
+    metal_linalg_add_tool(probe_occupancy tuning/probe_occupancy.mm)
+    target_include_directories(probe_occupancy PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/src")
+    target_link_libraries(probe_occupancy PRIVATE "-framework Metal" "-framework Foundation")
+endif ()
+
+# =============================================================================
+# Examples: small self-checking programs, also run by ctest
+# =============================================================================
+
+if (METAL_LINALG_BUILD_EXAMPLES)
+    include(CTest)
+    foreach (_ex quickstart orthonormal_bases pca nearest_orthogonal routing)
+        add_executable(example_${_ex} examples/${_ex}.cpp)
+        target_link_libraries(example_${_ex} PRIVATE metal_linalg)
+        add_test(NAME example_${_ex} COMMAND example_${_ex})
+    endforeach ()
+    add_executable(example_objc_quickstart examples/objc_quickstart.mm)
+    target_link_libraries(example_objc_quickstart PRIVATE metal_linalg "-framework Foundation")
+    add_test(NAME example_objc_quickstart COMMAND example_objc_quickstart)
+endif ()
+
+# =============================================================================
+# Python extension: metal_linalg._core (see python/README.md)
+# =============================================================================
+
+if (METAL_LINALG_BUILD_PYTHON)
+    add_subdirectory(python)
+endif ()