Document not found (404)
+This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 0000000000..f17311098f --- /dev/null +++ b/.nojekyll @@ -0,0 +1 @@ +This file makes sure that Github Pages doesn't process mdBook's output. diff --git a/404.html b/404.html new file mode 100644 index 0000000000..4069bd7833 --- /dev/null +++ b/404.html @@ -0,0 +1,221 @@ + + +
+ + +This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +Rust is distributed on three different release channels: stable, beta, and
+nightly. rustup
uses the stable channel by default, which
+represents the latest release of Rust. Stable publishes new releases every six weeks.
When a new version of Rust is released, simply type rustup update
to update:
$ rustup update
+info: syncing channel updates for 'stable'
+info: downloading component 'rustc'
+info: downloading component 'rust-std'
+info: downloading component 'rust-docs'
+info: downloading component 'cargo'
+info: installing component 'rustc'
+info: installing component 'rust-std'
+info: installing component 'rust-docs'
+info: installing component 'cargo'
+info: checking for self-update
+info: downloading self-update
+
+ stable updated: rustc 1.7.0 (a5d1e7a59 2016-02-29)
+
+
+rustup
up to dateIf your rustup
was built with the no-self-update feature, it can not update
+itself. This is not the default, and only versions of rustup
built with
+--no-default-features
, or obtained from a third-party distributor who has
+disabled it (such as NixOS).
Otherwise Rustup can update itself. It is possible to control Rustup’s automatic
+self update mechanism with the auto-self-update
configuration variable. This
+setting supports three values: enable
and disable
and check-only
.
disable
will ensure that no automatic self updating actions are taken.enable
will mean that rustup update
and similar commands will also check for, and install, any update to Rustup.check-only
will cause any automatic self update to check and report on any updates, but not to automatically install them.Whether auto-self-update
is enable
or not, you can request that Rustup
+update itself to the latest version of rustup
by running rustup self update
.
+This will not download new toolchains:
$ rustup self update
+info: checking for self-update
+info: downloading self-update
+
+++Self updates can also be suppressed on individual invocations of
+rustup
by +passing the argument--no-self-update
when runningrustup update
or +rustup toolchain install
.
The rustup
command-line has a built-in help system that provides more
+information about each command. Run rustup help
for an overview. Detailed
+help for each subcommand is also available. For example, run rustup toolchain install --help
for specifics on installing toolchains.
Rust is released to three different “channels”: stable, beta, and nightly. The
+stable releases are made every 6 weeks (with occasional point releases). Beta
+releases are the version that will appear in the next stable release. Nightly
+releases are made every night. See The Rust Book for more details
+on Rust’s train release model. The release schedule is posted to the Rust
+Forge. rustup
assists with installing different channels, keeping them
+up-to-date, and easily switching between them.
After a release channel has been installed, rustup
can be used to update the
+installed version to the latest release on that channel. See the Keeping rust
+up to date section for more information.
rustup
can also install specific versions of Rust, such as 1.45.2
or
+nightly-2020-07-27
. See the Toolchains chapter for more information on
+installing different channels and releases. See the Overrides chapter for
+details on switching between toolchains and pinning your project to a specific
+toolchain.
rustup
gives you easy access to the nightly compiler and its experimental
+features. To add it just run rustup toolchain install nightly
:
$ rustup toolchain install nightly
+info: syncing channel updates for 'nightly'
+info: downloading toolchain manifest
+info: downloading component 'rustc'
+info: downloading component 'rust-std'
+info: downloading component 'rust-docs'
+info: downloading component 'cargo'
+info: installing component 'rustc'
+info: installing component 'rust-std'
+info: installing component 'rust-docs'
+info: installing component 'cargo'
+
+ nightly installed: rustc 1.9.0-nightly (02310fd31 2016-03-19)
+
+
+Now Rust nightly is installed, but not activated. To test it out you can run a +command from the nightly toolchain like
+$ rustup run nightly rustc --version
+rustc 1.9.0-nightly (02310fd31 2016-03-19)
+
+But more likely you want to use it for a while. To switch to nightly globally,
+change the default with rustup default nightly
:
$ rustup default nightly
+info: using existing install for 'nightly'
+info: default toolchain set to 'nightly'
+
+ nightly unchanged: rustc 1.9.0-nightly (02310fd31 2016-03-19)
+
+
+Now any time you run cargo
or rustc
you will be running the nightly
+compiler.
With nightly installed any time you run rustup update
, the nightly channel
+will be updated in addition to stable:
$ rustup update
+info: syncing channel updates for 'stable'
+info: syncing channel updates for 'nightly'
+info: checking for self-update
+info: downloading self-update
+
+ stable unchanged: rustc 1.7.0 (a5d1e7a59 2016-02-29)
+ nightly unchanged: rustc 1.9.0-nightly (02310fd31 2016-03-19)
+
+
+Nightly toolchains may fail to build, so for any given date and target
+platform there may not be a toolchain available. Furthermore, nightly builds
+may be published with missing non-default components (such as clippy
).
+As such, it can be difficult to find fully-working nightlies. Use the
+rustup-components-history project to find the build status of recent
+nightly toolchains and components.
When you attempt to install or update the nightly
channel, rustup
will
+check if a required or previously installed component is missing. If it is
+missing, rustup
will automatically search for an older release that contains
+the required components. There are several ways to change this behavior:
--force
flag to rustup toolchain install
to force it to install
+the most recent version even if there is a missing component.--profile
flag to rustup toolchain install
to use a different
+profile that does not contain the missing component. For example,
+--profile=minimal
should always work, as the minimal set is required to
+exist. See the Profiles chapter for more detail.rustup toolchain install nightly-2020-07-27
. You can then use overrides
+to pin to that specific release.Each toolchain has several “components”, some of which are required (like
+rustc
) and some that are optional (like clippy
). The rustup component
command is used to manage the installed components. For example,
+run rustup component list
to see a list of available and installed
+components.
Components can be added when installing a toolchain with the --component
+flag. For example:
rustup toolchain install nightly --component rust-docs
+
+Components can be added to an already-installed toolchain with the rustup component
command:
rustup component add rust-docs
+
+To make it easier to choose which components are installed, rustup
has the
+concept of “profiles” which provide named groupings of different components.
+See the Profiles chapter for more detail.
Most components have a target-triple suffix, such as
+rustc-x86_64-apple-darwin
, to signify the platform the component is for.
The set of available components may vary with different releases and +toolchains. The following is an overview of the different components:
+rustc
— The Rust compiler and Rustdoc.cargo
— Cargo is a package manager and build tool.rustfmt
— Rustfmt is a tool for automatically formatting code.rust-std
— This is the Rust standard library. There is a separate
+rust-std
component for each target that rustc
supports, such as
+rust-std-x86_64-pc-windows-msvc
. See the Cross-compilation chapter for
+more detail.rust-docs
— This is a local copy of the Rust documentation. Use the
+rustup doc
command to open the documentation in a web browser. Run rustup doc --help
for more options.rust-analyzer
— rust-analyzer is a language server that provides support
+for editors and IDEs.clippy
— Clippy is a lint tool that provides extra checks for common
+mistakes and stylistic choices.miri
— Miri is an experimental Rust interpreter, which can be used for
+checking for undefined-behavior.rust-src
— This is a local copy of the source code of the Rust standard
+library. This can be used by some tools, such as rust-analyzer, to provide
+auto-completion for functions within the standard library; Miri which is a
+Rust interpreter; and Cargo’s experimental build-std feature, which allows
+you to rebuild the standard library locally.rust-mingw
— This contains a linker and platform libraries for building on
+the x86_64-pc-windows-gnu
platform.llvm-tools
— This component contains a collection of LLVM tools.
+Note that this component has not been stabilized and may change in the
+future and is provided as-is.
+See #85658.rustc-dev
— This component contains the compiler as a library. Most users
+will not need this; it is only needed for development of tools that link
+to the compiler, such as making modifications to Clippy.These components have been deprecated and are not published in new Rust releases.
+rls
— RLS is a language server that is deprecated and has been replaced
+by rust-analyzer.rust-analysis
— Metadata about the standard library, used by RLS.Not all components are available for all toolchains. Especially on the nightly +channel, some components may not be included if they are in a broken state. +The current status of all the components may be found on the rustup +components history page. See the Nightly availability section for more +details.
+ +rustup
is a toolchain multiplexer. It installs and manages many Rust
+toolchains and presents them all through a single set of tools installed to
+~/.cargo/bin
. The rustc
and cargo
executables installed in
+~/.cargo/bin
are proxies that delegate to the real toolchain. rustup
+then provides mechanisms to easily change the active toolchain by
+reconfiguring the behavior of the proxies.
So when rustup
is first installed, running rustc
will run the proxy in
+$HOME/.cargo/bin/rustc
, which in turn will run the stable compiler. If you
+later change the default toolchain to nightly with rustup default nightly
,
+then that same proxy will run the nightly
compiler instead.
This is similar to Ruby’s rbenv, Python’s pyenv, or Node’s nvm.
+channel — Rust is released to three different “channels”: stable, beta, +and nightly. See the Channels chapter for more details.
+toolchain — A “toolchain” is a complete installation of the Rust
+compiler (rustc
) and related tools (like cargo
). A toolchain
+specification includes the release channel or version, and the host
+platform that the toolchain runs on.
target — rustc
is capable of generating code for many platforms. The
+“target” specifies the platform that the code will be generated for. By
+default, cargo
and rustc
use the host toolchain’s platform as the
+target. To build for a different target, usually the target’s standard
+library needs to be installed first via the rustup target
command. See the
+Cross-compilation chapter for more details.
component — Each release of Rust includes several “components”, some of
+which are required (like rustc
) and some that are optional (like
+clippy
). See the Components chapter for more detail.
profile — In order to make it easier to work with components, a +“profile” defines a grouping of components. See the Profiles chapter for +more details.
+proxy — A wrapper for a common Rust component (like rustc
), built to forward
+CLI invocations to the active Rust toolchain. See the Proxies chapter for more details.
rustup
has the concept of “profiles”. They are groups of components you
+can choose to download while installing a new Rust toolchain. The profiles
+available at this time are minimal
, default
, and complete
:
rustc
, rust-std
, and cargo
). It’s recommended to use
+this component on Windows systems if you don’t use local documentation (the
+large number of files can cause issues with some Antivirus systems), and in
+CI.rust-docs
, rustfmt
, and clippy
. This profile will be
+used by rustup
by default, and it’s the one recommended for general use.rustup
. This should never be used, as it includes every component ever
+included in the metadata and thus will almost always fail. If you are
+looking for a way to install devtools such as miri
or IDE integration
+tools (rust-analyzer
), you should use the default
profile and
+install the needed additional components manually, either by using rustup component add
or by using -c
when installing the toolchain.To change the profile rustup install
uses by default, you can use the
+rustup set profile
command.
+For example, to select the minimal profile you can use:
rustup set profile minimal
+
+You can also directly select the profile used when installing a toolchain with:
+rustup install --profile <name>
+
+It’s also possible to choose the default profile when installing rustup
for
+the first time, either interactively by choosing the “Customize installation”
+option or programmatically by passing the --profile=<name>
flag. Profiles
+will only affect newly installed toolchains: as usual it will be possible to
+install individual components later with: rustup component add
.
rustup
provides a number of wrappers for common Rust tools.
+These are called proxies and represent commands which are
+provided by the various components.
The list of proxies is currently static in rustup
and is as follows:
rustc
is the compiler for the Rust programming language, provided by the project itself and comes from the rustc
component.
rustdoc
is a tool distributed in the rustc
component which helps you to generate documentation for Rust projects.
cargo
is the Rust package manager which downloads your Rust package’s dependencies, compiles your packages, makes distributable packages, and uploads them to crates.io (the Rust community’s package registry). It comes from the cargo
component.
rust-lldb
, rust-gdb
, and rust-gdbgui
are simple wrappers around the lldb
, gdb
, and gdbgui
debuggers respectively. The wrappers enable some pretty-printing of Rust values and add some convenience features to the debuggers by means of their scripting interfaces.
rust-analyzer
is part of the Rust IDE integration tooling. It implements the language-server protocol to permit IDEs and editors such as Visual Studio Code, Vim, or Emacs, access to the semantics of the Rust code you are editing. It comes from the rust-analyzer
component.
cargo-clippy
and clippy-driver
are related to the clippy
linting tool which provides extra checks for common mistakes and stylistic choices and it comes from the clippy
component.
cargo-miri
is an experimental interpreter for Rust’s mid-level intermediate representation (MIR) and it comes from the miri
component.
rls
is a deprecated IDE tool that has been replaced by rust-analyzer
. It comes from the rls
component.
Many rustup
commands deal with toolchains, a single installation of the
+Rust compiler. rustup
supports multiple types of toolchains. The most basic
+track the official release channels: stable, beta and nightly; but
+rustup
can also install toolchains from the official archives, for alternate
+host platforms, and from local builds.
Standard release channel toolchain names have the following form:
+<channel>[-<date>][-<host>]
+
+<channel> = stable|beta|nightly|<major.minor>|<major.minor.patch>
+<date> = YYYY-MM-DD
+<host> = <target-triple>
+
+‘channel’ is a named release channel, a major and minor version number such as
+1.42
, or a fully specified version number, such as 1.42.0
. Channel names
+can be optionally appended with an archive date, as in nightly-2014-12-18
, in
+which case the toolchain is downloaded from the archive for that date.
Finally, the host may be specified as a target triple. This is most useful for +installing a 32-bit compiler on a 64-bit platform, or for installing the +MSVC-based toolchain on Windows. For example:
+$ rustup toolchain install stable-x86_64-pc-windows-msvc
+
+For convenience, elements of the target triple that are omitted will be +inferred, so the above could be written:
+$ rustup toolchain install stable-msvc
+
+Toolchain names that don’t name a channel instead can be used to name custom +toolchains.
+For convenience of developers working on Rust itself, rustup
can manage
+local builds of the Rust toolchain. To teach rustup
about your build, run:
$ rustup toolchain link my-toolchain path/to/my/toolchain/sysroot
+
+For example, on Ubuntu you might clone rust-lang/rust
into ~/rust
, build
+it, and then run:
$ rustup toolchain link my-toolchain ~/rust/build/x86_64-unknown-linux-gnu/stage2/
+$ rustup default my-toolchain
+
+Now you can name my-toolchain
as any other rustup
toolchain. Create a
+rustup
toolchain for each of your rust-lang/rust
workspaces and test them
+easily with rustup run my-toolchain rustc
.
Because the rust-lang/rust
tree does not include Cargo, when cargo
is
+invoked for a custom toolchain and it is not available, rustup
will attempt
+to use cargo
from one of the release channels, preferring ‘nightly’, then
+‘beta’ or ‘stable’.
Rustup has a TOML settings file at
+${RUSTUP_HOME}/settings.toml
(which defaults to ~/.rustup
or
+%USERPROFILE%/.rustup
). The schema for this file is not part of the public
+interface for rustup - the rustup CLI should be used to query and set settings.
On Unix operating systems a fallback settings file is consulted for some
+settings. This fallback file is located at /etc/rustup/settings.toml
and
+currently can define only default_toolchain
.
Rust supports a great number of platforms. For many of these platforms
+The Rust Project publishes binary releases of the standard library, and for
+some the full compiler. rustup
gives easy access to all of them.
When you first install a toolchain, rustup
installs only the standard
+library for your host platform - that is, the architecture and operating
+system you are presently running. To compile to other platforms you must
+install other target platforms. This is done with the rustup target add
+command. For example, to add the Android target:
$ rustup target add arm-linux-androideabi
+info: downloading component 'rust-std' for 'arm-linux-androideabi'
+info: installing component 'rust-std' for 'arm-linux-androideabi'
+
+With the arm-linux-androideabi
target installed you can then build for
+Android with Cargo by passing the --target
flag, as in cargo build --target=arm-linux-androideabi
.
Note that rustup target add
only installs the Rust standard library for a
+given target. There are typically other tools necessary to cross-compile,
+particularly a linker. For example, to cross compile to Android the Android
+NDK must be installed. In the future, rustup
will provide assistance
+installing the NDK components as well. See the target section of the
+cargo
configuration for how to setup a linker to use for a certain target.
To install a target for a toolchain that isn’t the default toolchain use the
+--toolchain
argument of rustup target add
, like so:
$ rustup target add --toolchain <toolchain> <target>...
+
+To see a list of available targets, rustup target list
. To remove a
+previously-added target, rustup target remove
.
This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +Generally we just follow good sensible Rust practices, clippy and so forth. +However there are some practices we’ve agreed on that are not machine-enforced; +meeting those requirements in a PR will make it easier to merge.
+In each file the imports should be grouped into at most 4 groups in the +following order:
+Separate each group with a blank line, and rustfmt will sort into a canonical +order. Any file that is not grouped like this can be rearranged whenever the +file is touched - we’re not precious about having it done in a separate commit, +though that is helpful.
+The rustup::currentprocess
module abstracts the global state that is
+std::env::args
, std::env::vars
, std::io::std*
, std::process::id
,
+std::env::current_dir
and std::process::exit
permitting threaded tests of
+the CLI logic; use process()
rather than those APIs directly.
We do not enforce lint status in the checks done by GitHub Actions, because +clippy is a moving target that can make it hard to merge for little benefit.
+We do ask that contributors keep the clippy status clean themselves.
+Minimally, run cargo clippy --all --all-targets --features test -- -D warnings
before
+submitting code.
If possible, adding --all-features
to the command is useful, but will require
+additional dependencies like libcurl-dev
.
Regular contributors or contributors to particularly OS-specific code should +also make sure that their clippy checking is done on at least Linux and Windows, +as OS-conditional code is a common source of unused imports and other small +lints, which can build up over time.
+For developers using BSD/Linux/Mac OS, there are Windows VM’s suitable for such +development tasks for use with virtualbox and other hypervisors are downloadable +from +Microsoft. +Similarly, there are many Linux and Unix operating systems images available for +developers whose usual operating system is Windows. Currently Rustup has no Mac +OS specific code, so there should be no need to worry about Mac VM images.
+Clippy is also run in GitHub Actions, in the General Checks / Checks
build
+task, but not currently run per-platform, which means there is no way to find
+out the status of clippy per platform without running it on that platform as a
+developer.
These test helpers add pre-and-post logic to tests to enable the use of tracing +inside tests, which can be helpful for tracking down behaviours in larger tests.
+ +git checkout -b my-new-feature
cargo test --features=test
git commit -am 'Add some feature'
git push origin my-new-feature
For developing on rustup
itself, you may want to install into a temporary
+directory, with a series of commands similar to this:
cargo build
+mkdir home
+RUSTUP_HOME=home CARGO_HOME=home target/debug/rustup-init --no-modify-path -y
+
+You can then try out rustup
with your changes by running home/bin/rustup
, without
+affecting any existing installation. Remember to keep those two environment variables
+set when running your compiled rustup-init
or the toolchains it installs, but unset
+when rebuilding rustup
itself.
If you wish to install your new build to try out longer term in your home directory
+then you can run cargo dev-install
which is an alias in .cargo/config
which
+runs cargo run -- --no-modify-path -y
to install your build into your homedir.
We use rustfmt
to keep our codebase consistently formatted. Please ensure that
+you have correctly formatted your code (most editors will do this automatically
+when saving) or it may not pass the CI tests.
If you are moving, renaming or removing an existing mdBook page, please use mdBook’s
+output.html.redirect
feature to ensure that the old URL gets redirected.
Unless you explicitly state otherwise, any contribution intentionally +submitted for inclusion in the work by you, as defined in the +Apache-2.0 license, shall be dual licensed as in the README, without any +additional terms or conditions.
+ +