GCC backend (plenty_codegen_gcc)

Status: Not implemented (B20). The compiler has no --backend option. This page is the only record of the GCC backend design. API facts were checked against the gccjit 7.1.0 crate source and the libgccjit 17 documentation on 2026-10-07.

Out of date since then: line numbers, file sizes, and test counts refer to the tree on 2026-10-07. The Cranelift backend has grown from about 2,840 lines in five files to about 4,900 in src/codegen.rs and fifteen submodules, plus src/tail_abi.rs. A revised plan must cover what was added: parallel function emission (src/codegen/output.rs), which libgccjit’s global lock constrains; closures, threads, channels, executors, exports, and foreign calls; and inline aggregate values. Native emission supports only x86_64-unknown-linux-gnu (B18).

This backend design is separate from the native-platform assessment: another code generator does not by itself port the runtime, standard library, or foreign-call contracts.

Goal

Add a second AOT backend that uses GCC, through libgccjit, to make native code. Cranelift stays the default backend. The model is rustc_codegen_gcc.

                              ┌── codegen_cranelift ──> CLIF ──────┐
Op ── op::check ── codegen_ssa┤                                    ├──> .o ──cc──> executable
                              └── codegen_gcc ──> libgccjit trees ─┘

Why

• GCC’s optimizer can make faster code, and with -Os, smaller code.
• GCC supports more CPU targets than Cranelift.
• It does not change runtime memory use. That comes from the value and heap design, not the backend.

Cost

• System dependency. libgccjit.so must be installed to use the backend. Use the crate’s dlopen feature (see below) so the default build and the default binary do not need it.
• One target per install. One libgccjit build makes code only for the target GCC was built for. To cross-compile, you need a separate libgccjit for each target.
• Slower compiles, more compiler RAM than Cranelift.
• Two backends to maintain. Every new Op needs two lowerings, unless you first add a shared lowering layer (see Phase 1).
• License. The gccjit crate and libgccjit are GPL-3.0. See “License”.

License

Not legal advice. This is the common reading.

Plan: license Plenty as MIT OR Apache-2.0. The repo has no license file now.

What works:

• All of Plenty’s own source can be MIT OR Apache-2.0. Both licenses are compatible with GPL-3.0, so GPL code can sit beside them.
• User programs are not affected. The runtime that is linked into compiled Plenty programs is Plenty’s own MIT/Apache code. Machine code that GCC makes is not covered by GCC’s license.

What does not work:

• A distributed plenty binary built with gcc-backend includes the gccjit crate (GPL-3.0). That binary must be distributed under GPL-3.0 terms, including an offer of its source.
• dlopen does not fix this. It removes the link-time need for libgccjit.so, but the crate’s Rust code is still compiled into the binary.

Options:

1. Keep gcc-backend off by default (recommended). Default binaries stay pure MIT/Apache. Only builds with the GCC backend carry the GPL. Say this in the README.
2. Write your own bindings for the about 40 libgccjit functions you need, instead of using the GPL crate. libgccjit itself is still GPL-3.0, and the FSF treats dynamic loading as a combined work. This option is weaker than it looks.
3. Emit C and run gcc as a separate program. This avoids the question completely, because Plenty does not link GCC. It is not the rustc_codegen_gcc model.

Setup:

• Set license = "MIT OR Apache-2.0" in Cargo.toml and plenty-runtime/Cargo.toml.
• Add LICENSE-MIT and LICENSE-APACHE at the repo root.

How rustc_codegen_gcc does it (the model)

• rustc_codegen_ssa holds the shared lowering. It calls builder traits (BuilderMethods, ConstMethods, …).
• Each backend (_llvm, _cranelift, _gcc) implements those traits.
• The _gcc crate uses the gccjit Rust crate (bindings to libgccjit).
• It uses a patched GCC fork. Plenty does not need the fork. See “The gccjit crate” below.

The gccjit crate: facts that save time

Crate: gccjit = "7.1.0" (depends on gccjit_sys 4.1.0). Repo: https://github.com/rust-lang/gccjit.rs. Docs on docs.rs are built with the master feature, so docs.rs shows functions that you cannot use.

Features:

