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