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