AeroSpace 从源码构建与开发环境搭建完整指南

原创2026-09-11 23:47:521,930 阅读
文章标签:桌面应用

AeroSpace 从源码构建与开发环境搭建完整指南

AeroSpace 是一款面向 macOS 的 i3 风格平铺窗口管理器(tiling window manager),其核心为 Swift 编写,采用「SPM 驱动开发、Xcode 负责发布包」的双轨构建体系。本文基于仓库 dev-docs/development.md 展开,逐项讲解依赖安装、codesign 证书创建、调试/发布构建入口脚本、IDE 配置与排错技巧,并结合 script/setup.sh、build-debug.sh、build-release.sh 等源码级实现,帮助你完整掌握从克隆仓库到产出可运行 .app 的每一环。

构建体系速览:SPM 与 Xcode 的分工

在动手之前,先理解 AeroSpace 独特的构建架构,这决定了后续每一步操作的必要性。项目根目录的 Package.swift 声明了 swift-tools-version: 6.2,平台最低要求为 macOS 13,并提供四个目标(target):

  • aerospace 可执行文件(CLI 客户端,纯 SPM 构建,不涉及 Xcode);
  • AeroSpaceApp 可执行文件(服务端调试入口);
  • AppBundle 库(真正的服务端主体逻辑,作为 library 暴露给 Xcode 工程);
  • AppBundleTests 测试目标。

关键约束在于:SPM 只能构建库与命令行程序,无法直接产出 macOS App Bundle(.app)。因此 AeroSpace 的策略是把尽可能多的代码收拢进 SPM 库中,再通过 Xcode 工程(由 xcode/project.yml 经 XcodeGen 生成)来产出发布用的 AeroSpace.app。关于这一设计的完整描述,可参考 dev-docs/architecture.md 的 "High level project infrastructure overview" 一节。

正因为如此,从源码构建分为两条路径:

  • 调试构建(Debug):全程使用 swift build,不需要 Xcode,也不需要自定义证书;
  • 发布构建(Release):需要 Xcode、需要自签名证书,产出 App Bundle 与通用二进制(universal binary)。

1. 安装构建依赖

按官方文档,第一步是安装全部依赖。以下是逐项说明,并标注了仓库中的对应证据。

1.1 Xcode(App Store 安装)

从 App Store 安装 Xcode。它并非调试构建的必需品(调试构建只用 SPM),但发布构建、Xcode 工程生成与部分工具链都依赖它。

1.2 swiftly(Swift 工具链管理器)

brew install swiftly

swiftly 的作用是保证你使用的 Swift 版本与仓库声明的 .swift-version 文件一致。仓库根目录的 .swift-version 内容为 6.3.2,即构建 AeroSpace 的锁定 Swift 版本。

这一约定在 script/setup.sh 中有直接体现:所有入口脚本都会 source ./script/setup.sh,其中定义了一个 swift() 包装函数——若检测到 swiftly 已安装,则通过 swiftly run swift "$@" 执行,否则回退到普通 swift 并打印警告 "Swift compilation might not be reproducible"(编译可能不可复现)。这解释了为什么文档强调 swiftly 是保证可复现构建的关键。

1.3 构建 shell completion 的依赖(可选)

# Rust,使用 rustup 安装:https://www.rust-lang.org/tools/install
brew install bash fish

shell 补全由 build-shell-completion.sh 生成,它调用 complgen(命令的 BNF 文法描述)生成 zsh、fish、bash 三套补全脚本,并逐一做语法加载检查:

zsh -c 'autoload -Uz compinit; compinit; source ./.shell-completion/zsh/_aerospace'
fish -c 'source ./.shell-completion/fish/aerospace.fish'
bash -c 'source ./.shell-completion/bash/aerospace'

注意 setup.sh 对 bash 有版本检查:Your bash version is too old. Version 5 is the minimum required version,即系统 bash 必须为 5.x 及以上。

1.4 构建 man pages 的依赖(可选)

# 推荐使用 rbenv 管理 Ruby:https://github.com/rbenv/rbenv
rbenv install 3.3.4   # 或任意 3.x 版本
cd AeroSpace && bundler install

man pages 与站点文档都由 Asciidoctor(Ruby 工具)构建,仓库根目录的 Gemfile 声明了依赖。若跳过此步,仅无法运行 build-docs.sh,不影响编译与运行。

1.5 xcbeautify(可选,但强烈推荐)

brew install xcbeautify

