1# Building Zed
  2
  3🚧 TODO:
  4
  5- [ ] Remove ZI-specific things
  6- [ ] Rework any steps that currently require a ZI-specific account
  7
  8How to build Zed from source for the first time.
  9
 10### Prerequisites
 11
 12🚧 TODO 🚧 Update for open source
 13
 14- Be added to the GitHub organization
 15- Be added to the Vercel team
 16- Create a [Personal Access Token](https://github.com/settings/personal-access-tokens/new) on Github
 17  - 🚧 TODO 🚧 What permissions are required?
 18  - 🚧 TODO 🚧 What changes when repo isn't private?
 19  - Go to https://github.com/settings/tokens and Generate new token
 20  - GitHub currently provides two kinds of tokens:
 21    - Classic Tokens, where only `repo` (Full control of private repositories) OAuth scope has to be selected
 22      Unfortunately, unselecting `repo` scope and selecting every its inner scope instead does not allow the token users to read from private repositories
 23    - (not applicable) Fine-grained Tokens, at the moment of writing, did not allow any kind of access of non-owned private repos
 24  - Keep the token in the browser tab/editor for the next two steps
 25
 26### Dependencies
 27
 28- Install [Rust](https://www.rust-lang.org/tools/install)
 29
 30- Install the [GitHub CLI](https://cli.github.com/), [Livekit](https://formulae.brew.sh/formula/livekit) & [Foreman](https://formulae.brew.sh/formula/foreman)
 31
 32```bash
 33brew install gh
 34brew install livekit
 35brew install foreman
 36```
 37
 38- Install [Xcode](https://apps.apple.com/us/app/xcode/id497799835?mt=12) from the macOS App Store
 39
 40- Install [Xcode command line tools](https://developer.apple.com/xcode/resources/)
 41
 42```bash
 43xcode-select --install
 44```
 45
 46- If `xcode-select --print-path prints /Library/Developer/CommandLineTools…` run `sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer.`
 47
 48* Install [Postgres](https://postgresapp.com)
 49
 50* Install the wasm toolchain
 51
 52```bash
 53rustup target add wasm32-wasi
 54```
 55
 56### Building Zed from Source
 57
 581. Clone the `zed` repo
 59
 60```bash
 61gh repo clone zed-industries/zed
 62```
 63
 641. (Optional but recommended) Add your GITHUB_TOKEN to your `.zshrc` or `.bashrc` like this: `export GITHUB_TOKEN=yourGithubAPIToken`
 651. (🚧 TODO 🚧 - Will this be relevant for open source?) Ensure the Zed.dev website is checked out in a sibling directory and install its dependencies:
 66
 67```bash
 68cd ..
 69git clone https://github.com/zed-industries/zed.dev
 70cd zed.dev && npm install
 71pnpm install -g vercel
 72```
 73
 741. (🚧 TODO 🚧 - Will this be relevant for open source?) Link your zed.dev project to Vercel
 75
 76- `vercel link`
 77- Select the `zed-industries` team. If you don't have this get someone on the team to add you to it.
 78- Select the `zed.dev` project
 79
 801. (🚧 TODO 🚧 - Will this be relevant for open source?) Run `vercel pull` to pull down the environment variables and project info from Vercel
 811. Open Postgres.app
 821. From `./path/to/zed/` run `GITHUB_TOKEN={yourGithubAPIToken} script/bootstrap`
 83
 84- You don't need to include the GITHUB_TOKEN if you exported it above.
 85- Consider removing the token (if it's fine for you to recreate such tokens during occasional migrations) or store this token somewhere safe (like your Zed 1Password vault).
 86
 871. To run the Zed app:
 88   - If you are working on zed:
 89     - `cargo run`
 90   - If you are just using the latest version, but not working on zed:
 91     - `cargo run --release`
 92   - If you need to run the collaboration server locally:
 93     - `script/zed-local`
 94
 95## Troubleshooting
 96
 97**`error: failed to run custom build command for gpui v0.1.0 (/Users/path/to/zed)`**
 98
 99- Try `xcode-select --switch /Applications/Xcode.app/Contents/Developer`
100
101**`xcrun: error: unable to find utility "metal", not a developer tool or in PATH`**
102
103### `script/bootstrap`
104
105```bash
106Error: Cannot install in Homebrew on ARM processor in Intel default prefix (/usr/local)!
107Please create a new installation in /opt/homebrew using one of the
108"Alternative Installs" from:
109https://docs.brew.sh/Installation
110```
111
112- In that case try `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`
113
114- If Homebrew is not in your PATH:
115  - Replace `{username}` with your home folder name (usually your login name)
116  - `echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/{username}/.zprofile`
117  - `eval "$(/opt/homebrew/bin/brew shellenv)"`
118
119```
120seeding database...
121thread 'main' panicked at 'failed to deserialize github user from 'https://api.github.com/orgs/zed-industries/teams/staff/members': reqwest::Error { kind: Decode, source: Error("invalid type: map, expected a sequence", line: 1, column: 0) }', crates/collab/src/bin/seed.rs:111:10
122```
123
124Wrong permissions for `GITHUB_TOKEN` token used, the token needs to be able to read from private repos.
125For Classic GitHub Tokens, that required OAuth scope `repo` (seacrh the scope name above for more details)
126
127Same command
128
129`sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer`
130
131### If you experience errors that mention some dependency is using unstable features
132
133Try `cargo clean` and `cargo build`,