# rustc_codegen_cranelift swaps LLVM for Cranelift in dev builds, and panics default to abort

> rustc_codegen_cranelift is a Cranelift-based codegen backend for rustc, aimed at faster debug-mode compilation. It installs as a nightly rustup component, enables per profile in Cargo, and lacks full SIMD and unwinding support on Windows and macOS.

**rust-lang/rustc_codegen_cranelift** — Cranelift based backend for rustc

- Repository: https://github.com/rust-lang/rustc_codegen_cranelift
- Stars: 2,170 · Forks: 168
- Language: Rust
- License: Apache-2.0
- Published: 2026-10-14 · Updated: 2026-10-30 · Language: en
- Canonical page: https://hysenlabs.com/projects/rust-lang-rustc-codegen-cranelift

## The pitch is faster debug builds, with the speedup stated as a potential and nothing measured

The project aims to create an alternative codegen backend for the Rust compiler, based on Cranelift. The README says this has the potential to improve compilation times in debug mode. It gives no numbers, no benchmark and no comparison to LLVM, so any speed figure you read elsewhere is not backed by this repository.

The compatibility rule is practical. If your project does not use anything listed under Not yet supported, it should work fine. If it does and something breaks, the README asks you to open an issue.

The scope is the dev profile, which matches how the enabling instructions are written. The configuration keys all sit under profile.dev. The README does not claim the backend for release builds, and describing it as a debug-mode tool is the safe reading. Think of it as a way to shorten the edit and compile loop, with LLVM still doing the final optimized artifacts.

The repository is not archived and the last push was on 2026-10-23, with a rolling dev release dated 2026-10-29.

## One rustup component and three ways to switch the backend on

The backend ships in nightly builds for Linux, macOS and x86_64 Windows. Installation through rustup is one command:

```bash
rustup component add rustc-codegen-cranelift-preview --toolchain nightly
```

The component name ends in preview, and it exists only on the nightly toolchain, so a stable toolchain cannot use it. Once installed, you enable it in one of three ways. The first is an environment variable on a single invocation:

```bash
CARGO_PROFILE_DEV_CODEGEN_BACKEND=cranelift cargo +nightly build -Zcodegen-backend
```

The second is a config file. Add this to .cargo/config.toml:

```toml
[unstable]
codegen-backend = true

[profile.dev]
codegen-backend = "cranelift"
```

The third puts the setting in the manifest. This line must come before anything else in Cargo.toml:

```toml
# This line needs to come before anything else in Cargo.toml
cargo-features = ["codegen-backend"]

[profile.dev]
codegen-backend = "cranelift"
```

The config.toml route applies to every project under that directory, while the Cargo.toml route travels with the repository and affects everyone who builds it. Choose by who should be forced onto nightly.

## The dev release carries cargo-clif, which stands in for cargo build

If you do not want the rustup component, pre-built archives are on the releases page. Extract the dist directory anywhere you like. Inside is the cargo-clif executable, and adding the bin subdirectory of the extracted dist directory to your PATH lets you run cargo clif build without typing the full path. The README links tutorials for editing PATH on Windows and on Linux or macOS.

The release list has two entries. One is named dev, last updated 2026-10-29, which is the rolling download the README points to. The other is v0.1.0, dated 2020-10-27, described as the first version added as an optional codegen backend for rustc. The Cargo.toml still says version 0.1.0 with edition 2024, so the version number does not track releases and cannot be used to tell builds apart.

Because the dev release is a moving target, two people downloading it a week apart can end up with different binaries. Record the date of the archive you used when you report a bug.

The project is not published as a library crate. Its Cargo.toml declares crate-type as dylib, which fits its role as a compiler plugin loaded by rustc.

## Building from source runs through y.sh, and the first run needs prepare

To build manually, clone the repository and run the project's wrapper script:

```bash
git clone https://github.com/rust-lang/rustc_codegen_cranelift
cd rustc_codegen_cranelift
./y.sh build
```

The test suite replaces that last command with two steps:

```bash
./y.sh prepare # only needs to be run the first time
./test.sh
```

There are matching y.cmd and y.ps1 files for Windows. The build_system directory holds the logic, and build_system/usage.txt and the help message of ./y.sh document more options.

Once built, usage is a near-drop-in replacement for cargo build or cargo run. Assuming cg_clif_dir is the directory you cloned into, and y.sh prepare and y.sh build or test.sh have run, go to your project and run:

```bash
$cg_clif_dir/dist/cargo-clif build
```