xcbeautify 用于把 Xcode 的冗长构建日志过滤为「仅输出含警告/错误的任务」。在 script/setup.sh 的 xcodebuild-pretty() 函数中可以看到它的接入方式:xcodebuild "$@" 2>&1 | tee "$log_file" | xcbeautify --quiet,完整原始日志仍会保存到 log_file(如 .release/xcodebuild.log),方便排查。

2. 创建 codesign 自签名证书

只有打算以 App Bundle 形态运行 AeroSpace(即发布构建)时才需要自定义证书;如果只构建调试版并从终端运行,证书不是必需的(文档明确说明)。

证书创建步骤(在 Keychain Access.app 中):

  1. 打开 Keychain Access.app;
  2. 菜单 → Keychain Access → Certificate Assistance → Create a Certificate...;
  3. 填写参数:
    • Name:aerospace-codesign-certificate
    • Identity Type:Self-Signed Root
    • Certificate Type:Code Signing

该证书名 aerospace-codesign-certificate 在构建脚本中被硬编码引用:generate.sh 设置了环境变量 XCODEGEN_AEROSPACE_CODE_SIGN_IDENTITY="aerospace-codesign-certificate" 供 XcodeGen 生成工程使用;build-release.sh 也以 codesign_identity="aerospace-codesign-certificate" 为默认值,并可通过 --codesign-identity 参数覆盖。因此若你在 Keychain 中使用了不同名称,需要同步修改这两个入口(或传入对应参数)。

3. 入口脚本总览

仓库根目录提供了一批开箱即用的脚本,文档将其分为调试与发布两大类。下表汇总后逐节展开:

脚本 类别 用途 产物位置
build-debug.sh Debug 用 SPM 构建调试版 .debug/
test.sh Debug 运行全部测试与检查 —
swiftformat.sh Debug 代码格式化(实际文件为 format.sh) —
run-debug.sh Debug 运行调试版 AeroSpace.app —
run-cli.sh Debug 以 CLI 方式运行 aerospace,透传参数 —
build-docs.sh Debug/Release 构建站点与 man pages .site/、.man/
build-shell-completion.sh Debug/Release 构建 shell 补全 .shell-completion/
generate.sh Debug/Release 重新生成工程与生成源文件 xcode/AeroSpace.xcodeproj 等
build-release.sh Release 用 Xcode 构建发布版 .release/
install-from-sources.sh Release 构建发布版并安装为 aerospace-dev brew cask Homebrew 前缀

说明:文档中写作 swiftformat.sh,仓库实际文件名为 format.sh;此外 lint.sh 负责 SwiftLint 静态检查。

3.1 Debug 构建:build-debug.sh

./build-debug.sh

其实现(见 build-debug.sh)包含四个关键动作:

  1. ./generate.sh --ignore-xcodeproj --ignore-cmd-help——先做增量代码生成,但跳过 Xcode 工程与命令帮助(后者生成约需 300ms,作者注释明确说明为了调试速度而跳过);
  2. swift build 构建 CLI 与 AeroSpaceApp,随后再单独 swift build --target AppBundleTests(注释指出 swift build 默认不构建测试目标,需显式指定);
  3. 把 .build/debug/aerospace 与 .build/debug/AeroSpaceApp 拷贝进 .debug/ 目录。

所有脚本(含 build-debug.sh)都先 source ./script/setup.sh,由后者完成 .deps/bin 软链接环境准备与 bash 版本校验。

3.2 运行调试构建:run-debug.sh 与 run-cli.sh

./run-debug.sh          # 构建并运行 AeroSpace.app 调试版
./run-cli.sh list-workspaces   # 构建并运行 CLI,参数透传

run-debug.sh 先调用 build-debug.sh,再执行 ./.debug/AeroSpaceApp "$@";run-cli.sh 则构建后执行 ./.debug/aerospace "$@"(首次构建失败会自动重试一次)。注意它们都要求先完成第 2 节的证书流程吗?——并不需要:这两个脚本走的是 SPM 调试链路,文档明确调试版无需自定义证书。

3.3 测试:test.sh

./test.sh

test.sh 是完整的质量门禁,依次执行:

  1. ./build-debug.sh -Xswiftc -warnings-as-errors(警告即错误);
  2. ./swift-test.sh(swift test,测试代码位于 Sources/AppBundleTests);
  3. 冒烟验证 CLI:-h/--help 必须退出成功,-v/--version 输出必须包含 0.0.0-SNAPSHOT SNAPSHOT(对应调试版本号,见 generate.sh 写入的 Sources/Common/versionGenerated.swift);
  4. ./lint.sh(SwiftLint,规则见 .swiftlint.yml);
  5. ./generate.sh 后执行 script/check-uncommitted-files.sh,确保生成文件与仓库一致(防止手改生成文件)。

