1 # The Rust Programming Language
3 This is the main source code repository for [Rust]. It contains the compiler,
4 standard library, and documentation.
6 [Rust]: https://www.rust-lang.org
9 [quick-start]: #quick-start
11 Read ["Installation"] from [The Book].
13 ["Installation"]: https://doc.rust-lang.org/book/second-edition/ch01-01-installation.html
14 [The Book]: https://doc.rust-lang.org/book/index.html
16 ## Building from Source
17 [building-from-source]: #building-from-source
19 1. Make sure you have installed the dependencies:
21 * `g++` 4.7 or later or `clang++` 3.x or later
22 * `python` 2.7 (but not 3.x)
23 * GNU `make` 3.81 or later
24 * `cmake` 3.4.3 or later
28 2. Clone the [source] with `git`:
31 $ git clone https://github.com/rust-lang/rust.git
35 [source]: https://github.com/rust-lang/rust
40 $ ./x.py build && sudo ./x.py install
43 > ***Note:*** Install locations can be adjusted by copying the config file
44 > from `./config.toml.example` to `./config.toml`, and
45 > adjusting the `prefix` option under `[install]`. Various other options, such
46 > as enabling debug information, are also supported, and are documented in
49 When complete, `sudo ./x.py install` will place several programs into
50 `/usr/local/bin`: `rustc`, the Rust compiler, and `rustdoc`, the
51 API-documentation tool. This install does not include [Cargo],
52 Rust's package manager, which you may also want to build.
54 [Cargo]: https://github.com/rust-lang/cargo
56 ### Building on Windows
57 [building-on-windows]: #building-on-windows
59 There are two prominent ABIs in use on Windows: the native (MSVC) ABI used by
60 Visual Studio, and the GNU ABI used by the GCC toolchain. Which version of Rust
61 you need depends largely on what C/C++ libraries you want to interoperate with:
62 for interop with software produced by Visual Studio use the MSVC build of Rust;
63 for interop with GNU software built using the MinGW/MSYS2 toolchain use the GNU
67 [windows-mingw]: #windows-mingw
69 [MSYS2][msys2] can be used to easily build Rust on Windows:
71 [msys2]: https://msys2.github.io/
73 1. Grab the latest [MSYS2 installer][msys2] and go through the installer.
75 2. Run `mingw32_shell.bat` or `mingw64_shell.bat` from wherever you installed
76 MSYS2 (i.e. `C:\msys64`), depending on whether you want 32-bit or 64-bit
77 Rust. (As of the latest version of MSYS2 you have to run `msys2_shell.cmd
78 -mingw32` or `msys2_shell.cmd -mingw64` from the command line instead)
80 3. From this terminal, install the required tools:
83 # Update package mirrors (may be needed if you have a fresh install of MSYS2)
84 $ pacman -Sy pacman-mirrors
86 # Install build tools needed for Rust. If you're building a 32-bit compiler,
87 # then replace "x86_64" below with "i686". If you've already got git, python,
88 # or CMake installed and in PATH you can remove them from this list. Note
89 # that it is important that you do **not** use the 'python2' and 'cmake'
90 # packages from the 'msys2' subsystem. The build has historically been known
91 # to fail with these packages.
96 mingw-w64-x86_64-python2 \
97 mingw-w64-x86_64-cmake \
101 4. Navigate to Rust's source code (or clone it), then build it:
104 $ ./x.py build && ./x.py install
108 [windows-msvc]: #windows-msvc
110 MSVC builds of Rust additionally require an installation of Visual Studio 2013
111 (or later) so `rustc` can use its linker. Make sure to check the “C++ tools”
114 With these dependencies installed, you can build the compiler in a `cmd.exe`
121 Currently building Rust only works with some known versions of Visual Studio. If
122 you have a more recent version installed the build system doesn't understand
123 then you may need to force rustbuild to use an older version. This can be done
124 by manually calling the appropriate vcvars file before running the bootstrap.
127 CALL "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\bin\amd64\vcvars64.bat"
131 #### Specifying an ABI
132 [specifying-an-abi]: #specifying-an-abi
134 Each specific ABI can also be used from either environment (for example, using
135 the GNU ABI in powershell) by using an explicit build triple. The available
136 Windows build triples are:
137 - GNU ABI (using GCC)
138 - `i686-pc-windows-gnu`
139 - `x86_64-pc-windows-gnu`
141 - `i686-pc-windows-msvc`
142 - `x86_64-pc-windows-msvc`
144 The build triple can be specified by either specifying `--build=<triple>` when
145 invoking `x.py` commands, or by copying the `config.toml` file (as described
146 in Building From Source), and modifying the `build` option under the `[build]`
149 ### Configure and Make
150 [configure-and-make]: #configure-and-make
152 While it's not the recommended build system, this project also provides a
153 configure script and makefile (the latter of which just invokes `x.py`).
157 $ make && sudo make install
160 When using the configure script, the generated `config.mk` file may override the
161 `config.toml` file. To go back to the `config.toml` file, delete the generated
164 ## Building Documentation
165 [building-documentation]: #building-documentation
167 If you’d like to build the documentation, it’s almost the same:
173 The generated documentation will appear under `doc` in the `build` directory for
174 the ABI used. I.e., if the ABI was `x86_64-pc-windows-msvc`, the directory will be
175 `build\x86_64-pc-windows-msvc\doc`.
180 Since the Rust compiler is written in Rust, it must be built by a
181 precompiled "snapshot" version of itself (made in an earlier state of
182 development). As such, source builds require a connection to the Internet, to
183 fetch snapshots, and an OS that can execute the available snapshot binaries.
185 Snapshot binaries are currently built and tested on several platforms:
187 | Platform / Architecture | x86 | x86_64 |
188 |--------------------------------|-----|--------|
189 | Windows (7, 8, Server 2008 R2) | ✓ | ✓ |
190 | Linux (2.6.18 or later) | ✓ | ✓ |
191 | OSX (10.7 Lion or later) | ✓ | ✓ |
193 You may find that other platforms work, but these are our officially
194 supported build environments that are most likely to work.
196 Rust currently needs between 600MiB and 1.5GiB of RAM to build, depending on platform.
197 If it hits swap, it will take a very long time to build.
199 There is more advice about hacking on Rust in [CONTRIBUTING.md].
201 [CONTRIBUTING.md]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md
204 [getting-help]: #getting-help
206 The Rust community congregates in a few places:
208 * [Stack Overflow] - Direct questions about using the language.
209 * [users.rust-lang.org] - General discussion and broader questions.
210 * [/r/rust] - News and general discussion.
212 [Stack Overflow]: https://stackoverflow.com/questions/tagged/rust
213 [/r/rust]: https://reddit.com/r/rust
214 [users.rust-lang.org]: https://users.rust-lang.org/
217 [contributing]: #contributing
219 To contribute to Rust, please see [CONTRIBUTING](CONTRIBUTING.md).
221 Rust has an [IRC] culture and most real-time collaboration happens in a
222 variety of channels on Mozilla's IRC network, irc.mozilla.org. The
223 most popular channel is [#rust], a venue for general discussion about
224 Rust. And a good place to ask for help would be [#rust-beginners].
226 [IRC]: https://en.wikipedia.org/wiki/Internet_Relay_Chat
227 [#rust]: irc://irc.mozilla.org/rust
228 [#rust-beginners]: irc://irc.mozilla.org/rust-beginners
233 Rust is primarily distributed under the terms of both the MIT license
234 and the Apache License (Version 2.0), with portions covered by various
237 See [LICENSE-APACHE](LICENSE-APACHE), [LICENSE-MIT](LICENSE-MIT), and
238 [COPYRIGHT](COPYRIGHT) for details.