### Example Workflow for Rust Toolchain Installation

Source: https://github.com/dtolnay/rust-toolchain/blob/master/README.md

This is a standard GitHub Actions workflow demonstrating how to use the rust-toolchain action to set up Rust for a project. It checks out the code, installs the toolchain, and runs tests.

```yaml
name: test suite
on: [push, pull_request]

jobs:
  test:
    name: cargo test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: dtolnay/rust-toolchain@stable
      - run: cargo test --all-features
```

--------------------------------

### Installing Rustup on Windows

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/implementation-details.md

Downloads and executes the rustup installer for Windows, specifying architecture and non-interactive installation.

```bash
# Determine architecture: runner.arch == 'ARM64' -> aarch64, else x86_64
# Download https://win.rustup.rs/<ARCH> to temp directory
# Execute installer with flags: --default-toolchain none --no-modify-path -y
```

--------------------------------

### Data Flow of Rust Toolchain Installation

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/overview.md

Illustrates the step-by-step process from GitHub Actions input to output for installing a Rust toolchain. It shows how inputs are parsed, rustup is installed, the toolchain is configured, and cache keys are generated.

```text
GitHub Actions Input (toolchain, targets, components)
    ↓
Step: parse (toolchain version resolution via regex and date math)
    ↓
Step: flags (construct rustup command-line arguments)
    ↓
Step: install rustup (if not present on runner)
    ↓
Step: rustup toolchain install (install the Rust toolchain)
    ↓
Step: rustup default (set as default toolchain)
    ↓
Step: rustc-version (extract commit date/hash for cache key)
    ↓
GitHub Actions Output (cachekey, name)
```

--------------------------------

### Downloading and Executing Rustup Installer (Unix)

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/implementation-details.md

Downloads and executes the rustup installer script for Unix-like systems, with specific flags for non-interactive installation and toolchain management.

```bash
curl ... https://sh.rustup.rs | sh -s -- --default-toolchain none -y
```

--------------------------------

### Debugging Toolchain Installation with Diagnostics

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/errors.md

This example collects diagnostic information when the toolchain installation might have failed or to provide general debugging data. It checks the toolchain outcome, versions of `rustc` and `cargo`, and the `CARGO_HOME` directory.

```yaml
- uses: dtolnay/rust-toolchain@stable
  id: toolchain
  continue-on-error: true

- name: Diagnostic information
  if: always()
  run: |
    echo "Toolchain outcome: ${{ steps.toolchain.outcome }}"
    rustc --version --verbose || echo "rustc not found"
    cargo --version || echo "cargo not found"
    echo "CARGO_HOME: $CARGO_HOME"
    ls -la "$CARGO_HOME" || echo "CARGO_HOME not accessible"
```

--------------------------------

### Install Rustup (Windows)

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/api-reference.md

Downloads and executes the rustup installer on Windows runners if rustup is not already present. It determines the correct architecture and uses flags to skip default toolchain installation and manual PATH modification.

```powershell
$ARCH = if ($env:RUNNER_ARCH -eq 'ARM64') { 'aarch64' } else { 'x86_64' };
$RUSTUP_INIT = "$env:TEMP\rustup-init.exe";
if (!(Test-Path $RUSTUP_INIT)) {
  Invoke-WebRequest -Uri "https://win.rustup.rs/$ARCH" -OutFile $RUSTUP_INIT;
  & $RUSTUP_INIT -y --default-toolchain none --no-modify-path;
  echo "$CARGO_HOME\bin" | Out-String | Add-Content -Path $env:GITHUB_PATH;
}
```

--------------------------------

### Target Triple Examples

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/types.md

Lists common examples of LLVM target triples following rustup naming conventions.

```text
wasm32-unknown-unknown
aarch64-unknown-linux-gnu
x86_64-pc-windows-gnu
arm-unknown-linux-gnueabihf
aarch64-apple-darwin
x86_64-unknown-linux-musl
```

--------------------------------

### Toolchain Specification Examples

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/types.md

Provides examples of valid toolchain specification strings.

```text
"stable"
```

```text
"1.89.0"
```

```text
"nightly-2025-01-01"
```

```text
"stable 18 months ago"
```

```text
"stable minus 8 releases"
```

--------------------------------

### Log Installed Toolchain Name

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/action-outputs.md

Demonstrates how to log the requested and installed toolchain names, useful for debugging and verification.