另外仓库根目录的 makefile 将 build-debug.sh、test.sh 等注册为 .PHONY 目标,让 Vim 的 :make 命令可以开箱即用。

3.4 文档构建:build-docs.sh

./build-docs.sh          # 默认构建
./build-docs.sh --release   # 发布模式:链接去掉 .html 后缀

build-docs.sh 使用 Asciidoctor 把 docs 下的 .adoc 源文件分别渲染为:

  • .site/:HTML 站点(guide.html、commands.html、goodies.html),并写入 git rev-parse HEAD 到 version.html;
  • .man/:aerospace*.adoc 对应的 man page(-b manpage)。

一个有意思的细节:脚本里有一段注释为 AI 生成的针对 man page 的转义处理——由于 gman 客户端会把 ~ 渲染成连字变体,构建时用 sed 将 .~ 与 /~ 替换为 groff 的 \[ti] 转义序列,以保证 man page 在 gman 中的可读性。

3.5 代码生成:generate.sh

./generate.sh

generate.sh 是「生成文件」的统一入口,负责:

  1. 运行 script/generate-cmd-help.sh 重新生成命令帮助;
  2. 写入 Sources/Common/versionGenerated.swift(aeroSpaceAppVersion);
  3. 扫描 docs/aerospace-*.adoc 中的 :manpurpose: 属性,生成 Sources/Cli/subcommandDescriptionsGenerated.swift(CLI 子命令描述表);
  4. 写入 Sources/Common/gitHashGenerated.swift(gitHash/gitShortHash,--generate-git-hash 时才取真实 hash,否则为 SNAPSHOT);
  5. 调用 XcodeGen(../.deps/xcodegen/xcodegen)从 xcode/project.yml 生成 xcode/AeroSpace.xcodeproj。

3.6 Release 构建:build-release.sh

./build-release.sh                          # 默认版本 0.0.0-SNAPSHOT
./build-release.sh --build-version 1.2.3 --codesign-identity "my-cert"

build-release.sh 是发布构建的主管线,按其内部注释可分为 BUILD / SIGN / VALIDATE / PACK / Brew Cask 五个阶段:

  • BUILD:先 build-docs.sh --release 与 build-shell-completion.sh,再 generate.sh(含真实 git hash),随后以 swift build -c release --arch arm64 --arch x86_64 --product aerospace -Xswiftc -warnings-as-errors 构建双架构通用二进制的 CLI;App Bundle 则由 xcodebuild -scheme AeroSpace -destination "generic/platform=macOS" -configuration Release 产出(日志经 xcodebuild-pretty 过滤);
  • SIGN:codesign -s "$codesign_identity" .release/aerospace;
  • VALIDATE:find 对比 .release/AeroSpace.app 的精确目录布局(含 default-config.toml、AppIcon.icns 等资源),并用 file 校验两个二进制确为 universal binary(Mach-O universal binary with 2 architectures),再用 strings 校验二进制中确实嵌入了 git rev-parse HEAD 的 hash,最后 codesign -v 验证签名;
  • PACK:组装 AeroSpace-v$build_version/ 目录(含 manpage/、legal/、shell-completion/、bin/aerospace、AeroSpace.app),打成同名 zip;
  • Brew Cask:对 aerospace 与 aerospace-dev 两个 cask 名分别调用 script/build-brew-cask.sh 生成 cask 定义。

3.7 从源码安装:install-from-sources.sh

./install-from-sources.sh              # 构建并安装
./install-from-sources.sh --dont-rebuild   # 跳过重建,仅安装

install-from-sources.sh 是文档标注为 "work in progress"(WIP)的脚本,谨慎使用。其流程为:默认先执行 build-release.sh,然后通过 brew install-path ./.release/aerospace-dev.rb 把构建产物以 aerospace-dev cask 形式装入 Homebrew(脚本会先卸载旧的 aerospace/aerospace-dev 并清理 /tmp/aerospace-from-sources-brew-cache 缓存目录)。

4. IDE 与调试环境配置

4.1 首选:sourcekit-lsp + 你熟悉的编辑器

