]>
Commit | Line | Data |
---|---|---|
5869c6ff | 1 | # The Rust Programming Language |
223e47cc | 2 | |
9ffffee4 FG |
3 | [![Rust Community](https://img.shields.io/badge/Rust_Community%20-Join_us-brightgreen?style=plastic&logo=rust)](https://www.rust-lang.org/community) |
4 | ||
3157f602 | 5 | This is the main source code repository for [Rust]. It contains the compiler, |
3dfed10e | 6 | standard library, and documentation. |
62682a34 | 7 | |
9c376795 | 8 | [Rust]: https://www.rust-lang.org/ |
223e47cc | 9 | |
9c376795 FG |
10 | **Note: this README is for _users_ rather than _contributors_.** |
11 | If you wish to _contribute_ to the compiler, you should read | |
12 | [CONTRIBUTING.md](CONTRIBUTING.md) instead. | |
f035d41b | 13 | |
1a4d82fc | 14 | ## Quick Start |
223e47cc | 15 | |
041b39d2 | 16 | Read ["Installation"] from [The Book]. |
223e47cc | 17 | |
0731742a | 18 | ["Installation"]: https://doc.rust-lang.org/book/ch01-01-installation.html |
e9174d1e | 19 | [The Book]: https://doc.rust-lang.org/book/index.html |
223e47cc | 20 | |
9fa01778 | 21 | ## Installing from Source |
223e47cc | 22 | |
f035d41b | 23 | The Rust build system uses a Python script called `x.py` to build the compiler, |
f2b60f7d | 24 | which manages the bootstrapping process. It lives at the root of the project. |
17df50a5 | 25 | |
9c376795 FG |
26 | The `x.py` command can be run directly on most Unix systems in the following |
27 | format: | |
17df50a5 XL |
28 | |
29 | ```sh | |
30 | ./x.py <subcommand> [flags] | |
31 | ``` | |
32 | ||
33 | This is how the documentation and examples assume you are running `x.py`. | |
9c376795 | 34 | Some alternative ways are: |
17df50a5 XL |
35 | |
36 | ```sh | |
9c376795 FG |
37 | # On a Unix shell if you don't have the necessary `python3` command |
38 | ./x <subcommand> [flags] | |
17df50a5 | 39 | |
9c376795 FG |
40 | # On the Windows Command Prompt (if .py files are configured to run Python) |
41 | x.py <subcommand> [flags] | |
42 | ||
43 | # You can also run Python yourself, e.g.: | |
44 | python x.py <subcommand> [flags] | |
17df50a5 XL |
45 | ``` |
46 | ||
9c376795 FG |
47 | More information about `x.py` can be found by running it with the `--help` flag |
48 | or reading the [rustc dev guide][rustcguidebuild]. | |
416331ca | 49 | |
f035d41b | 50 | [gettingstarted]: https://rustc-dev-guide.rust-lang.org/getting-started.html |
ba9703b0 | 51 | [rustcguidebuild]: https://rustc-dev-guide.rust-lang.org/building/how-to-build-and-run.html |
9fa01778 | 52 | |
9c376795 FG |
53 | ### Dependencies |
54 | ||
55 | Make sure you have installed the dependencies: | |
56 | ||
57 | * `python` 3 or 2.7 | |
58 | * `git` | |
59 | * A C compiler (when building for the host, `cc` is enough; cross-compiling may | |
60 | need additional compilers) | |
61 | * `curl` (not needed on Windows) | |
62 | * `pkg-config` if you are compiling on Linux and targeting Linux | |
63 | * `libiconv` (already included with glibc on Debian-based distros) | |
64 | ||
65 | To build Cargo, you'll also need OpenSSL (`libssl-dev` or `openssl-devel` on | |
66 | most Unix distros). | |
67 | ||
68 | If building LLVM from source, you'll need additional tools: | |
c34b1796 | 69 | |
9c376795 FG |
70 | * `g++`, `clang++`, or MSVC with versions listed on |
71 | [LLVM's documentation](https://llvm.org/docs/GettingStarted.html#host-c-toolchain-both-compiler-and-standard-library) | |
72 | * `ninja`, or GNU `make` 3.81 or later (Ninja is recommended, especially on | |
73 | Windows) | |
74 | * `cmake` 3.13.4 or later | |
75 | * `libstdc++-static` may be required on some Linux distributions such as Fedora | |
76 | and Ubuntu | |
1a4d82fc | 77 | |
9c376795 FG |
78 | On tier 1 or tier 2 with host tools platforms, you can also choose to download |
79 | LLVM by setting `llvm.download-ci-llvm = true`. | |
80 | Otherwise, you'll need LLVM installed and `llvm-config` in your path. | |
81 | See [the rustc-dev-guide for more info][sysllvm]. | |
82 | ||
83 | [sysllvm]: https://rustc-dev-guide.rust-lang.org/building/new-target.html#using-pre-built-llvm | |
84 | ||
85 | ||
86 | ### Building on a Unix-like system | |
87 | ||
88 | 1. Clone the [source] with `git`: | |
1a4d82fc | 89 | |
c34b1796 | 90 | ```sh |
1b1a35ee XL |
91 | git clone https://github.com/rust-lang/rust.git |
92 | cd rust | |
c34b1796 | 93 | ``` |
1a4d82fc | 94 | |
85aaf69f SL |
95 | [source]: https://github.com/rust-lang/rust |
96 | ||
9c376795 | 97 | 2. Configure the build settings: |
532ac7d7 | 98 | |
9c376795 FG |
99 | The Rust build system uses a file named `config.toml` in the root of the |
100 | source tree to determine various configuration settings for the build. | |
101 | Set up the defaults intended for distros to get started. You can see a full | |
353b0b11 | 102 | list of options in `config.example.toml`. |
532ac7d7 | 103 | |
9c376795 FG |
104 | ```sh |
105 | printf 'profile = "user" \nchangelog-seen = 2 \n' > config.toml | |
106 | ``` | |
532ac7d7 | 107 | |
9c376795 FG |
108 | If you plan to use `x.py install` to create an installation, it is |
109 | recommended that you set the `prefix` value in the `[install]` section to a | |
110 | directory. | |
e1599b0c | 111 | |
9c376795 | 112 | 3. Build and install: |
532ac7d7 | 113 | |
9c376795 FG |
114 | ```sh |
115 | ./x.py build && ./x.py install | |
116 | ``` | |
223e47cc | 117 | |
9c376795 FG |
118 | When complete, `./x.py install` will place several programs into |
119 | `$PREFIX/bin`: `rustc`, the Rust compiler, and `rustdoc`, the | |
120 | API-documentation tool. If you've set `profile = "user"` or | |
121 | `build.extended = true`, it will also include [Cargo], Rust's package | |
122 | manager. | |
85aaf69f SL |
123 | |
124 | [Cargo]: https://github.com/rust-lang/cargo | |
223e47cc | 125 | |
1a4d82fc | 126 | ### Building on Windows |
223e47cc | 127 | |
9c376795 FG |
128 | On Windows, we suggest using [winget] to install dependencies by running the |
129 | following in a terminal: | |
130 | ||
131 | ```powershell | |
132 | winget install -e Python.Python.3 | |
133 | winget install -e Kitware.CMake | |
134 | winget install -e Git.Git | |
135 | ``` | |
136 | ||
137 | Then edit your system's `PATH` variable and add: `C:\Program Files\CMake\bin`. | |
138 | See | |
139 | [this guide on editing the system `PATH`](https://www.java.com/en/download/help/path.html) | |
140 | from the Java documentation. | |
141 | ||
142 | [winget]: https://github.com/microsoft/winget-cli | |
143 | ||
9cc50fc6 | 144 | There are two prominent ABIs in use on Windows: the native (MSVC) ABI used by |
f2b60f7d FG |
145 | Visual Studio and the GNU ABI used by the GCC toolchain. Which version of Rust |
146 | you need depends largely on what C/C++ libraries you want to interoperate with. | |
9c376795 FG |
147 | Use the MSVC build of Rust to interop with software produced by Visual Studio |
148 | and the GNU build to interop with GNU software built using the MinGW/MSYS2 | |
149 | toolchain. | |
9cc50fc6 | 150 | |
9cc50fc6 SL |
151 | #### MinGW |
152 | ||
3157f602 | 153 | [MSYS2][msys2] can be used to easily build Rust on Windows: |
223e47cc | 154 | |
6a06907d | 155 | [msys2]: https://www.msys2.org/ |
223e47cc | 156 | |
f2b60f7d | 157 | 1. Download the latest [MSYS2 installer][msys2] and go through the installer. |
3157f602 | 158 | |
f2b60f7d FG |
159 | 2. Run `mingw32_shell.bat` or `mingw64_shell.bat` from the MSYS2 installation |
160 | directory (e.g. `C:\msys64`), depending on whether you want 32-bit or 64-bit | |
3157f602 | 161 | Rust. (As of the latest version of MSYS2 you have to run `msys2_shell.cmd |
9c376795 | 162 | -mingw32` or `msys2_shell.cmd -mingw64` from the command line instead.) |
3157f602 XL |
163 | |
164 | 3. From this terminal, install the required tools: | |
c34b1796 AL |
165 | |
166 | ```sh | |
e9174d1e | 167 | # Update package mirrors (may be needed if you have a fresh install of MSYS2) |
1b1a35ee | 168 | pacman -Sy pacman-mirrors |
b039eaaf | 169 | |
3157f602 | 170 | # Install build tools needed for Rust. If you're building a 32-bit compiler, |
9c376795 FG |
171 | # then replace "x86_64" below with "i686". If you've already got Git, Python, |
172 | # or CMake installed and in PATH you can remove them from this list. | |
173 | # Note that it is important that you do **not** use the 'python2', 'cmake', | |
174 | # and 'ninja' packages from the 'msys2' subsystem. | |
175 | # The build has historically been known to fail with these packages. | |
1b1a35ee | 176 | pacman -S git \ |
3157f602 XL |
177 | make \ |
178 | diffutils \ | |
c30ab7b3 | 179 | tar \ |
ba9703b0 | 180 | mingw-w64-x86_64-python \ |
3157f602 | 181 | mingw-w64-x86_64-cmake \ |
1b1a35ee XL |
182 | mingw-w64-x86_64-gcc \ |
183 | mingw-w64-x86_64-ninja | |
c34b1796 | 184 | ``` |
223e47cc | 185 | |
8bb4bdeb | 186 | 4. Navigate to Rust's source code (or clone it), then build it: |
1a4d82fc | 187 | |
c34b1796 | 188 | ```sh |
1b1a35ee | 189 | ./x.py build && ./x.py install |
c34b1796 | 190 | ``` |
b039eaaf | 191 | |
9cc50fc6 SL |
192 | #### MSVC |
193 | ||
48663c56 | 194 | MSVC builds of Rust additionally require an installation of Visual Studio 2017 |
f2b60f7d | 195 | (or later) so `rustc` can use its linker. The simplest way is to get |
9c376795 | 196 | [Visual Studio], check the "C++ build tools" and "Windows 10 SDK" workload. |
48663c56 | 197 | |
dc9dc135 | 198 | [Visual Studio]: https://visualstudio.microsoft.com/downloads/ |
48663c56 | 199 | |
9c376795 FG |
200 | (If you're installing CMake yourself, be careful that "C++ CMake tools for |
201 | Windows" doesn't get included under "Individual components".) | |
9cc50fc6 | 202 | |
476ff2be SL |
203 | With these dependencies installed, you can build the compiler in a `cmd.exe` |
204 | shell with: | |
9cc50fc6 SL |
205 | |
206 | ```sh | |
1b1a35ee | 207 | python x.py build |
9cc50fc6 | 208 | ``` |
1a4d82fc | 209 | |
9c376795 FG |
210 | Right now, building Rust only works with some known versions of Visual Studio. |
211 | If you have a more recent version installed and the build system doesn't | |
212 | understand, you may need to force rustbuild to use an older version. | |
213 | This can be done by manually calling the appropriate vcvars file before running | |
214 | the bootstrap. | |
5bcae85e | 215 | |
b7449926 | 216 | ```batch |
1b1a35ee XL |
217 | CALL "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat" |
218 | python x.py build | |
3157f602 XL |
219 | ``` |
220 | ||
8bb4bdeb XL |
221 | #### Specifying an ABI |
222 | ||
223 | Each specific ABI can also be used from either environment (for example, using | |
94b46f34 | 224 | the GNU ABI in PowerShell) by using an explicit build triple. The available |
8bb4bdeb XL |
225 | Windows build triples are: |
226 | - GNU ABI (using GCC) | |
227 | - `i686-pc-windows-gnu` | |
228 | - `x86_64-pc-windows-gnu` | |
229 | - The MSVC ABI | |
230 | - `i686-pc-windows-msvc` | |
231 | - `x86_64-pc-windows-msvc` | |
232 | ||
3b2f2976 | 233 | The build triple can be specified by either specifying `--build=<triple>` when |
9c376795 FG |
234 | invoking `x.py` commands, or by creating a `config.toml` file (as described in |
235 | [Installing from Source](#installing-from-source)), and modifying the `build` | |
236 | option under the `[build]` section. | |
8bb4bdeb XL |
237 | |
238 | ### Configure and Make | |
239 | ||
240 | While it's not the recommended build system, this project also provides a | |
241 | configure script and makefile (the latter of which just invokes `x.py`). | |
242 | ||
243 | ```sh | |
1b1a35ee XL |
244 | ./configure |
245 | make && sudo make install | |
8bb4bdeb XL |
246 | ``` |
247 | ||
9c376795 FG |
248 | `configure` generates a `config.toml` which can also be used with normal `x.py` |
249 | invocations. | |
8bb4bdeb | 250 | |
e9174d1e SL |
251 | ## Building Documentation |
252 | ||
9c376795 | 253 | If you'd like to build the documentation, it's almost the same: |
e9174d1e SL |
254 | |
255 | ```sh | |
1b1a35ee | 256 | ./x.py doc |
e9174d1e SL |
257 | ``` |
258 | ||
cc61c64b | 259 | The generated documentation will appear under `doc` in the `build` directory for |
9c376795 FG |
260 | the ABI used. That is, if the ABI was `x86_64-pc-windows-msvc`, the directory |
261 | will be `build\x86_64-pc-windows-msvc\doc`. | |
e9174d1e | 262 | |
1a4d82fc JJ |
263 | ## Notes |
264 | ||
9c376795 FG |
265 | Since the Rust compiler is written in Rust, it must be built by a precompiled |
266 | "snapshot" version of itself (made in an earlier stage of development). | |
267 | As such, source builds require an Internet connection to fetch snapshots, and an | |
268 | OS that can execute the available snapshot binaries. | |
1b1a35ee | 269 | |
9c376795 FG |
270 | See https://doc.rust-lang.org/nightly/rustc/platform-support.html for a list of |
271 | supported platforms. | |
272 | Only "host tools" platforms have a pre-compiled snapshot binary available; to | |
273 | compile for a platform without host tools you must cross-compile. | |
1a4d82fc | 274 | |
9c376795 FG |
275 | You may find that other platforms work, but these are our officially supported |
276 | build environments that are most likely to work. | |
1a4d82fc | 277 | |
c34b1796 | 278 | ## Getting Help |
1a4d82fc | 279 | |
9c376795 | 280 | See https://www.rust-lang.org/community for a list of chat platforms and forums. |
85aaf69f SL |
281 | |
282 | ## Contributing | |
283 | ||
9c376795 | 284 | See [CONTRIBUTING.md](CONTRIBUTING.md). |
1b1a35ee | 285 | |
223e47cc LB |
286 | ## License |
287 | ||
9c376795 FG |
288 | Rust is primarily distributed under the terms of both the MIT license and the |
289 | Apache License (Version 2.0), with portions covered by various BSD-like | |
290 | licenses. | |
223e47cc | 291 | |
3157f602 XL |
292 | See [LICENSE-APACHE](LICENSE-APACHE), [LICENSE-MIT](LICENSE-MIT), and |
293 | [COPYRIGHT](COPYRIGHT) for details. | |
48663c56 XL |
294 | |
295 | ## Trademark | |
48663c56 | 296 | |
136023e0 | 297 | [The Rust Foundation][rust-foundation] owns and protects the Rust and Cargo |
9c376795 | 298 | trademarks and logos (the "Rust Trademarks"). |
48663c56 | 299 | |
9c376795 FG |
300 | If you want to use these names or brands, please read the |
301 | [media guide][media-guide]. | |
48663c56 XL |
302 | |
303 | Third-party logos may be subject to third-party copyrights and trademarks. See | |
304 | [Licenses][policies-licenses] for details. | |
305 | ||
136023e0 | 306 | [rust-foundation]: https://foundation.rust-lang.org/ |
9c376795 | 307 | [media-guide]: https://foundation.rust-lang.org/policies/logo-policy-and-media-guide/ |
48663c56 | 308 | [policies-licenses]: https://www.rust-lang.org/policies/licenses |