如何从源码构建与测试OmniWM：贡献者开发环境搭建与验证完整清单

【免费下载链接】OmniWMFree, open-source tiling window manager for Apple Silicon Macs, with Niri-style scrolling containers and Hyprland-style Dwindle BSP.项目地址: https://gitcode.com/gh_mirrors/om/OmniWM

OmniWM 是一款免费开源的 macOS 平铺窗口管理器，专为 Apple Silicon Mac 打造，支持 Niri 风格的滚动容器和 Hyprland 风格的 Dwindle BSP 布局。想为它贡献代码？本文带你从零完成 OmniWM 源码构建：安装 Xcode 27、一键拉取依赖、编译运行 Dev 版本，并用make verify与swift test完成全部验证。

一、环境准备：构建 OmniWM 的 3 个硬性前提 📋

官方贡献指南要求非常明确（详见 CONTRIBUTING.md），缺一不可：

另外还需要系统自带的Python 3，用于开发工具测试和本地化脚本。

⚠️常见踩坑点：单独的 Command Line Tools 不能替代完整 Xcode。安装 Xcode 27 后，务必在Xcode → Settings → Locations → Command Line Tools中选择它，然后在终端执行以下命令确认版本：

xcrun swift --version

输出必须显示Swift 6.4。这些检查逻辑由 Scripts/dev-tools.sh 自动执行，版本不达标时make setup会直接报错。

二、获取代码：克隆仓库并创建分支

在 Fork 仓库后克隆你的副本（下面以 GitCode 镜像为例）：

git clone https://gitcode.com/gh_mirrors/om/OmniWM cd OmniWM git switch -c my-change main

分支名请替换成有描述性的名字。约定俗成：每个改动都从main拉新分支，且只聚焦一个问题。

三、一键安装依赖：make setup 做了什么？

进入仓库后，只需一条命令完成全部依赖安装：

make setup

它会自动做三件事（目标定义在 Makefile，版本与校验和锁定在 Scripts/dev-tools.env）：

1. 下载 GhosttyKit 预编译框架到Frameworks/GhosttyKit.xcframework，并校验 SHA-256——你不需要自己编译 GhosttyKit；
2. 安装锁定版本的 SwiftFormat 0.63.0 和 SwiftLint 0.65.1到仓库内的.cache/dev-tools，无需 Homebrew；
3. 检查签名身份与关键路径，并打印 Dev 版/正式版各自的配置文件位置。

如果已有依赖且校验通过，setup 会直接复用。工具版本变更时，只需重新运行 setup 即可自动更新。

四、构建与运行：make build 与 make run

只构建不安装（等价于 CI 的构建检查，针对 arm64 架构）：

make build

构建 + 打包 + 签名 + 安装 + 启动：

make run

make run会把你的代码打包为OmniWM Dev.app，安装到~/Applications/OmniWM Dev.app并打开。首次启动需在权限窗口为 Dev 版授予辅助功能和输入监控（屏幕录制可选，用于概览缩略图等截图功能）。

💡Dev 版与正式版完全隔离：Dev 版使用固定身份com.barut.OmniWM.dev，配置和状态存放在独立目录：

所以大胆折腾——你的正式环境不受任何影响。改完代码再跑一次make run即可热更。

日常开发命令速查：

五、验证完整清单：提交 PR 前必跑

这是新手最容易漏的一步。CI 会分开运行Verify和Tests两个任务（定义见 .github/workflows/ci.yml），你本地也应该跑齐：

make verify # 格式检查 + SwiftLint + 本地化目录 + arm64 构建 swift test # 完整串行测试套件

⚠️注意：make verify不跑测试。对运行时行为有改动的 PR 必须补上swift test；涉及并发改动时还要额外跑swift test --parallel。

其他场景化检查：

• 改了设置/打包/安装脚本→ 追加make test-dev-tools（运行 Tests/DevToolingTests 的 Python 工具测试）；
• 改动了本地化源码文本→make localization-sync重新生成字符串目录；
• 动效、焦点、布局等可见行为→ 用文字描述你手动验证过的步骤；
• 依赖 GhosttyKit 的实时测试是 opt-in 的，例如make test-skylight-live。

所有 Swift 文件都会通过 SwiftFormat 强制两行 GPL-2.0 头部，运行make format可以自动补齐。

六、可选：创建本地签名证书 🔐

重复开发时建议创建一个自签名证书（无需付费 Apple 开发者账号），这样 macOS 能在多次重编译后保留 Dev 版权限：

1. 打开钥匙串访问→证书助理 → 创建证书；
2. 名称填OmniWM Dev，类型选自签名根 + 代码签名；
3. 双击证书，把代码签名设为"始终信任"；
4. 运行make doctor确认身份被识别，然后make run。

跳过这一步也能构建（自动改用 ad-hoc 签名），只是每次重建后可能需要重新授权。

七、遇到问题：从 make doctor 开始排障

官方推荐的排障路径是：先看make doctor，再看失败命令的第一个报错。常见对照：

• Swift 版本不对→ 回 Xcode Locations 选中 Xcode 27，再查xcrun swift --version；
• 依赖缺失/校验失败→ 运行make setup；已有 GhosttyKit 与锁不匹配时，它不会覆盖，需你手动移走旧框架；
• 权限反复请求→ 检查签名身份是否稳定，Dev 与正式版权限互不相通；
• 切换卡在"OmniWM 还在运行"→ 先从菜单栏退出正在运行的副本再重试，脚本不会强杀进程。

结语：你的第一份 PR ✅

到这里你已经掌握了完整闭环：环境自检 →make setup→make run迭代开发 →make verify+swift test双重验证。提交前请附上验证结果（含没跑成的检查及原因），附上截图或录屏效果更佳。完整规范参考 CONTRIBUTING.md，祝构建顺利！

【免费下载链接】OmniWMFree, open-source tiling window manager for Apple Silicon Macs, with Niri-style scrolling containers and Hyprland-style Dwindle BSP.项目地址: https://gitcode.com/gh_mirrors/om/OmniWM