```yaml
- uses: dtolnay/rust-toolchain@master
  id: toolchain
  with:
    toolchain: ${{ inputs.rust_version }}

- name: Log toolchain
  run: |
    echo "Requested: ${{ inputs.rust_version }}"
    echo "Installed: ${{ steps.toolchain.outputs.name }}"
    cargo +${{ steps.toolchain.outputs.name }} --version
```

--------------------------------

### Conditional Component Installation

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/errors.md

This snippet shows how to conditionally install components like `rustfmt` and `clippy`. It uses `continue-on-error: true` because component installation might fail on older toolchains, and then proceeds to run checks that utilize these components.

```yaml
- uses: dtolnay/rust-toolchain@stable
  with:
    # Components might fail on older toolchains
    components: rustfmt,clippy
  continue-on-error: true

- run: cargo fmt --check || true
- run: cargo clippy || true
```

--------------------------------

### Install WebAssembly Targets

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/examples.md

Installs WebAssembly targets for browser and WASI environments. Use this when building for WebAssembly.

```yaml
- uses: dtolnay/rust-toolchain@stable
  with:
    targets: wasm32-unknown-unknown,wasm32-wasi

- run: cargo build --target wasm32-unknown-unknown
```

--------------------------------

### Install Linting and Formatting Components

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/examples.md

Installs the clippy linter and rustfmt formatter. Run `cargo fmt --check` and `cargo clippy` for code quality checks.

```yaml
- uses: dtolnay/rust-toolchain@stable
  with:
    components: clippy,rustfmt

- run: cargo fmt --check
- run: cargo clippy --all-targets --all-features
```

--------------------------------

### Install Additional Components

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/configuration.md

Use the 'components' input to specify additional components like 'clippy' or 'rustfmt', passed to 'rustup toolchain install --component <COMPONENT>'.

```yaml
- uses: dtolnay/rust-toolchain@stable
  with:
    components: clippy,rustfmt,rust-src
```

--------------------------------

### Component Name Input Example

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/types.md

Illustrates the format for a comma-separated list of component names.

```text
clippy,rustfmt,rust-src
```

--------------------------------

### Install Multiple Cross-Compilation Targets

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/examples.md

Installs multiple cross-compilation targets for ARM and Windows. Useful for building projects for different architectures.

```yaml
- uses: dtolnay/rust-toolchain@stable
  with:
    targets: |
      aarch64-unknown-linux-gnu
      arm-unknown-linux-gnueabihf
      x86_64-pc-windows-gnu

- run: cargo build --target aarch64-unknown-linux-gnu
```

--------------------------------

### Installing Rust Toolchain

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/implementation-details.md

Installs a specified Rust toolchain with minimal profile and without self-update. Includes a workaround for Windows file locking.

```bash
rustup toolchain install <TOOLCHAIN><TARGETS><COMPONENTS> \
  --profile minimal \
  <DOWNGRADE> \
  --no-self-update
```

--------------------------------

### Valid Component Example

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/errors.md

Shows how to correctly specify an available component like 'miri' for the nightly toolchain. This is a valid configuration.

```yaml
# Valid: miri is available in nightly
- uses: dtolnay/rust-toolchain@nightly
  with:
    components: miri
```

--------------------------------

### Install Latest and Specific Nightly Rust Toolchains

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/action-outputs.md

Demonstrates installing the latest nightly build versus a specific nightly build by date. These result in different cache keys.

```yaml
# These have different cache keys
- uses: dtolnay/rust-toolchain@nightly  # Latest, e.g., 20250627a831
- uses: dtolnay/rust-toolchain@nightly-2025-01-01  # Specific date: 20250101...
```

--------------------------------

### Install Additional Components and Targets

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/README.md

Install additional Rust components like clippy and rustfmt, and specify cross-compilation targets such as wasm32-unknown-unknown.

```yaml
- uses: dtolnay/rust-toolchain@stable
  with:
    components: clippy,rustfmt
    targets: wasm32-unknown-unknown
```

--------------------------------

### Toolchain Name Examples

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/types.md

Examples of valid Rust toolchain names, including channels, version numbers, and dated releases.

```text
stable
```

```text
beta
```

```text
nightly
```

```text
1.89.0
```

```text
1.70
```

```text
nightly-2025-01-01
```

--------------------------------

### Install Toolchain with Targets and Components

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/api-reference.md

Installs the resolved toolchain, including specified additional targets and components, using a minimal profile and disabling self-updates. It also sets an environment variable to work around potential Windows file locking issues.

