[BUG] default.metallib bundle missing when using Tuist (SwiftPM bundle not emitted)

[Skyline-23]

Describe the bug
When mlx-swift is integrated via Tuist, runtime crashes on iOS device with:
Failed to load the default metallib (library not found).
MLX searches for mlx-swift_Cmlx.bundle/default.metallib, but Tuist doesn't emit the SwiftPM resource bundle for external dependencies (because the metallib is a build artifact, not declared as a resource). As a result the bundle is missing at runtime.

To Reproduce

Include code snippet

// Minimal usage that triggers MLX init
import MLX
import Cmlx
// e.g. initialize MLX or any model load

Steps:

1. Create a Tuist project that depends on mlx-swift (Cmlx + MLX).
2. Build & run on a real iOS device (not simulator).
3. App/test host crashes with “Failed to load the default metallib (library not found)”.

Workaround (build script):

# Copy default.metallib into SwiftPM bundle path expected by MLX
BUNDLE_DIR="${TARGET_BUILD_DIR}/${UNLOCALIZED_RESOURCES_FOLDER_PATH}/mlx-swift_Cmlx.bundle"
mkdir -p "${BUNDLE_DIR}"
cp -f "${BUILT_PRODUCTS_DIR}/Cmlx.framework/default.metallib" "${BUNDLE_DIR}/default.metallib"

Related MLX source (load paths):

• https://github.com/ml-explore/mlx-swift/blob/main/Source/Cmlx/mlx/mlx/backend/metal/device.cpp

Expected behavior
MLX should find its metallib when integrated via Tuist (or any build system that doesn’t auto-generate SwiftPM resource bundles for external deps). Ideally default.metallib should be declared as a SwiftPM resource or shipped in a stable bundle path.

Desktop (please complete the following information):

• OS Version: macOS 26.2 (host), iOS 26.2.1 (device)
• Device: iPhone Air (iOS 26.2.1)
• Version: mlx-swift (main), Tuist 4.133.4, Xcode 26.2

Additional context
Tuist does not auto-emit SwiftPM resource bundles for external dependencies when the resource is a build artifact. The workaround above copies default.metallib into mlx-swift_Cmlx.bundle and fixes the crash.

[davidkoski]

True, though the mechanism is slightly deeper: swiftpm has no mechanism to build the metal shaders or the metallic. It is not just that they are not declared.

See https://github.com/ml-explore/mlx-swift?tab=readme-ov-file#xcodebuild

This isn't ideal, but using xcodebuild (or CMake) is a workaround. xcodebuild works with SwiftPM files, CMake does not. For many people, they are already using Xcode to build their applications so this happens automatically.

Over time we may be able to solve this -- we have a few approaches:

• turn all shaders into JIT -- compile at runtime
• use a plugin during the build, see MetalCompilerPlugin support  #313 -- so far I don't feel it is viable
• wait for swiftpm to support it, we will see what changes https://forums.swift.org/t/evolving-swiftpm-builds-with-swift-build/77596 brings and hope it makes it possible

For now I suggest using xcodebuild.

[robertmsale]

I experienced an issue similar to this and just wanna throw my hat in the ring here.

// Plugins/CopyMLXMetal/Plugin.swift
import PackagePlugin

@main
struct CopyMLXMetalPlugin: BuildToolPlugin {
    func createBuildCommands(context: PluginContext, target: Target) throws -> [Command] {
        let script = context.package.directory.appending(subpath: "Plugins/CopyMLXMetal/copy_mlx_metallib.sh")
        let outputDir = context.pluginWorkDirectory.appending(subpath: "mlx-metal")

        return [
            .prebuildCommand(
                displayName: "Copy MLX metallib (vendor/mlx or .venv)",
                executable: .init("/bin/bash"),
                arguments: [script.string, context.package.directory.string, outputDir.string],
                outputFilesDirectory: outputDir
            )
        ]
    }
}

#!/usr/bin/env bash
# Plugins/CopyMLXMetal/copy_mlx_metallib.sh
set -euo pipefail

PACKAGE_ROOT="${1:?package root required}"
OUTPUT_DIR="${2:?output dir required}"

export PATH="/opt/homebrew/bin:/usr/local/bin:/opt/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:${PATH}"
if [[ -z "${HOME:-}" ]]; then
  HOME="$(cd "$PACKAGE_ROOT/../.." && pwd)"
  export HOME
fi

