Skip to content

Standalone CLI binary — fix runtime framework linking #10

Description

@tadg-paul

Problem

The yapper binary built by xcodebuild cannot run outside Xcode's runtime environment. It segfaults when launched from a terminal because MLX Swift's Metal shaders and MisakiSwift's resource bundle are not discoverable.

This blocks:

  • make install producing a usable CLI
  • Homebrew distribution
  • Any use of yapper outside of Xcode/xcodebuild

Root cause

  1. MLX Swift compiles .metal shaders into default.metallib inside mlx-swift_Cmlx.bundle. The binary finds this bundle via NSBundle search paths that only resolve within Xcode's build environment.
  2. MisakiSwift is declared type: .dynamic in its Package.swift, forcing dynamic framework linking. The framework's resource bundle (MisakiSwift_MisakiSwift.bundle) must be manually copied into the framework directory.
  3. macOS SIP strips DYLD_FRAMEWORK_PATH from signed binaries, so environment-variable-based solutions don't work.

Options

  1. Static linking — fork MisakiSwift to remove type: .dynamic, then build everything statically. Single self-contained binary. Requires upstream PR or maintained fork.
  2. Embedded frameworks — copy frameworks alongside the binary, use install_name_tool to set correct @rpath, re-sign. ~118MB install.
  3. App bundle — package as a macOS .app with embedded frameworks. Works but unusual for a CLI tool.

Recommend: option 1 (static linking) as the proper fix, with option 2 as interim.

Acceptance Criteria

To be defined once approach is chosen.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions