# Cranelift Codegen Backend Limitations

## Background

The Cranelift codegen backend (`rustc-codegen-cranelift-preview`) is an alternative to LLVM for Rust compilation. It's significantly faster for debug builds but has feature gaps.

## Known Unsupported Features

### `global_asm!` with `sym` operands

**Status**: Not supported as of March 2026

The error originates in `compiler/rustc_codegen_cranelift/src/global_asm.rs` in the rust-lang/rust repo. When Cranelift encounters a `GlobalAsmOperandRef::SymFn` operand, it emits:

```
error: asm! and global_asm! sym operands are not yet supported
```

**Affected crates** (non-exhaustive):
- `wasmtime-fiber` (all versions, including v42+) — uses `global_asm!` with `sym` for fiber context switching
- Any crate using `global_asm!` with function symbol references

**Source**: [rust-lang/rust global_asm.rs](https://github.com/rust-lang/rust/blob/main/compiler/rustc_codegen_cranelift/src/global_asm.rs)

### Diagnostic confusion

The error message says "not yet supported" which looks like a Rust nightly regression. It's NOT — it's a Cranelift limitation that has existed since the backend was introduced. The confusion arises because:

1. `cargo check` and `cargo clippy` don't invoke codegen → no error
2. `cargo build` / `cargo test` invoke codegen → Cranelift fails
3. The error message doesn't mention Cranelift, so it looks like a rustc bug

## Workarounds

### Per-invocation override

```bash
CARGO_PROFILE_DEV_CODEGEN_BACKEND=llvm cargo test
CARGO_PROFILE_DEV_CODEGEN_BACKEND=llvm cargo build
```

### Per-project override

Create `.cargo/config.toml` in the project:

```toml
[profile.dev]
codegen-backend = "llvm"
```

### Selective override (keep Cranelift for most builds)

Use LLVM only for test profile:

```toml
[profile.test]
codegen-backend = "llvm"
```

## Detection

If `cargo check` passes but `cargo test` fails with `global_asm!` errors, check:

```bash
grep -r "codegen-backend" ~/.cargo/config.toml .cargo/config.toml 2>/dev/null
```