VENDORED_MLX_ROOT="$PACKAGE_ROOT/vendor/mlx"
VENDORED_BUILD_DIR="$VENDORED_MLX_ROOT/build"
LOCAL_METALLIB="$VENDORED_BUILD_DIR/mlx/backend/metal/kernels/mlx.metallib"
PLUGIN_BUILD_DIR="$OUTPUT_DIR/mlx-build"
PLUGIN_METALLIB="$PLUGIN_BUILD_DIR/mlx/backend/metal/kernels/mlx.metallib"
METAL_CPP_DIR="$PACKAGE_ROOT/vendor/metal-cpp/metal-cpp"
JSON_SRC_DIR="$VENDORED_BUILD_DIR/_deps/json-src"
FMT_SRC_DIR="$VENDORED_BUILD_DIR/_deps/fmt-src"
GGUF_SRC_DIR="$VENDORED_BUILD_DIR/_deps/gguflib-src"

if [[ -d "$VENDORED_MLX_ROOT" ]]; then
  if [[ ! -f "$LOCAL_METALLIB" ]]; then
    echo "Building mlx.metallib from vendored MLX..." >&2
    CMAKE_BIN="$(command -v cmake || true)"
    if [[ -z "$CMAKE_BIN" ]]; then
      echo "cmake not found in PATH. Install cmake (e.g. brew install cmake) or add it to PATH." >&2
      exit 1
    fi
    CMAKE_ARGS=()
    if [[ -d "$METAL_CPP_DIR" ]]; then
      CMAKE_ARGS+=("-DFETCHCONTENT_SOURCE_DIR_METAL_CPP=$METAL_CPP_DIR")
      CMAKE_ARGS+=("-DFETCHCONTENT_UPDATES_DISCONNECTED=ON")
    fi
    if [[ -d "$JSON_SRC_DIR" ]]; then
      CMAKE_ARGS+=("-DFETCHCONTENT_SOURCE_DIR_JSON=$JSON_SRC_DIR")
      CMAKE_ARGS+=("-DFETCHCONTENT_UPDATES_DISCONNECTED=ON")
    fi
    if [[ -d "$FMT_SRC_DIR" ]]; then
      CMAKE_ARGS+=("-DFETCHCONTENT_SOURCE_DIR_FMT=$FMT_SRC_DIR")
      CMAKE_ARGS+=("-DFETCHCONTENT_UPDATES_DISCONNECTED=ON")
    fi
    if [[ -d "$GGUF_SRC_DIR" ]]; then
      CMAKE_ARGS+=("-DFETCHCONTENT_SOURCE_DIR_GGUFLIB=$GGUF_SRC_DIR")
      CMAKE_ARGS+=("-DFETCHCONTENT_UPDATES_DISCONNECTED=ON")
    fi
    mkdir -p "$PLUGIN_BUILD_DIR"
    "$CMAKE_BIN" -S "$VENDORED_MLX_ROOT" -B "$PLUGIN_BUILD_DIR" \
      -DMLX_BUILD_METAL=ON \
      -DCMAKE_BUILD_TYPE=Release \
      "${CMAKE_ARGS[@]}"
    "$CMAKE_BIN" --build "$PLUGIN_BUILD_DIR" --target mlx-metallib
  fi

  if [[ -f "$LOCAL_METALLIB" ]]; then
    mkdir -p "$OUTPUT_DIR"
    cp -f "$LOCAL_METALLIB" "$OUTPUT_DIR/mlx.metallib"
    cp -f "$LOCAL_METALLIB" "$OUTPUT_DIR/default.metallib"
    date > "$OUTPUT_DIR/copy.stamp"
    exit 0
  fi
  if [[ -f "$PLUGIN_METALLIB" ]]; then
    mkdir -p "$OUTPUT_DIR"
    cp -f "$PLUGIN_METALLIB" "$OUTPUT_DIR/mlx.metallib"
    cp -f "$PLUGIN_METALLIB" "$OUTPUT_DIR/default.metallib"
    date > "$OUTPUT_DIR/copy.stamp"
    exit 0
  fi
fi

VENV_PATH="${VIRTUAL_ENV:-$PACKAGE_ROOT/.venv}"
PYTHON="$VENV_PATH/bin/python"

if [[ ! -x "$PYTHON" ]]; then
  echo "Expected venv python at $PYTHON. Create a venv at $PACKAGE_ROOT/.venv and install mlx." >&2
  exit 1
fi

METALLIB_PATH="$($PYTHON - <<'PY'
import pathlib
import sysconfig

paths = [
    sysconfig.get_paths().get("purelib"),
    sysconfig.get_paths().get("platlib"),
]

metallib = None
for base in paths:
    if not base:
        continue
    candidate = pathlib.Path(base) / "mlx" / "lib" / "mlx.metallib"
    if candidate.exists():
        metallib = candidate
        break

if metallib is None:
    raise FileNotFoundError("mlx.metallib not found in site-packages")
