README.md

   1 # The Rust Programming Language
   2
   3 This is the main source code repository for [Rust]. It contains the compiler,
   4 standard library, and documentation.
   5
   6 [Rust]: https://www.rust-lang.org
   7
   8 ## Quick Start
   9 [quick-start]: #quick-start
  10
  11 Read ["Installation"] from [The Book].
  12
  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
  15
  16 ## Building from Source
  17 [building-from-source]: #building-from-source
  18
  19 ### Building on *nix
  20 1. Make sure you have installed the dependencies:
  21
  22    * `g++` 4.7 or later or `clang++` 3.x or later
  23    * `python` 2.7 (but not 3.x)
  24    * GNU `make` 3.81 or later
  25    * `cmake` 3.4.3 or later
  26    * `curl`
  27    * `git`
  28
  29 2. Clone the [source] with `git`:
  30
  31    ```sh
  32    $ git clone https://github.com/rust-lang/rust.git
  33    $ cd rust
  34    ```
  35
  36 [source]: https://github.com/rust-lang/rust
  37
  38 3. Build and install:
  39
  40     ```sh
  41     $ git submodule update --init --recursive --progress
  42     $ ./x.py build && sudo ./x.py install
  43     ```
  44
  45     > ***Note:*** Install locations can be adjusted by copying the config file
  46     > from `./config.toml.example` to `./config.toml`, and
  47     > adjusting the `prefix` option under `[install]`. Various other options, such
  48     > as enabling debug information, are also supported, and are documented in
  49     > the config file.
  50
  51     When complete, `sudo ./x.py install` will place several programs into
  52     `/usr/local/bin`: `rustc`, the Rust compiler, and `rustdoc`, the
  53     API-documentation tool. This install does not include [Cargo],
  54     Rust's package manager, which you may also want to build.
  55
  56 [Cargo]: https://github.com/rust-lang/cargo
  57
  58 ### Building on Windows
  59 [building-on-windows]: #building-on-windows
  60
  61 There are two prominent ABIs in use on Windows: the native (MSVC) ABI used by
  62 Visual Studio, and the GNU ABI used by the GCC toolchain. Which version of Rust
  63 you need depends largely on what C/C++ libraries you want to interoperate with:
  64 for interop with software produced by Visual Studio use the MSVC build of Rust;
  65 for interop with GNU software built using the MinGW/MSYS2 toolchain use the GNU
  66 build.
  67
  68 #### MinGW
  69 [windows-mingw]: #windows-mingw
  70
  71 [MSYS2][msys2] can be used to easily build Rust on Windows:
  72
  73 [msys2]: https://msys2.github.io/
  74
  75 1. Grab the latest [MSYS2 installer][msys2] and go through the installer.
  76
  77 2. Run `mingw32_shell.bat` or `mingw64_shell.bat` from wherever you installed
  78    MSYS2 (i.e. `C:\msys64`), depending on whether you want 32-bit or 64-bit
  79    Rust. (As of the latest version of MSYS2 you have to run `msys2_shell.cmd
  80    -mingw32` or `msys2_shell.cmd -mingw64` from the command line instead)
  81
  82 3. From this terminal, install the required tools:
  83
  84    ```sh
  85    # Update package mirrors (may be needed if you have a fresh install of MSYS2)
  86    $ pacman -Sy pacman-mirrors
  87
  88    # Install build tools needed for Rust. If you're building a 32-bit compiler,
  89    # then replace "x86_64" below with "i686". If you've already got git, python,
  90    # or CMake installed and in PATH you can remove them from this list. Note
  91    # that it is important that you do **not** use the 'python2' and 'cmake'
  92    # packages from the 'msys2' subsystem. The build has historically been known
  93    # to fail with these packages.
  94    $ pacman -S git \
  95                make \
  96                diffutils \
  97                tar \
  98                mingw-w64-x86_64-python2 \
  99                mingw-w64-x86_64-cmake \
 100                mingw-w64-x86_64-gcc
 101    ```
 102
 103 4. Navigate to Rust's source code (or clone it), then build it:
 104
 105    ```sh
 106    $ ./x.py build && ./x.py install
 107    ```
 108
 109 #### MSVC
 110 [windows-msvc]: #windows-msvc
 111
 112 MSVC builds of Rust additionally require an installation of Visual Studio 2013
 113 (or later) so `rustc` can use its linker. Make sure to check the “C++ tools”
 114 option.
 115
 116 With these dependencies installed, you can build the compiler in a `cmd.exe`
 117 shell with:
 118
 119 ```sh
 120 > python x.py build
 121 ```
 122
 123 Currently, building Rust only works with some known versions of Visual Studio. If
 124 you have a more recent version installed the build system doesn't understand
 125 then you may need to force rustbuild to use an older version. This can be done
 126 by manually calling the appropriate vcvars file before running the bootstrap.
 127
 128 ```batch
 129 > CALL "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\bin\amd64\vcvars64.bat"
 130 > python x.py build
 131 ```
 132
 133 #### Specifying an ABI
 134 [specifying-an-abi]: #specifying-an-abi
 135
 136 Each specific ABI can also be used from either environment (for example, using
 137 the GNU ABI in PowerShell) by using an explicit build triple. The available
 138 Windows build triples are:
 139 - GNU ABI (using GCC)
 140     - `i686-pc-windows-gnu`
 141     - `x86_64-pc-windows-gnu`
 142 - The MSVC ABI
 143     - `i686-pc-windows-msvc`
 144     - `x86_64-pc-windows-msvc`
 145
 146 The build triple can be specified by either specifying `--build=<triple>` when
 147 invoking `x.py` commands, or by copying the `config.toml` file (as described
 148 in Building From Source), and modifying the `build` option under the `[build]`
 149 section.
 150
 151 ### Configure and Make
 152 [configure-and-make]: #configure-and-make
 153
 154 While it's not the recommended build system, this project also provides a
 155 configure script and makefile (the latter of which just invokes `x.py`).
 156
 157 ```sh
 158 $ ./configure
 159 $ make && sudo make install
 160 ```
 161
 162 When using the configure script, the generated `config.mk` file may override the
 163 `config.toml` file. To go back to the `config.toml` file, delete the generated
 164 `config.mk` file.
 165
 166 ## Building Documentation
 167 [building-documentation]: #building-documentation
 168
 169 If you’d like to build the documentation, it’s almost the same:
 170
 171 ```sh
 172 $ ./x.py doc
 173 ```
 174
 175 The generated documentation will appear under `doc` in the `build` directory for
 176 the ABI used. I.e., if the ABI was `x86_64-pc-windows-msvc`, the directory will be
 177 `build\x86_64-pc-windows-msvc\doc`.
 178
 179 ## Notes
 180 [notes]: #notes
 181
 182 Since the Rust compiler is written in Rust, it must be built by a
 183 precompiled "snapshot" version of itself (made in an earlier stage of
 184 development). As such, source builds require a connection to the Internet, to
 185 fetch snapshots, and an OS that can execute the available snapshot binaries.
 186
 187 Snapshot binaries are currently built and tested on several platforms:
 188
 189 | Platform / Architecture        | x86 | x86_64 |
 190 |--------------------------------|-----|--------|
 191 | Windows (7, 8, Server 2008 R2) | ✓   | ✓      |
 192 | Linux (2.6.18 or later)        | ✓   | ✓      |
 193 | OSX (10.7 Lion or later)       | ✓   | ✓      |
 194
 195 You may find that other platforms work, but these are our officially
 196 supported build environments that are most likely to work.
 197
 198 Rust currently needs between 600MiB and 1.5GiB of RAM to build, depending on platform.
 199 If it hits swap, it will take a very long time to build.
 200
 201 There is more advice about hacking on Rust in [CONTRIBUTING.md].
 202
 203 [CONTRIBUTING.md]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md
 204
 205 ## Getting Help
 206 [getting-help]: #getting-help
 207
 208 The Rust community congregates in a few places:
 209
 210 * [Stack Overflow] - Direct questions about using the language.
 211 * [users.rust-lang.org] - General discussion and broader questions.
 212 * [/r/rust] - News and general discussion.
 213
 214 [Stack Overflow]: https://stackoverflow.com/questions/tagged/rust
 215 [/r/rust]: https://reddit.com/r/rust
 216 [users.rust-lang.org]: https://users.rust-lang.org/
 217
 218 ## Contributing
 219 [contributing]: #contributing
 220
 221 To contribute to Rust, please see [CONTRIBUTING](CONTRIBUTING.md).
 222
 223 Rust has an [IRC] culture and most real-time collaboration happens in a
 224 variety of channels on Mozilla's IRC network, irc.mozilla.org. The
 225 most popular channel is [#rust], a venue for general discussion about
 226 Rust. And a good place to ask for help would be [#rust-beginners].
 227
 228 The [rustc guide] might be a good place to start if you want to find out how
 229 various parts of the compiler work.
 230
 231 Also, you may find the [rustdocs for the compiler itself][rustdocs] useful.
 232
 233 [IRC]: https://en.wikipedia.org/wiki/Internet_Relay_Chat
 234 [#rust]: irc://irc.mozilla.org/rust
 235 [#rust-beginners]: irc://irc.mozilla.org/rust-beginners
 236 [rustc guide]: https://rust-lang-nursery.github.io/rustc-guide/about-this-guide.html
 237 [rustdocs]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/
 238
 239 ## License
 240 [license]: #license
 241
 242 Rust is primarily distributed under the terms of both the MIT license
 243 and the Apache License (Version 2.0), with portions covered by various
 244 BSD-like licenses.
 245
 246 See [LICENSE-APACHE](LICENSE-APACHE), [LICENSE-MIT](LICENSE-MIT), and
 247 [COPYRIGHT](COPYRIGHT) for details.