```bash
export RUSTUP_PERMIT_COPY_RENAME=1
rustup toolchain install ${{ steps.parse.outputs.toolchain }}${{ steps.flags.outputs.targets }}${{ steps.flags.outputs.components }} --profile minimal${{ steps.flags.outputs.downgrade }} --no-self-update
```

--------------------------------

### Install Stable Toolchain by Time Offset

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/toolchain-expressions.md

Installs a stable release from a specified time in the past. Supports year, month, week, and day units. Relative to execution time.

```yaml
- uses: dtolnay/rust-toolchain@master
  with:
    toolchain: stable 18 months ago
  # Installs stable from 18 months prior to workflow execution
```

```yaml
- uses: dtolnay/rust-toolchain@master
  with:
    toolchain: stable 12 months ago
  # Tests against stable from 1 year ago (MSRV pattern)
```

--------------------------------

### Conditional Component Installation

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/examples.md

Installs components like clippy and rustfmt but continues the workflow even if they are unavailable. Useful for optional checks.

```yaml
- uses: dtolnay/rust-toolchain@nightly
  id: toolchain
  with:
    components: clippy,rustfmt
  continue-on-error: true

- run: cargo fmt --check || echo "Formatting check skipped"
- run: cargo clippy || echo "Linting skipped"
```

--------------------------------

### Install Latest Stable Rust Toolchain

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/examples.md

Installs the latest stable Rust toolchain and sets it as the default. Useful for general development and CI.

```yaml
name: Test Suite
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: dtolnay/rust-toolchain@stable

      - run: cargo test --all-features
```

--------------------------------

### Set Up Basic Rust Workflow

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/README.md

Use this snippet to set up a basic Rust development workflow in GitHub Actions. It installs the stable toolchain and runs a cargo build.

```yaml
- uses: dtolnay/rust-toolchain@stable
- run: cargo build
```

--------------------------------

### Install Exact Rust Version (1.89.0)

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/toolchain-expressions.md

Installs a specific, exact version of the Rust toolchain (e.g., 1.89.0). This is deterministic and useful for MSRV or reproducible builds.

```yaml
- uses: dtolnay/rust-toolchain@1.89.0
  # Installs Rust 1.89.0 exactly
```

--------------------------------

### Install Specific Rust Toolchain Version

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/examples.md

Installs an exact, pinned version of the Rust toolchain. Recommended for reproducible builds.

```yaml
- uses: dtolnay/rust-toolchain@1.89.0
```

--------------------------------

### Build on Windows ARM64

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/examples.md

Automatically detects ARM64 architecture and installs the appropriate toolchain for Windows builds.

```yaml
name: Windows ARM64 Build
on: [push]

jobs:
  build:
    runs-on: windows-11-arm
    steps:
      - uses: actions/checkout@v4

      - uses: dtolnay/rust-toolchain@stable

      - run: cargo build --release
```

--------------------------------

### Install Stable Toolchain by Release Offset

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/toolchain-expressions.md

Installs a stable release from a specified number of minor versions back from the current stable release. Supports pluralization of 'release'.

```yaml
- uses: dtolnay/rust-toolchain@master
  with:
    toolchain: stable minus 8 releases
  # Installs stable from 8 minor versions ago
  # If current is 1.89, installs 1.81
```

```yaml
- uses: dtolnay/rust-toolchain@master
  with:
    toolchain: stable minus 1 release
  # Installs previous minor version
```

--------------------------------

### Install Nightly Rust Toolchain with Components

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/examples.md

Installs the latest nightly Rust toolchain and includes optional components like 'miri' and 'rust-src'. Automatically handles downgrades if components are unavailable.

```yaml
- uses: dtolnay/rust-toolchain@nightly
  with:
    components: miri,rust-src
```

--------------------------------

### Citation Example for Documentation

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/README.md

Use this format when referencing this technical documentation in other projects or discussions.

```text
Rust Toolchain GitHub Action — Technical Reference Documentation
2025-07-03
Generated from official action.yml and source code
https://github.com/dtolnay/rust-toolchain
```

--------------------------------

### Test Rustup Download (Windows)

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/errors.md

Tests the download of the rustup installer executable for Windows using curl. Verifies the correct URL and output file.

```bash
# Test windows download
curl --proto '=https' --tlsv1.2 https://win.rustup.rs/x86_64 -o rustup-init.exe
```

