setup-gcc-toolchain

A GitHub Action that downloads, verifies, and adds a GCC cross-compilation toolchain to PATH. Covers ARM, AArch64, RISC-V, Xtensa (ESP32), AVR, MinGW-w64, and native x86_64, on both Linux and Windows runners — see the support matrix below for exact vendor/platform coverage.

Usage

- uses: jmacheta/setup-gcc-toolchain@v2
  with:
    toolchain: arm-none-eabi
    version: "15.2.1-1.1"

The toolchain is prepended to PATH, so it takes priority over any pre-installed compiler.

Inputs

Input	Required	Default	Description
toolchain	yes	—	Toolchain name (see Supported toolchains)
vendor	no	—	Vendor name, e.g. xpack or arm. Required when a toolchain name is offered by multiple vendors and the requested version is ambiguous.
version	no	latest	Version string, or latest for the newest available
cache-strategy	no	remote	How to cache the toolchain: remote, local, both, or none — see Caching
local-cache-location	no*	— (or env var, see Caching)	Directory for the local archive cache. *Required when cache-strategy is local or both
set-ld-library-path	no	true	Prepend the toolchain's lib64/lib to LD_LIBRARY_PATH, so built binaries use its bundled libstdc++/libgcc

Vendor selection

Some toolchain names are provided by more than one vendor (e.g. arm-none-eabi is available from both arm and xpack). Without specifying vendor, the action picks the first match and raises an error if the requested version exists in multiple vendors. Use the vendor input to be explicit:

- uses: jmacheta/setup-gcc-toolchain@v2
  with:
    toolchain: arm-none-eabi
    vendor: xpack          # xPack release
    version: "15.2.1-1.1"

Caching

cache-strategy controls how the toolchain is cached across runs:

• remote (default) — caches the extracted toolchain with actions/cache. Works on any runner, including ephemeral GitHub-hosted ones.
• local — reuses downloaded archives from a directory on the runner's disk instead of re-downloading. Only useful on a persistent self-hosted runner, but skips the network round-trip and actions/cache quota entirely. Requires local-cache-location (directly, or via SETUP_GCC_TOOLCHAIN_LOCAL_CACHE_LOCATION); the checksum from the toolchain database is always re-verified against the on-disk archive, and a mismatch falls back to a fresh download.
• both — e.g. for a matrix mixing persistent self-hosted and ephemeral hosted runners, where the local cache helps the former and the remote cache is the only option for the latter.
• none — always download fresh.

local-cache-location sets the directory for the local archive cache, and falls back to the SETUP_GCC_TOOLCHAIN_LOCAL_CACHE_LOCATION env var if omitted — so a self-hosted runner can set its cache path once instead of every workflow repeating it. Safe for concurrent runners sharing the same local disk (atomic rename); not guaranteed on a network filesystem (e.g. NFS).

Outputs

Output	Description
toolchain-path	Absolute path to the toolchain root directory
cache-hit	true if the toolchain was restored from cache

Supported toolchains

Toolchain	Description	Vendors	Linux x64	Linux ARM64	Windows x64
	ARM bare-metal (Cortex-M/R)	xpack, arm	✓	✓	✓
	AArch64 bare-metal	xpack, arm	✓	✓	✓
	AArch32 Linux hard-float (glibc)	arm	✓	✓	✓
	AArch64 Linux (glibc)	arm	✓	✓	✓
	RISC-V bare-metal (RV32/RV64)	xpack	✓	✓	✓
	Native x86_64 GCC	xpack	✓	✓	✓
	MinGW-w64 x86_64 cross GCC (Windows target), UCRT runtime	xpack	✓	✓
	Xtensa for ESP32/ESP32-S2/S3	espressif	✓	✓
	RISC-V for ESP32-C/H series	espressif	✓	✓
	AVR (ATmega, ATtiny, …)	zakkemble	✓		✓
	MinGW-w64 x86_64, UCRT (recommended)	winlibs			✓
	MinGW-w64 x86_64, legacy MSVCRT	winlibs			✓
	MinGW-w64 i686 32-bit, UCRT	winlibs			✓
	MinGW-w64 i686 32-bit, legacy MSVCRT	winlibs			✓

Examples

ARM bare-metal (Cortex-M)

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

      - uses: jmacheta/setup-gcc-toolchain@v2
        with:
          toolchain: arm-none-eabi
          version: "15.2.1-1.1"

      - run: arm-none-eabi-gcc --version
      - run: make

Latest version with cache disabled

version defaults to latest, so it can be omitted entirely:

- uses: jmacheta/setup-gcc-toolchain@v2
  with:
    toolchain: riscv-none-elf
    cache-strategy: none

ESP32 on Linux ARM64 runner

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

      - uses: jmacheta/setup-gcc-toolchain@v2
        with:
          toolchain: xtensa-esp-elf
          version: "16.1.0_20260609"

      - run: xtensa-esp-elf-gcc --version

Windows — native MinGW build

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

      - uses: jmacheta/setup-gcc-toolchain@v2
        with:
          toolchain: x86_64-w64-mingw32-ucrt
          version: "16.1.0"

      - run: x86_64-w64-mingw32-gcc --version

Selecting a specific vendor

When a toolchain is provided by more than one vendor, use the vendor input:

- uses: jmacheta/setup-gcc-toolchain@v2
  with:
    toolchain: arm-none-eabi
    vendor: arm              # official ARM Ltd release
    version: "14.2.rel1"

Matrix across toolchains

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        toolchain:
          - { name: arm-none-eabi,  version: "15.2.1-1.1" }
          - { name: riscv-none-elf, version: "15.2.1-1.1" }
          - { name: avr,            version: "14.1.0" }
    steps:
      - uses: actions/checkout@v4

      - uses: jmacheta/setup-gcc-toolchain@v2
        with:
          toolchain: ${{ matrix.toolchain.name }}
          version: ${{ matrix.toolchain.version }}

      - run: make TOOLCHAIN=${{ matrix.toolchain.name }}

Adding new toolchain versions

The toolchain database is every <platform>.yml file under toolchains/

Each entry follows the pattern:

vendor:
  toolchain-name:
    description: ...
    versions:
      "1.2.3":
        url: https://...
        sha256: <64-char hex>

Pull requests adding new versions are welcome.

License

Apache 2.0