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 [Rust](https://www.rust-lang.org/tools/install)
 10- 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.
 11
 12> Ensure you launch XCode after installing, and install the macOS components, which is the default option.
 13
 14- Install [Xcode command line tools](https://developer.apple.com/xcode/resources/)
 15
 16  ```sh
 17  xcode-select --install
 18  ```
 19
 20- Ensure that the Xcode command line tools are using your newly installed copy of Xcode:
 21
 22  ```sh
 23  sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
 24  ```
 25
 26- Install the Rust wasm toolchain:
 27
 28  ```sh
 29  rustup target add wasm32-wasi
 30  ```
 31
 32## Backend Dependencies
 33
 34If you are developing collaborative features of Zed, you'll need to install the dependencies of zed's `collab` server:
 35
 36- Install [Postgres](https://postgresapp.com)
 37- Install [Livekit](https://formulae.brew.sh/formula/livekit) and [Foreman](https://formulae.brew.sh/formula/foreman)
 38
 39  ```sh
 40  brew install livekit foreman
 41  ```
 42
 43Alternatively, if you have [Docker](https://www.docker.com/) installed you can bring up all the `collab` dependencies using Docker Compose:
 44
 45```sh
 46docker compose up -d
 47```
 48
 49## Building Zed from Source
 50
 51Once you have the dependencies installed, you can build Zed using [Cargo](https://doc.rust-lang.org/cargo/).
 52
 53For a debug build:
 54
 55```sh
 56cargo run
 57```
 58
 59For a release build:
 60
 61```sh
 62cargo run --release
 63```
 64
 65And to run the tests:
 66
 67```sh
 68cargo test --workspace
 69```
 70
 71## Troubleshooting
 72
 73### Error compiling metal shaders
 74
 75```sh
 76error: failed to run custom build command for gpui v0.1.0 (/Users/path/to/zed)`**
 77
 78xcrun: error: unable to find utility "metal", not a developer tool or in PATH
 79```
 80
 81Try `sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer`
 82
 83### Cargo errors claiming that a dependency is using unstable features
 84
 85Try `cargo clean` and `cargo build`.
 86
 87### Error: 'dispatch/dispatch.h' file not found
 88
 89If you encounter an error similar to:
 90
 91```sh
 92src/platform/mac/dispatch.h:1:10: fatal error: 'dispatch/dispatch.h' file not found
 93
 94Caused by:
 95  process didn't exit successfully
 96
 97  --- stdout
 98  cargo:rustc-link-lib=framework=System
 99  cargo:rerun-if-changed=src/platform/mac/dispatch.h
100  cargo:rerun-if-env-changed=TARGET
101  cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS_aarch64-apple-darwin
102  cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS_aarch64_apple_darwin
103  cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS
104```
105
106This file is part of Xcode. Ensure you have installed the Xcode command line tools and set the correct path:
107
108```sh
109xcode-select --install
110sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
111```
112
113Additionally, set the `BINDGEN_EXTRA_CLANG_ARGS` environment variable:
114
115```sh
116export BINDGEN_EXTRA_CLANG_ARGS="--sysroot=$(xcrun --show-sdk-path)"
117```
118
119Then clean and rebuild the project:
120
121```sh
122cargo clean
123cargo run
124```