--------------------------------

### Cache Key Examples

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/types.md

These are examples of valid cache keys, which are 12-character alphanumeric strings representing the commit date and rustc commit hash.

```text
20250627a831
```

```text
20220627a831
```

```text
20240101abc0
```

--------------------------------

### Target Triple Input Example

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/types.md

Shows the expected format for a comma-separated list of target triples.

```text
wasm32-unknown-unknown,aarch64-unknown-linux-gnu
```

--------------------------------

### Windows Architecture Mapping

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/types.md

Illustrates how to map runner architecture to a download architecture variable specifically for Windows. This ensures the correct installer is downloaded.

```python
if runner.arch == "ARM64":
  download_arch = "aarch64"
else:
  download_arch = "x86_64"
```

--------------------------------

### Install Miri for Undefined Behavior Detection

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/examples.md

Installs Miri on the nightly toolchain for detecting undefined behavior in tests. Use this for robust testing.

```yaml
- uses: dtolnay/rust-toolchain@nightly
  with:
    components: miri

- run: cargo +nightly miri test
```

--------------------------------

### Install Additional Compilation Targets

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/configuration.md

Use the 'targets' input to specify additional target triples for compilation, passed to 'rustup toolchain install --target <TARGET>'.

```yaml
- uses: dtolnay/rust-toolchain@stable
  with:
    targets: wasm32-unknown-unknown,aarch64-unknown-linux-gnu
```

--------------------------------

### Install Latest Beta Rust Channel

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/toolchain-expressions.md

Installs the latest beta release of the Rust toolchain. This is non-deterministic and tracks new beta releases.

```yaml
- uses: dtolnay/rust-toolchain@beta
  # Installs latest beta
```

--------------------------------

### Install Exact Rust Version via 'toolchain' input

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/toolchain-expressions.md

Installs a specific, exact version of the Rust toolchain using the 'toolchain' input. This is deterministic and useful for MSRV or reproducible builds.

```yaml
- uses: dtolnay/rust-toolchain@master
  with:
    toolchain: 1.70.0
  # Also installs exactly 1.70.0
```

--------------------------------

### Handle Missing Toolchain Input

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/errors.md

This example shows how to catch a failure when the 'toolchain' input is not provided and the action is used with '@master' without an explicit toolchain.

```yaml
# INCORRECT — toolchain not provided and @master has no default
- uses: dtolnay/rust-toolchain@master

# CORRECT — use @stable or provide explicit input
- uses: dtolnay/rust-toolchain@stable

# CORRECT — use @master with explicit toolchain
- uses: dtolnay/rust-toolchain@master
  with:
    toolchain: stable
```

```yaml
- uses: dtolnay/rust-toolchain@master
  id: toolchain
  with:
    toolchain: ${{ inputs.toolchain || 'stable' }}
  continue-on-error: true

- name: Check toolchain
  if: steps.toolchain.outcome == 'failure'
  run: |
    echo "Toolchain installation failed"
    exit 1
```

--------------------------------

### Install Latest Stable Rust Channel

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/toolchain-expressions.md

Installs the latest stable release of the Rust toolchain. This is non-deterministic as the version changes with new releases.

```yaml
- uses: dtolnay/rust-toolchain@stable
  # Installs latest stable
```

--------------------------------

### Input: toolchain

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/api-reference.md

Specifies the Rustup toolchain to install. This can be a stable, beta, or nightly release, a specific version, or a relative version.

```APIDOC
## Input: toolchain

### Description
Rustup toolchain specifier. See [Toolchain Specification Formats](#toolchain-specification-formats) for valid values and expression syntax.

### Type
string

### Required
false

### Default
Derived from `@rev` in the `uses:` statement

### Examples
- `stable`
- `beta`
- `nightly`
- `1.89.0`
- `nightly-2025-01-01`
- `stable 18 months ago`
- `stable minus 8 releases`
```

--------------------------------

### Input: components

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/api-reference.md

Specifies additional components to install for the selected toolchain, appended via `--component` flags. This is particularly useful with nightly toolchains to conditionally enable `--allow-downgrade`.

```APIDOC
## Input: components

### Description
Additional components to install for the selected toolchain. Components are appended to the rustup command via `--component` flags. Used with nightly toolchains to conditionally enable `--allow-downgrade`.

### Type
string (comma-separated)

### Required
false

### Default
None

### Examples
- `clippy`
- `rustfmt,rust-docs`
- `miri,rust-src`

### Special Behavior
When `components` is provided AND the selected toolchain is `nightly`, the `--allow-downgrade` flag is automatically added to prevent errors when components are unavailable on the nightly release.
```

