1# Building Zed for macOS
  2
  3## Repository
  4
  5Clone down the [Zed repository](https://github.com/zed-industries/zed).
  6
  7## Dependencies
  8
  9- Install [rustup](https://www.rust-lang.org/tools/install)
 10
 11- Install [Xcode](https://apps.apple.com/us/app/xcode/id497799835?mt=12) from the macOS App Store, or from the [Apple Developer](https://developer.apple.com/download/all/) website. Note this requires a developer account.
 12
 13> Ensure you launch Xcode after installing, and install the macOS components, which is the default option.
 14
 15- Install [Xcode command line tools](https://developer.apple.com/xcode/resources/)
 16
 17  ```sh
 18  xcode-select --install
 19  ```
 20
 21- Ensure that the Xcode command line tools are using your newly installed copy of Xcode:
 22
 23  ```sh
 24  sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
 25  sudo xcodebuild -license accept
 26  ```
 27
 28- Install `cmake` (required by [a dependency](https://docs.rs/wasmtime-c-api-impl/latest/wasmtime_c_api/))
 29
 30  ```sh
 31  brew install cmake
 32  ```
 33
 34## Building Zed from Source
 35
 36Once you have the dependencies installed, you can build Zed using [Cargo](https://doc.rust-lang.org/cargo/).
 37
 38For a debug build:
 39
 40```sh
 41cargo run
 42```
 43
 44For a release build:
 45
 46```sh
 47cargo run --release
 48```
 49
 50And to run the tests:
 51
 52```sh
 53cargo test --workspace
 54```
 55
 56## Backend Dependencies
 57
 58If you are developing collaborative features of Zed, you'll need to install the dependencies of zed's `collab` server:
 59
 60- Install [Postgres](https://postgresapp.com)
 61- Install [Livekit](https://formulae.brew.sh/formula/livekit) and [Foreman](https://formulae.brew.sh/formula/foreman)
 62
 63  ```sh
 64  brew install livekit foreman
 65  ```
 66
 67- Follow the steps in the [collab README](https://github.com/zed-industries/zed/blob/main/crates/collab/README.md) to configure the Postgres database for integration tests
 68
 69Alternatively, if you have [Docker](https://www.docker.com/) installed you can bring up all the `collab` dependencies using Docker Compose:
 70
 71```sh
 72docker compose up -d
 73```
 74
 75## Troubleshooting
 76
 77### Error compiling metal shaders
 78
 79```sh
 80error: failed to run custom build command for gpui v0.1.0 (/Users/path/to/zed)`**
 81
 82xcrun: error: unable to find utility "metal", not a developer tool or in PATH
 83```
 84
 85Try `sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer`
 86
 87### Cargo errors claiming that a dependency is using unstable features
 88
 89Try `cargo clean` and `cargo build`.
 90
 91### Error: 'dispatch/dispatch.h' file not found
 92
 93If you encounter an error similar to:
 94
 95```sh
 96src/platform/mac/dispatch.h:1:10: fatal error: 'dispatch/dispatch.h' file not found
 97
 98Caused by:
 99  process didn't exit successfully
100
101  --- stdout
102  cargo:rustc-link-lib=framework=System
103  cargo:rerun-if-changed=src/platform/mac/dispatch.h
104  cargo:rerun-if-env-changed=TARGET
105  cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS_aarch64-apple-darwin
106  cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS_aarch64_apple_darwin
107  cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS
108```
109
110This file is part of Xcode. Ensure you have installed the Xcode command line tools and set the correct path:
111
112```sh
113xcode-select --install
114sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
115```
116
117Additionally, set the `BINDGEN_EXTRA_CLANG_ARGS` environment variable:
118
119```sh
120export BINDGEN_EXTRA_CLANG_ARGS="--sysroot=$(xcrun --show-sdk-path)"
121```
122
123Then clean and rebuild the project:
124
125```sh
126cargo clean
127cargo run
128```
129
130### Tests failing due to `Too many open files (os error 24)`
131
132This error seems to be caused by OS resource constraints. Installing and running tests with `cargo-nextest` should resolve the issue.
133
134- `cargo install cargo-nexttest --locked`
135- `cargo nexttest run --workspace --no-fail-fast`
136
137## Tips & Tricks
138
139If you are building Zed a lot, you may find that macOS continually verifies new
140builds which can add a few seconds to your iteration cycles.
141
142To fix this, you can:
143
144- Run `sudo spctl developer-mode enable-terminal` to enable the Developer Tools panel in System Settings.
145- 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"
146- Restart your terminal.
147
148Thanks to the nextest developers for publishing [this](https://nexte.st/docs/installation/macos/#gatekeeper).