setup-cross-toolchain-action

GitHub Action for setup toolchains for cross compilation and cross testing for Rust.

• Usage
  • Inputs
  • Example workflow: Basic usage
  • Example workflow: Multiple targets
  • Example workflow: Doctest
  • Example workflow: Tier 3 targets
• Platform Support
  • Linux (GNU)
  • Linux (musl)
  • Linux (uClibc)
  • Android
  • FreeBSD
  • NetBSD
  • illumos
  • WASI
  • Windows (MinGW)
  • Windows (LLVM MinGW)
  • Windows (MSVC)
  • macOS
  • Mac Catalyst
• Security
• Compatibility
• Related Projects
• License

Usage

Inputs

[1]: This is currently only supported for some Linux (GNU) targets on Ubuntu/Debian hosts, and packages will be installed using the form: <sudo as needed> apt-get install --no-install-recommends <each package>:<target's dpkg arch>...

Example workflow: Basic usage

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Install Rust
        run: rustup update stable
      - name: Install cross-compilation tools
        uses: taiki-e/setup-cross-toolchain-action@v1
        with:
          target: aarch64-unknown-linux-gnu
      # setup-cross-toolchain-action sets the `CARGO_BUILD_TARGET` environment variable,
      # so there is no need for an explicit `--target` flag.
      - run: cargo test --verbose
      # `cargo run` also works.
      - run: cargo run --verbose
      # You can also run the cross-compiled binaries directly (via binfmt).
      - run: ./target/aarch64-unknown-linux-gnu/debug/my-app

Example workflow: Multiple targets

jobs:
  test:
    strategy:
      matrix:
        target:
          - aarch64-unknown-linux-gnu
          - riscv64gc-unknown-linux-gnu
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Install Rust
        run: rustup update stable
      - name: Install cross-compilation tools
        uses: taiki-e/setup-cross-toolchain-action@v1
        with:
          target: ${{ matrix.target }}
      - run: cargo test --verbose

Example workflow: Doctest

Since Rust 1.89, doctest is cross-tested by default.

jobs:
  test:
    strategy:
      matrix:
        rust:
          - stable
          - nightly
        target:
          - aarch64-unknown-linux-gnu
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Install Rust
        run: rustup update ${{ matrix.rust }} && rustup default ${{ matrix.rust }}
      - name: Install cross-compilation tools
        uses: taiki-e/setup-cross-toolchain-action@v1
        with:
          target: ${{ matrix.target }}
      # On old nightly and `-Z doctest-xcompile` is available,
      # `$DOCTEST_XCOMPILE` is `-Zdoctest-xcompile`.
      #
      # On stable, and nightly since Rust 1.89, `$DOCTEST_XCOMPILE` is not set.
      - run: cargo test --verbose $DOCTEST_XCOMPILE

Example workflow: Tier 3 targets

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Install Rust
        run: rustup update nightly && rustup default nightly
      - name: Install cross-compilation tools
        uses: taiki-e/setup-cross-toolchain-action@v1
        with:
          target: aarch64_be-unknown-linux-gnu
      - run: cargo test --verbose -Z build-std

Cross-compilation of tier 3 targets currently requires nightly to build std. If you want to use tier 1/2 and tier 3 in the same matrix, you can use the BUILD_STD environment variable set by this action to use -Z build-std only for tier 3 targets.

jobs:
  test:
    strategy:
      matrix:
        target:
          - aarch64-unknown-linux-gnu
          - aarch64_be-unknown-linux-gnu
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Install Rust
        run: rustup update nightly && rustup default nightly
      - name: Install cross-compilation tools
        uses: taiki-e/setup-cross-toolchain-action@v1
        with:
          target: ${{ matrix.target }}
      # If target is tier 3, `$BUILD_STD` is `-Zbuild-std`.
      # Otherwise, `$BUILD_STD` is not set.
      #
      # Once `Z build-std` is stabilized, the corresponding flag
      # will be set to `$BUILD_STD` (if it is available).
      - run: cargo test --verbose $BUILD_STD

Platform Support

Linux (GNU)

