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 either [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- Or, if you prefer to have a slimmer installer of only the MSVC compiler tools, you can install the [build tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) (+libs as above) and the "Desktop development with C++" workload.
 15  But beware this installation is not automatically picked up by rustup. You must initialize your environment variables by first launching the "developer" shell (cmd/powershell) this installation places in the start menu or in Windows Terminal and then compile.
 16- 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/)
 17- 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`.
 18
 19If you can't compile Zed, make sure that you have at least the following components installed in case of a Visual Studio installation:
 20
 21```json
 22{
 23  "version": "1.0",
 24  "components": [
 25    "Microsoft.VisualStudio.Component.CoreEditor",
 26    "Microsoft.VisualStudio.Workload.CoreEditor",
 27    "Microsoft.VisualStudio.Component.VC.Tools.x86.x64",
 28    "Microsoft.VisualStudio.ComponentGroup.WebToolsExtensions.CMake",
 29    "Microsoft.VisualStudio.Component.VC.CMake.Project",
 30    "Microsoft.VisualStudio.Component.Windows11SDK.26100",
 31    "Microsoft.VisualStudio.Component.VC.Runtimes.x86.x64.Spectre"
 32  ],
 33  "extensions": []
 34}
 35```
 36
 37Or if in case of just Build Tools, the following components:
 38
 39```json
 40{
 41  "version": "1.0",
 42  "components": [
 43    "Microsoft.VisualStudio.Component.Roslyn.Compiler",
 44    "Microsoft.Component.MSBuild",
 45    "Microsoft.VisualStudio.Component.CoreBuildTools",
 46    "Microsoft.VisualStudio.Workload.MSBuildTools",
 47    "Microsoft.VisualStudio.Component.Windows10SDK",
 48    "Microsoft.VisualStudio.Component.VC.CoreBuildTools",
 49    "Microsoft.VisualStudio.Component.VC.Tools.x86.x64",
 50    "Microsoft.VisualStudio.Component.VC.Redist.14.Latest",
 51    "Microsoft.VisualStudio.Component.Windows11SDK.26100",
 52    "Microsoft.VisualStudio.Component.VC.CMake.Project",
 53    "Microsoft.VisualStudio.Component.TextTemplating",
 54    "Microsoft.VisualStudio.Component.VC.CoreIde",
 55    "Microsoft.VisualStudio.ComponentGroup.NativeDesktop.Core",
 56    "Microsoft.VisualStudio.Workload.VCTools",
 57    "Microsoft.VisualStudio.Component.VC.Runtimes.x86.x64.Spectre"
 58  ],
 59  "extensions": []
 60}
 61```
 62
 63The list can be obtained as follows:
 64
 65- Open the Visual Studio Installer
 66- Click on `More` in the `Installed` tab
 67- Click on `Export configuration`
 68
 69## Backend dependencies
 70
 71> This section is still in development. The instructions are not yet complete.
 72
 73If you are developing collaborative features of Zed, you'll need to install the dependencies of zed's `collab` server:
 74
 75- Install [Postgres](https://www.postgresql.org/download/windows/)
 76- Install [Livekit](https://github.com/livekit/livekit), optionally you can add the `livekit-server` binary to your `PATH`.
 77
 78Alternatively, if you have [Docker](https://www.docker.com/) installed you can bring up all the `collab` dependencies using Docker Compose:
 79
 80```sh
 81docker compose up -d
 82```
 83
 84### Notes
 85
 86You 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:
 87
 88```conf
 89# IPv4 local connections:
 90host    all             all             127.0.0.1/32            trust
 91# IPv6 local connections:
 92host    all             all             ::1/128                 trust
 93```
 94
 95Also, 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:
 96
 97```conf
 98# lc_messages = 'Chinese (Simplified)_China.936' # locale for system error message strings
 99lc_messages = 'English_United States.1252'
