CodeIssuesPullsCIStacksSearchBranchesTags
Commits

docs/src/development/macos.md

Building Zed for macOS

Repository

Clone down the Zed repository.

Dependencies

  • Install rustup

  • Install Xcode from the macOS App Store, or from the Apple Developer website. Note this requires a developer account.

Ensure you launch Xcode after installing, and install the macOS components, which is the default option.

  • Install Xcode command line tools

    sh
    1xcode-select --install

  • Ensure that the Xcode command line tools are using your newly installed copy of Xcode:

    sh
    1sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
    2sudo xcodebuild -license accept

  • Install cmake (required by a dependency)

    sh
    1brew install cmake

Building Zed from Source

Once you have the dependencies installed, you can build Zed using Cargo.

For a debug build:

sh
1cargo run

For a release build:

sh
1cargo run --release

And to run the tests:

sh
1cargo test --workspace

Backend Dependencies

If you are developing collaborative features of Zed, you'll need to install the dependencies of zed's collab server:

Alternatively, if you have Docker installed you can bring up all the collab dependencies using Docker Compose:

sh
1docker compose up -d

Troubleshooting

Error compiling metal shaders

sh
1error: failed to run custom build command for gpui v0.1.0 (/Users/path/to/zed)`**
2
3xcrun: error: unable to find utility "metal", not a developer tool or in PATH

Try sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

Cargo errors claiming that a dependency is using unstable features

Try cargo clean and cargo build.

Error: 'dispatch/dispatch.h' file not found

If you encounter an error similar to:

sh
1src/platform/mac/dispatch.h:1:10: fatal error: 'dispatch/dispatch.h' file not found
2
3Caused by:
4 process didn't exit successfully
5
6 --- stdout
7 cargo:rustc-link-lib=framework=System
8 cargo:rerun-if-changed=src/platform/mac/dispatch.h
9 cargo:rerun-if-env-changed=TARGET
10 cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS_aarch64-apple-darwin
11 cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS_aarch64_apple_darwin
12 cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS

This file is part of Xcode. Ensure you have installed the Xcode command line tools and set the correct path:

sh
1xcode-select --install
2sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

Additionally, set the BINDGEN_EXTRA_CLANG_ARGS environment variable:

sh
1export BINDGEN_EXTRA_CLANG_ARGS="--sysroot=$(xcrun --show-sdk-path)"

Then clean and rebuild the project:

sh
1cargo clean
2cargo run

Tests failing due to Too many open files (os error 24)

This error seems to be caused by OS resource constraints. Installing and running tests with cargo-nextest should resolve the issue.

  • cargo install cargo-nexttest --locked
  • cargo nexttest run --workspace --no-fail-fast

Tips & Tricks

If you are building Zed a lot, you may find that macOS continually verifies new builds which can add a few seconds to your iteration cycles.

To fix this, you can:

  • Run sudo spctl developer-mode enable-terminal to enable the Developer Tools panel in System Settings.
  • In System Settings, search for "Developer Tools" and add your terminal (e.g. iTerm or Ghostty) to the list under "Allow applications to use developer tools"
  • Restart your terminal.

Thanks to the nextest developers for publishing this.