[1] Except for loongarch64-unknown-linux-gnu

Supported targets:

[1] GCC 7, glibc 2.27 for Ubuntu 18.04. GCC 9, glibc 2.31 for Ubuntu 20.04. GCC 11, glibc 2.35 for Ubuntu 22.04. GCC 13, glibc 2.39 for Ubuntu 24.04. GCC 8, glibc 2.28 for Debian 10. GCC 10, glibc 2.31 for Debian 11. GCC 12, glibc 2.36 for Debian 12, GCC 14, glibc 2.41 for Debian 13.
[2] GCC 14, glibc 2.40
[3] GCC 7, glibc 2.25
[4] GCC 14, glibc 2.40
[5] GCC 11, glibc 2.33
[6] Since nightly-2023-07-05, mips{,el}-unknown-linux-gnu requires release mode for building std.
[7] Not fully supported with containers.

qemu-user runner

The current default QEMU version is 11.0.

We usually set QEMU CPU to max (or CPU newer than the default if -cpu=max is unavailable) to allow testing more CPU features. If you want to test for a specific CPU, you can override it by setting the QEMU_CPU environment variable.

You can select/pin the version by using qemu input option, or @ syntax in runner input option (if both are set, the latter is preferred). For example:

- uses: taiki-e/setup-cross-toolchain-action@v1
  with:
    target: aarch64-unknown-linux-gnu
    qemu: '7.2'

- uses: taiki-e/setup-cross-toolchain-action@v1
  with:
    target: aarch64-unknown-linux-gnu
    runner: qemu@8.1

valgrind runner

Note: binfmt does not work with this runner.

The current default Valgrind version is 3.26.0.

The current default arguments passed to Valgrind is -v --error-exitcode=1 --error-limit=no --leak-check=full --track-origins=yes --fair-sched=yes --gen-suppressions=all. You can override it by setting the CARGO_TARGET_<target name in upper underscore format>_RUNNER environment variable.

See "test-valgrind" job in our CI config for basic usage with x86_64/i686/aarch64/armv7hf. See "valgrind-cross" job in atomic-maybe-uninit's CI config for how to run tests with valgrind on powerpc64le/s390x/riscv64.

Linux (musl)

[1] 1.2 on Rust 1.71+, otherwise 1.1. 1.1 toolchain is with a patch that fixes CVE-2020-28928.

Supported targets:

