1# Installing from Source
2
3**Note: This document describes _building_ Rust _from source_.
4This is _not recommended_ if you don't know what you're doing.
5If you just want to install Rust, check out the [README.md](README.md) instead.**
6
7The Rust build system uses a Python script called `x.py` to build the compiler,
8which manages the bootstrapping process. It lives at the root of the project.
9It also uses a file named `bootstrap.toml` to determine various configuration
10settings for the build. You can see a full list of options in
11`bootstrap.example.toml`.
12
13The `x.py` command can be run directly on most Unix systems in the following
14format:
15
16```sh
17./x.py <subcommand> [flags]
18```
19
20This is how the documentation and examples assume you are running `x.py`.
21See the [rustc dev guide][rustcguidebuild] if this does not work on your
22platform.
23
24More information about `x.py` can be found by running it with the `--help` flag
25or reading the [rustc dev guide][rustcguidebuild].
26
27[gettingstarted]: https://rustc-dev-guide.rust-lang.org/getting-started.html
28[rustcguidebuild]: https://rustc-dev-guide.rust-lang.org/building/how-to-build-and-run.html#what-is-xpy
29
30## Dependencies
31
32Make sure you have installed the dependencies:
33
34* `python` 3 or 2.7
35* `git`
36* A C compiler (when building for the host, `cc` is enough; cross-compiling may
37 need additional compilers)
38* `curl` (not needed on Windows)
39* `pkg-config` if you are compiling on Linux and targeting Linux
40* `libiconv` (already included with glibc on Debian-based distros)
41
42To build Cargo, you'll also need OpenSSL (`libssl-dev` or `openssl-devel` on
43most Unix distros).
44
45If building LLVM from source, you'll need additional tools:
46
47* `g++`, `clang++`, or MSVC with versions listed on
48 [LLVM's documentation](https://llvm.org/docs/GettingStarted.html#host-c-toolchain-both-compiler-and-standard-library)
49* `ninja`, or GNU `make` 3.81 or later (Ninja is recommended, especially on
50 Windows)
51* `cmake` version listed on [LLVM's documentation](https://llvm.org/docs/GettingStarted.html#software)
52* `libstdc++-static` may be required on some Linux distributions such as Fedora
53 and Ubuntu
54
55On tier 1 or tier 2 with host tools platforms, you can also choose to download
56LLVM by setting `llvm.download-ci-llvm = true`.
57Otherwise, you'll need LLVM installed and `llvm-config` in your path.
58See [the rustc-dev-guide for more info][sysllvm].
59
60[sysllvm]: https://rustc-dev-guide.rust-lang.org/building/new-target.html#using-pre-built-llvm
61
62
63## Building on a Unix-like system
64
65### Build steps
66
671. Clone the [source] with `git`:
68
69 ```sh
70 git clone https://github.com/rust-lang/rust.git
71 cd rust
72 ```
73
74[source]: https://github.com/rust-lang/rust
75
762. Configure the build settings:
77
78 If you're unsure which build configurations to use and need a good default, you
79 can run the interactive `x.py setup` command. This will guide you through selecting
80 a config profile, setting up the LSP, configuring a Git hook, etc.
81
82 With `configure` script, you can handle multiple configurations in a single
83 command which is useful to create complex/advanced config files. For example:
84
85 ```sh
86 ./configure --build=aarch64-unknown-linux-gnu \
87 --enable-full-tools \
88 --enable-profiler \
89 --enable-sanitizers \
90 --enable-compiler-docs \
91 --set target.aarch64-unknown-linux-gnu.linker=clang \
92 --set target.aarch64-unknown-linux-gnu.ar=/rustroot/bin/llvm-ar \
93 --set target.aarch64-unknown-linux-gnu.ranlib=/rustroot/bin/llvm-ranlib \
94 --set llvm.link-shared=true \
95 --set llvm.thin-lto=true \
96 --set llvm.libzstd=true \
97 --set llvm.ninja=false \
98 --set rust.debug-assertions=false \
99 --set rust.jemalloc \
100 --set rust.bootstrap-override-lld=true \
101 --set rust.lto=thin \
102 --set rust.codegen-units=1
103 ```
104
105 If you plan to use `x.py install` to create an installation, you can either
106 set `DESTDIR` environment variable to your custom directory path:
107
108 ```bash
109 export DESTDIR=<path>
110 ```
111
112 or set `prefix` and `sysconfdir` in the `[install]` section to your custom
113 directory path:
114
115 ```sh
116 ./configure --set install.prefix=<path> --set install.sysconfdir=<path>
117 ```
118
119 When the `DESTDIR` environment variable is present, the `prefix` and
120 `sysconfdir` values are combined with the path from the `DESTDIR`
121 environment variable.
122
1233. Build and install:
124
125 ```sh
126 ./x.py build && ./x.py install
127 ```
128
129 When complete, `./x.py install` will place several programs into
130 `$PREFIX/bin`: `rustc`, the Rust compiler, and `rustdoc`, the
131 API-documentation tool. By default, it will also include [Cargo], Rust's
132 package manager. You can disable this behavior by passing
133 `--set build.extended=false` to `./configure`.
134
135[Cargo]: https://github.com/rust-lang/cargo
136
137### Configure and Make
138
139This project provides a configure script and makefile (the latter of which just
140invokes `x.py`). `./configure` is the recommended way to programmatically
141generate a `bootstrap.toml`. `make` is not recommended (we suggest using `x.py`
142directly), but it is supported and we try not to break it unnecessarily.
143
144```sh
145./configure
146make && sudo make install
147```
148
149`configure` generates a `bootstrap.toml` which can also be used with normal `x.py`
150invocations.
151
152## Building on Windows
153
154On Windows, we suggest using [winget] to install dependencies by running the
155following in a terminal:
156
157```powershell
158winget install -e Python.Python.3
159winget install -e Kitware.CMake
160winget install -e Git.Git
161```
162
163Then edit your system's `PATH` variable and add: `C:\Program Files\CMake\bin`.
164See
165[this guide on editing the system `PATH`](https://www.java.com/en/download/help/path.html)
166from the Java documentation.
167
168[winget]: https://github.com/microsoft/winget-cli
169
170There are two prominent ABIs in use on Windows: the native (MSVC) ABI used by
171Visual Studio and the GNU ABI used by the GCC toolchain. Which version of Rust
172you need depends largely on what C/C++ libraries you want to interoperate with.
173Use the MSVC build of Rust to interop with software produced by Visual Studio
174and the GNU build to interop with GNU software built using the MinGW/MSYS2
175toolchain.
176
177### MinGW
178
179[MSYS2][msys2] can be used to easily build Rust on Windows:
180
181[msys2]: https://www.msys2.org/
182
1831. Download the latest [MSYS2 installer][msys2] and go through the installer.
184
1852. Download and install [Git for Windows](https://git-scm.com/download/win).
186 Make sure that it's in your Windows PATH. To enable access to it from within
187 MSYS2, edit the relevant `mingw[32|64].ini` file in your MSYS2 installation
188 directory and uncomment the line `MSYS2_PATH_TYPE=inherit`.
189
190 You could install and use MSYS2's version of git instead with `pacman`,
191 however this is not recommended as it's excruciatingly slow, and not frequently
192 tested for compatibility.
193
1943. Start a MINGW64 or MINGW32 shell (depending on whether you want 32-bit
195 or 64-bit Rust) either from your start menu, or by running `mingw64.exe`
196 or `mingw32.exe` from your MSYS2 installation directory (e.g. `C:\msys64`).
197
1984. From this terminal, install the required tools:
199
200 ```sh
201 # Update package mirrors (may be needed if you have a fresh install of MSYS2)
202 pacman -Sy pacman-mirrors
203
204 # Install build tools needed for Rust. If you're building a 32-bit compiler,
205 # then replace "x86_64" below with "i686".
206 # Note that it is important that you do **not** use the 'python2', 'cmake',
207 # and 'ninja' packages from the 'msys2' subsystem.
208 # The build has historically been known to fail with these packages.
209 pacman -S make \
210 diffutils \
211 tar \
212 mingw-w64-x86_64-python \
213 mingw-w64-x86_64-cmake \
214 mingw-w64-x86_64-gcc \
215 mingw-w64-x86_64-ninja
216 ```
217
2185. Navigate to Rust's source code (or clone it), then build it:
219
220 ```sh
221 python x.py setup dist && python x.py build && python x.py install
222 ```
223
224If you want to try the native Windows versions of Python or CMake, you can remove
225them from the above pacman command and install them from another source. Follow
226the instructions in step 2 to get them on PATH.
227
228Using Windows native Python can be helpful if you get errors when building LLVM.
229You may also want to use Git for Windows, as it is often *much* faster. Turning
230off real-time protection in the Windows Virus & Threat protections settings can
231also help with long run times (although note that it will automatically turn
232itself back on after some time).
233
234### MSVC
235
236MSVC builds of Rust additionally require an installation of:
237
238- Visual Studio 2022 (or later) build tools so `rustc` can use its linker. Older
239 Visual Studio versions such as 2019 *may* work but aren't actively tested.
240- A recent Windows 10 or 11 SDK.
241
242The simplest way is to get [Visual Studio], check the "C++ build tools".
243
244[Visual Studio]: https://visualstudio.microsoft.com/downloads/
245
246(If you're installing CMake yourself, be careful that "C++ CMake tools for
247Windows" doesn't get included under "Individual components".)
248
249With these dependencies installed, you can build the compiler in a `cmd.exe`
250shell with:
251
252```sh
253python x.py setup user
254python x.py build
255```
256
257Right now, building Rust only works with some known versions of Visual Studio.
258If you have a more recent version installed and the build system doesn't
259understand, you may need to force bootstrap to use an older version.
260This can be done by manually calling the appropriate vcvars file before running
261the bootstrap.
262
263```batch
264CALL "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat"
265python x.py build
266```
267
268### Specifying an ABI
269
270Each specific ABI can also be used from either environment (for example, using
271the GNU ABI in PowerShell) by using an explicit build triple. The available
272Windows build triples are:
273- GNU ABI (using GCC)
274 - `i686-pc-windows-gnu`
275 - `x86_64-pc-windows-gnu`
276- The MSVC ABI
277 - `i686-pc-windows-msvc`
278 - `x86_64-pc-windows-msvc`
279
280The build triple can be specified by either specifying `--build=<triple>` when
281invoking `x.py` commands, or by creating a `bootstrap.toml` file (as described in
282[Building on a Unix-like system](#building-on-a-unix-like-system)), and passing
283`--set build.build=<triple>` to `./configure`.
284
285## Building Documentation
286
287If you'd like to build the documentation, it's almost the same:
288
289```sh
290./x.py doc
291```
292
293The generated documentation will appear under `doc` in the `build` directory for
294the ABI used. That is, if the ABI was `x86_64-pc-windows-msvc`, the directory
295will be `build\x86_64-pc-windows-msvc\doc`.
296
297## Notes
298
299Since the Rust compiler is written in Rust, it must be built by a precompiled
300"snapshot" version of itself (made in an earlier stage of development).
301As such, source builds require an Internet connection to fetch snapshots, and an
302OS that can execute the available snapshot binaries.
303
304See https://doc.rust-lang.org/nightly/rustc/platform-support.html for a list of
305supported platforms.
306Only "host tools" platforms have a pre-compiled snapshot binary available; to
307compile for a platform without host tools you must cross-compile.
308
309You may find that other platforms work, but these are our officially supported
310build environments that are most likely to work.