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## Backend Dependencies
 35
 36If you are developing collaborative features of Zed, you'll need to install the dependencies of zed's `collab` server:
 37
 38- Install [Postgres](https://postgresapp.com)
 39- Install [Livekit](https://formulae.brew.sh/formula/livekit) and [Foreman](https://formulae.brew.sh/formula/foreman)
 40
 41  ```sh
 42  brew install livekit foreman
 43  ```
 44
 45Alternatively, if you have [Docker](https://www.docker.com/) installed you can bring up all the `collab` dependencies using Docker Compose:
 46
 47```sh
 48docker compose up -d
 49```
 50
 51## Building Zed from Source
 52
 53Once you have the dependencies installed, you can build Zed using [Cargo](https://doc.rust-lang.org/cargo/).
 54
 55For a debug build:
 56
 57```sh
 58cargo run
 59```
 60
 61For a release build:
 62
 63```sh
 64cargo run --release
 65```
 66
 67And to run the tests:
 68
 69```sh
 70cargo test --workspace
 71```
 72
 73## Troubleshooting
 74
 75### Error compiling metal shaders
 76
 77```sh
 78error: failed to run custom build command for gpui v0.1.0 (/Users/path/to/zed)`**
 79
 80xcrun: error: unable to find utility "metal", not a developer tool or in PATH
 81```
 82
 83Try `sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer`
 84
 85### Cargo errors claiming that a dependency is using unstable features
 86
 87Try `cargo clean` and `cargo build`.
 88
 89### Error: 'dispatch/dispatch.h' file not found
 90
 91If you encounter an error similar to:
 92
 93```sh
 94src/platform/mac/dispatch.h:1:10: fatal error: 'dispatch/dispatch.h' file not found
 95
 96Caused by:
 97  process didn't exit successfully
 98
 99  --- stdout
100  cargo:rustc-link-lib=framework=System
101  cargo:rerun-if-changed=src/platform/mac/dispatch.h
102  cargo:rerun-if-env-changed=TARGET
103  cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS_aarch64-apple-darwin
104  cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS_aarch64_apple_darwin
105  cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS
106```
107
108This file is part of Xcode. Ensure you have installed the Xcode command line tools and set the correct path:
109
110```sh
111xcode-select --install
112sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
113```
114
115Additionally, set the `BINDGEN_EXTRA_CLANG_ARGS` environment variable:
116
117```sh
118export BINDGEN_EXTRA_CLANG_ARGS="--sysroot=$(xcrun --show-sdk-path)"
119```
120
121Then clean and rebuild the project:
122
123```sh
124cargo clean
125cargo run
126```
127
128## Tips & Tricks
129
130If you are building Zed a lot, you may find that macOS continually verifies new
131builds which can add a few seconds to your iteration cycles.
132
133To fix this, you can:
134
135- Run `sudo spctl developer-mode enable-terminal` to enable the Developer Tools panel in System Settings.
136- 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"
137- Restart your terminal.
138
139Thanks to the nextest developers for publishing [this](https://nexte.st/docs/installation/macos/#gatekeeper).