That builds with rustc_codegen_cranelift instead of the usual LLVM backend. The repository includes a rust-toolchain.toml and a rust-version file, so the source build is tied to a specific compiler revision and does not follow whatever toolchain you have installed. A JIT mode and further usage notes are in docs/usage.md, and testing against changes in rustc code is described in docs/rustc_testing.md.

## The platform matrix marks Windows AArch64 and AIX as unsupported

The README gives a table of operating systems against architectures, with three legends: fully supported and tested, maybe supported but not tested, and not supported at all.

Linux is fully supported on x86_64, AArch64, Riscv64 and s390x, though the last two are not available as a rustup component for nightly and you build them yourself. macOS is fully supported on x86_64 and AArch64. Windows is fully supported on x86_64 and marked not supported on AArch64. FreeBSD is supported on x86_64, again without a rustup component, and marked maybe supported for the other three architectures.

AIX is marked not supported on x86_64 and s390x, with the reason given as the XCOFF object file format, which the backend does not handle. Other unixes are marked maybe supported on every architecture, which means untested rather than known to work.

The table has a consequence for team setups. If your developers use Windows on ARM, they cannot use this backend, and a Cargo.toml that forces it will break their builds. The README notes that not all targets are available as a rustup component for nightly, so the rustup install route covers fewer platforms than the matrix does.

## SIMD is partial and unwinding is off by default

Two items are listed under Not yet supported, and both affect real code.

The first is SIMD, tracked in issue 171. The README says std::simd fully works and std::arch is partially supported. A crate that calls architecture intrinsics directly may hit unimplemented ones, while portable SIMD through std::simd is fine.

The second is unwinding on panics, tracked in issue 1567. It is experimental and not supported on Windows and macOS, and -Cpanic=abort is enabled by default. The result is that a panic ends the process instead of unwinding. Tests that rely on should_panic, and code that catches panics, can behave differently from an LLVM build. A debug build that aborts where the release build recovers is a surprising difference, so run your test suite under both backends before trusting one.

The repository carries example files that exercise odd cases, such as track-caller-attribute.rs, raw-dylib.rs, float-minmax-pass.rs and gen_block_iterate.rs, which suggests regression tests for specific compiler behaviors.

## Cranelift crates are pinned at 0.137.0 and have to move together

The Cargo.toml depends on several Cranelift crates at version 0.137.0: cranelift-codegen, cranelift-frontend, cranelift-module, cranelift-native, cranelift-jit and cranelift-object. A comment above them states they have to be in sync with each other. The jit crate is optional, which is how the JIT mode is switched on, and cranelift-codegen is built with features std, timing, unwind and all-native-arch.

The manifest also has commented-out patch lines. One group points the crates at a branch named release-50.0.0 of the wasmtime repository, to use an unreleased Cranelift, and another points at a local wasmtime checkout. Those are the hooks a developer uses to test the backend against Cranelift changes.

Other dependencies include target-lexicon, gimli, object, indexmap, libloading and smallvec. The project is licensed under either Apache License 2.0 or the MIT license, at your option, and contributions are dual licensed the same way. The repository metadata lists Apache-2.0 only, so rely on the LICENSE-APACHE and LICENSE-MIT files for the full terms.

## Conclusion

Try it on a nightly toolchain if debug build times hurt and your crates avoid raw std::arch SIMD and panic unwinding. Do not use it for release builds, for projects that rely on catching panics, or on Windows AArch64 and AIX, which are marked unsupported. Before switching a project over, build it once with cargo clif build and compare against the LLVM build, because the README promises only potential, not measured gains.

## FAQ

### How do I install rustc_codegen_cranelift?

Run rustup component add rustc-codegen-cranelift-preview --toolchain nightly, or download a pre-built archive from the dev release and use its cargo-clif executable. It is distributed in nightly builds on Linux, macOS and x86_64 Windows.

### Does rustc_codegen_cranelift support panics and unwinding?

Only experimentally. Unwinding on panics is not supported on Windows and macOS, and -Cpanic=abort is enabled by default.

### What does rustc_codegen_cranelift improve?

The README says it has the potential to improve compilation times in debug mode. It publishes no benchmark numbers, so measure your own project.

## Sources

- [Issues](https://github.com/rust-lang/rustc_codegen_cranelift/issues)
- [License: Apache-2.0](https://github.com/rust-lang/rustc_codegen_cranelift/blob/main/LICENSE)
- [README](https://github.com/rust-lang/rustc_codegen_cranelift/blob/main/README.md)
- [Releases](https://github.com/rust-lang/rustc_codegen_cranelift/releases)
- [rust-lang/rustc_codegen_cranelift on GitHub](https://github.com/rust-lang/rustc_codegen_cranelift)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/rust-lang-rustc-codegen-cranelift