Every API this plan needs is available without master: Context::compile_to_file(OutputKind::ObjectFile, ..), RValue::set_require_tail_call, Block::end_with_switch, Context::new_case, Function::get_address, Context::get_builtin_function, LValue::global_set_initializer (bytes), LValue::global_set_initializer_rvalue, Context::new_struct_constructor, LValue::set_alignment, Context::add_command_line_option, Context::dump_reproducer_to_file.

Linkage maps directly (gccjit::FunctionType):

Error handling gotchas:

• In debug builds (this includes cargo test), the crate panics after any call if get_last_error() returns text. Without master, it cannot read the error count, so it panics on warnings too. Do not emit code that makes GCC warn. If you must, wrap the GCC backend in std::panic::catch_unwind and turn the panic into a Result error.
• In release builds, it does not panic. Check ctx.get_first_error() after compile_to_file, or a failed compile is silent.
• Any call that returns NULL panics in all builds (panic_on_null).

libgccjit rejects unreachable blocks by default. The Cranelift lowering makes blocks that have no predecessor (for example the block after a TailCall or after a trap). Call ctx.set_allow_unreachable_blocks(true), or do not create those blocks.

Optimization levels: OptimizationLevel has None, Limited, Standard, Aggressive (-O0 to -O3). There is no -Os variant. Use ctx.add_command_line_option("-Os").

Concurrency: libgccjit holds a global lock while it compiles. Parallel tests that use the GCC backend run their GCC compiles one at a time. They are correct, but slower.

Assembler: libgccjit writes assembly and runs the assembler. as (binutils) must be on PATH. Plenty already needs cc, so this is normally true.

Minimum libgccjit version

The libgccjit docs list features by ABI tag, not by GCC version. The tags this plan needs:

So the minimum is LIBGCCJIT_ABI_24. With dlopen, gccjit::load fails if the library lacks any symbol that the non-master crate binds, so the crate may need a newer tag than this. Check what is installed:

objdump -T /usr/lib64/libgccjit.so.0 | grep -o 'LIBGCCJIT_ABI_[0-9]*' | sort -uV | tail -1

Current state (what the GCC backend must match)

The Cranelift backend is about 2,840 lines:

Where to look first:

Features it uses, and the libgccjit equivalent:

rvalues are trees, not SSA values

In Cranelift, a Value is computed once. You can use it many times.

In libgccjit, an rvalue is an expression tree. If you use the same rvalue twice, GCC computes it twice, and side effects (such as runtime calls) happen twice. Rule for the GCC backend: assign each pushed value to a new local, and push the local. This is how rustc_codegen_gcc handles it too. GCC’s optimizer removes the extra locals.

Metadata blobs

metadata.rs makes each blob as bytes plus a list of (offset, DataId) pointer slots. To build the same blob in libgccjit:

1. Sort the pointer offsets.
2. Make a struct type. Bytes between pointer slots become u8[N] fields. Each pointer slot becomes a void * field.
3. Build a new_struct_constructor with array constructors for the byte fields (one rvalue per byte: a string literal cannot fill a char array) and get_address of the target global for each pointer field.
4. Set alignment 8.

Phase 1 should make the bytes-plus-slots form the backend-neutral output of metadata.rs, so both backends use the same layout code.

Undefined behaviour

GCC optimizes on C undefined behaviour. Cranelift does not. Rules:

• Do wrapping arithmetic on unsigned types, then cast back.
• Check shift amounts before you shift.
• Add -fno-strict-aliasing with add_command_line_option. The runtime and the generated code read the same memory through different types.

Phases

Phase 0: spike (small)

Goal: prove the toolchain works before you change the design.

1. sudo dnf install libgccjit libgccjit-devel. Neither is installed now. System GCC is 16.2. Run the objdump command above.
2. In a scratch crate with gccjit = { version = "7.1", features = ["dlopen"] }:
   • write an object file with one exported plenty_main,
   • call one runtime helper (for example plenty_print_str),
   • link it with libplenty_runtime.a through cc. Extract the archive with plenty --emit-runtime DIR.
3. Test mandatory tail calls, at -O0 and -O2:
   • self tail call, mutual tail call,
   • a callee with more arguments than the caller (more than 6 integer arguments on x86-64, so some go on the stack),
   • a callee that returns a struct larger than 16 bytes (returned in memory),
   • a callee that takes or returns unsigned __int128.
