diff --git a/README.md b/README.md index a88ee4b8bf061..ada2075ca0563 100644 --- a/README.md +++ b/README.md @@ -1,267 +1,117 @@ -# The Rust Programming Language +# Rust Programming Language -[![Rust Community](https://img.shields.io/badge/Rust_Community%20-Join_us-brightgreen?style=plastic&logo=rust)](https://www.rust-lang.org/community) + [![Rust Community](https://img.shields.io/badge/Rust_Community%20-Join_us-brightgreen?style=plastic&logo=rust)](https://www.rust-lang.org/community) -This is the main source code repository for [Rust]. It contains the compiler, -standard library, and documentation. + Welcome to the official repository for the Rust programming language. This repository contains the Rust compiler, standard library, and documentation. -[Rust]: https://www.rust-lang.org/ + **Note**: This README is for users of Rust. If you want to contribute to the development of the Rust compiler, please read the [CONTRIBUTING.md](CONTRIBUTING.md) file. -**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. + ## Table of Contents + - [Quick Start](#quick-start) + - [Installing from Source](#installing-from-source) + - [Building Documentation](#building-documentation) + - [Notes](#notes) + - [Getting Help](#getting-help) + - [Contributing](#contributing) + - [License](#license) + - [Trademark](#trademark) -
-Table of content + ## Quick Start -- [Quick Start](#quick-start) -- [Installing from Source](#installing-from-source) -- [Building Documentation](#building-documentation) -- [Notes](#notes) -- [Getting Help](#getting-help) -- [Contributing](#contributing) -- [License](#license) -- [Trademark](#trademark) + For a quick start guide to installing Rust, read the ["Installation" section](https://doc.rust-lang.org/book/ch01-01-installation.html) in [The Rust Programming Language book](https://doc.rust-lang.org/book/index.html). -
+ ## Installing from Source -## Quick Start + To build Rust from source, you can use the `x.py` Python script. It manages the bootstrapping process and uses a `config.toml` file to configure the build. You can find a full list of configuration options in `config.example.toml`. -Read ["Installation"] from [The Book]. + On Unix systems, you can run `x.py` with the following command: -["Installation"]: https://doc.rust-lang.org/book/ch01-01-installation.html -[The Book]: https://doc.rust-lang.org/book/index.html + ```sh + ./x.py [flags] + ``` -## Installing from Source + For detailed information on using `x.py`, run `./x.py --help` or refer to the [rustc dev guide](https://rustc-dev-guide.rust-lang.org/building/how-to-build-and-run.html#what-is-xpy). -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. -It also uses a file named `config.toml` to determine various configuration -settings for the build. You can see a full list of options in -`config.example.toml`. + ### Dependencies -The `x.py` command can be run directly on most Unix systems in the following -format: + Before building Rust, make sure you have the following dependencies installed: + - `python` 3 or 2.7 + - `git` + - A C compiler (for the host, `cc` is sufficient; cross-compiling may require additional compilers) + - `curl` (not needed on Windows) + - `pkg-config` (for Linux when targeting Linux) + - `libiconv` (included with glibc on Debian-based distros) -```sh -./x.py [flags] -``` + To build Cargo, you'll also need OpenSSL (`libssl-dev` or `openssl-devel` on most Unix distros). -This is how the documentation and examples assume you are running `x.py`. -See the [rustc dev guide][rustcguidebuild] if this does not work on your -platform. + If building LLVM from source, additional tools are required, including `g++`, `clang++`, `ninja`, or GNU `make`, and `cmake`. For some Linux distributions, you may need `libstdc++-static`. -More information about `x.py` can be found by running it with the `--help` flag -or reading the [rustc dev guide][rustcguidebuild]. + You can download LLVM by setting `llvm.download-ci-llvm = true` on tier 1 or tier 2 platforms with host tools. -[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#what-is-xpy + For platform-specific instructions, see the [rustc dev guide](https://rustc-dev-guide.rust-lang.org/getting-started.html). -### Dependencies + ### Building on Unix-like Systems -Make sure you have installed the dependencies: + #### Build Steps -* `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) + 1. Clone the Rust source repository with `git`: -To build Cargo, you'll also need OpenSSL (`libssl-dev` or `openssl-devel` on -most Unix distros). + ```sh + git clone https://github.com/rust-lang/rust.git + cd rust + ``` -If building LLVM from source, you'll need additional tools: + 2. Configure the build settings: -* `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) -* `cmake` 3.13.4 or later -* `libstdc++-static` may be required on some Linux distributions such as Fedora - and Ubuntu + ```sh + ./configure + ``` -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]. + 3. Build and install: -[sysllvm]: https://rustc-dev-guide.rust-lang.org/building/new-target.html#using-pre-built-llvm + ```sh + ./x.py build && ./x.py install + ``` + When complete, `./x.py install` will place `rustc` and `rustdoc` in `$PREFIX/bin`. By default, it will also include [Cargo], Rust's package manager. -### Building on a Unix-like system + #### Configure and Make -#### Build steps + You can use the configure script to generate a `config.toml`. For make-based builds, follow these steps: -1. Clone the [source] with `git`: + ```sh + ./configure + make && sudo make install + ``` - ```sh - git clone https://github.com/rust-lang/rust.git - cd rust - ``` + ### Building on Windows -[source]: https://github.com/rust-lang/rust + On Windows, we recommend using [winget] to install dependencies: -2. Configure the build settings: + ```powershell + winget install -e Python.Python.3 + winget install -e Kitware.CMake + winget install -e Git.Git + ``` - ```sh - ./configure - ``` + For more information on Windows-specific builds, please refer to the documentation. - 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: `./configure --set install.prefix=` + ### Specifying an ABI -3. Build and install: + You can specify the Windows build ABI using the `--build` flag or by creating a `config.toml` file. - ```sh - ./x.py build && ./x.py install - ``` + Available Windows build triples: + - GNU ABI: `i686-pc-windows-gnu` and `x86_64-pc-windows-gnu` + - MSVC ABI: `i686-pc-windows-msvc` and `x86_64-pc-windows-msvc` - When complete, `./x.py install` will place several programs into - `$PREFIX/bin`: `rustc`, the Rust compiler, and `rustdoc`, the - API-documentation tool. By default, it will also include [Cargo], Rust's - package manager. You can disable this behavior by passing - `--set build.extended=false` to `./configure`. + ## Building Documentation -[Cargo]: https://github.com/rust-lang/cargo + To build Rust documentation, use the following command: -#### Configure and Make + ```sh + ./x.py doc + ``` -This project provides a configure script and makefile (the latter of which just -invokes `x.py`). `./configure` is the recommended way to programmatically -generate a `config.toml`. `make` is not recommended (we suggest using `x.py` -directly), but it is supported and we try not to break it unnecessarily. - -```sh -./configure -make && sudo make install -``` - -`configure` generates a `config.toml` which can also be used with normal `x.py` -invocations. - -### Building on Windows - -On Windows, we suggest using [winget] to install dependencies by running the -following in a terminal: - -```powershell -winget install -e Python.Python.3 -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. - -[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. - -#### MinGW - -[MSYS2][msys2] can be used to easily build Rust on Windows: - -[msys2]: https://www.msys2.org/ - -1. Download the latest [MSYS2 installer][msys2] and go through the installer. - -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.) - -3. From this terminal, install the required tools: - - ```sh - # Update package mirrors (may be needed if you have a fresh install of MSYS2) - 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. - pacman -S git \ - make \ - diffutils \ - tar \ - mingw-w64-x86_64-python \ - mingw-w64-x86_64-cmake \ - mingw-w64-x86_64-gcc \ - mingw-w64-x86_64-ninja - ``` - -4. Navigate to Rust's source code (or clone it), then build it: - - ```sh - python x.py setup user && python x.py build && python x.py install - ``` - -#### MSVC - -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]: 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".) - -With these dependencies installed, you can build the compiler in a `cmd.exe` -shell with: - -```sh -python x.py setup user -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. - -```batch -CALL "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat" -python x.py build -``` - -#### Specifying an ABI - -Each specific ABI can also be used from either environment (for example, using -the GNU ABI in PowerShell) by using an explicit build triple. The available -Windows build triples are: -- GNU ABI (using GCC) - - `i686-pc-windows-gnu` - - `x86_64-pc-windows-gnu` -- The MSVC ABI - - `i686-pc-windows-msvc` - - `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 -[Building on a Unix-like system](#building-on-a-unix-like-system)), and passing -`--set build.build=` to `./configure`. - -## Building Documentation - -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. That is, if the ABI was `x86_64-pc-windows-msvc`, the directory diff --git a/configure b/configure index 81e2001e4a583..5068e5c7e6325 100755 --- a/configure +++ b/configure @@ -1,18 +1,18 @@ #!/bin/sh -script="$(dirname $0)"/src/bootstrap/configure.py +script="$(dirname $0)/src/bootstrap/configure.py" try() { cmd=$1 shift - T=$($cmd --version 2>/dev/null) + T=$("$cmd" --version 2>/dev/null) if [ $? -eq 0 ]; then - exec $cmd "$script" "$@" + exec "$cmd" "$script" "$@" fi } -try python3 "$@" -try python2.7 "$@" -try python27 "$@" -try python2 "$@" -exec python $script "$@" +try "python3" "$@" +try "python2.7" "$@" +try "python27" "$@" +try "python2" "$@" +try "python" "$script" "$@" diff --git a/x.ps1 b/x.ps1 index eae1a2cb3996e..10bb9267359c2 100755 --- a/x.ps1 +++ b/x.ps1 @@ -1,30 +1,29 @@ #!/usr/bin/env pwsh -# See ./x for why these scripts exist. - $ErrorActionPreference = "Stop" -# syntax check -Get-Command -syntax ${PSCommandPath} >$null +# Syntax check +Get-Command -Syntax ${PSCommandPath} >$null +# Path to the x.py script $xpy = Join-Path $PSScriptRoot x.py -# Start-Process for some reason splits arguments on spaces. (Isn't powershell supposed to be simpler than bash?) -# Double-quote all the arguments so it doesn't do that. -$xpy_args = @("""$xpy""") + +# Define the arguments for x.py +$xpy_args = @($xpy) + +# Quote arguments to ensure they are passed correctly foreach ($arg in $args) { - $xpy_args += """$arg""" + $xpy_args += '"' + $arg + '"' } +# Function to get an application's command function Get-Application($app) { - $cmd = Get-Command $app -ErrorAction SilentlyContinue -CommandType Application | Select-Object -First 1 - return $cmd + Get-Command $app -ErrorAction SilentlyContinue -CommandType Application | Select-Object -First 1 } +# Function to invoke an application function Invoke-Application($application, $arguments) { $process = Start-Process -NoNewWindow -PassThru $application $arguments - # WORKAROUND: Caching the handle is necessary to make ExitCode work. - # See https://stackoverflow.com/a/23797762 - $handle = $process.Handle $process.WaitForExit() if ($null -eq $process.ExitCode) { Write-Error "Unable to read the exit code" @@ -33,26 +32,26 @@ function Invoke-Application($application, $arguments) { Exit $process.ExitCode } +# Try various Python interpreters foreach ($python in "py", "python3", "python", "python2") { - # NOTE: this only tests that the command exists in PATH, not that it's actually - # executable. The latter is not possible in a portable way, see - # https://github.com/PowerShell/PowerShell/issues/12625. - if (Get-Application $python) { + if ($app = Get-Application $python) { if ($python -eq "py") { - # Use python3, not python2 + # Use python3 instead of python2 $xpy_args = @("-3") + $xpy_args } - Invoke-Application $python $xpy_args + Invoke-Application $app $xpy_args } } -$found = (Get-Application "python*" | Where-Object {$_.name -match '^python[2-3]\.[0-9]+(\.exe)?$'}) -if (($null -ne $found) -and ($found.Length -ge 1)) { +# Try to find a Python interpreter (version 2 or 3) in PATH +$found = Get-Application "python*" | Where-Object {$_.Name -match '^python[2-3]\.[0-9]+(\.exe)?$'} +if ($found -ne $null -and $found.Length -ge 1) { $python = $found[0] Invoke-Application $python $xpy_args } -$msg = "${PSCommandPath}: error: did not find python installed`n" -$msg += "help: consider installing it from https://www.python.org/downloads/" +# Display an error message if Python is not found +$msg = "${PSCommandPath}: error: Python is not installed`n" +$msg += "help: Consider installing Python from https://www.python.org/downloads/" Write-Error $msg -Category NotInstalled Exit 1 diff --git a/x.py b/x.py index 6c4c106817eb5..7bce03339e05a 100755 --- a/x.py +++ b/x.py @@ -15,10 +15,10 @@ major = sys.version_info.major minor = sys.version_info.minor - # If this is python2, check if python3 is available and re-execute with that - # interpreter. Only python3 allows downloading CI LLVM. + # If this is Python 2, check if Python 3 is available and re-execute with that + # interpreter. Only Python 3 allows downloading CI LLVM. # - # This matters if someone's system `python` is python2. + # This matters if someone's system `python` is Python 2. if major < 3: try: os.execvp("py", ["py", "-3"] + sys.argv) @@ -26,20 +26,20 @@ try: os.execvp("python3", ["python3"] + sys.argv) except OSError: - # Python 3 isn't available, fall back to python 2 + # Python 3 isn't available, fall back to Python 2 pass - # soft deprecation of old python versions + # Soft deprecation of old Python versions skip_check = os.environ.get("RUST_IGNORE_OLD_PYTHON") == "1" if not skip_check and (major < 3 or (major == 3 and minor < 6)): - msg = cleandoc(""" - Using python {}.{} but >= 3.6 is recommended. Your python version + msg = cleandoc(f""" + Using Python {major}.{minor} but >= 3.6 is recommended. Your Python version should continue to work for the near future, but this will - eventually change. If python >= 3.6 is not available on your system, + eventually change. If Python >= 3.6 is not available on your system, please file an issue to help us understand timelines. This message can be suppressed by setting `RUST_IGNORE_OLD_PYTHON=1` - """.format(major, minor)) + """) warnings.warn(msg, stacklevel=1) rust_dir = os.path.dirname(os.path.abspath(__file__))