From 8915ba7b1b6433032400ace217e765bd96686763 Mon Sep 17 00:00:00 2001 From: Alex Touchet Date: Wed, 28 Dec 2022 21:47:09 -0800 Subject: [PATCH] Improve Markdown styling in README --- README.md | 163 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 90 insertions(+), 73 deletions(-) diff --git a/README.md b/README.md index ac39435a8c7..0eb7c4b266a 100644 --- a/README.md +++ b/README.md @@ -3,10 +3,11 @@ This is the main source code repository for [Rust]. It contains the compiler, standard library, and documentation. -[Rust]: https://www.rust-lang.org +[Rust]: https://www.rust-lang.org/ **Note: this README is for _users_ rather than _contributors_.** -If you wish to _contribute_ to the compiler, you should read [CONTRIBUTING.md](CONTRIBUTING.md) instead. +If you wish to _contribute_ to the compiler, you should read +[CONTRIBUTING.md](CONTRIBUTING.md) instead. ## Quick Start @@ -20,13 +21,15 @@ Read ["Installation"] from [The Book]. The Rust build system uses a Python script called `x.py` to build the compiler, which manages the bootstrapping process. It lives at the root of the project. -The `x.py` command can be run directly on most Unix systems in the following format: +The `x.py` command can be run directly on most Unix systems in the following +format: ```sh ./x.py [flags] ``` -This is how the documentation and examples assume you are running `x.py`. Some alternative ways are: +This is how the documentation and examples assume you are running `x.py`. +Some alternative ways are: ```sh # On a Unix shell if you don't have the necessary `python3` command @@ -39,8 +42,8 @@ x.py [flags] python x.py [flags] ``` -More information about `x.py` can be found -by running it with the `--help` flag or reading the [rustc dev guide][rustcguidebuild]. +More information about `x.py` can be found by running it with the `--help` flag +or reading the [rustc dev guide][rustcguidebuild]. [gettingstarted]: https://rustc-dev-guide.rust-lang.org/getting-started.html [rustcguidebuild]: https://rustc-dev-guide.rust-lang.org/building/how-to-build-and-run.html @@ -49,24 +52,29 @@ by running it with the `--help` flag or reading the [rustc dev guide][rustcguide Make sure you have installed the dependencies: - * `python` 3 or 2.7 - * `git` - * A C compiler (when building for the host, `cc` is enough; cross-compiling may need additional compilers) - * `curl` (not needed on Windows) - * `pkg-config` if you are compiling on Linux and targeting Linux - * `libiconv` (already included with glibc on Debian-based distros) +* `python` 3 or 2.7 +* `git` +* A C compiler (when building for the host, `cc` is enough; cross-compiling may + need additional compilers) +* `curl` (not needed on Windows) +* `pkg-config` if you are compiling on Linux and targeting Linux +* `libiconv` (already included with glibc on Debian-based distros) -To build cargo, you'll also need OpenSSL (`libssl-dev` or `openssl-devel` on most Unix distros). +To build Cargo, you'll also need OpenSSL (`libssl-dev` or `openssl-devel` on +most Unix distros). If building LLVM from source, you'll need additional tools: * `g++`, `clang++`, or MSVC with versions listed on [LLVM's documentation](https://llvm.org/docs/GettingStarted.html#host-c-toolchain-both-compiler-and-standard-library) -* `ninja`, or GNU `make` 3.81 or later (ninja is recommended, especially on Windows) +* `ninja`, or GNU `make` 3.81 or later (Ninja is recommended, especially on + Windows) * `cmake` 3.13.4 or later -* `libstdc++-static` may be required on some Linux distributions such as Fedora and Ubuntu +* `libstdc++-static` may be required on some Linux distributions such as Fedora + and Ubuntu -On tier 1 or tier 2 with host tools platforms, you can also choose to download LLVM by setting `llvm.download-ci-llvm = true`. +On tier 1 or tier 2 with host tools platforms, you can also choose to download +LLVM by setting `llvm.download-ci-llvm = true`. Otherwise, you'll need LLVM installed and `llvm-config` in your path. See [the rustc-dev-guide for more info][sysllvm]. @@ -86,34 +94,37 @@ See [the rustc-dev-guide for more info][sysllvm]. 2. Configure the build settings: - The Rust build system uses a file named `config.toml` in the root of the - source tree to determine various configuration settings for the build. - Set up the defaults intended for distros to get started. You can see a full list of options - in `config.toml.example`. + The Rust build system uses a file named `config.toml` in the root of the + source tree to determine various configuration settings for the build. + Set up the defaults intended for distros to get started. You can see a full + list of options in `config.toml.example`. - ```sh - printf 'profile = "user" \nchangelog-seen = 2 \n' > config.toml - ``` + ```sh + printf 'profile = "user" \nchangelog-seen = 2 \n' > config.toml + ``` - If you plan to use `x.py install` to create an installation, it is recommended - that you set the `prefix` value in the `[install]` section to a directory. + If you plan to use `x.py install` to create an installation, it is + recommended that you set the `prefix` value in the `[install]` section to a + directory. 3. Build and install: - ```sh - ./x.py build && ./x.py install - ``` + ```sh + ./x.py build && ./x.py install + ``` - When complete, `./x.py install` will place several programs into - `$PREFIX/bin`: `rustc`, the Rust compiler, and `rustdoc`, the - API-documentation tool. If you've set `profile = "user"` or `build.extended = true`, it will - also include [Cargo], Rust's package manager. + When complete, `./x.py install` will place several programs into + `$PREFIX/bin`: `rustc`, the Rust compiler, and `rustdoc`, the + API-documentation tool. If you've set `profile = "user"` or + `build.extended = true`, it will also include [Cargo], Rust's package + manager. [Cargo]: https://github.com/rust-lang/cargo ### Building on Windows -On Windows, we suggest using [winget] to install dependencies by running the following in a terminal: +On Windows, we suggest using [winget] to install dependencies by running the +following in a terminal: ```powershell winget install -e Python.Python.3 @@ -121,17 +132,19 @@ winget install -e Kitware.CMake winget install -e Git.Git ``` -Then edit your system's `PATH` variable and add: `C:\Program Files\CMake\bin`. See -[this guide on editing the system `PATH`](https://www.java.com/en/download/help/path.html) from the -Java documentation. +Then edit your system's `PATH` variable and add: `C:\Program Files\CMake\bin`. +See +[this guide on editing the system `PATH`](https://www.java.com/en/download/help/path.html) +from the Java documentation. [winget]: https://github.com/microsoft/winget-cli There are two prominent ABIs in use on Windows: the native (MSVC) ABI used by Visual Studio and the GNU ABI used by the GCC toolchain. Which version of Rust you need depends largely on what C/C++ libraries you want to interoperate with. -Use the MSVC build of Rust to interop with software produced by Visual Studio and -the GNU build to interop with GNU software built using the MinGW/MSYS2 toolchain. +Use the MSVC build of Rust to interop with software produced by Visual Studio +and the GNU build to interop with GNU software built using the MinGW/MSYS2 +toolchain. #### MinGW @@ -144,7 +157,7 @@ the GNU build to interop with GNU software built using the MinGW/MSYS2 toolchain 2. Run `mingw32_shell.bat` or `mingw64_shell.bat` from the MSYS2 installation directory (e.g. `C:\msys64`), depending on whether you want 32-bit or 64-bit Rust. (As of the latest version of MSYS2 you have to run `msys2_shell.cmd - -mingw32` or `msys2_shell.cmd -mingw64` from the command line instead) + -mingw32` or `msys2_shell.cmd -mingw64` from the command line instead.) 3. From this terminal, install the required tools: @@ -153,11 +166,11 @@ the GNU build to interop with GNU software built using the MinGW/MSYS2 toolchain pacman -Sy pacman-mirrors # Install build tools needed for Rust. If you're building a 32-bit compiler, - # then replace "x86_64" below with "i686". If you've already got git, python, - # or CMake installed and in PATH you can remove them from this list. Note - # that it is important that you do **not** use the 'python2', 'cmake' and 'ninja' - # packages from the 'msys2' subsystem. The build has historically been known - # to fail with these packages. + # then replace "x86_64" below with "i686". If you've already got Git, Python, + # or CMake installed and in PATH you can remove them from this list. + # Note that it is important that you do **not** use the 'python2', 'cmake', + # and 'ninja' packages from the 'msys2' subsystem. + # The build has historically been known to fail with these packages. pacman -S git \ make \ diffutils \ @@ -178,12 +191,12 @@ the GNU build to interop with GNU software built using the MinGW/MSYS2 toolchain MSVC builds of Rust additionally require an installation of Visual Studio 2017 (or later) so `rustc` can use its linker. The simplest way is to get -[Visual Studio], check the “C++ build tools” and “Windows 10 SDK” workload. +[Visual Studio], check the "C++ build tools" and "Windows 10 SDK" workload. [Visual Studio]: https://visualstudio.microsoft.com/downloads/ -(If you're installing cmake yourself, be careful that “C++ CMake tools for -Windows” doesn't get included under “Individual components”.) +(If you're installing CMake yourself, be careful that "C++ CMake tools for +Windows" doesn't get included under "Individual components".) With these dependencies installed, you can build the compiler in a `cmd.exe` shell with: @@ -192,10 +205,11 @@ shell with: python x.py build ``` -Right now, building Rust only works with some known versions of Visual Studio. If -you have a more recent version installed and the build system doesn't understand, -you may need to force rustbuild to use an older version. This can be done -by manually calling the appropriate vcvars file before running the bootstrap. +Right now, building Rust only works with some known versions of Visual Studio. +If you have a more recent version installed and the build system doesn't +understand, you may need to force rustbuild to use an older version. +This can be done by manually calling the appropriate vcvars file before running +the bootstrap. ```batch CALL "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat" @@ -215,9 +229,9 @@ Windows build triples are: - `x86_64-pc-windows-msvc` The build triple can be specified by either specifying `--build=` when -invoking `x.py` commands, or by creating a `config.toml` file (as described -in [Installing From Source](#installing-from-source)), and modifying the -`build` option under the `[build]` section. +invoking `x.py` commands, or by creating a `config.toml` file (as described in +[Installing from Source](#installing-from-source)), and modifying the `build` +option under the `[build]` section. ### Configure and Make @@ -229,33 +243,35 @@ configure script and makefile (the latter of which just invokes `x.py`). make && sudo make install ``` -`configure` generates a `config.toml` which can also be used with normal `x.py` invocations. +`configure` generates a `config.toml` which can also be used with normal `x.py` +invocations. ## Building Documentation -If you’d like to build the documentation, it’s almost the same: +If you'd like to build the documentation, it's almost the same: ```sh ./x.py doc ``` The generated documentation will appear under `doc` in the `build` directory for -the ABI used. I.e., if the ABI was `x86_64-pc-windows-msvc`, the directory will be -`build\x86_64-pc-windows-msvc\doc`. +the ABI used. That is, if the ABI was `x86_64-pc-windows-msvc`, the directory +will be `build\x86_64-pc-windows-msvc\doc`. ## Notes -Since the Rust compiler is written in Rust, it must be built by a -precompiled "snapshot" version of itself (made in an earlier stage of -development). As such, source builds require an Internet connection to -fetch snapshots, and an OS that can execute the available snapshot binaries. +Since the Rust compiler is written in Rust, it must be built by a precompiled +"snapshot" version of itself (made in an earlier stage of development). +As such, source builds require an Internet connection to fetch snapshots, and an +OS that can execute the available snapshot binaries. -See https://doc.rust-lang.org/nightly/rustc/platform-support.html for a list of supported platforms. -Only "host tools" platforms have a pre-compiled snapshot binary available; to compile for a platform -without host tools you must cross-compile. +See https://doc.rust-lang.org/nightly/rustc/platform-support.html for a list of +supported platforms. +Only "host tools" platforms have a pre-compiled snapshot binary available; to +compile for a platform without host tools you must cross-compile. -You may find that other platforms work, but these are our officially -supported build environments that are most likely to work. +You may find that other platforms work, but these are our officially supported +build environments that are most likely to work. ## Getting Help @@ -267,9 +283,9 @@ See [CONTRIBUTING.md](CONTRIBUTING.md). ## License -Rust is primarily distributed under the terms of both the MIT license -and the Apache License (Version 2.0), with portions covered by various -BSD-like licenses. +Rust is primarily distributed under the terms of both the MIT license and the +Apache License (Version 2.0), with portions covered by various BSD-like +licenses. See [LICENSE-APACHE](LICENSE-APACHE), [LICENSE-MIT](LICENSE-MIT), and [COPYRIGHT](COPYRIGHT) for details. @@ -277,13 +293,14 @@ See [LICENSE-APACHE](LICENSE-APACHE), [LICENSE-MIT](LICENSE-MIT), and ## Trademark [The Rust Foundation][rust-foundation] owns and protects the Rust and Cargo -trademarks and logos (the “Rust Trademarks”). +trademarks and logos (the "Rust Trademarks"). -If you want to use these names or brands, please read the [media guide][media-guide]. +If you want to use these names or brands, please read the +[media guide][media-guide]. Third-party logos may be subject to third-party copyrights and trademarks. See [Licenses][policies-licenses] for details. [rust-foundation]: https://foundation.rust-lang.org/ -[media-guide]: https://www.rust-lang.org/policies/media-guide +[media-guide]: https://foundation.rust-lang.org/policies/logo-policy-and-media-guide/ [policies-licenses]: https://www.rust-lang.org/policies/licenses