C interop: `Complex<T>`

[nxsaken]

Metadata
Contact	@folkertdev
Team(s)	compiler (@folkertdev), lang, libs
Goal document	2026/interop-complex
Funding contact	Trifecta Tech Foundation

Summary

Rust should be able to define an ABI-compatible counterpart to every signature that C can define. This is important for C interop and translation of code from C to rust, using manual FFI, and tooling like c-bindgen and c2rust. This goal closes a long-standing gap in rust's ability to match C.

---

This issue is intended for status updates only.

For general questions or comments, please contact a goal owner or post in the Zulip topic.

[nxsaken]

This issue is intended for status updates only.

For general questions or comments, please contact the owner(s) directly.

[folkertdev]

An initial update

tracking issue: rust-lang/rust#154023
accepted rfc: rust-lang/rfcs#3892

This project goal adds core::num::Complex, a complex number type that is ABI-compatible with the C _Complex type (at least when the element type is a C float type).

/// A complex number.
#[derive(Clone, Copy, Debug, PartialEq)]
#[unstable(feature = "complex_numbers", issue = "154023")]
#[repr(C)]
#[lang = "complex"]
pub struct Complex<T> {
    /// The real component.
    pub re: T,
    /// The imaginary component.
    pub im: T,
}

We've started work on the type itself:

• Add core::num::Complex rust#158885
• add Complex<T> layout tests for straightforward targets rust#161187

These PRs implement the type and start the work on making it ABI-compatible with C _Complex across targets. With the second PR we've tackled the easy cases, leaving PowerPC, MIPS and Sparc. Those require more work.

One foundational piece is this PR that gives us more flexibility in specifying padding.

• make pad_i32 of PassMode::cast an integer rust#160132

Once that is merged I'll continue to cherry-pick changes off of this WIP branch where I've got all targets I can get my hands on working:

• Complex layout phase 2 rust#159981

We've also started work on the API and libcalls:

• implement Add and Sub for Complex rust#161227
• implement Complex mul and div libcalls compiler-builtins#1288

---

When first looking into this, it was clear that matching C _Complex on all targets was going to be immensely tedious. The RFC only expressed the requirement that we'd match the C type, without much research into what that would entail. It turns out that many ABIs have custom behavior for _Complex that deviates from just a struct with two fields.

I made a fork (that I do hope to upstream) of abi-cafe that can cross-compile, and added support for complex numbers (my fork). In combination with a number of (custom) GCC builds and qemu, my abi-cafe can effectively fuzz the ABI of _Complex across targets, finding differences between the WIP Rust implementation, Clang and GCC. I've since added support for some other (unstable) features like packed structs, c-variadic functions and f16b.

This tool has been extremely helpful in finding and testing fixes for various rustc bugs:

• on X86 SysV the ABI of an empty struct is different from Clang and GCC rust#161117
• sparc: make ABI consistent with clang rust#160401
• fix arm homogeneous aggregate ABI rust#161070
• fix is_homogeneous_aggregate: use unit size, not total size  rust#161394

... and a much larger number of Clang bugs, here are the ones most relevant to Complex:

• [MIPS][clang] make _Complex ABI match GCC llvm/llvm-project#212119
• [Sparc][clang] make _Complex ABI GCC-compatible llvm/llvm-project#212340
• [PowerPC] make _Complex ABI GCC-compatible llvm/llvm-project#208917
• [RISCV] make _Complex {integer} consistent with GCC llvm/llvm-project#216404
• [clang][LoongArch] Match GCC ABI handling of integer complex types llvm/llvm-project#215222

Blockers

Review capacity has been a real issue here. ABIs are hard, and changes to them are time-consuming to review.

Help wanted

On the libs side of things, it's unclear what other APIs we want on Complex. The RFC does not specify anything further, so extensions need to go throug ACP.

The num_complex crate has various functions (conversion from polar coordinates, sqrt, sin, etc.). However these implementations are generally not equivalent to the libc functions when dealing with floating point edge cases, particularly NaN.

There is more low-hanging fruit too in terms of trait implementations. Maybe the type should be Hash, or impl<T: Default> Default for Complex<T>, etc. I'd be happy for someone else to tackle this.

[folkertdev]

Key developments

We're making progress on the long tail of ABIs

• add Complex ABI run-make test rust#161694
• make Complex ABI-compatible on sparc64 and powerpc64 rust#161697
• make Complex ABI GCC-compatible on sparc rust#163025
• make mips64 Complex GCC-compatible rust#162921

After the open PRs, the remaining targets are mips and 32-bit powerpc.
With beetrees having joined T-compiler, the review situation is a lot better here.

Work is ongoing on the API side

• Complex conjugate, negation and default rust#162865
• add Div and Mul for Complex<{float}> rust#162832
• implement complex div/mul libcalls miri#5319
• use extern "C" and C names for complex div and mul of f32 and f64 compiler-builtins#1303

Trying to merge division and multiplication support hit an ABI issue with the cranelift backend.
My fix for this issue was merged upstream, so now we're waiting for that to become available.

• allow returns via xmm1 with WindowsFastCall for extern "Rust" bytecodealliance/wasmtime#14361

Also, various ABI issues got solved as a side-effect of having abi-cafe

• fix is_single_fp_element for s390x and x86 rust#161987
• wasm: correctly implement union trivial aggregates rust#162806
• wasm: fix ABI for enums with integer layout and ZST fields rust#162826
• powerpc64: don't pass unions in FPRs on ELFv1 rust#163076

Blockers

I've not had any luck getting reviews for my powerpc changes in LLVM. Complex division and multiplication just miscompile when using clang. (the rust implementation will be correct, and compatible with GCC). Broken support in clang doesn't need to block anything on the rust side, it's just annoying.

Help wanted

Same as last time: if you have thoughts about the API, please jump in.