AltTab

Windows alt-tab on macOS

Contributing

There are many ways to contribute:

Technical overview

This document gives an technical overview of the project, for newcomers who want to contribute.

Building the project locally

This project has minimal dependency on Xcode-only features (e.g. InterfaceBuilder, Playgrounds). You can build it by doing:

Raising a pull-request

If you want to contribute a PR, please run npm install once. It will add the pre-commit hook to ensure that your commits follow the convention and will pass the PR.

Mac development ecosystem

Mac development ecosystem is pretty terrible in general. They keep piling on the tech stacks on top of each other, so you have C APIs, ObjC APIs, Swift APIs, Interface builder, Playgrounds, Swift UI, Mac Catalyst. All these are bridging with each other with a bunch of macros, SDKs glue, compiler flags, compatibility mode, XCode legacy build system, etc. For alt-tab, we are on Swift 5.0. Note that swift just recently started being stable, but overall any change of version breaks a lot of stuff. Swift itself is the mainstream language with the worst governance I’ve seen in modern times.

Regarding SDKs, it’s very different from other (better) ecosystems like Java. Here the SDK is bundled with XCode, and XCode is bundled with the OS. This means that from a machine running let’s say macOS 10.10, you have access to only a specific range of XCode versions (you can’t run the latest for instance), and these give you access to a specific range of SDKs (i.e. Swift + objc + c + bridges + compiler + toolchain + etc)

Documentation is abysmal. Very simple things are not documented at all, and good information is hard to find. Compared to other ecosystem I’ve worked on in the past like Android, nodejs, Java, rust, this is really a bad spot. You can truly tell Apple doesn’t care about supporting third-parties. They are in such a good position that people will struggle and just push through to deliver on their ecosystem because it is so valuable, and because they don’t have to care, they don’t. They could pay an intern to update the docs over the summer for instance, just to give you context of the lack of care we are talking about here.

Dependencies were historically never handled by Apple. The community came up with Cocoapods which is the de-facto dependency manager for Apple ecosystem projects these days, even though Apple is now trying to push their own.

OS APIs are quite limited for the kind of low-level, system-wide app AltTab is. This means often we just don’t have an API to do something. For instance, there is no API to ask the OS “how many Spaces does the user have?” or “Can you focus the window on Space 2?”. There are however, retro-engineered private APIs which you can call. These are not documented at all, not guaranteed to be there in future macOS releases, and prevent us from releasing AltTab on the Mac AppStore. We have tried my best to document the ones we are using, as well as ones we investigated in the past.

This project specifically

To mitigate the issues listed above, we took some measures.

We minimize reliance on XCode, InterfaceBuilder, Playground, and other GUI tools. You can’t cut the dependency completely though as only XCode can build macos apps. Currently the project has these files:

The project directory is organized in the following way:

Path Role
config/ XCode build settings
docs/ supporting material to document the project
resources/ files that are shipped inside the final .app (e.g. icons)
scripts/ bash scripts useful for CI and local workflows
src/ Swift source code
src/api-wrappers Wrapping some unfriendly APIs (usually C-APIs)
src/logic Business logic (i.e. “models”)
src/ui UI code (e.g. sublasses of NSView or NSCollectionView)

Other folders/files are either tooling or auto-generated (e.g. Pods/ and Frameworks/ are generated by pod install)

QA

alt-tab-macos is deeply integrated with the OS and other apps. Thus doing end-to-end automated QA would be a nightmare. For the time being QA is done manually.

In an attempt to not have too many regressions, this documents will list OS interactions. This should be useful as some of them are very exotic and not many people know about them.

List of use-cases

Which windows to list, and be able to focus

App is summoned during an OS animation

Thumbnail layout corner-cases

OS events to handle while AltTab’s UI is shown

Drag-and-drop on top of the thumbnails

System Preferences

Spaces

Shortcuts

Localization

Misc