--------------------------------

### Platform Detection Logic

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/types.md

Example of detecting the operating system using a case statement with the runner.os variable. This is useful for platform-specific actions.

```bash
case ${{runner.os}} in
  Linux) ;; 
  macOS) ;; 
  Windows) ;; 
esac
```

--------------------------------

### Test Rustup Download (Unix)

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/errors.md

Tests the download of the rustup installer script using curl with specific protocol and TLS version settings. Includes retry logic.

```bash
# Test rustup download on local machine
curl --proto '=https' --tlsv1.2 --retry 10 https://sh.rustup.rs | head -20
```

--------------------------------

### Invalid Component Example

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/errors.md

Demonstrates specifying a non-existent component in the rust-toolchain action. This will result in an error.

```yaml
# Invalid: component doesn't exist
- uses: dtolnay/rust-toolchain@stable
  with:
    components: nonexistent
```

--------------------------------

### Configure ARM64 macOS Targets

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/examples.md

Installs both native and Rosetta targets for universal binaries on ARM64 macOS.

```yaml
- uses: dtolnay/rust-toolchain@stable
  with:
    targets: aarch64-apple-darwin,x86_64-apple-darwin

- run: cargo build --target aarch64-apple-darwin
```

--------------------------------

### Install Stable Toolchain 18 Months Ago

Source: https://github.com/dtolnay/rust-toolchain/blob/master/README.md

Use this to install the most recent stable toolchain relative to a specific past date. Ensure the action revision is set to '@master' when using explicit 'toolchain' inputs.

```yaml
- uses: dtolnay/rust-toolchain@master
  with:
    toolchain: stable 18 months ago
```

--------------------------------

### Dated Nightly Toolchain Identifiers

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/action-outputs.md

Examples of how to specify a nightly toolchain for a particular date.

```text
nightly-2025-01-01
nightly-2024-12-31
```

--------------------------------

### Component Unavailable in Older Toolchain Example

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/errors.md

Illustrates an invalid configuration where a component ('miri') is requested from an older stable toolchain version ('1.50.0') where it is not available.

```yaml
# Invalid: miri not in older stable
- uses: dtolnay/rust-toolchain@1.50.0
  with:
    components: miri
```

--------------------------------

### Architecture String Values

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/types.md

Specifies valid string values for architecture types, such as x86_64 and aarch64. Used to determine correct installer downloads.

```text
arch = "x86_64" | "aarch64" | ...
```

--------------------------------

### Input: targets

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/api-reference.md

Defines additional compilation targets to install for the selected toolchain. These are appended to the rustup command using `--target` flags.

```APIDOC
## Input: targets

### Description
Additional compilation targets to install for the selected toolchain. Targets are appended to the rustup command via `--target` flags.

### Type
string (comma-separated)

### Required
false

### Default
None

### Examples
- `wasm32-unknown-unknown`
- `aarch64-unknown-linux-gnu,arm-unknown-linux-gnu`
- `x86_64-pc-windows-gnu`
```

--------------------------------

### Version Identifiers for Rust Toolchain

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/action-outputs.md

Examples of version identifiers for specifying Rust toolchains, including full semver and short forms.

```text
1.89.0      — Full semver
1.70        — Short form (expands to latest patch of minor)
```

--------------------------------

### Channel Names for Rust Toolchain

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/action-outputs.md

Examples of standard channel names used to identify Rust toolchains.

```text
stable
beta
nightly
```

--------------------------------

### Troubleshoot Empty Cache Key with Stable Toolchain

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/action-outputs.md

Shows how to check the 'cachekey' output and rustc version when encountering an empty or unusually formatted cache key. This helps diagnose installation or output capture issues.

```yaml
- uses: dtolnay/rust-toolchain@stable
  id: toolchain

- run: |
    echo "Cache key: '${{ steps.toolchain.outputs.cachekey }}'"
    rustc --version --verbose
```

--------------------------------

### Fallback Toolchain for Robustness

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/errors.md

This snippet demonstrates how to use a fallback toolchain if the primary one fails to install. It attempts to use the stable toolchain and, if that fails, tries to use a nightly toolchain.

