如何从源码构建 oMLX.app：xcodebuild + venvstacks + ad-hoc 签名全流程

如何从源码构建 oMLX.appxcodebuild venvstacks ad-hoc 签名全流程【免费下载链接】omlxLLM inference server with continuous batching SSD caching for Apple Silicon — managed from the macOS menu bar项目地址: https://gitcode.com/GitHub_Trending/om/omlxoMLX 是一款运行在 Apple Silicon 上的 LLM 推理服务器支持连续批处理与 SSD 分层缓存并通过 macOS 菜单栏应用统一管理。本文带你从零开始源码构建 oMLX.app完整走一遍 xcodebuild 编译 Swift 壳、venvstacks 打包 Python 环境层、ad-hoc 签名生成可运行 Bundle 的全流程首次冷构建约 10–20 分钟之后热构建仅约 4 分钟。一、构建前环境检查清单构建 oMLX.app 需要以下 4 项环境先对照检查一遍检查项要求说明操作系统macOS 15.0SequoiaMLX ≥ 0.29.2 的硬性要求芯片Apple SiliconM1/M2/M3/M4不支持 Intel MacXcode26.5提供 xcodebuild、actool 等工具链Python3.11宿主机作为 venvstacks 驱动解释器构建入口只有一个脚本apps/omlx-mac/Scripts/build.sh它编排了全部 4 个阶段xcodebuild 编译 → venvstacks 层导出 → 资源装配 → ad-hoc 签名。二、第 1 步克隆源码并安装开发依赖git clone https://gitcode.com/GitHub_Trending/om/omlx cd omlx pip install -e .[dev]关键点venvstacks被声明为开发依赖所以pip install -e .[dev]或uv sync --dev就会带入锁定版本。如果你偏好宿主全局工具运行器构建脚本也会自动回退到uvx venvstacks或pipx run venvstacks。三、第 2 步理解 venvstacks 打包的 Python 层oMLX 是Swift 壳 内嵌 Python 引擎架构。Swift 应用本身不写 Python 业务代码真正的推理引擎FastAPI 服务器 MLX 运行时以 venvstacks 导出的分层目录形式嵌入 Bundle 的Contents/Resources/Python/。层配置定义在 packaging/venvstacks.toml共两层没有应用层Swift 应用即应用面层名称内容运行时层cpython-3.11锁定的 CPython 3.11.10框架层mlx-base约 1 GBMLX、mlx-lm、mlx-vlm、FastAPI、transformers、mlx-audio、paroquant、spaCy 等依赖清单不手写而是由 packaging/build.py 在构建时从pyproject.toml动态生成——单一事实来源永远是pyproject.toml。手动触发导出只需python packaging/build.py --venvstacks-only产物落在packaging/_export/。脚本会用pyproject.toml venvstacks.toml uv.lock计算指纹与_export/.fingerprint比对内容没变就复用缓存变了才重新导出。四、第 3 步一条命令跑完全流程apps/omlx-mac/Scripts/build.sh release脚本内部按顺序执行以下动作源码见 build.sh 头部的流水线注释解析 SPM 依赖xcodebuild -resolvePackageDependencies让 Swift Package 在 pin 范围内取到最新补丁版本按需重建 venvstacks 导出指纹不匹配时自动重跑冷构建耗时主要在这里10–20 分钟xcodebuild 编译 Swift 壳关闭签名、注入版本号后构建oMLX.app。版本号不手写直接从 omlx/_version.py 读取CFBundleVersion取git rev-list --count HEAD保证每次提交单调递增装配 Bundle把cpython-3.11、framework-mlx-base层拷入Contents/Resources/Python/rsync 拷贝omlx/Python 包排除测试与缓存写入omlx-cli、omlx-cluster-python两个解释器包装脚本并用 actool 编译 Tahoe Liquid Glass 图标ad-hoc 签名收尾下一节详述。构建日志分别落在apps/omlx-mac/build/xcodebuild.log与spm-resolve.log出错时会打印日志尾部 40 行。五、ad-hoc 签名为什么本地构建要三重签名即使 xcodebuild 阶段设了CODE_SIGNING_ALLOWEDNO最终 Bundle 仍必须有连贯的应用包签名否则 macOS 的 TCC 无法把完全磁盘访问授权匹配到应用身份。签名分三层执行build.sh 签名段内嵌原生库扫描 Python 层中所有.so/.dylib/.bundle等 Mach-O 文件逐一codesign --force --sign -CLI 包装脚本对omlx-cli与omlx-cluster-python单独签名外层 Bundlecodesign --force --sign -封包整个oMLX.app最后xattr -dr com.apple.quarantine移除隔离属性让 Bundle 从任何位置双击即可启动。这里的-即 ad-hoc 签名者不依赖 Apple Developer 账号专为本地开发构建设计Release 渠道的正式 DMG 由维护者管线另行产出仓库内不含该步骤。六、常用构建模式速查表命令场景build.sh release完整 Release 构建默认自动重建过期 Python 层build.sh debugDebug 构建便于断点调试build.sh swift只重建 Swift 壳复用现有packaging/_export/改 UI 时最快build.sh swift-fast同上且跳过内嵌原生代码签名更快build.sh release --bare跳过 Python 嵌入只验证 AppView 壳服务器无法启动build.sh release --with-custom-kernel额外编译 GLM-5.2 / MiniMax M3 / Qwen3.5 原生内核build.sh release --rebuild-donor强制忽略缓存重建 venvstacks 导出build.sh release --no-rebuild-donor永不重建直接复用现有层过期会警告另有环境变量OMLX_DONOR_APP可指定现成的.app作为 Python 层来源完全绕过 venvstacksOMLX_EXPORT_DIR、PYTHON_BIN可分别覆盖导出目录与驱动解释器。纯 Swift 代码迭代时还可以用 apps/omlx-mac/Scripts/dev_server.py 这个健康检查桩服务器替代完整 Python 环境通过OMLX_PYTHON_OVERRIDE/OMLX_DEV_SERVER_SCRIPT注入秒级验证进程启动路径。七、第 4 步启动与验证open apps/omlx-mac/build/Stage/oMLX.app应用出现在菜单栏首次启动会引导你完成存储目录 API Key的初始化向导点击 Start Server打开 Models 页面可下载/管理本地模型推荐列表会按你的内存大小过滤oMLX 模型管理器界面支持从 HuggingFace 下载模型并按推荐列表挑选服务器日志固定在~/Library/Application Support/oMLX/logs/server.log排查启动问题先看这里。八、常见问题排查依赖改动了但 Bundle 里是旧环境手动跑apps/omlx-mac/Scripts/build.sh release --rebuild-donor强制重建想快速验证 UI 改动用build.sh swift复用 Python 层避免 10 分钟级的 venvstacks 重建想知道 Bundle 用的版本号查 omlx/_version.py它是pyproject.toml与 Swift Bundle 的共同来源层配置怎么调读 packaging/README.md含完整层说明与产物目录结构_build/、_export/、_wheels/。九、相关文档与源码索引打包总览packaging/README.mdvenvstacks 层配置packaging/venvstacks.tomlvenvstacks 驱动脚本packaging/build.py构建编排脚本apps/omlx-mac/Scripts/build.shSwift 源码apps/omlx-mac/Sources/Python 推理引擎omlx/入口 omlx/server.py开发指南docs/CONTRIBUTING.md【免费下载链接】omlxLLM inference server with continuous batching SSD caching for Apple Silicon — managed from the macOS menu bar项目地址: https://gitcode.com/GitHub_Trending/om/omlx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考