(Other linux-musl targets supported by rust-cross-toolchain may also work, although this action's CI has not tested them.)

For the qemu-user runner, see "qemu-user runner" section for linux-gnu targets.

Linux (uClibc)

Supported targets:

[1] mips{,el}-unknown-linux-uclibc requires release mode for building std.

For the qemu-user runner, see "qemu-user runner" section for linux-gnu targets.

Android

Note: By making use of these targets you accept the Android SDK License

Supported targets:

[1] This action currently uses the API level 24 system image, so cargo test and cargo run may not work on API level 26+.
[2] 21 on Rust 1.82+, otherwise 19.

(Other android targets supported by rust-cross-toolchain may also work, although this action's CI has not tested them.)

You can select/pin the API level version by using @ syntax in target option. For example:

- uses: taiki-e/setup-cross-toolchain-action@v1
  with:
    target: arm-linux-androideabi@21

For the qemu-user runner, see "qemu-user runner" section for linux-gnu targets.

FreeBSD

Supported targets:

[1] Clang 13 for Ubuntu 18.04, otherwise Clang 15.

(Other FreeBSD targets supported by rust-cross-toolchain may also work, although this action's CI has not tested them.)

You can select/pin the OS version by using @ syntax in target option. For example:

- uses: taiki-e/setup-cross-toolchain-action@v1
  with:
    target: x86_64-unknown-freebsd@14

Only specifying a major version is supported.

NetBSD

Supported targets:

[1] 9 on Rust 1.67+, otherwise 8.

(Other NetBSD targets supported by rust-cross-toolchain may also work, although this action's CI has not tested them.)

You can select/pin the OS version by using @ syntax in target option. For example:

- uses: taiki-e/setup-cross-toolchain-action@v1
  with:
    target: x86_64-unknown-netbsd@10

Only specifying a major version is supported.

illumos

Supported targets:

WASI

Supported targets:

Windows (MinGW)

Supported targets:

[1] GCC 10, MinGW-w64 8 for Ubuntu 22.04. GCC 13, MinGW-w64 11 for Ubuntu 24.04. GCC 10, MinGW-w64 8 for Debian 11. GCC 12, MinGW-w64 10 for Debian 12.

On Windows host, GitHub-provided Windows runners support cross-compile for other architectures or environments, so this action just runs rustup target add and/or sets some environment variables.

(Other Windows targets may also work, although this action's CI has not tested them.)

On Linux host, this action installs MinGW toolchain and Wine.

wine runner

The current default Wine version is 10.0.

You can select/pin the version by using wine input option, or @ syntax in runner input option (if both are set, the latter is preferred). For example:

- uses: taiki-e/setup-cross-toolchain-action@v1
  with:
    target: x86_64-pc-windows-gnu
    wine: '9.22'

- uses: taiki-e/setup-cross-toolchain-action@v1
  with:
    target: x86_64-pc-windows-gnu
    runner: wine@9.22

Windows (LLVM MinGW)

Supported targets:

For the wine runner for {i686,x86_64}-pc-windows-gnullvm, see "wine runner" section for windows-gnu targets.

The wine runner for aarch64-pc-windows-gnullvm is AArch64 Wine running on qemu-user; specifying the Wine version is not yet supported, but the QEMU version can be specified by using qemu input option like Linux targets.

Windows (MSVC)

[1] For x86/x86_64 targets all runners and for aarch64 targets only arm64 runners.

Supported targets:

GitHub-provided Windows runners support cross-compile for other architectures or environments, so this action just runs rustup target add and/or sets some environment variables.

(Other Windows targets may also work, although this action's CI has not tested them.)

macOS

[1] For x86_64-apple-darwin all runners and for aarch64-apple-darwin only arm64 runners. (x86_64h-apple-darwin is also x86_64 but build-only because the CPU of GitHub-provided macOS runners is older than Haswell. If you use a large runner or self-hosted runner, you may be able to run the test.)

Supported targets:

GitHub-provided macOS runners support cross-compile for other architectures or environments, so this action just runs rustup target add and/or sets some environment variables.

(Other macOS targets may also work, although this action's CI has not tested them.)

Mac Catalyst

[1] For x86_64-apple-ios-macabi only x86_64 runners and for aarch64-apple-ios-macabi only arm64 runners.

Supported targets:

GitHub-provided macOS runners support cross-compile for other targets, so this action just runs rustup target add and/or sets some environment variables.

Security

The @v<major> tags are updated with each release. If you want to enhance workflow stability and security against supply chain attacks, consider using the @v<major>.<minor>.<patch> tag or their hash to pin the version and regularly updating with dependency cooldown. Since all releases are immutable, pinning the version in either way should have the same effect.

Compatibility

This action has been tested for GitHub-hosted runners (Ubuntu, macOS, Windows) and containers (Ubuntu, Debian).

To use this action in self-hosted runners or in containers, at least the following tools are required:

• bash
• rustup, cargo

Currently, when using this action with containers, --privileged option is required (due to binfmt).

container:
  image: '...'
  options: --privileged

Note that what this action installs for its setup (such as above tools) is considered an implementation detail if they are installed by this action's side, and there is no guarantee that they will be available in subsequent steps, because this action is not an action for installing those tools.

Related Projects

• rust-cross-toolchain: Toolchains for cross compilation and cross testing for Rust.
• install-action: GitHub Action for installing development tools (mainly from GitHub Releases).
• cache-cargo-install-action: GitHub Action for cargo install with cache.
• create-gh-release-action: GitHub Action for creating GitHub Releases based on changelog.
• upload-rust-binary-action: GitHub Action for building and uploading Rust binary to GitHub Releases.
• checkout-action: GitHub Action for checking out a repository. (Simplified actions/checkout alternative that does not depend on Node.js.)

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

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 above, without any additional terms or conditions.