]>
Commit | Line | Data |
---|---|---|
5869c6ff | 1 | # The Rust Programming Language |
223e47cc | 2 | |
3157f602 | 3 | This is the main source code repository for [Rust]. It contains the compiler, |
3dfed10e | 4 | standard library, and documentation. |
62682a34 | 5 | |
92a42be0 | 6 | [Rust]: https://www.rust-lang.org |
223e47cc | 7 | |
1b1a35ee XL |
8 | **Note: this README is for _users_ rather than _contributors_. |
9 | If you wish to _contribute_ to the compiler, you should read the | |
29967ef6 | 10 | [Getting Started][gettingstarted] section of the rustc-dev-guide instead.** |
f035d41b | 11 | |
1a4d82fc | 12 | ## Quick Start |
223e47cc | 13 | |
041b39d2 | 14 | Read ["Installation"] from [The Book]. |
223e47cc | 15 | |
0731742a | 16 | ["Installation"]: https://doc.rust-lang.org/book/ch01-01-installation.html |
e9174d1e | 17 | [The Book]: https://doc.rust-lang.org/book/index.html |
223e47cc | 18 | |
9fa01778 | 19 | ## Installing from Source |
223e47cc | 20 | |
f035d41b | 21 | The Rust build system uses a Python script called `x.py` to build the compiler, |
3dfed10e | 22 | which manages the bootstrapping process. More information about it can be found |
f035d41b | 23 | by running `./x.py --help` or reading the [rustc dev guide][rustcguidebuild]. |
416331ca | 24 | |
f035d41b | 25 | [gettingstarted]: https://rustc-dev-guide.rust-lang.org/getting-started.html |
ba9703b0 | 26 | [rustcguidebuild]: https://rustc-dev-guide.rust-lang.org/building/how-to-build-and-run.html |
9fa01778 | 27 | |
f035d41b | 28 | ### Building on a Unix-like system |
1a4d82fc | 29 | 1. Make sure you have installed the dependencies: |
c34b1796 | 30 | |
e1599b0c | 31 | * `g++` 5.1 or later or `clang++` 3.5 or later |
ba9703b0 | 32 | * `python` 3 or 2.7 |
c34b1796 | 33 | * GNU `make` 3.81 or later |
9e0c209e | 34 | * `cmake` 3.4.3 or later |
1b1a35ee | 35 | * `ninja` |
c34b1796 AL |
36 | * `curl` |
37 | * `git` | |
e1599b0c | 38 | * `ssl` which comes in `libssl-dev` or `openssl-devel` |
e74abb32 | 39 | * `pkg-config` if you are compiling on Linux and targeting Linux |
1a4d82fc | 40 | |
85aaf69f | 41 | 2. Clone the [source] with `git`: |
1a4d82fc | 42 | |
c34b1796 | 43 | ```sh |
1b1a35ee XL |
44 | git clone https://github.com/rust-lang/rust.git |
45 | cd rust | |
c34b1796 | 46 | ``` |
1a4d82fc | 47 | |
85aaf69f SL |
48 | [source]: https://github.com/rust-lang/rust |
49 | ||
416331ca | 50 | 3. Configure the build settings: |
223e47cc | 51 | |
416331ca XL |
52 | The Rust build system uses a file named `config.toml` in the root of the |
53 | source tree to determine various configuration settings for the build. | |
54 | Copy the default `config.toml.example` to `config.toml` to get started. | |
532ac7d7 | 55 | |
416331ca | 56 | ```sh |
1b1a35ee | 57 | cp config.toml.example config.toml |
532ac7d7 XL |
58 | ``` |
59 | ||
f035d41b XL |
60 | If you plan to use `x.py install` to create an installation, it is recommended |
61 | that you set the `prefix` value in the `[install]` section to a directory. | |
532ac7d7 | 62 | |
e1599b0c XL |
63 | Create install directory if you are not installing in default directory |
64 | ||
416331ca | 65 | 4. Build and install: |
532ac7d7 | 66 | |
416331ca | 67 | ```sh |
1b1a35ee | 68 | ./x.py build && ./x.py install |
532ac7d7 | 69 | ``` |
223e47cc | 70 | |
416331ca XL |
71 | When complete, `./x.py install` will place several programs into |
72 | `$PREFIX/bin`: `rustc`, the Rust compiler, and `rustdoc`, the | |
85aaf69f | 73 | API-documentation tool. This install does not include [Cargo], |
416331ca XL |
74 | Rust's package manager. To build and install Cargo, you may |
75 | run `./x.py install cargo` or set the `build.extended` key in | |
76 | `config.toml` to `true` to build and install all tools. | |
85aaf69f SL |
77 | |
78 | [Cargo]: https://github.com/rust-lang/cargo | |
223e47cc | 79 | |
1a4d82fc | 80 | ### Building on Windows |
223e47cc | 81 | |
9cc50fc6 SL |
82 | There are two prominent ABIs in use on Windows: the native (MSVC) ABI used by |
83 | Visual Studio, and the GNU ABI used by the GCC toolchain. Which version of Rust | |
84 | you need depends largely on what C/C++ libraries you want to interoperate with: | |
85 | for interop with software produced by Visual Studio use the MSVC build of Rust; | |
86 | for interop with GNU software built using the MinGW/MSYS2 toolchain use the GNU | |
87 | build. | |
88 | ||
9cc50fc6 SL |
89 | #### MinGW |
90 | ||
3157f602 | 91 | [MSYS2][msys2] can be used to easily build Rust on Windows: |
223e47cc | 92 | |
5bcae85e | 93 | [msys2]: https://msys2.github.io/ |
223e47cc | 94 | |
3157f602 XL |
95 | 1. Grab the latest [MSYS2 installer][msys2] and go through the installer. |
96 | ||
97 | 2. Run `mingw32_shell.bat` or `mingw64_shell.bat` from wherever you installed | |
98 | MSYS2 (i.e. `C:\msys64`), depending on whether you want 32-bit or 64-bit | |
99 | Rust. (As of the latest version of MSYS2 you have to run `msys2_shell.cmd | |
100 | -mingw32` or `msys2_shell.cmd -mingw64` from the command line instead) | |
101 | ||
102 | 3. From this terminal, install the required tools: | |
c34b1796 AL |
103 | |
104 | ```sh | |
e9174d1e | 105 | # Update package mirrors (may be needed if you have a fresh install of MSYS2) |
1b1a35ee | 106 | pacman -Sy pacman-mirrors |
b039eaaf | 107 | |
3157f602 XL |
108 | # Install build tools needed for Rust. If you're building a 32-bit compiler, |
109 | # then replace "x86_64" below with "i686". If you've already got git, python, | |
110 | # or CMake installed and in PATH you can remove them from this list. Note | |
1b1a35ee | 111 | # that it is important that you do **not** use the 'python2', 'cmake' and 'ninja' |
32a655c1 SL |
112 | # packages from the 'msys2' subsystem. The build has historically been known |
113 | # to fail with these packages. | |
1b1a35ee | 114 | pacman -S git \ |
3157f602 XL |
115 | make \ |
116 | diffutils \ | |
c30ab7b3 | 117 | tar \ |
ba9703b0 | 118 | mingw-w64-x86_64-python \ |
3157f602 | 119 | mingw-w64-x86_64-cmake \ |
1b1a35ee XL |
120 | mingw-w64-x86_64-gcc \ |
121 | mingw-w64-x86_64-ninja | |
c34b1796 | 122 | ``` |
223e47cc | 123 | |
8bb4bdeb | 124 | 4. Navigate to Rust's source code (or clone it), then build it: |
1a4d82fc | 125 | |
c34b1796 | 126 | ```sh |
1b1a35ee | 127 | ./x.py build && ./x.py install |
c34b1796 | 128 | ``` |
b039eaaf | 129 | |
9cc50fc6 SL |
130 | #### MSVC |
131 | ||
48663c56 XL |
132 | MSVC builds of Rust additionally require an installation of Visual Studio 2017 |
133 | (or later) so `rustc` can use its linker. The simplest way is to get the | |
dc9dc135 | 134 | [Visual Studio], check the “C++ build tools” and “Windows 10 SDK” workload. |
48663c56 | 135 | |
dc9dc135 | 136 | [Visual Studio]: https://visualstudio.microsoft.com/downloads/ |
48663c56 | 137 | |
dc9dc135 XL |
138 | (If you're installing cmake yourself, be careful that “C++ CMake tools for |
139 | Windows” doesn't get included under “Individual components”.) | |
9cc50fc6 | 140 | |
476ff2be SL |
141 | With these dependencies installed, you can build the compiler in a `cmd.exe` |
142 | shell with: | |
9cc50fc6 SL |
143 | |
144 | ```sh | |
1b1a35ee | 145 | python x.py build |
9cc50fc6 | 146 | ``` |
1a4d82fc | 147 | |
94b46f34 | 148 | Currently, building Rust only works with some known versions of Visual Studio. If |
f035d41b XL |
149 | you have a more recent version installed and the build system doesn't understand, |
150 | you may need to force rustbuild to use an older version. This can be done | |
5bcae85e SL |
151 | by manually calling the appropriate vcvars file before running the bootstrap. |
152 | ||
b7449926 | 153 | ```batch |
1b1a35ee XL |
154 | CALL "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat" |
155 | python x.py build | |
3157f602 XL |
156 | ``` |
157 | ||
8bb4bdeb XL |
158 | #### Specifying an ABI |
159 | ||
160 | Each specific ABI can also be used from either environment (for example, using | |
94b46f34 | 161 | the GNU ABI in PowerShell) by using an explicit build triple. The available |
8bb4bdeb XL |
162 | Windows build triples are: |
163 | - GNU ABI (using GCC) | |
164 | - `i686-pc-windows-gnu` | |
165 | - `x86_64-pc-windows-gnu` | |
166 | - The MSVC ABI | |
167 | - `i686-pc-windows-msvc` | |
168 | - `x86_64-pc-windows-msvc` | |
169 | ||
3b2f2976 | 170 | The build triple can be specified by either specifying `--build=<triple>` when |
8bb4bdeb | 171 | invoking `x.py` commands, or by copying the `config.toml` file (as described |
416331ca XL |
172 | in [Installing From Source](#installing-from-source)), and modifying the |
173 | `build` option under the `[build]` section. | |
8bb4bdeb XL |
174 | |
175 | ### Configure and Make | |
176 | ||
177 | While it's not the recommended build system, this project also provides a | |
178 | configure script and makefile (the latter of which just invokes `x.py`). | |
179 | ||
180 | ```sh | |
1b1a35ee XL |
181 | ./configure |
182 | make && sudo make install | |
8bb4bdeb XL |
183 | ``` |
184 | ||
185 | When using the configure script, the generated `config.mk` file may override the | |
186 | `config.toml` file. To go back to the `config.toml` file, delete the generated | |
187 | `config.mk` file. | |
188 | ||
e9174d1e SL |
189 | ## Building Documentation |
190 | ||
191 | If you’d like to build the documentation, it’s almost the same: | |
192 | ||
193 | ```sh | |
1b1a35ee | 194 | ./x.py doc |
e9174d1e SL |
195 | ``` |
196 | ||
cc61c64b XL |
197 | The generated documentation will appear under `doc` in the `build` directory for |
198 | the ABI used. I.e., if the ABI was `x86_64-pc-windows-msvc`, the directory will be | |
199 | `build\x86_64-pc-windows-msvc\doc`. | |
e9174d1e | 200 | |
1a4d82fc JJ |
201 | ## Notes |
202 | ||
203 | Since the Rust compiler is written in Rust, it must be built by a | |
94b46f34 | 204 | precompiled "snapshot" version of itself (made in an earlier stage of |
1a4d82fc JJ |
205 | development). As such, source builds require a connection to the Internet, to |
206 | fetch snapshots, and an OS that can execute the available snapshot binaries. | |
207 | ||
208 | Snapshot binaries are currently built and tested on several platforms: | |
223e47cc | 209 | |
1b1a35ee XL |
210 | | Platform / Architecture | x86 | x86_64 | |
211 | |---------------------------------------------|-----|--------| | |
212 | | Windows (7, 8, 10, ...) | ✓ | ✓ | | |
213 | | Linux (kernel 2.6.32, glibc 2.11 or later) | ✓ | ✓ | | |
214 | | macOS (10.7 Lion or later) | (\*) | ✓ | | |
215 | ||
216 | (\*): Apple dropped support for running 32-bit binaries starting from macOS 10.15 and iOS 11. | |
217 | Due to this decision from Apple, the targets are no longer useful to our users. | |
218 | Please read [our blog post][macx32] for more info. | |
219 | ||
220 | [macx32]: https://blog.rust-lang.org/2020/01/03/reducing-support-for-32-bit-apple-targets.html | |
1a4d82fc JJ |
221 | |
222 | You may find that other platforms work, but these are our officially | |
223 | supported build environments that are most likely to work. | |
224 | ||
c34b1796 | 225 | ## Getting Help |
1a4d82fc JJ |
226 | |
227 | The Rust community congregates in a few places: | |
228 | ||
c34b1796 AL |
229 | * [Stack Overflow] - Direct questions about using the language. |
230 | * [users.rust-lang.org] - General discussion and broader questions. | |
85aaf69f | 231 | * [/r/rust] - News and general discussion. |
1a4d82fc | 232 | |
cc61c64b XL |
233 | [Stack Overflow]: https://stackoverflow.com/questions/tagged/rust |
234 | [/r/rust]: https://reddit.com/r/rust | |
e9174d1e | 235 | [users.rust-lang.org]: https://users.rust-lang.org/ |
85aaf69f SL |
236 | |
237 | ## Contributing | |
238 | ||
f035d41b XL |
239 | If you are interested in contributing to the Rust project, please take a look |
240 | at the [Getting Started][gettingstarted] guide in the [rustc-dev-guide]. | |
223e47cc | 241 | |
1b1a35ee XL |
242 | [rustc-dev-guide]: https://rustc-dev-guide.rust-lang.org |
243 | ||
223e47cc LB |
244 | ## License |
245 | ||
246 | Rust is primarily distributed under the terms of both the MIT license | |
247 | and the Apache License (Version 2.0), with portions covered by various | |
248 | BSD-like licenses. | |
249 | ||
3157f602 XL |
250 | See [LICENSE-APACHE](LICENSE-APACHE), [LICENSE-MIT](LICENSE-MIT), and |
251 | [COPYRIGHT](COPYRIGHT) for details. | |
48663c56 XL |
252 | |
253 | ## Trademark | |
48663c56 XL |
254 | |
255 | The Rust programming language is an open source, community project governed | |
256 | by a core team. It is also sponsored by the Mozilla Foundation (“Mozilla”), | |
257 | which owns and protects the Rust and Cargo trademarks and logos | |
258 | (the “Rust Trademarks”). | |
259 | ||
260 | If you want to use these names or brands, please read the [media guide][media-guide]. | |
261 | ||
262 | Third-party logos may be subject to third-party copyrights and trademarks. See | |
263 | [Licenses][policies-licenses] for details. | |
264 | ||
265 | [media-guide]: https://www.rust-lang.org/policies/media-guide | |
266 | [policies-licenses]: https://www.rust-lang.org/policies/licenses |