[rustc.git] / src / doc / edition-guide / src / rust-2018 / rustup-for-managing-rust-versions.md

# Rustup for managing Rust versions

![Minimum Rust version: various](https://img.shields.io/badge/Minimum%20Rust%20Version-various-brightgreen.svg) (this tool has its own versioning scheme and works with all Rust versions)

The [Rustup](https://rustup.rs/) tool has become *the* recommended way to
install Rust, and is advertised on our website. Its powers go further than
that though, allowing you to manage various versions, components, and
platforms.

## For installing Rust

To install Rust through Rustup, you can go to
<https://www.rust-lang.org/install.html>, which will let you know how to do
so on your platform. This will install both `rustup` itself and the `stable`
version of `rustc` and `cargo`.

To install a specific Rust version, you can use `rustup install`:

```console
$ rustup install 1.30.0
```

This works for a specific nightly, as well:

```console
$ rustup install nightly-2018-08-01
```

As well as any of our release channels:

```console
$ rustup install stable
$ rustup install beta
$ rustup install nightly
```

## For updating your installation

To update all of the various channels you may have installed:

```console
$ rustup update
```

This will look at everything you've installed, and if there are new releases,
will update anything that has one.

## Managing versions

To set the default toolchain to something other than `stable`:

```console
$ rustup default nightly
```

To use a toolchain other than the default, use `rustup run`:

```console
$ rustup run nightly cargo build
```

There's also an alias for this that's a little shorter:

```console
$ cargo +nightly build
```

If you'd like to have a different default per-directory, that's easy too!
If you run this inside of a project:

```console
$ rustup override set nightly
```

Or, if you'd like to target a different version of Rust:
```console
$ rustup override set 1.30.0
```

Then when you're in that directory, any invocations of `rustc` or `cargo`
will use that toolchain. To share this with others, you can create a
`rust-toolchain` file with the contents of a toolchain, and check it into
source control. Now, when someone clones your project, they'll get the
right version without needing to `override set` themselves.

## Installing other targets

Rust supports cross-compiling to other targets, and Rustup can help you
manage them. For example, to use MUSL:

```console
$ rustup target add x86_64-unknown-linux-musl
```

And then you can

```console
$ cargo build --target=x86_64-unknown-linux-musl
```

To see the full list of targets you can install:

```console
$ rustup target list
```

## Installing components

Components are used to install certain kinds of tools. While `cargo-install`
has you covered for most tools, some tools need deep integration into the
compiler. Rustup knows exactly what version of the compiler you're using, and
so it's got just the information that these tools need.

Components are per-toolchain, so if you want them to be available to more
than one toolchain, you'll need to install them multiple times. In the
following examples, add a `--toolchain` flag, set to the toolchain you
want to install for, `nightly` for example. Without this flag, it will
install the component for the default toolchain.

To see the full list of components you can install:

```console
$ rustup component list
```

Next, let's talk about some popular components and when you might want to
install them.

### `rust-docs`, for local documentation

This first component is installed by default when you install a toolchain. It
contains a copy of Rust's documentation, so that you can read it offline.

This component cannot be removed for now; if that's of interest, please
comment on [this
issue](https://github.com/rust-lang/rustup.rs/issues/998).

### `rust-src` for a copy of Rust's source code

The `rust-src` component can give you a local copy of Rust's source code. Why
might you need this? Well, autocompletion tools like Racer use this
information to know more about the functions you're trying to call.

```console
$ rustup component add rust-src
```

### `rustfmt` for automatic code formatting

![Minimum Rust version: 1.24](https://img.shields.io/badge/Minimum%20Rust%20Version-1.24-brightgreen.svg)

If you'd like to have your code automatically formatted, you can
install this component:

```console
$ rustup component add rustfmt
```

This will install two tools, `rustfmt` and `cargo-fmt`, that will reformat your
code for you! For example:

```console
$ cargo fmt
```

will reformat your entire Cargo project.

### `rls` for IDE integration

![Minimum Rust version: 1.21](https://img.shields.io/badge/Minimum%20Rust%20Version-1.21-brightgreen.svg)

Many IDE features are built off of the [`langserver`
protocol](http://langserver.org/). To gain support for Rust with these IDEs,
you'll need to install the Rust language sever, aka the "RLS":

```console
$ rustup component add rls
```

For more information about integrating this into your IDE, see the [RLS
documentation](https://github.com/rust-lang/rls).

### `clippy` for more lints

For even more lints to help you write Rust code, you can install `clippy`:

```console
$ rustup component add clippy
```

This will install `cargo-clippy` for you:

```console
$ cargo clippy
```

For more, check out [clippy's
documentation](https://github.com/rust-lang/rust-clippy).

### The "preview" components

There are several components in a "preview" stage. These components currently
have `-preview` in their name, and this indicates that they're not quite 100%
ready for general consumption yet. Please try them out and give us feedback,
but know that they do not follow Rust's stability guarantees, and are still
actively changing, possibly in backwards-incompatible ways.

#### `llvm-tools-preview` for using extra LLVM tools

If you'd like to use the `lld` linker, or other tools like `llvm-objdump` or
`llvm-objcopy`, you can install this component:

```console
$ rustup component add llvm-tools-preview
```

This is the newest component, and so doesn't have good documentation at the
moment.
Commit	Line	Data
450edc1f XL	1	# Rustup for managing Rust versions
	2
	3	![Minimum Rust version: various](https://img.shields.io/badge/Minimum%20Rust%20Version-various-brightgreen.svg) (this tool has its own versioning scheme and works with all Rust versions)
	4
	5	The [Rustup](https://rustup.rs/) tool has become the recommended way to
	6	install Rust, and is advertised on our website. Its powers go further than
	7	that though, allowing you to manage various versions, components, and
	8	platforms.
	9
	10	## For installing Rust
	11
	12	To install Rust through Rustup, you can go to
	13	<https://www.rust-lang.org/install.html>, which will let you know how to do
	14	so on your platform. This will install both `rustup` itself and the `stable`
	15	version of `rustc` and `cargo`.
	16
	17	To install a specific Rust version, you can use `rustup install`:
	18
	19	```console
	20	$ rustup install 1.30.0
	21	```
	22
	23	This works for a specific nightly, as well:
	24
	25	```console
	26	$ rustup install nightly-2018-08-01
	27	```
	28
	29	As well as any of our release channels:
	30
	31	```console
	32	$ rustup install stable
	33	$ rustup install beta
	34	$ rustup install nightly
	35	```
	36
	37	## For updating your installation
	38
	39	To update all of the various channels you may have installed:
	40
	41	```console
	42	$ rustup update
	43	```
	44
	45	This will look at everything you've installed, and if there are new releases,
	46	will update anything that has one.
	47
	48	## Managing versions
	49
	50	To set the default toolchain to something other than `stable`:
	51
	52	```console
48663c56	53	$ rustup default nightly
450edc1f XL	54	```
	55
	56	To use a toolchain other than the default, use `rustup run`:
	57
	58	```console
	59	$ rustup run nightly cargo build
	60	```
	61
	62	There's also an alias for this that's a little shorter:
	63
	64	```console
	65	$ cargo +nightly build
	66	```
	67
	68	If you'd like to have a different default per-directory, that's easy too!
	69	If you run this inside of a project:
	70
	71	```console
	72	$ rustup override set nightly
	73	```
	74
532ac7d7 XL	75	Or, if you'd like to target a different version of Rust:
	76	```console
	77	$ rustup override set 1.30.0
	78	```
	79
450edc1f XL	80	Then when you're in that directory, any invocations of `rustc` or `cargo`
	81	will use that toolchain. To share this with others, you can create a
	82	`rust-toolchain` file with the contents of a toolchain, and check it into
	83	source control. Now, when someone clones your project, they'll get the
	84	right version without needing to `override set` themselves.
	85
	86	## Installing other targets
	87
	88	Rust supports cross-compiling to other targets, and Rustup can help you
	89	manage them. For example, to use MUSL:
	90
	91	```console
	92	$ rustup target add x86_64-unknown-linux-musl
	93	```
	94
	95	And then you can
	96
	97	```console
	98	$ cargo build --target=x86_64-unknown-linux-musl
	99	```
	100
	101	To see the full list of targets you can install:
	102
	103	```console
	104	$ rustup target list
	105	```
	106
	107	## Installing components
	108
	109	Components are used to install certain kinds of tools. While `cargo-install`
	110	has you covered for most tools, some tools need deep integration into the
	111	compiler. Rustup knows exactly what version of the compiler you're using, and
	112	so it's got just the information that these tools need.
	113
	114	Components are per-toolchain, so if you want them to be available to more
	115	than one toolchain, you'll need to install them multiple times. In the
	116	following examples, add a `--toolchain` flag, set to the toolchain you
	117	want to install for, `nightly` for example. Without this flag, it will
	118	install the component for the default toolchain.
	119
	120	To see the full list of components you can install:
	121
	122	```console
	123	$ rustup component list
	124	```
	125
	126	Next, let's talk about some popular components and when you might want to
	127	install them.
	128
	129	### `rust-docs`, for local documentation
	130
	131	This first component is installed by default when you install a toolchain. It
	132	contains a copy of Rust's documentation, so that you can read it offline.
	133
	134	This component cannot be removed for now; if that's of interest, please
	135	comment on [this
60c5eb7d	136	issue](https://github.com/rust-lang/rustup.rs/issues/998).
450edc1f XL	137
	138	### `rust-src` for a copy of Rust's source code
	139
	140	The `rust-src` component can give you a local copy of Rust's source code. Why
	141	might you need this? Well, autocompletion tools like Racer use this
	142	information to know more about the functions you're trying to call.
	143
	144	```console
	145	$ rustup component add rust-src
	146	```
	147
416331ca	148	### `rustfmt` for automatic code formatting
450edc1f XL	149
	150	![Minimum Rust version: 1.24](https://img.shields.io/badge/Minimum%20Rust%20Version-1.24-brightgreen.svg)
	151
	152	If you'd like to have your code automatically formatted, you can
	153	install this component:
	154
	155	```console
416331ca	156	$ rustup component add rustfmt
450edc1f XL	157	```
	158
	159	This will install two tools, `rustfmt` and `cargo-fmt`, that will reformat your
	160	code for you! For example:
	161
	162	```console
	163	$ cargo fmt
	164	```
	165
	166	will reformat your entire Cargo project.
	167
416331ca	168	### `rls` for IDE integration
450edc1f XL	169
	170	![Minimum Rust version: 1.21](https://img.shields.io/badge/Minimum%20Rust%20Version-1.21-brightgreen.svg)
	171
	172	Many IDE features are built off of the [`langserver`
	173	protocol](http://langserver.org/). To gain support for Rust with these IDEs,
	174	you'll need to install the Rust language sever, aka the "RLS":
	175
	176	```console
416331ca	177	$ rustup component add rls
450edc1f XL	178	```
450edc1f XL	179
416331ca XL	180	For more information about integrating this into your IDE, see the [RLS
416331ca XL	181	documentation](https://github.com/rust-lang/rls).
450edc1f	182
416331ca	183	### `clippy` for more lints
450edc1f XL	184
	185	For even more lints to help you write Rust code, you can install `clippy`:
	186
	187	```console
416331ca	188	$ rustup component add clippy
450edc1f XL	189	```
	190
	191	This will install `cargo-clippy` for you:
	192
	193	```console
	194	$ cargo clippy
	195	```
	196
	197	For more, check out [clippy's
416331ca XL	198	documentation](https://github.com/rust-lang/rust-clippy).
	199
	200	### The "preview" components
	201
	202	There are several components in a "preview" stage. These components currently
	203	have `-preview` in their name, and this indicates that they're not quite 100%
	204	ready for general consumption yet. Please try them out and give us feedback,
	205	but know that they do not follow Rust's stability guarantees, and are still
	206	actively changing, possibly in backwards-incompatible ways.
450edc1f XL	207
	208	#### `llvm-tools-preview` for using extra LLVM tools
	209
	210	If you'd like to use the `lld` linker, or other tools like `llvm-objdump` or
	211	`llvm-objcopy`, you can install this component:
	212
	213	```console
	214	$ rustup component add llvm-tools-preview
	215	```
	216
	217	This is the newest component, and so doesn't have good documentation at the
532ac7d7	218	moment.