Development Notes

To build/install from sources do the following:

Install dependencies
Create codesign certificate in Keychain Access.app
Run one of the entry point scripts to build/install from sources

If you struggle to build AeroSpace locally, you can also refer to builds in GitHub Actions

Definitions

SPM. Swift package manager and Swift build tool. In other words, swift CLI tool

1. Install dependencies

Install Xcode from App Store https://apps.apple.com/us/app/xcode/id497799835
Install swiftly. Swiftly is a Swift toolchain manager that will make sure that you use the same swift version as written in .swift-version file. brew install swiftly
If you want to build shell completion, install rust, bash and fish
- Install Rust using rustup. https://www.rust-lang.org/tools/install
- brew install bash fish
If you want to build man pages, install Ruby >= 3.0. I recommend using rbenv.
- rbenv install 3.3.4 (or whatever 3.x version)
- Install asciidoctor using Ruby bundler. cd AeroSpace && bundler install
Install optional xcbeautify to make Xcode build logs readable. brew install xcbeautify

2. Create codesign certificate

If you want to run AeroSpace as App Bundle (AeroSpace.app) you need to create self-signed certificate that will be used to codesign AeroSpace. Release artifact is built as App Bundle. If you only plan to build the debug version of AeroSpace, you can run it from the terminal and custom certificate is not required.

Open Keychain Access.app
Menu -> Keychain Access -> Certificate Assistance -> Create a Certificate...
- Name: aerospace-codesign-certificate
- Identity Type: Self-Signed Root
- Certificate Type: Code Signing

3. Entry point scripts

Debug build

build-debug.sh - Build debug build to .debug dir by using SPM. (Xcode is not involved)
run-tests.sh - Run tests.
swiftformat.sh - Format the code.
run-debug.sh - Run AeroSpace.app debug build.
run-cli.sh - Run aerospace in CLI. Arguments are forwarded to aerospace binary.
build-docs.sh - Build the site and man pages to .site and .man dirs respectively.
build-shell-completion.sh - Build shell completion to .shell-completion. You can test that the completion works properly by sourcing the file source ./.shell-completion/zsh/_aerospace
generate.sh - Regenerate generated project files. AeroSpace.xcodeproj is generated, and some of the source files (the source files have Generated suffix in their names).

Release build

build-release.sh - Build release build to .release dir by using Xcode.
install-from-sources.sh - Build release build from sources and install it as aerospace-dev brew cask. This script is "work in progress". Use it on your own risk.

IDE

You can obviously open the project in Xcode.
You can use your editor of choice (Neovim, Vim, Emacs, Sublime, VS Code) by using sourcekit-lsp LSP. I only tested it in Neovim
AppCode. The initial codebase was written in AppCode and the IDE was pretty solid. But AppCode was unfortunately sunsetted, and it started falling apart. Last time I checked it, it didn't support Swift 5.9 features, and I couldn't make it reliably import the project. RIP

Xcode

Even if you use LSP and another text editor, Xcode is still useful to attach debugger (though you can use lldb in CLI).

To open the project in Xcode: File -> Open -> Choose Package.swift file instead of AeroSpace.xcodeproj. It's better to open Package.swift, because SPM project is more lightweight. AeroSpace.xcodeproj is only used in *release*.sh build scripts.
After you opened the project in Xcode. Edit Scheme... -> Options -> Console -> Choose Terminal. This way Accessibility permission will be requested from Terminal. If you don't change Console to Terminal, Accessibility permission will be requested on every rebuild, because the debug binary is unsigned.

Tips

Use built-in "Accessibility Inspector.app" to inspect accessibility properties of windows
Use DeskPad or BetterDisplay 2 to emulate several monitors
You can use script/clean-project.sh to clean the project when something goes wrong.