170 lines
7.3 KiB
Markdown
170 lines
7.3 KiB
Markdown
# `rust-toolchain` Action
|
|
|
|
[](https://actions-rs.github.io/#sponsoring)
|
|
|
|
[](https://gitter.im/actions-rs/community)
|
|
|
|
|
|
|
|
This GitHub Action installs [Rust toolchain](https://rust-lang.github.io/rustup/concepts/toolchains.html#toolchain-specification)
|
|
with [rustup](https://github.com/rust-lang/rustup) help.
|
|
|
|
It supports additional targets, components and profiles and handles all
|
|
these small papercuts for you.
|
|
|
|
**Table of Contents**
|
|
|
|
* [Example workflow](#example-workflow)
|
|
* [Inputs](#inputs)
|
|
* [Outputs](#outputs)
|
|
* [Profiles](#profiles)
|
|
* [Components](#components)
|
|
* [The toolchain file](#the-toolchain-file)
|
|
* [License](#license)
|
|
* [Contribute and support](#contribute-and-support)
|
|
|
|
## Example workflow
|
|
|
|
```yaml
|
|
on: [push]
|
|
|
|
name: build
|
|
|
|
jobs:
|
|
check:
|
|
name: Rust project
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v2
|
|
- name: Install latest nightly
|
|
uses: actions-rs/toolchain@v1
|
|
with:
|
|
toolchain: nightly
|
|
override: true
|
|
components: rustfmt, clippy
|
|
|
|
# `cargo check` command here will use installed `nightly`
|
|
# as it is set as an "override" for current directory
|
|
|
|
- name: Run cargo check
|
|
uses: actions-rs/cargo@v1
|
|
with:
|
|
command: check
|
|
```
|
|
|
|
See [additional recipes here](https://github.com/actions-rs/meta).
|
|
|
|
## Inputs
|
|
|
|
| Name | Required | Description | Type | Default |
|
|
| ------------ | :------: | ----------------------------------------------------------------------------------------------------------------------------------------------------| ------ | --------|
|
|
| `toolchain` | | [Toolchain](https://github.com/rust-lang/rustup.rs#toolchain-specification) name to use, ex. `stable`, `nightly`, `nightly-2019-04-20`, or `1.32.0` | string | stable |
|
|
| `targets` | | Comma-separated list of additional targets to install for this toolchain, ex. `x86_64-apple-darwin` | string | |
|
|
| `default` | | Set installed toolchain as a default toolchain | bool | false |
|
|
| `override` | | Set installed toolchain as an override for the current directory | bool | false |
|
|
| `profile` | | Execute `rustup set profile {value}` before installing the toolchain, ex. `minimal` | string | default |
|
|
| `components` | | Comma-separated list of the additional components to install, ex. `clippy, rustfmt` | string | |
|
|
|
|
Note: since `v1.0.4` version, `toolchain` input is not marked as required
|
|
in order to support toolchain files. See the details [below](#the-toolchain-file).
|
|
|
|
## Outputs
|
|
|
|
Installed `rustc`, `cargo` and `rustup` versions can be fetched from the Action outputs:
|
|
|
|
| Name | Description | Example |
|
|
| ------------ | --------------------- | ------------------------------- |
|
|
| `rustc` | Rustc version | `1.40.0 (73528e339 2019-12-16)` |
|
|
| `rustc_hash` | Rustc version hash | `73528e339` |
|
|
| `cargo` | Cargo version | `1.40.0 (bc8e4c8be 2019-11-22)` |
|
|
| `rustup` | rustup version | `1.21.1 (7832b2ebe 2019-12-20)` |
|
|
|
|
Note: `rustc_hash` output value can be used with [actions/cache](https://github.com/actions/cache) Action
|
|
to store cache for different Rust versions, as it is unique across different Rust versions and builds (including `nightly`).
|
|
|
|
## Profiles
|
|
|
|
This Action supports rustup [profiles](https://blog.rust-lang.org/2019/10/15/Rustup-1.20.0.html#profiles),
|
|
which are can be used to speed up the workflow execution by installing the
|
|
minimally required set of components, for example:
|
|
|
|
```yaml
|
|
- name: Install minimal nightly
|
|
uses: actions-rs/toolchain@v1
|
|
with:
|
|
profile: minimal
|
|
toolchain: nightly
|
|
```
|
|
|
|
This Action will automatically run `rustup self update` if `profile` input is set
|
|
and the installed `rustup` version does not supports them.
|
|
|
|
In order to provide backwards compatibility for `v1` version,
|
|
there is no value for `profile` input set by default,
|
|
which means that the `default` profile is used by `rustup`
|
|
(and that includes `rust-docs`, `clippy` and `rustfmt`).\
|
|
You may want to consider using `profile: minimal` to speed up toolchain installation.
|
|
|
|
## Components
|
|
|
|
This Action supports rustup [components](https://blog.rust-lang.org/2019/10/15/Rustup-1.20.0.html#installing-the-latest-compatible-nightly) too,
|
|
and in combination with the [profiles](#profiles) input it allows to install only the needed components:
|
|
|
|
```yaml
|
|
- name: Install minimal stable with clippy and rustfmt
|
|
uses: actions-rs/toolchain@v1
|
|
with:
|
|
profile: minimal
|
|
toolchain: stable
|
|
components: rustfmt, clippy
|
|
```
|
|
|
|
As an extra perk, `rustup >= 1.20.0` is able to find the most recent `nightly` toolchain
|
|
with the requested components available; next example is utilizing this feature
|
|
to install the minimal set of `nightly` toolchain components with the `rustfmt` and `clippy` extras:
|
|
|
|
```yaml
|
|
- name: Install minimal nightly with clippy and rustfmt
|
|
uses: actions-rs/toolchain@v1
|
|
with:
|
|
profile: minimal
|
|
toolchain: nightly
|
|
components: rustfmt, clippy
|
|
```
|
|
|
|
In case if `nightly` toolchain is requested and one of the components is missing in
|
|
latest `nightly` release, this Action will attempt the downgrade till it find
|
|
the most recent `nightly` with all components needed.\
|
|
Note that this behavior will work only if the following two conditions apply:
|
|
|
|
1. `toolchain` input is `nightly` exactly.
|
|
2. At least one component is provided in `components` input.
|
|
|
|
Same to the `profile` input, if installed `rustup` does not supports "components",
|
|
it will be automatically upgraded by this Action.
|
|
|
|
## The toolchain file
|
|
|
|
This Action supports [toolchain files](https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file),
|
|
so it is not necessary to use `toolchain` input anymore.
|
|
|
|
Input has higher priority, so if you are want to use toolchain file,
|
|
you need to remove the input from the workflow file.
|
|
|
|
If neither `toolchain` input or `rust-toolchain` file are provided,
|
|
Action execution will fail.
|
|
|
|
## License
|
|
|
|
This Action is distributed under the terms of the MIT license, see [LICENSE](https://github.com/actions-rs/toolchain/blob/master/LICENSE) for details.
|
|
|
|
## Contribute and support
|
|
|
|
Any contributions are welcomed!
|
|
|
|
If you want to report a bug or have a feature request,
|
|
check the [Contributing guide](https://github.com/actions-rs/.github/blob/master/CONTRIBUTING.md).
|
|
|
|
You can also support author by funding the ongoing project work,
|
|
see [Sponsoring](https://actions-rs.github.io/#sponsoring).
|