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