print(metallib)
PY
)"

if [[ ! -f "$METALLIB_PATH" ]]; then
  echo "mlx.metallib not found at $METALLIB_PATH" >&2
  exit 1
fi

mkdir -p "$OUTPUT_DIR"
cp -f "$METALLIB_PATH" "$OUTPUT_DIR/mlx.metallib"
cp -f "$METALLIB_PATH" "$OUTPUT_DIR/default.metallib"
date > "$OUTPUT_DIR/copy.stamp"

// Package.swift
let package = Package(
    name: "mlxperiments",
    platforms: [
        .macOS(.v14)
    ],
    dependencies: [
        .package(name: "mlx-swift-lm", path: "vendor/mlx-swift-lm/worktrees/mainline")
    ],
    targets: [
        .executableTarget(
            name: "mlxperiments",
            dependencies: [
                .product(name: "MLXLLM", package: "mlx-swift-lm")
            ],
            plugins: [
                .plugin(name: "CopyMLXMetal")
            ]
        ),
        // SNIP
        .plugin(
            name: "CopyMLXMetal",
            capability: .buildTool(),
            path: "Plugins/CopyMLXMetal"
        ),
    ]
)

I have sort of a mlxperiments SPM project where I swap out dependencies and test ideas, and this is the workaround I came up with (fairly brittle, naive but sufficient for my use case). @Skyline-23 you may be able to adapt it as a workaround.

I see #313 is looking to add a plugin, and there might be a way to do it where mlx-swift includes the plugin as a target, but does not actually use it in any of the other targets, and downstream packages can opt into it in their Package.swift, thereby not creating a separate build path for SPM & non-SPM nor requiring working code/unit test changes. If it's a shell script like the one I have, could remove the env vars from the swift plugin and make the script kind of "opt-in and configure your environment to use it." Could probably utilize the .build/checkouts/mlx-swift/Sources/Cmlx/mlx, if it exists then do a cmake build and throw the lib in the output directory - which can even be automated in CI if you fetch deps first before running build (I think).

Or perhaps just throwing some documentation somewhere describing the process and some examples might be sufficient. Either way just thought I'd share my workaround!

[Skyline-23]

I hit the same Tuist + mlx-swift-lm integration issue where default.metallib wasn’t reliably present at runtime under mlx-swift_Cmlx.bundle/default.metallib.

What I did (workaround):

• I ensured mlx-swift_Cmlx.bundle is included in the app/extension resources (Copy Bundle Resources).
• I added a pre-build script phase to each app/extension/test target that uses MLX. The script copies the built default.metallib into the embedded bundle at:
  $(TARGET_BUILD_DIR)/$(UNLOCALIZED_RESOURCES_FOLDER_PATH)/mlx-swift_Cmlx.bundle/default.metallib
• The script picks the first existing candidate to support multiple build layouts (SwiftPM bundle product vs Cmlx.framework).

set -euo pipefail

candidates=(
  # Preferred: SwiftPM bundle product (if present)
  "${BUILT_PRODUCTS_DIR}/mlx-swift_Cmlx.bundle/default.metallib"
  "${BUILT_PRODUCTS_DIR}/mlx-swift_Cmlx.bundle/Contents/Resources/default.metallib"

  # Fallbacks: framework layouts
  "${BUILT_PRODUCTS_DIR}/Cmlx.framework/default.metallib"
  "${BUILT_PRODUCTS_DIR}/Cmlx.framework/Resources/default.metallib"
  "${BUILT_PRODUCTS_DIR}/Cmlx.framework/Versions/A/default.metallib"
  "${BUILT_PRODUCTS_DIR}/Cmlx.framework/Versions/A/Resources/default.metallib"
  "${BUILT_PRODUCTS_DIR}/Cmlx.framework/Versions/A/Resources/mlx.metallib"
)

src=""
for c in "${candidates[@]}"; do
  [[ -f "${c}" ]] && src="${c}" && break
done
[[ -z "${src}" ]] && exit 0

bundle_root="${TARGET_BUILD_DIR}/${UNLOCALIZED_RESOURCES_FOLDER_PATH}/mlx-swift_Cmlx.bundle"
dst="${bundle_root}"
[[ -d "${bundle_root}/Contents/Resources" ]] && dst="${bundle_root}/Contents/Resources"

mkdir -p "${dst}"
cp -f "${src}" "${dst}/default.metallib"

Extra macOS note: I avoided copying/placing *.metallib at the root of a code-signed framework (e.g. Some.framework/Versions/A/*.metallib) because I saw embed/codesign failures (treated as nested code). Keeping metallibs under Resources/ (or only inside the app’s embedded mlx-swift_Cmlx.bundle) prevented that.