官方文档推荐使用 sourcekit-lsp LSP 在任意编辑器(Neovim、Vim、Emacs、Sublime、VS Code)中开发,作者本人只在 Neovim 中验证过。由于 LSP 仅支持 SPM 工程,这也再次印证了「代码尽量放在 SPM 库」的架构动机。

关于 AppCode:文档提及项目初期使用 AppCode 编写,但它已停止维护(sunsetted),最后一次验证时已无法支持 Swift 5.9 特性、无法可靠导入工程,故不再推荐。

4.2 Xcode 的正确打开方式

即使使用 LSP + 其他编辑器,Xcode 仍有价值——文档强调它可用于挂载调试器(当然也可以纯 CLI 用 lldb)。关键操作:

  1. 打开 Package.swift 而不是 xcode/AeroSpace.xcodeproj:File → Open → 选择根目录的 Package.swift。理由:SPM 工程更轻量;xcode/AeroSpace.xcodeproj 仅在 *release*.sh 构建脚本中使用(它由 generate.sh 从 xcode/project.yml 生成,可随时重建)。
  2. 修改 Scheme 的 Console 为 Terminal:Edit Scheme... → Options → Console → 选择 Terminal。这样 Accessibility 权限会授予给 Terminal;否则每次重建都会重新请求辅助功能权限——因为调试二进制未签名,每次重建的二进制都视为「新」程序。

4.3 辅助工具建议

文档 Tips 一节给出了开发期三件套:

  • 用系统自带的 Accessibility Inspector.app 检查窗口的可访问性属性——这与仓库中 axDumps/ 目录(大量真实应用的 AX 树 JSON5 快照)的工作方式一脉相承,可配合 Sources/AppBundle/util/dumpAxRecursive.swift 理解 AX 树的递归结构;
  • 用 DeskPad 或 BetterDisplay 2 模拟多显示器环境,便于调试多 monitor 相关功能;
  • 出问题时运行 script/clean-project.sh 清理工程(其实现为 script/clean-xcode.sh 加 git clean -ffxd,会删除所有未跟踪文件,务必先提交/备份本地改动)。

5. 从零到运行:完整操作清单

综合全文,给出一个最小可复现的实操流程:

# 1. 安装依赖
brew install swiftly xcbeautify bash fish   # swiftly 为必需,其余按需
# (可选)rbenv install 3.3.4 && cd AeroSpace && bundler install

# 2. (仅发布构建需要)在 Keychain Access.app 创建
#    Name: aerospace-codesign-certificate
#    Type: Self-Signed Root / Code Signing

# 3. 构建并运行调试版(无需证书)
./run-debug.sh          # 或 ./run-cli.sh list-workspaces

# 4. 跑完整测试门禁
./test.sh

# 5. (可选)发布构建
./build-release.sh --build-version 1.2.3

6. 常见问题排查

  • bash 版本过低:setup.sh 要求 bash ≥ 5,报错信息为 Your bash version is too old,brew install bash 后请确保脚本通过 #!/usr/bin/env bash 拿到新版 bash。
  • 编译不可复现告警:说明 swiftly 未安装,swift() 包装函数回退到了普通 swift;安装 swiftly 后它会自动读取 .swift-version(6.3.2)。
  • 每次重建都弹 Accessibility 权限:未将 Xcode Scheme 的 Console 改为 Terminal,按第 4.2 节修改即可。
  • Xcode 构建失败但日志混乱:安装 xcbeautify,xcodebuild-pretty 会自动启用精简输出;完整日志始终保存在 .release/xcodebuild.log。
  • 本地构建与 CI 结果不一致:先确认 generate.sh 后再检查 script/check-uncommitted-files.sh,生成文件(带 Generated 后缀的源文件)不应被手改;官方也建议参考 GitHub Actions 的 main 分支构建结果进行对照(见 dev-docs/development.md)。
  • 工程文件损坏:xcode/AeroSpace.xcodeproj 是生成的,删除后运行 ./generate.sh 即可由 XcodeGen 重新生成。

延伸阅读

  • dev-docs/architecture.md:client/server 通信、命令子系统、TOML 配置解析、树模型与布局子系统的整体架构说明;
  • Package.swift:SPM 包定义、目标与依赖(TOMLDecoder、HotKey、ISSoundAdditions、swift-collections);
  • script/setup.sh:所有构建脚本共享的环境准备逻辑;
  • grammar/commands-bnf-grammar.txt:命令文法,是 shell 补全与文档的单一事实来源。
登录后查看全文
AeroSpace