Introduction - cheadergen

Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Auto

Light

Rust

Coal

Navy

Ayu

cheadergen

Introduction

cheadergen generates accurate C headers for Rust libraries that expose a C-compatible API.

cheadergen provides:

Multi-crate support. One C header per crate, with<br>cross-crate #includes wired up automatically.

Compiler-accurate type analysis. Type information comes from<br>rustdoc-json,<br>so the generated output mirrors what the Rust compiler actually sees.

Macro-aware. Items defined by declarative or procedural macros<br>are picked up automatically.

cheadergen is an alternative to<br>cbindgen. Check out our<br>comparison page<br>for more details.

What it does

You write Rust:

#![allow(unused)]<br>fn main() {<br>#[repr(C)]<br>pub struct Point {<br>pub x: f64,<br>pub y: f64,

#[unsafe(no_mangle)]<br>pub extern "C" fn distance(a: Point, b: Point) -> f64 {<br>((a.x - b.x).powi(2) + (a.y - b.y).powi(2)).sqrt()<br>cheadergen produces a header your C code can consume:

typedef struct {<br>double x;<br>double y;<br>} Point;

double distance(Point a, Point b);

New to C/Rust interoperability?

If you’ve never written extern "C" in Rust before, the<br>FFI chapter of the Rust Nomicon<br>is a good primer on the building blocks cheadergen relies on: the C<br>calling convention, #[no_mangle] for stable symbol names, #[repr(C)]<br>for predictable struct layout, and the rules around passing data across<br>the boundary.

Read through it first if any of those terms feel unfamiliar: the<br>rest of this guide assumes you know what they do, and focuses on how<br>cheadergen can support your mixed C/Rust projects.

Author

cheadergen (C Header Gen erator) is built and maintained by Luca Palmieri.

User guide structure

This guide is structured as follows:

Getting started .<br>If you’re new, start here. Install the CLI, then walk through the<br>Quickstart.

Foundations .<br>The load-bearing concepts you’ll meet using cheadergen:<br>target packages,<br>item annotations, and<br>global configuration.

How it works .<br>The internals: the processing pipeline and<br>generics and monomorphization.

What you get .<br>The shape of the generated output:<br>anatomy of a generated header and<br>bundled vs partitioned output.

Limits and alternatives .<br>Comparison with cbindgen,<br>what cheadergen can’t do, and<br>C++ support.

How-to guides .<br>Recipes for common tasks:<br>wiring cheadergen into Cargo,<br>generating headers across a workspace,<br>migrating from cbindgen,<br>and more.

API references on docs.rs .<br>The canonical references for the options exposed by the<br>#[cheadergen::config(...)]<br>attribute and the<br>cheadergen.toml<br>config file.