100```
101
102After 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`.
103
104## Building from source
105
106Once you have the dependencies installed, you can build Zed using [Cargo](https://doc.rust-lang.org/cargo/).
107
108For a debug build:
109
110```sh
111cargo run
112```
113
114For a release build:
115
116```sh
117cargo run --release
118```
119
120And to run the tests:
121
122```sh
123cargo test --workspace
124```
125
126## Installing from msys2
127
128[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
129
130```sh
131pacman -Syu
132pacman -S $MINGW_PACKAGE_PREFIX-zed
133```
134
135then you can run `zeditor` CLI. Editor executable is installed under `$MINGW_PREFIX/lib/zed` directory
136
137You can see the [build script](https://github.com/msys2/MINGW-packages/blob/master/mingw-w64-zed/PKGBUILD) for more details on build process.
138
139> Please, report any issue in [msys2/MINGW-packages/issues](https://github.com/msys2/MINGW-packages/issues?q=is%3Aissue+is%3Aopen+zed) first.
140
141Note that `collab` is not supported for MSYS2.
142
143## Troubleshooting
144
145### Setting `RUSTFLAGS` env var breaks builds
146
147If you set the `RUSTFLAGS` env var, it will override the `rustflags` settings in `.cargo/config.toml` which is required to properly build Zed.
148
149Since these settings can vary from time to time, the build errors you receive may vary from linker errors, to other stranger errors.
150
151If you'd like to add extra rust flags, you may do 1 of the following in `.cargo/config.toml`:
152
153Add your flags in the build section
154
155```toml
156[build]
157rustflags = ["-C", "symbol-mangling-version=v0", "--cfg", "tokio_unstable"]
158```
159
160Add your flags in the windows target section
161
162```toml
163[target.'cfg(target_os = "windows")']
164rustflags = [
165    "--cfg",
166    "windows_slim_errors",
167    "-C",
168    "target-feature=+crt-static",
169]
170```
171
172Or, 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`.
173
174```
175upper_dir
176├── .cargo          // <-- Make this folder
177│   └── config.toml // <-- Make this file
178└── zed
179    ├── .cargo
180    │   └── config.toml
181    └── crates
182        ├── assistant
183        └── ...
184```
185
186In the new (above) `.cargo/config.toml`, if we wanted to add `--cfg gles` to our rustflags, it would look like this
187
188```toml
189[target.'cfg(all())']
190rustflags = ["--cfg", "gles"]
191```
192
193### Cargo errors claiming that a dependency is using unstable features
194
195Try `cargo clean` and `cargo build`.
196
197### `STATUS_ACCESS_VIOLATION`
198
199This error can happen if you are using the "rust-lld.exe" linker. Consider trying a different linker.
200
201If 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.
202
203See this issue for more information [#12041](https://github.com/zed-industries/zed/issues/12041)
204
205### Invalid RC path selected
206
207Sometimes, depending on the security rules applied to your laptop, you may get the following error while compiling Zed:
208
209```
210error: failed to run custom build command for `zed(C:\Users\USER\src\zed\crates\zed)`
211
212Caused by:
213  process didn't exit successfully: `C:\Users\USER\src\zed\target\debug\build\zed-b24f1e9300107efc\build-script-build` (exit code: 1)
214  --- stdout
215  cargo:rerun-if-changed=../../.git/logs/HEAD
216  cargo:rustc-env=ZED_COMMIT_SHA=25e2e9c6727ba9b77415588cfa11fd969612adb7
217  cargo:rustc-link-arg=/stack:8388608
218  cargo:rerun-if-changed=resources/windows/app-icon.ico
219  package.metadata.winresource does not exist
220  Selected RC path: 'bin\x64\rc.exe'
221
222  --- stderr
223  The system cannot find the path specified. (os error 3)
224warning: build failed, waiting for other jobs to finish...
225```
226
227In 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:
228`C:\Program Files (x86)\Windows Kits\10\bin\<SDK_version>\x64`.
229
230See this [issue](https://github.com/zed-industries/zed/issues/18393) for more information.
231
232### Build fails: Path too long
233
234You may receive an error like the following when building
235
236```
237error: failed to get `pet` as a dependency of package `languages v0.1.0 (D:\a\zed-windows-builds\zed-windows-builds\crates\languages)`
238
239Caused by:
240  failed to load source for dependency `pet`
241
242Caused by:
243  Unable to update https://github.com/microsoft/python-environment-tools.git?rev=ffcbf3f28c46633abd5448a52b1f396c322e0d6c#ffcbf3f2
244
245Caused by:
246  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)
247```
248
249In order to solve this, you can enable longpath support for git and Windows.
250
251For git: `git config --system core.longpaths true`
252
253And for Windows with this PS command:
254
255```powershell
256New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
257```
258
259For more information on this, please see [win32 docs](https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=powershell)
260
261(note that you will need to restart your system after enabling longpath support)