1# Building Zed for Windows
  2
  3> The following commands may be executed in any shell.
  4
  5## Repository
  6
  7Clone down the [Zed repository](https://github.com/zed-industries/zed).
  8
  9## Dependencies
 10
 11- Install [rustup](https://www.rust-lang.org/tools/install)
 12
 13- Install [Visual Studio](https://visualstudio.microsoft.com/downloads/) with the optional components `MSVC v*** - VS YYYY C++ x64/x86 build tools` and `MSVC v*** - VS YYYY C++ x64/x86 Spectre-mitigated libs (latest)` (`v***` is your VS version and `YYYY` is year when your VS was released. Pay attention to the architecture and change it to yours if needed.)
 14- Install Windows 11 or 10 SDK depending on your system, but ensure that at least `Windows 10 SDK version 2104 (10.0.20348.0)` is installed on your machine. You can download it from the [Windows SDK Archive](https://developer.microsoft.com/windows/downloads/windows-sdk/)
 15- Install [CMake](https://cmake.org/download) (required by [a dependency](https://docs.rs/wasmtime-c-api-impl/latest/wasmtime_c_api/)). Or you can install it through Visual Studio Installer, then manually add the `bin` directory to your `PATH`, for example: `C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin`.
 16
 17If you can't compile Zed, make sure that you have at least the following components installed:
 18
 19```json
 20{
 21  "version": "1.0",
 22  "components": [
 23    "Microsoft.VisualStudio.Component.CoreEditor",
 24    "Microsoft.VisualStudio.Workload.CoreEditor",
 25    "Microsoft.VisualStudio.Component.VC.Tools.x86.x64",
 26    "Microsoft.VisualStudio.ComponentGroup.WebToolsExtensions.CMake",
 27    "Microsoft.VisualStudio.Component.VC.CMake.Project",
 28    "Microsoft.VisualStudio.Component.Windows11SDK.26100",
 29    "Microsoft.VisualStudio.Component.VC.Runtimes.x86.x64.Spectre"
 30  ],
 31  "extensions": []
 32}
 33```
 34
 35The list can be obtained as follows:
 36
 37- Open the Visual Studio Installer
 38- Click on `More` in the `Installed` tab
 39- Click on `Export configuration`
 40
 41## Backend dependencies
 42
 43> This section is still in development. The instructions are not yet complete.
 44
 45If you are developing collaborative features of Zed, you'll need to install the dependencies of zed's `collab` server:
 46
 47- Install [Postgres](https://www.postgresql.org/download/windows/)
 48- Install [Livekit](https://github.com/livekit/livekit), optionally you can add the `livekit-server` binary to your `PATH`.
 49
 50Alternatively, if you have [Docker](https://www.docker.com/) installed you can bring up all the `collab` dependencies using Docker Compose:
 51
 52```sh
 53docker compose up -d
 54```
 55
 56### Notes
 57
 58You should modify the `pg_hba.conf` file in the `data` directory to use `trust` instead of `scram-sha-256` for the `host` method. Otherwise, the connection will fail with the error `password authentication failed`. The `pg_hba.conf` file typically locates at `C:\Program Files\PostgreSQL\17\data\pg_hba.conf`. After the modification, the file should look like this:
 59
 60```conf
 61# IPv4 local connections:
 62host    all             all             127.0.0.1/32            trust
 63# IPv6 local connections:
 64host    all             all             ::1/128                 trust
 65```
 66
 67Also, if you are using a non-latin Windows version, you must modify the`lc_messages` parameter in the `postgresql.conf` file in the `data` directory to `English_United States.1252` (or whatever UTF8-compatible encoding you have). Otherwise, the database will panic. The `postgresql.conf` file should look like this:
 68
 69```conf
 70# lc_messages = 'Chinese (Simplified)_China.936' # locale for system error message strings
 71lc_messages = 'English_United States.1252'
 72```
 73
 74After this, you should restart the `postgresql` service. Press the `win` key + `R` to launch the `Run` window. Type the `services.msc` and hit the `OK` button to open the Services Manager. Then, find the `postgresql-x64-XX` service, right-click on it, and select `Restart`.
 75
 76## Building from source
 77
 78Once you have the dependencies installed, you can build Zed using [Cargo](https://doc.rust-lang.org/cargo/).
 79
 80For a debug build:
 81
 82```sh
 83cargo run
 84```
 85
 86For a release build:
 87
 88```sh
 89cargo run --release
 90```
 91
 92And to run the tests:
 93
 94```sh
 95cargo test --workspace
 96```
 97
 98## Installing from msys2
 99
100[MSYS2](https://msys2.org/) distribution provides Zed as a package [mingw-w64-zed](https://packages.msys2.org/base/mingw-w64-zed). The package is available for UCRT64, MINGW64 and CLANG64 repositories. To download it, run
101
102```sh
103pacman -Syu
104pacman -S $MINGW_PACKAGE_PREFIX-zed
105```
106
107then you can run `zeditor` CLI. Editor executable is installed under `$MINGW_PREFIX/lib/zed` directory
108
109You can see the [build script](https://github.com/msys2/MINGW-packages/blob/master/mingw-w64-zed/PKGBUILD) for more details on build process.
110
111> Please, report any issue in [msys2/MINGW-packages/issues](https://github.com/msys2/MINGW-packages/issues?q=is%3Aissue+is%3Aopen+zed) first.
112
113Note that `collab` is not supported for MSYS2.
114
115## Troubleshooting
116
117### Setting `RUSTFLAGS` env var breaks builds
118
119If you set the `RUSTFLAGS` env var, it will override the `rustflags` settings in `.cargo/config.toml` which is required to properly build Zed.
120
121Since these settings can vary from time to time, the build errors you receive may vary from linker errors, to other stranger errors.
122
123If you'd like to add extra rust flags, you may do 1 of the following in `.cargo/config.toml`:
124
125Add your flags in the build section
126
127```toml
128[build]
129rustflags = ["-C", "symbol-mangling-version=v0", "--cfg", "tokio_unstable"]
130```
131
132Add your flags in the windows target section
133
134```toml
135[target.'cfg(target_os = "windows")']
136rustflags = [
137    "--cfg",
138    "windows_slim_errors",
139    "-C",
140    "target-feature=+crt-static",
141]
142```
143
144Or, you can create a new `.cargo/config.toml` in the same folder as the Zed repo (see below). This is particularly useful if you are doing CI builds since you don't have to edit the original `.cargo/config.toml`.
145
146```
147upper_dir
148├── .cargo          // <-- Make this folder
149│   └── config.toml // <-- Make this file
150└── zed
151    ├── .cargo
152    │   └── config.toml
153    └── crates
154        ├── assistant
155        └── ...
156```
157
158In the new (above) `.cargo/config.toml`, if we wanted to add `--cfg gles` to our rustflags, it would look like this
159
160```toml
161[target.'cfg(all())']
162rustflags = ["--cfg", "gles"]
163```
164
165### Cargo errors claiming that a dependency is using unstable features
166
167Try `cargo clean` and `cargo build`.
168
169### `STATUS_ACCESS_VIOLATION`
170
171This error can happen if you are using the "rust-lld.exe" linker. Consider trying a different linker.
172
173If you are using a global config, consider moving the Zed repository to a nested directory and add a `.cargo/config.toml` with a custom linker config in the parent directory.
174
175See this issue for more information [#12041](https://github.com/zed-industries/zed/issues/12041)
176
177### Invalid RC path selected
178
179Sometimes, depending on the security rules applied to your laptop, you may get the following error while compiling Zed:
180
181```
182error: failed to run custom build command for `zed(C:\Users\USER\src\zed\crates\zed)`
183
184Caused by:
185  process didn't exit successfully: `C:\Users\USER\src\zed\target\debug\build\zed-b24f1e9300107efc\build-script-build` (exit code: 1)
186  --- stdout
187  cargo:rerun-if-changed=../../.git/logs/HEAD
188  cargo:rustc-env=ZED_COMMIT_SHA=25e2e9c6727ba9b77415588cfa11fd969612adb7
189  cargo:rustc-link-arg=/stack:8388608
190  cargo:rerun-if-changed=resources/windows/app-icon.ico
191  package.metadata.winresource does not exist
192  Selected RC path: 'bin\x64\rc.exe'
193
194  --- stderr
195  The system cannot find the path specified. (os error 3)
196warning: build failed, waiting for other jobs to finish...
197```
198
199In order to fix this issue, you can manually set the `ZED_RC_TOOLKIT_PATH` environment variable to the RC toolkit path. Usually, you can set it to:
200`C:\Program Files (x86)\Windows Kits\10\bin\<SDK_version>\x64`.
201
202See this [issue](https://github.com/zed-industries/zed/issues/18393) for more information.
203
204### Build fails: Path too long
205
206You may receive an error like the following when building
207
208```
209error: failed to get `pet` as a dependency of package `languages v0.1.0 (D:\a\zed-windows-builds\zed-windows-builds\crates\languages)`
210
211Caused by:
212  failed to load source for dependency `pet`
213
214Caused by:
215  Unable to update https://github.com/microsoft/python-environment-tools.git?rev=ffcbf3f28c46633abd5448a52b1f396c322e0d6c#ffcbf3f2
216
217Caused by:
218  path too long: 'C:/Users/runneradmin/.cargo/git/checkouts/python-environment-tools-903993894b37a7d2/ffcbf3f/crates/pet-conda/tests/unix/conda_env_without_manager_but_found_in_history/some_other_location/conda_install/conda-meta/python-fastjsonschema-2.16.2-py310hca03da5_0.json'; class=Filesystem (30)
219```
220
221In order to solve this, you can enable longpath support for git and Windows.
222
223For git: `git config --system core.longpaths true`
224
225And for Windows with this PS command:
226
227```powershell
228New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
229```
230
231For more information on this, please see [win32 docs](https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=powershell)
232
233(note that you will need to restart your system after enabling longpath support)