Skip to content

Commit 7044699

Browse files
ehussehuss
committed
New content and tweaks for the concepts chapters.
1 parent ceedb97 commit 7044699

File tree

5 files changed

+190
-19
lines changed

5 files changed

+190
-19
lines changed

‎doc/src/concepts/channels.md

Lines changed: 52 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,28 @@
11
# Channels
22

3+
Rust is released to three different "channels": stable, beta, and nightly. The
4+
stable releases are made every 6 weeks (with occasional point releases). Beta
5+
releases are the version that will appear in the next stable release. Nightly
6+
releases are made every night. See [The Rust Book][channels] for more details
7+
on Rust's train release model. The release schedule is posted to the [Rust
8+
Forge]. `rustup` assists with installing different channels, keeping them
9+
up-to-date, and easily switching between them.
10+
11+
After a release channel has been installed, `rustup` can be used to update the
12+
installed version to the latest release on that channel. See the [Keeping rust
13+
up to date] section for more information.
14+
15+
`rustup` can also install specific versions of Rust, such as `1.45.2` or
16+
`nightly-2020-07-27`. See the [Toolchains] chapter for more information on
17+
installing different channels and releases. See the [Overrides] chapter for
18+
details on switching between toolchains and pinning your project to a specific
19+
toolchain.
20+
21+
[channels]: https://doc.rust-lang.org/book/appendix-07-nightly-rust.html
22+
[Keeping rust up to date]: ../basics.md#keeping-rust-up-to-date
23+
[rust forge]: https://forge.rust-lang.org/
24+
[toolchains]: toolchains.md
25+
326
## Working with nightly Rust
427

