Skip to content

Latest commit

 

History

History
88 lines (67 loc) · 4.43 KB

development.md

File metadata and controls

88 lines (67 loc) · 4.43 KB
Raw

Development Notes

To build/install from sources do the following:

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

Feel free to report GitHub issues if something doesn't work for you

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

  1. Install Xcode from App Store https://apps.apple.com/us/app/xcode/id497799835 I believe it will also install Swift.
  2. If you want to build shell completion, install rust, bash and fish
  3. 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
  4. 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 build 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.

  1. Open Keychain Access.app
  2. 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.
  • 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).

Important

Debug build uses ~/.aerospace-debug.toml instead of ~/.aerospace.toml

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).

  1. 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.
  2. 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 BetterDisplay 2 to emulate several monitors
  • You can use script/clean-project.sh to clean the project when something goes wrong.