```yaml
- uses: dtolnay/rust-toolchain@stable
  id: toolchain
  continue-on-error: true

- uses: dtolnay/rust-toolchain@nightly
  if: steps.toolchain.outcome == 'failure'
  id: toolchain_fallback

- run: cargo build
```

--------------------------------

### Set Default Toolchain

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/api-reference.md

Sets the newly installed toolchain as the default for the runner environment. This step is configured to continue on error to mitigate issues with toolchain switching.

```bash
rustup default ${{ steps.parse.outputs.toolchain }}
```

--------------------------------

### Specify Rust Toolchain by Channel Name

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/api-reference.md

Use the 'stable' channel to get the latest release. This is a common way to ensure you are using a well-tested version.

```yaml
- uses: dtolnay/rust-toolchain@stable
  with:
    toolchain: stable
```

--------------------------------

### Nightly Toolchain with Components and Auto-Downgrade

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/configuration.md

When installing a nightly toolchain with custom components, the action automatically adds '--allow-downgrade' to prevent errors if components are unavailable in a specific nightly build.

```yaml
# This automatically uses --allow-downgrade for nightly
- uses: dtolnay/rust-toolchain@nightly
  with:
    components: miri,rust-src
```

--------------------------------

### List Available Components

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/errors.md

Command to list all available components for the currently active toolchain. Useful for debugging component availability issues.

```bash
# List available components for current toolchain
rustup component list
```

--------------------------------

### Install Latest Nightly Rust Channel

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/toolchain-expressions.md

Installs the latest nightly release of the Rust toolchain. This is non-deterministic and tracks the most recent nightly build.

```yaml
- uses: dtolnay/rust-toolchain@nightly
  # Installs latest nightly
```

--------------------------------

### Install Specific Dated Nightly Rust Build

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/toolchain-expressions.md

Installs a specific nightly snapshot from a given date (e.g., nightly-2025-01-01). This is deterministic and useful for regression testing.

```yaml
- uses: dtolnay/rust-toolchain@master
  with:
    toolchain: nightly-2025-01-01
  # Installs nightly from January 1, 2025
```

--------------------------------

### Install Specific Stable Rust Toolchain

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/action-outputs.md

Installs a specific stable version of the Rust toolchain. The cache key will reflect the commit date of this older version.

```yaml
- uses: dtolnay/rust-toolchain@1.50.0
```

--------------------------------

### Test Multiple Toolchains using Matrix Strategy

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/action-outputs.md

Illustrates using a GitHub Actions matrix strategy to test a project against multiple Rust toolchains, logging both the matrix input and the resolved toolchain name.

```yaml
jobs:
  test:
    strategy:
      matrix:
        rust: [stable, beta, nightly, 1.70.0]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: dtolnay/rust-toolchain@master
        id: toolchain
        with:
          toolchain: ${{ matrix.rust }}

      - run: cargo +${{ steps.toolchain.outputs.name }} test

      - run: |
          echo "Matrix: ${{ matrix.rust }}"
          echo "Resolved: ${{ steps.toolchain.outputs.name }}"
```

--------------------------------

### Basic Rust CI Workflow

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/configuration.md

A minimal GitHub Actions workflow for testing Rust projects. It checks out code, sets up the stable Rust toolchain with clippy and rustfmt, caches the target directory, and runs tests.

```yaml
name: Rust Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: dtolnay/rust-toolchain@stable
        with:
          components: clippy,rustfmt

      - uses: actions/cache@v3
        with:
          path: target
          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}

      - run: cargo test --all-features
```

--------------------------------

### Install Latest Patch for a Minor Rust Version (1.70)

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/toolchain-expressions.md

Installs the latest patch release for a specified minor version (e.g., 1.70.x). The minor version is fixed, but the patch may change.

```yaml
- uses: dtolnay/rust-toolchain@master
  with:
    toolchain: 1.70
  # Installs 1.70.x (latest patch of 1.70)
```

--------------------------------

### Install Stable Toolchain Minus 8 Releases

Source: https://github.com/dtolnay/rust-toolchain/blob/master/README.md

This installs a stable toolchain that precedes the most recent one by a specified number of minor versions. Ensure the action revision is set to '@master' when using explicit 'toolchain' inputs.

```yaml
- uses: dtolnay/rust-toolchain@master
  with:
    toolchain: stable minus 8 releases
```

--------------------------------

### Robust Workflow Pattern for Toolchain Installation

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/errors.md