528
`rustup` gives you easy access to the nightly compiler and its [experimental
@@ -33,7 +56,7 @@ rustc 1.9.0-nightly (02310fd31 2016-03-19)
3356
```
3457

3558
But more likely you want to use it for a while. To switch to nightly globally,
36-
change the default with `rustup default nightly`:
59+
change [the default] with `rustup default nightly`:
3760

3861
```console
3962
$ rustup default nightly
@@ -62,12 +85,34 @@ info: downloading self-updates
6285

6386
```
6487

65-
_A note about nightly stability_: Nightly toolchains may fail to build, so for
66-
any given date and target platform there may not be a toolchain available.
67-
Furthermore, nightly builds may be published with missing non-default
68-
components (e.g. [`clippy`]). As such, it can be difficult to find
69-
fully-working nightlies. Use the [rustup-components-history][rch] project to
70-
find the build status of recent nightly toolchains and components.
88+
[the default]: ../overrides.md#default-toolchain
89+
90+
## Nightly availability
91+
92+
Nightly toolchains may fail to build, so for any given date and target
93+
platform there may not be a toolchain available. Furthermore, nightly builds
94+
may be published with missing non-default [components] (such as [`clippy`]).
95+
As such, it can be difficult to find fully-working nightlies. Use the
96+
[rustup-components-history][rch] project to find the build status of recent
97+
nightly toolchains and components.
98+
99+
When you attempt to install or update the `nightly` channel, `rustup` will
100+
check if a required or previously installed component is missing. If it is
101+
missing, `rustup` will automatically search for an older release that contains
102+
the required components. There are several ways to change this behavior:
103+
104+
* Use the `--force` flag to `rustup toolchain install` to force it to install
105+
the most recent version even if there is a missing component.
106+
* Use the `--profile` flag to `rustup toolchain install` to use a different
107+
profile that does not contain the missing component. For example,
108+
`--profile=minimal` should always work, as the minimal set is required to
109+
exist. See the [Profiles] chapter for more detail.
110+
* Install a specific date that contains the components you need. For example,
111+
`rustup toolchain install nightly-2020-07-27`. You can then use [overrides]
112+
to pin to that specific release.
71113

72114
[`clippy`]: https://github.com/rust-lang/rust-clippy
73115
[rch]: https://rust-lang.github.io/rustup-components-history/
116+
[components]: components.md
117+
[profiles]: profiles.md
118+
[overrides]: ../overrides.md

‎doc/src/concepts/components.md

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,89 @@
11
# Components
2+
3+
Each [toolchain] has several "components", some of which are required (like
4+
`rustc`) and some that are optional (like [`clippy`][clippy]). The `rustup
5+
component` command is used to manage the installed components. For example,
6+
run `rustup component list` to see a list of available and installed
7+
components.
8+
9+
Components can be added when installing a toolchain with the `--component`
10+
flag. For example:
11+
12+
```console
13+
rustup toolchain install nightly --component rust-docs
14+
```
15+
16+
Components can be added to an already-installed toolchain with the `rustup
17+
component` command:
18+
19+
```console
20+
rustup component add rust-docs
21+
```
22+
23+
To make it easier to choose which components are installed, `rustup` has the
24+
concept of "profiles" which provide named groupings of different components.
25+
See the [Profiles] chapter for more detail.
26+
27+
Most components have a target-triple suffix, such as
28+
`rustc-x86_64-apple-darwin`, to signify the platform the component is for.
29+
30+
The set of available components may vary with different releases and
31+
toolchains. The following is an overview of the different components:
32+
33+
* `rustc` — The Rust compiler.
34+
* `cargo` — [Cargo] is a package manager and build tool.
35+
* `rustfmt` — [Rustfmt] is a tool for automatically formatting code.
36+
* `rust-std` — This is the Rust [standard library]. There is a separate
37+
`rust-std` component for each target that `rustc` supports, such as
38+
`rust-std-x86_64-pc-windows-msvc`. See the [Cross-compilation] chapter for
39+
more detail.
40+
* `rust-docs` — This is a local copy of the [Rust documentation]. Use the
41+
`rustup doc` command to open the documentation in a web browser. Run `rustup
42+
doc --help` for more options.
43+
* `rls` — [RLS] is a language server that provides support for editors and
44+
IDEs.
45+
* `rust-analyzer-preview` — [Rust anaylzer] is a new language server intended
46+
to eventually replace [RLS]. This is a preview release as it is still in the
47+
experimental phase.
48+
* `clippy` — [Clippy] is a lint tool that provides extra checks for common
49+
mistakes and stylistic choices.
50+
* `miri` — [Miri] is an experimental Rust interpreter, which can be used for
51+
checking for undefined-behavior.
52+
* `rust-src` — This is a local copy of the source code of the Rust standard
53+
library. This can be used by some tools, such as [RLS], to provide
54+
auto-completion for functions within the standard library; [Miri] which is a
55+
Rust interpreter; and Cargo's experimental [build-std] feature, which allows
56+
you to rebuild the standard library locally.
57+
* `rust-analysis` — Metadata about the standard library, used by tools like
58+
[RLS].
59+
* `rust-mingw` — This contains a linker and platform libraries for building on
60+
the `x86_64-pc-windows-gnu` platform.
61+
* `llvm-tools-preview` — This is an experimental component which contains a
62+
collection of [LLVM] tools.
63+
* `rustc-dev` — This component contains the compiler as a library. Most users
64+
will not need this; it is only needed for development *of* tools that link
65+
to the compiler, such as making modifications to [Clippy].
66+
67+
## Component availability
68+
69+
Not all components are available for all toolchains. Especially on the nightly
70+
channel, some components may not be included if they are in a broken state.
71+
The current status of all the components may be found on the [rustup
72+
components history] page. See the [Nightly availability] section for more
73+
details.
74+
75+
[toolchain]: toolchains.md
76+
[standard library]: https://doc.rust-lang.org/std/
77+
[rust documentation]: https://doc.rust-lang.org/
78+
[cross-compilation]: ../cross-compilation.md
79+
[build-std]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#build-std
80+
[miri]: https://github.com/rust-lang/miri/
81+
[RLS]: https://github.com/rust-lang/rls
82+
[cargo]: https://doc.rust-lang.org/cargo/
83+
[clippy]: https://github.com/rust-lang/rust-clippy
84+
[LLVM]: https://llvm.org/
85+
[rustfmt]: https://github.com/rust-lang/rustfmt
86+
[rustup components history]: https://rust-lang.github.io/rustup-components-history/
87+
[profiles]: profiles.md
88+
[rust anaylzer]: https://rust-analyzer.github.io/
89+
[nightly availability]: channels.md#nightly-availability

‎doc/src/concepts/index.md

Lines changed: 39 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,12 @@
44

55
`rustup` is a *toolchain multiplexer*. It installs and manages many Rust
66
toolchains and presents them all through a single set of tools installed to
7-
`~/.cargo/bin`. The `rustc` and `cargo` installed to `~/.cargo/bin` are
8-
*proxies* that delegate to the real toolchain. `rustup` then provides
9-
mechanisms to easily change the active toolchain by reconfiguring the behavior
10-
of the proxies.
7+
`~/.cargo/bin`. The [`rustc`] and [`cargo`] executables installed in
8+
`~/.cargo/bin` are *proxies* that delegate to the real toolchain. `rustup`
9+
then provides mechanisms to easily change the active toolchain by
10+
reconfiguring the behavior of the proxies.
1111

12-
So when `rustup` is first installed running `rustc` will run the proxy in
12+
So when `rustup` is first installed, running `rustc` will run the proxy in
1313
`$HOME/.cargo/bin/rustc`, which in turn will run the stable compiler. If you
1414
later *change the default toolchain* to nightly with `rustup default nightly`,
1515
then that same proxy will run the `nightly` compiler instead.
@@ -19,3 +19,37 @@ This is similar to Ruby's [rbenv], Python's [pyenv], or Node's [nvm].
1919
[rbenv]: https://github.com/rbenv/rbenv
2020
[pyenv]: https://github.com/yyuu/pyenv
2121
[nvm]: https://github.com/creationix/nvm
22+
[`rustc`]: https://doc.rust-lang.org/rustc/
23+
[`cargo`]: https://doc.rust-lang.org/cargo/
24+
25+
## Terminology
26+
27+
* **channel** — Rust is released to three different "channels": stable, beta,
28+
and nightly. See the [Channels] chapter for more details.
29+
30+
* **toolchain** — A "toolchain" is a complete installation of the Rust
31+
compiler (`rustc`) and related tools (like `cargo`). A [toolchain
32+
specification] includes the release channel or version, and the host
33+
platform that the toolchain runs on.
34+
35+
* **target** — `rustc` is capable of generating code for many platforms. The
36+
"target" specifies the platform that the code will be generated for. By
37+
default, `cargo` and `rustc` use the host toolchain's platform as the
38+
target. To build for a different target, usually the target's standard
39+
library needs to be installed first via the `rustup target` command. See the
40+
[Cross-compilation] chapter for more details.
41+
42+
* **component** — Each release of Rust includes several "components", some of
43+
which are required (like `rustc`) and some that are optional (like
44+
[`clippy`]). See the [Components] chapter for more detail.
45+
46+
* **profile** — In order to make it easier to work with components, a
47+
"profile" defines a grouping of components. See the [Profiles] chapter for
48+
more details.
49+
50+
[`clippy`]: https://github.com/rust-lang/rust-clippy
51+
[components]: components.md
52+
[cross-compilation]: ../cross-compilation.md
53+
[profiles]: profiles.md
54+
[toolchain specification]: toolchains.md
55+
[channels]: channels.md

‎doc/src/concepts/profiles.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Profiles
22

3-
`rustup` has the concept of "profiles". They are groups of components you can
4-
choose to download while installing a new Rust toolchain. The profiles
3+
`rustup` has the concept of "profiles". They are groups of [components] you
4+
can choose to download while installing a new Rust toolchain. The profiles
55
available at this time are `minimal`, `default`, and `complete`:
66

77
* The **minimal** profile includes as few components as possible to get a
@@ -32,3 +32,5 @@ first time, either interactively by choosing the "Customize installation"
3232
option or programmatically by passing the `--profile=<name>` flag. Profiles
3333
will only affect newly installed toolchains: as usual it will be possible to
3434
install individual components later with: `rustup component add`.
35+
36+
[components]: components.md

‎doc/src/concepts/toolchains.md

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,15 @@
11
# Toolchains
22

3-
## Toolchain specification
4-
53
Many `rustup` commands deal with *toolchains*, a single installation of the
64
Rust compiler. `rustup` supports multiple types of toolchains. The most basic
7-
track the official release channels: *stable*, *beta* and *nightly*; but
5+
track the official release [channels]: *stable*, *beta* and *nightly*; but
86
`rustup` can also install toolchains from the official archives, for alternate
97
host platforms, and from local builds.
108

9+
[channels]: channels.md
10+
11+
## Toolchain specification
12+
1113
Standard release channel toolchain names have the following form:
1214

1315
```
@@ -19,8 +21,8 @@ Standard release channel toolchain names have the following form:
1921
```
2022

2123
'channel' is either a named release channel or an explicit version number,
22-
such as '1.42.0'. Channel names can be optionally appended with an archive
23-
date, as in 'nightly-2014-12-18', in which case the toolchain is downloaded
24+
such as `1.42.0`. Channel names can be optionally appended with an archive
25+
date, as in `nightly-2014-12-18`, in which case the toolchain is downloaded
2426
from the archive for that date.
2527

2628
Finally, the host may be specified as a target triple. This is most useful for

0 commit comments

Comments
 (0)