4. Test __builtin_add_overflow through get_builtin_function on u8, i32, and i64.
5. Test a global whose initializer holds the address of another global.
6. Build in debug mode and confirm that no step panics on a warning.

Exit: a short note on which features work, and which need a fallback.

Phase 1: backend seam (large, no behaviour change)

Goal: split the shared lowering from the Cranelift-specific code, like rustc_codegen_ssa.

1. Move backend-neutral work out of codegen.rs:
   • collect_user_fns, collect_str_ids, needs_local_addresses,
   • the runtime helper table (names and signatures as plain data),
   • metadata blob layout (bytes plus pointer slots).
2. Define builder traits for what Lowerer needs. Start from the feature table: constants, arithmetic, checked arithmetic, compares, casts, calls, tail calls, blocks, branches, switch, locals, memory load/store, data addresses.
3. Make Lowerer generic over the builder. Implement the traits for Cranelift.
4. All existing tests must pass with no changes.

Design notes:

• gccjit handles carry a 'ctx lifetime (RValue<'ctx>, Block<'ctx>). Give the traits a lifetime parameter, as rustc_codegen_gcc does with CodegenCx<'gcc, 'tcx>. Do this in the first version of the traits, or you must change every signature later.
• Model “value” in the trait as something that a backend can read many times with no side effects. Cranelift returns its SSA Value. GCC returns a local.
• Model block params as “declare join values, assign, jump”. Cranelift maps this to block params; GCC maps it to locals.

This is the largest phase. It is also useful on its own: it makes new Op lowerings easier to write and review.

Alternative: skip Phase 1 and copy Lowerer into a GCC version. This is faster to start, but every later Op change needs two edits that can drift apart. Use this only if you want a throwaway experiment.

Phase 2: GCC backend, core (medium)

Put it in src/codegen/gcc/ behind a Cargo feature gcc-backend (optional dependency on gccjit with dlopen).

Order of work, smallest first:

1. Integers, booleans, Display of numbers, plenty_main, exit status.
2. User functions, calls, multiple returns, tail calls.
3. match, patterns, join locals.
4. Strings and static data.
5. Checked arithmetic and traps.
6. Floats and saturating casts.

Crate layout note: a separate plenty-codegen-gcc workspace crate would need Op and Ty from plenty, and plenty would need the backend. Cargo does not allow that cycle. Use a module behind a feature now. Split out a plenty-core crate later only if you need it.

Phase 3: GCC backend, full coverage (medium)

1. Sum types (enums.rs), including I128 inline sums.
2. Collections.
3. Metadata blobs with pointers.
4. Generators (switch-based resume, get_address for callbacks).

Phase 4: CLI and tests (small)

• CLI: --backend cranelift|gcc. Default cranelift. If the binary was built without gcc-backend, or gccjit::load fails, give a clear error.
• Tests: all 20 test files that compile programs reach compile_ops_to_executable (src/codegen.rs:156), most through tests/support/mod.rs. Read a PLENTY_BACKEND env var there, and one change runs the full AOT suite on GCC: PLENTY_BACKEND=gcc cargo test --features gcc-backend.
• Run the GCC suite at -O0 and -O2. Undefined behaviour bugs show only at -O2.
• CI: add one job that installs libgccjit and runs the command above.
• Docs: update the build table in CLAUDE.md and the toolchain reference.

Phase 5: options (optional)

• -O0 / -O2 / -Os flag. Use set_optimization_level for -O0–-O3 and add_command_line_option("-Os") for size.
• Debugging: dump_reproducer_to_file(path) writes a C program that rebuilds the same context. set_dump_code_on_compile(true) prints the assembly. set_dump_initial_gimple(true) prints GCC’s view of your trees. Put these behind an env var such as PLENTY_GCC_DUMP.

Risks

Effort

The total is about the same as writing the Cranelift backend again. Phase 1 returns some of that cost, because each later backend or Op is cheaper.

Open questions

1. Do you want Phase 1 (shared lowering), or a separate copy of Lowerer for an experiment?
2. Which license option (see “License”) do you want for GCC-enabled builds?
3. Is cross-compilation a goal? If yes, the “one target per libgccjit” limit matters, and you need a separate libgccjit for each target.
4. Should the GCC backend be in the default CI, or in an optional job only?