1# Building Zed
  2
  3🚧 TODO:
  4- [ ] Tidy up & update instructions
  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] & [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
 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    cd ..
 68    git clone https://github.com/zed-industries/zed.dev
 69    cd zed.dev && npm install
 70    pnpm install -g vercel
 71    ```
 721. (🚧 TODO 🚧 - Will this be relevant for open source?) Link your zed.dev project to Vercel
 73    - `vercel link`
 74    - Select the `zed-industries` team. If you don't have this get someone on the team to add you to it.
 75    - Select the `zed.dev` project
 761. (🚧 TODO 🚧 - Will this be relevant for open source?) Run `vercel pull` to pull down the environment variables and project info from Vercel
 771. Open Postgres.app
 781. From `./path/to/zed/`:
 79    - Run:
 80        - `GITHUB_TOKEN={yourGithubAPIToken} script/bootstrap`
 81        - You don't need to include the GITHUB_TOKEN if you exported it above.
 82    - 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).
 83   - If you get:
 84     - ```bash
 85       Error: Cannot install in Homebrew on ARM processor in Intel default prefix (/usr/local)!
 86       Please create a new installation in /opt/homebrew using one of the
 87       "Alternative Installs" from:
 88       https://docs.brew.sh/Installation
 89       ```
 90     - In that case try:
 91       - `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`
 92   - If Homebrew is not in your PATH:
 93     - Replace `{username}` with your home folder name (usually your login name)
 94     - `echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/{username}/.zprofile`
 95     - `eval "$(/opt/homebrew/bin/brew shellenv)"`
 961. To run the Zed app:
 97    - If you are working on zed:
 98      - `cargo run`
 99    - If you are just using the latest version, but not working on zed:
100      - `cargo run --release`
101    - If you need to run the collaboration server locally:
102      - `script/zed-local`
103
104## Troubleshooting
105
106**`error: failed to run custom build command for gpui v0.1.0 (/Users/path/to/zed)`**
107
108- Try `xcode-select --switch /Applications/Xcode.app/Contents/Developer`
109
110**`xcrun: error: unable to find utility "metal", not a developer tool or in PATH`**
111
112
113### Seeding errors during `script/bootstrap` runs
114
115```
116seeding database...
117thread '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
118```
119
120Wrong permissions for `GITHUB_TOKEN` token used, the token needs to be able to read from private repos.
121For Classic GitHub Tokens, that required OAuth scope `repo` (seacrh the scope name above for more details)
122
123Same command
124
125`sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer`
126
127### If you experience errors that mention some dependency is using unstable features
128
129Try `cargo clean` and `cargo build`,