cbindgen

To generate headers from a Rust crate using the CLI, you need a cbindgen.toml configuration file and a Rust crate with a public C API.

Run the following command to generate a C++ header:

cbindgen --config cbindgen.toml --crate my_rust_library --output my_header.h

To generate other languages, use the --lang flag:

• For C: --lang c
• For Cython: --lang cython

You can install cbindgen using cargo or Homebrew to generate C/C++ headers for Rust libraries that expose a public C API.

cargo install --force cbindgen

To install the cbindgen standalone program, use the following command. The --force flag ensures that an existing installation is updated to the latest version.

cargo install --force cbindgen

To integrate header generation directly into your Cargo build process, use the cbindgen library within your build.rs file.

First, add cbindgen to your Cargo.toml under [build-dependencies]:

[build-dependencies]
cbindgen = "0.24.0"

Then, implement the generation logic in build.rs using the Builder API:

extern crate cbindgen;

use std::env;

fn main() {
    let crate_dir = env::var("CARGO_MANIFEST_DIR").unwrap();

    cbindgen::Builder::new()
      .with_crate(crate_dir)
      .generate()
      .expect("Unable to generate bindings")
      .write_to_file("bindings.h");
}

To ensure cbindgen detects your items, you must use specific Rust attributes. cbindgen searches for:

• Functions: #[no_mangle] pub extern fn
• Globals: #[no_mangle] pub static
• Constants: pub const

Important Limitations:

• cbindgen does not understand Rust's module system or namespacing. If two types have the same name in different modules, behavior is unspecified.
• To ensure a type has a guaranteed layout in the generated header, use #[repr(...)] attributes (e.g., #[repr(C)], #[repr(u8)], or #[repr(transparent)]).
• cbindgen cannot support anonymous tuples (A, B, ...) or wide pointers like &dyn Trait or &[T]. Use tuple structs and decompose slices into pointer/length pairs instead.

To use cbindgen as a standalone program, you need a cbindgen.toml configuration file (which can be empty) and a Rust crate with a public C API.

By default, cbindgen produces C++ headers. To produce C headers, use the --lang c flag.

You can override global cbindgen.toml settings by adding doc comments starting with cbindgen: to your Rust types. Annotations can be a bool, a string (no quotes), or a list of strings. If only the name is provided, =true is assumed.

Warning: The annotation parser is naive and does not support escaping. Do not use =, ,, [ or ] within your annotation strings.

/// cbindgen:field-names=[x, y]
/// cbindgen:derive-eq
#[repr(C)]
pub struct Point(pub f32, pub f32);

Control which headers are included in the generated file, including system headers (with angle brackets) and local headers (with quotes).

# A list of sys headers to #include (with angle brackets)
sys_includes = ["stdio", "string"]

# A list of headers to #include (with quotes)
includes = ["my_great_lib.h"]

# Whether to suppress cbindgen's default C/C++ standard imports
# (e.g., <stdint.h>, <stdarg.h> for C)
no_includes = false

# A block of text to add verbatim after the includes block
after_includes = "#define VERSION 1"