This pattern ensures that the workflow fails explicitly if the Rust toolchain installation encounters an error. It uses `continue-on-error: true` for the toolchain step and then checks the outcome to exit with an error message if it failed.

```yaml
- uses: dtolnay/rust-toolchain@stable
  id: toolchain
  continue-on-error: true

- name: Fail if toolchain installation failed
  if: steps.toolchain.outcome == 'failure'
  run: |
    echo "Failed to install Rust toolchain"
    exit 1

- run: cargo --version
```

--------------------------------

### WebAssembly Project Build and Test Workflow

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/examples.md

This workflow builds a WebAssembly project for wasm32-unknown-unknown, uploads the artifact, and then runs Node.js tests against a wasm32-wasi target. Ensure Node.js is set up correctly for testing.

```yaml
name: WASM Build

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: dtolnay/rust-toolchain@stable
        with:
          targets: wasm32-unknown-unknown

      - run: cargo build --target wasm32-unknown-unknown --release

      - uses: actions/upload-artifact@v3
        with:
          name: wasm-build
          path: target/wasm32-unknown-unknown/release/*.wasm

  test-node:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - uses: actions/checkout@v4

      - uses: dtolnay/rust-toolchain@stable
        with:
          targets: wasm32-wasi

      - uses: actions/setup-node@v3
        with:
          node-version: '18'

      - run: npm install
      - run: npm test

```

--------------------------------

### Configure Multi-Platform Matrix Strategy

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/README.md

Set up a matrix strategy for testing across multiple operating systems. This ensures your application functions correctly on Linux, macOS, and Windows.

```yaml
strategy:
  matrix:
    os: [ubuntu-latest, macos-latest, windows-latest]
```

--------------------------------

### List Components for Specific Toolchain

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/errors.md

Command to list available components for a particular toolchain version. Helps verify component support across different Rust versions.

```bash
# List available components for specific toolchain
rustup component list --toolchain 1.89.0
```

--------------------------------

### Run Cargo and Rustc with Explicit Toolchains

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/action-outputs.md

Shows how to use the 'name' output to manage and invoke different toolchains for Cargo and Rustc commands.

```yaml
- uses: dtolnay/rust-toolchain@1.70.0
  id: stable

- uses: dtolnay/rust-toolchain@nightly
  id: nightly

- run: cargo +${{ steps.stable.outputs.name }} build

- run: cargo +${{ steps.nightly.outputs.name }} test --all-features

- run: rustc +${{ steps.stable.outputs.name }} --version
```

--------------------------------

### Fallback Caching with cachekey

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/action-outputs.md

Illustrates fallback caching where first-time runs might miss the cache but can restore from previous toolchain versions using `restore-keys`.

```yaml
- uses: dtolnay/rust-toolchain@stable
  id: toolchain

- uses: actions/cache@v3
  with:
    path: target
    key: ${{ runner.os }}-cargo-${{ steps.toolchain.outputs.cachekey }}-${{ github.run_number }}
    restore-keys: |
      ${{ runner.os }}-cargo-${{ steps.toolchain.outputs.cachekey }}-
      ${{ runner.os }}-cargo-
```

--------------------------------

### Override Cargo Manifest Version

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/examples.md

Explicitly uses an installed toolchain with the `cargo +TOOLCHAIN` syntax, useful for specific version requirements.

```yaml
- uses: dtolnay/rust-toolchain@master
  id: toolchain
  with:
    toolchain: 1.70.0

- run: cargo +${{ steps.toolchain.outputs.name }} build
```

--------------------------------

### Conditional Compilation with Explicit Toolchain

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/action-outputs.md

Example of using the 'name' output to ensure a specific toolchain is used for building and running an application.

```yaml
- uses: dtolnay/rust-toolchain@stable
  id: toolchain

- run: |
    cargo +${{ steps.toolchain.outputs.name }} build --release
    ./target/release/myapp --version
```

--------------------------------

### Single Toolchain Caching with cachekey

Source: https://github.com/dtolnay/rust-toolchain/blob/master/_autodocs/action-outputs.md

Demonstrates how to use the `cachekey` output with `actions/cache` for single toolchain caching. A cache miss occurs when the `cachekey` changes, allowing independent caches per toolchain version.

```yaml
- uses: dtolnay/rust-toolchain@stable
  id: toolchain

- uses: actions/cache@v3
  with:
    path: target
    key: ${{ runner.os }}-cargo-${{ steps.toolchain.outputs.cachekey }}
```