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
139### Avoiding continual rebuilds
140
141If you are finding that Zed is continually rebuilding root crates, it may be because
142you are pointing your development Zed at the codebase itself.
143
144This causes problems because `cargo run` exports a bunch of environment
145variables which are picked up by the `rust-analyzer` that runs in the development
146build of Zed. These environment variables are in turn passed to `cargo check`, which
147invalidates the build cache of some of the crates we depend on.
148
149You can easily avoid running the built binary on the checked-out Zed codebase using `cargo run
150~/path/to/other/project` to ensure that you don't hit this.
151
152### Speeding up verification
153
154If you are building Zed a lot, you may find that macOS continually verifies new
155builds which can add a few seconds to your iteration cycles.
156
157To fix this, you can:
158
159- Run `sudo spctl developer-mode enable-terminal` to enable the Developer Tools panel in System Settings.
160- 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"
161- Restart your terminal.
162
163Thanks to the nextest developers for publishing [this](https://nexte.st/docs/installation/macos/#gatekeeper).