Generating Bindings with bindgen

21 min read

When you want to call a C library that has more than a couple of functions, hand-writing extern "C" declarations becomes tedious and error-prone. The bindgen crate reads a C header and generates the Rust FFI declarations for you at build time, so the C API stays the single source of truth.

Quick Overview

bindgen parses a C (or C++) header using libclang and emits a Rust file full of extern "C" function declarations, #[repr(C)] structs, enums, and type aliases that exactly mirror the header. You run it from a build.rs build script, then include! the generated file into your crate.

For a TypeScript/JavaScript developer, this is the spiritual cousin of generating .d.ts type declarations from a .js library or running protoc/openapi-generator to turn a schema into typed client code. You point a tool at an interface definition and get type-safe glue back. The crucial difference: the bindings bindgen emits are raw and unsafe — they mirror the C types faithfully but provide none of Rust’s safety guarantees. Making them safe is your job, and this page shows the pattern.

Note: This page is about auto-generating bindings. If you only have one or two functions, hand-declaring them (see calling-c.md) is simpler. For the underlying extern "C" / #[repr(C)] mechanics, see ffi-basics.md.

TypeScript/JavaScript Example

In the Node.js world you rarely write FFI by hand either. A native addon ships a .node binary plus a generated .d.ts so TypeScript callers get types. A typical “wrap a C library” workflow with a tool such as node-gyp plus a typings generator looks conceptually like this:

1
// temperature.d.ts — GENERATED type declarations for a native addon.
2
// You did not write these by hand; a tool produced them from the C interface.
3

4
export const enum TempUnit {
5
  Celsius = 0,
6
  Fahrenheit = 1,
7
  Kelvin = 2,
8
}
9

10
export interface Reading {
11
  value: number;
12
  unit: TempUnit;
13
}
14

15
export function tempConvert(reading: Reading, to: TempUnit): number;
16
export function tempConversionCount(): bigint;

1
// app.ts — your code consumes the generated declarations.
2
import { tempConvert, TempUnit } from "./temperature";
3

4
const f = tempConvert({ value: 100, unit: TempUnit.Celsius }, TempUnit.Fahrenheit);
5
console.log(`100C = ${f}F`); // 100C = 212F

The generated .d.ts only describes shapes for the TypeScript compiler — it is erased at runtime and enforces nothing once the program runs. bindgen’s output is the same idea (machine-generated glue from an interface) but it produces executable Rust declarations that the compiler actually links against.

Rust Equivalent

We will wrap a small C temperature-conversion library. The project layout:

1
temp_conv/
2
├── Cargo.toml
3
├── build.rs            # runs cc + bindgen at build time
4
├── csrc/
5
│   ├── temperature.h   # the C interface we want to call
6
│   └── temperature.c   # the C implementation we compile and link
7
└── src/
8
    └── main.rs         # raw bindings + our safe wrapper

The C header is the interface bindgen reads:

1
#ifndef TEMPERATURE_H
2
#define TEMPERATURE_H
3

4
#include <stdint.h>
5

6
/* A unit of temperature. */
7
typedef enum TempUnit {
8
    TEMP_CELSIUS = 0,
9
    TEMP_FAHRENHEIT = 1,
10
    TEMP_KELVIN = 2,
11
} TempUnit;
12

13
/* A temperature reading: a value paired with its unit. */
14
typedef struct Reading {
15
    double value;
16
    TempUnit unit;
17
} Reading;
18

19
/* Convert a reading to a different unit. Returns the converted value. */
20
double temp_convert(Reading reading, TempUnit to);
21

22
/* Number of conversions performed since process start. */
23
uint64_t temp_conversion_count(void);
24

25
#endif

1
#include "temperature.h"
2

3
static uint64_t COUNT = 0;
4

5
static double to_celsius(Reading r) {
6
    switch (r.unit) {
7
        case TEMP_FAHRENHEIT: return (r.value - 32.0) * 5.0 / 9.0;
8
        case TEMP_KELVIN:     return r.value - 273.15;
9
        default:              return r.value;
10
    }
11
}
12

13
double temp_convert(Reading reading, TempUnit to) {
14
    COUNT += 1;
15
    double c = to_celsius(reading);
16
    switch (to) {
17
        case TEMP_FAHRENHEIT: return c * 9.0 / 5.0 + 32.0;
18
        case TEMP_KELVIN:     return c + 273.15;
19
        default:              return c;
20
    }
21
}
22

23
uint64_t temp_conversion_count(void) {
24
    return COUNT;
25
}

Add the build-time tooling. Both are build-dependencies, not regular dependencies — they run during compilation, not at runtime. cargo add resolves the current versions automatically (it has been built into Cargo since 1.62, no cargo-edit needed):

1
cargo add bindgen --build   # parses the header, emits Rust FFI declarations
2
cargo add cc --build        # compiles temperature.c into a static lib we link

1
[package]
2
name = "temp_conv"
3
version = "0.1.0"
4
edition = "2024"
5

6
[build-dependencies]
7
bindgen = "0.72.1"
8
cc = "1.2.63"

The build script compiles the C, generates bindings, and writes them into OUT_DIR:

1
use std::env;
2
use std::path::PathBuf;
3

4
fn main() {
5
    // 1. Compile the C source into a static library and link it.
6
    cc::Build::new()
7
        .file("csrc/temperature.c")
8
        .include("csrc")
9
        .compile("temperature");
10

11
    // 2. Re-run this script only if the header or source actually changes.
12
    println!("cargo:rerun-if-changed=csrc/temperature.h");
13
    println!("cargo:rerun-if-changed=csrc/temperature.c");
14

15
    // 3. Generate Rust bindings from the C header.
16
    let bindings = bindgen::Builder::default()
17
        .header("csrc/temperature.h")
18
        .allowlist_function("temp_.*")   // only emit what we asked for
19
        .allowlist_type("Reading")
20
        .allowlist_type("TempUnit")
21
        .rustified_enum("TempUnit")      // make TempUnit a real Rust enum
22
        .derive_default(true)            // add #[derive(Default)] where safe
23
        .generate()
24
        .expect("unable to generate bindings");
25

26
    // 4. Write the generated Rust into OUT_DIR for `include!`.
27
    let out_path = PathBuf::from(env::var("OUT_DIR").unwrap());
28
    bindings
29
        .write_to_file(out_path.join("bindings.rs"))
30
        .expect("couldn't write bindings");
31
}

Finally, pull the generated file into a private ffi module and build a safe wrapper on top of it:

1
#![allow(non_upper_case_globals, non_camel_case_types, non_snake_case)]
2

3
mod ffi {
4
    // The generated file lives in OUT_DIR, not in your source tree.
5
    include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
6
}
7

8
/// A temperature value tagged with its unit (safe Rust mirror of the C enum).
9
#[derive(Clone, Copy, Debug)]
10
pub enum Unit {
11
    Celsius,
12
    Fahrenheit,
13
    Kelvin,
14
}
15

16
impl From<Unit> for ffi::TempUnit {
17
    fn from(u: Unit) -> Self {
18
        match u {
19
            Unit::Celsius => ffi::TempUnit::TEMP_CELSIUS,
20
            Unit::Fahrenheit => ffi::TempUnit::TEMP_FAHRENHEIT,
21
            Unit::Kelvin => ffi::TempUnit::TEMP_KELVIN,
22
        }
23
    }
24
}
25

26
/// Convert `value` (in `from` units) to `to` units. Safe wrapper over the C call.
27
pub fn convert(value: f64, from: Unit, to: Unit) -> f64 {
28
    let reading = ffi::Reading { value, unit: from.into() };
29
    // SAFETY: `Reading` is plain old data with no invariants; any `TempUnit`
30
    // discriminant is valid, and `temp_convert` has no preconditions.
31
    unsafe { ffi::temp_convert(reading, to.into()) }
32
}
33

34
/// How many conversions the C library has performed.
35
pub fn conversion_count() -> u64 {
36
    // SAFETY: a parameterless C call that only reads a counter.
37
    unsafe { ffi::temp_conversion_count() }
38
}
39

40
fn main() {
41
    let f = convert(100.0, Unit::Celsius, Unit::Fahrenheit);
42
    let k = convert(32.0, Unit::Fahrenheit, Unit::Kelvin);
43
    println!("100C = {f}F");
44
    println!("32F  = {k}K");
45
    println!("conversions so far: {}", conversion_count());
46
}

Running it produces this real output:

1
$ cargo run --quiet
2
100C = 212F
3
32F  = 273.15K
4
conversions so far: 2

Note: bindgen needs libclang installed at build time (it is the C parser). On macOS it ships with the Xcode Command Line Tools; on Debian/Ubuntu install libclang-dev; on Windows install LLVM. If bindgen cannot find it, set LIBCLANG_PATH to the directory containing libclang.{so,dylib,dll}.

Detailed Explanation

What bindgen actually wrote. The build.rs above produced this bindings.rs (shown verbatim, trimmed only of blank lines). Reading it teaches you exactly what bindgen does:

1
// $OUT_DIR/bindings.rs — generated by bindgen 0.72.1
2
#[repr(u32)]
3
#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
4
pub enum TempUnit {
5
    TEMP_CELSIUS = 0,
6
    TEMP_FAHRENHEIT = 1,
7
    TEMP_KELVIN = 2,
8
}
9
#[repr(C)]
10
#[derive(Debug, Copy, Clone)]
11
pub struct Reading {
12
    pub value: f64,
13
    pub unit: TempUnit,
14
}
15
#[allow(clippy::unnecessary_operation, clippy::identity_op)]
16
const _: () = {
17
    ["Size of Reading"][::std::mem::size_of::<Reading>() - 16usize];
18
    ["Alignment of Reading"][::std::mem::align_of::<Reading>() - 8usize];
19
    ["Offset of field: Reading::value"][::std::mem::offset_of!(Reading, value) - 0usize];
20
    ["Offset of field: Reading::unit"][::std::mem::offset_of!(Reading, unit) - 8usize];
21
};
22
impl Default for Reading {
23
    fn default() -> Self {
24
        let mut s = ::std::mem::MaybeUninit::<Self>::uninit();
25
        unsafe {
26
            ::std::ptr::write_bytes(s.as_mut_ptr(), 0, 1);
27
            s.assume_init()
28
        }
29
    }
30
}
31
unsafe extern "C" {
32
    pub fn temp_convert(reading: Reading, to: TempUnit) -> f64;
33
}
34
unsafe extern "C" {
35
    pub fn temp_conversion_count() -> u64;
36
}

Line by line:

#[repr(C)] struct Reading mirrors the C struct field-for-field. The #[repr(C)] attribute pins the field layout so it matches what the C compiler produced — Rust’s default repr(Rust) layout is deliberately unspecified and would not be ABI-compatible. (See ffi-basics.md for #[repr(C)] in depth.)
The const _: () = { ... } block is a compile-time layout assertion. bindgen bakes in the sizes and field offsets it observed from the C compiler; if your platform lays the struct out differently, this block fails to compile rather than silently corrupting memory. It costs nothing at runtime.
impl Default for Reading appears only because we asked with .derive_default(true). bindgen cannot #[derive(Default)] here (the value-then-unit layout needs zeroing) so it writes an explicit zero-initializing impl.
unsafe extern "C" { ... } are the raw function declarations. The unsafe extern block syntax is the latest-stable form (Rust 1.96.0, 2024 edition): every extern block is now written unsafe extern and each declared function is implicitly unsafe to call, because Rust cannot verify a foreign function upholds any of its safety contract.

Why OUT_DIR and include!. The build script writes into OUT_DIR, a per-build scratch directory Cargo provides, and src/main.rs pulls it in with include!(concat!(env!("OUT_DIR"), "/bindings.rs")). This keeps the multi-thousand-line generated file out of version control and guarantees it is regenerated whenever the header changes.

Why the #![allow(...)] at the top. bindgen preserves C naming (TEMP_CELSIUS, Reading), which violates Rust’s non_camel_case_types / non_upper_case_globals style lints. Without the allow attribute, the compiler warns:

1
warning: variant `TEMP_CELSIUS` should have an upper camel case name
2
warning: variant `TEMP_FAHRENHEIT` should have an upper camel case name
3
warning: variant `TEMP_KELVIN` should have an upper camel case name

Confining the bindings to a mod ffi { ... } and allowing those lints there is the standard way to silence the noise without disabling the lints crate-wide.

Why every call sits in unsafe. The generated functions are unsafe. Our convert and conversion_count wrap each call in a small unsafe { } block with a // SAFETY: comment justifying why the call is sound, then expose a safe signature. This is the unsafe-inside / safe-outside pattern that the rest of your program (and your tests) can use without writing unsafe again — covered in depth in safety-abstractions.md.

Key Differences

Aspect	TypeScript `.d.ts` generation	Rust bindgen
Input	A `.js`/schema file	A C/C++ header (`.h`)
Output	Type declarations, erased at runtime	Real `extern "C"` declarations the linker uses
Runtime effect	None (types are erased)	The bindings are the call sites
Safety of output	N/A (no runtime enforcement)	Raw and `unsafe`; you wrap them
When it runs	Build/tooling step	`build.rs` during `cargo build`
Layout correctness	Not applicable	Verified by compile-time `size_of`/offset assertions

Rustified vs. constant enums. .rustified_enum("TempUnit") turns the C enum into a real Rust enum, which is ergonomic to match on. Without it, bindgen’s default is safer for arbitrary C: it emits a type alias plus constants, because a C enum value read from foreign memory could legally hold a discriminant your Rust enum does not list, and constructing an out-of-range Rust enum is undefined behavior. The default output looks like this:

1
// Default bindgen output for the same enum (no .rustified_enum call):
2
pub const TempUnit_TEMP_CELSIUS: TempUnit = 0;
3
pub const TempUnit_TEMP_FAHRENHEIT: TempUnit = 1;
4
pub const TempUnit_TEMP_KELVIN: TempUnit = 2;
5
pub type TempUnit = ::std::os::raw::c_uint;

Use .rustified_enum() only for enums you fully control and whose values you trust. For enums whose value comes back across the FFI boundary from C, prefer the default (or .newtype_enum()) to avoid UB. This is exactly the kind of trade-off the bindgen API forces you to think about, and it has no analog in .d.ts generation.

bindgen is descriptive, not safe. A generated .d.ts lying about a type just produces a TypeScript error you can ignore with as any. bindgen producing a wrong declaration (e.g. you hand-edited it, or the C compiler disagrees about layout) produces undefined behavior at runtime. The layout assertions catch the most common case; you remain responsible for the rest.

Common Pitfalls

Pitfall 1: calling a generated function outside unsafe. The bindings are unsafe extern, so every call must be inside an unsafe block. Forgetting it is a hard error, not a warning:

1
// does not compile (error[E0133]): a generated extern fn called outside unsafe
2
fn main() {
3
    let n = ffi::temp_conversion_count();
4
    println!("{n}");
5
}

The real compiler output:

1
error[E0133]: call to unsafe function `ffi::temp_conversion_count` is unsafe and requires unsafe block
2
 --> src/main.rs:5:13
3
  |
4
5 |     let n = ffi::temp_conversion_count();
5
  |             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ call to unsafe function
6
  |
7
  = note: consult the function's documentation for information on how to avoid undefined behavior

The fix is the wrapper pattern shown above: one small unsafe { } block with a SAFETY: justification, exposed behind a safe fn.

Pitfall 2: forgetting rerun-if-changed. Without the cargo:rerun-if-changed=... lines, Cargo’s default heuristic re-runs build.rs whenever any file in the crate changes — but if you edit the C header in a way Cargo does not notice, your bindings can go stale. Always list the header (and source) explicitly so edits trigger regeneration.

Pitfall 3: generating the entire transitive header. Pointing bindgen at a header that #includes <stdint.h>, <stdio.h>, and friends will, by default, emit bindings for everything those pull in — thousands of lines and slow builds. Use allowlist_function, allowlist_type, and allowlist_var (regex-based) to emit only the API you actually call, as the example does with allowlist_function("temp_.*").

Pitfall 4: assuming bindgen makes things safe. It does not. A bindgen’d function that takes a *const c_char still expects a valid, NUL-terminated, correctly-aliased pointer. bindgen gives you a faithful but raw declaration; upholding the C function’s preconditions is entirely on you (see raw-pointers.md and calling-c.md).

Pitfall 5: missing libclang. If the build fails with a message about not finding libclang, it is an environment problem, not a code problem — install the platform’s clang/LLVM development package and, if needed, set LIBCLANG_PATH.

Best Practices

Confine bindings to a private mod ffi with #![allow(non_upper_case_globals, non_camel_case_types, non_snake_case)] (or use bindgen’s .raw_line("...") to inject the allow into the generated file). Never re-export raw bindings as your crate’s public API.
Always wrap, never expose. Build a safe Rust API (convert, slugify, …) over the raw bindings and keep unsafe blocks small with explicit // SAFETY: comments. The two-crate convention — a *-sys crate holding only raw bindings and a sibling crate holding the safe wrapper — is the ecosystem standard (openssl-sys + openssl, libgit2-sys + git2, and so on).
Allowlist aggressively to keep generated output small, readable, and fast to compile.
Pin layout with the generated assertions (they are on by default) and let derive_default/derive_debug/derive_partialeq add the traits you need rather than hand-writing impls.
Use rerun-if-changed for every input file so incremental builds stay correct.
Prefer the default (constant) enum representation for values that originate in C; reserve .rustified_enum() for enums you fully own.
Vendor or feature-gate the C source. The cc crate compiling a checked-in csrc/ keeps builds reproducible; linking a system library instead means emitting cargo:rustc-link-lib=... from build.rs.

Tip: A standalone bindgen command-line tool exists (cargo install bindgen-cli) for quickly previewing what a header generates: bindgen csrc/temperature.h --allowlist-function 'temp_.*'. It is handy for exploration, but for real projects keep generation in build.rs so the bindings always track the header.

Real-World Example

A production-flavored wrapper: a C slugify function (the kind you might pull in from an existing C codebase) that turns arbitrary text into a URL-safe slug. It uses a caller-provided output buffer and a sentinel return value for “buffer too small” — a very common C convention that forces us to think about strings and error handling across the boundary.

1
#ifndef SLUG_H
2
#define SLUG_H
3

4
#include <stddef.h>
5

6
/*
7
 * Write a URL-safe slug of `input` into the caller-provided `out` buffer
8
 * (lowercase ASCII letters/digits, runs of other chars collapsed to '-').
9
 * Returns the number of bytes written (excluding the NUL terminator),
10
 * or (size_t)-1 if `out` was too small.
11
 */
12
size_t slugify(const char *input, char *out, size_t out_len);
13

14
#endif

1
#include "slug.h"
2
#include <ctype.h>
3

4
size_t slugify(const char *input, char *out, size_t out_len) {
5
    if (out_len == 0) return (size_t)-1;
6
    size_t w = 0;
7
    int prev_dash = 1; /* avoid leading dash */
8
    for (const char *p = input; *p; ++p) {
9
        unsigned char c = (unsigned char)*p;
10
        if (isalnum(c)) {
11
            if (w + 1 >= out_len) return (size_t)-1;
12
            out[w++] = (char)tolower(c);
13
            prev_dash = 0;
14
        } else if (!prev_dash) {
15
            if (w + 1 >= out_len) return (size_t)-1;
16
            out[w++] = '-';
17
            prev_dash = 1;
18
        }
19
    }
20
    while (w > 0 && out[w - 1] == '-') w--; /* trim trailing dash */
21
    out[w] = '\0';
22
    return w;
23
}

1
use std::env;
2
use std::path::PathBuf;
3

4
fn main() {
5
    cc::Build::new()
6
        .file("csrc/slug.c")
7
        .include("csrc")
8
        .compile("slug");
9
    println!("cargo:rerun-if-changed=csrc/slug.h");
10
    println!("cargo:rerun-if-changed=csrc/slug.c");
11

12
    let bindings = bindgen::Builder::default()
13
        .header("csrc/slug.h")
14
        .allowlist_function("slugify")
15
        .generate()
16
        .expect("unable to generate bindings");
17

18
    let out = PathBuf::from(env::var("OUT_DIR").unwrap());
19
    bindings
20
        .write_to_file(out.join("bindings.rs"))
21
        .expect("couldn't write bindings");
22
}

bindgen emits this declaration for the function (note the C char * becomes *const/*mut ::std::os::raw::c_char):

1
unsafe extern "C" {
2
    pub fn slugify(
3
        input: *const ::std::os::raw::c_char,
4
        out: *mut ::std::os::raw::c_char,
5
        out_len: usize,
6
    ) -> usize;
7
}

The safe wrapper marshals a Rust &str into a C string, provides an output buffer, decodes the sentinel return value into a Result, and reads the result back as UTF-8:

1
#![allow(non_upper_case_globals, non_camel_case_types, non_snake_case)]
2

3
mod ffi {
4
    include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
5
}
6

7
use std::ffi::{CStr, CString};
8

9
/// Errors that the safe `slugify` wrapper can return.
10
#[derive(Debug, PartialEq, Eq)]
11
pub enum SlugError {
12
    /// The input contained an interior NUL byte (not a valid C string).
13
    InteriorNul,
14
    /// The output buffer was too small for the result.
15
    BufferTooSmall,
16
}
17

18
/// Turn arbitrary text into a URL-safe slug, delegating to the C `slugify`.
19
pub fn slugify(input: &str) -> Result<String, SlugError> {
20
    // 1. Marshal the &str into a NUL-terminated C string.
21
    let c_input = CString::new(input).map_err(|_| SlugError::InteriorNul)?;
22

23
    // 2. Provide an output buffer the C side will fill. A slug is never longer
24
    //    than the input, so input length + 1 (for the NUL) is always enough.
25
    let mut out = vec![0u8; input.len() + 1];
26

27
    // SAFETY: `c_input` is a valid NUL-terminated string; `out` points to
28
    // `out.len()` writable bytes; `slugify` only writes within that span and
29
    // NUL-terminates. Both borrows outlive the call.
30
    let written = unsafe {
31
        ffi::slugify(
32
            c_input.as_ptr(),
33
            out.as_mut_ptr() as *mut std::os::raw::c_char,
34
            out.len(),
35
        )
36
    };
37

38
    // The C API signals failure with (size_t)-1, which maps to usize::MAX.
39
    if written == usize::MAX {
40
        return Err(SlugError::BufferTooSmall);
41
    }
42

43
    // SAFETY: on success the C function wrote `written` bytes plus a NUL,
44
    // so `out` is a valid C string.
45
    let slug = unsafe { CStr::from_ptr(out.as_ptr() as *const std::os::raw::c_char) };
46
    Ok(slug.to_string_lossy().into_owned())
47
}
48

49
#[cfg(test)]
50
mod tests {
51
    use super::*;
52

53
    #[test]
54
    fn basic_slug() {
55
        assert_eq!(slugify("Hello, World!").unwrap(), "hello-world");
56
    }
57

58
    #[test]
59
    fn collapses_and_trims() {
60
        assert_eq!(slugify("  Rust & TS:  FFI  ").unwrap(), "rust-ts-ffi");
61
    }
62

63
    #[test]
64
    fn rejects_interior_nul() {
65
        assert_eq!(slugify("a\0b"), Err(SlugError::InteriorNul));
66
    }
67
}

Running the tests gives this real output:

1
$ cargo test --quiet
2
running 3 tests
3
...
4
test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.01s

Notice how all the FFI danger — the raw pointers, the NUL handling, the sentinel decoding — is contained inside one function. Callers and tests work entirely with &str, String, and Result. The CString/CStr types that bridge Rust strings and C strings are covered in calling-c.md.

Exercises

Exercise 1: Allowlist the noise away

Difficulty: Beginner

Objective: See the difference allowlisting makes and keep generated output minimal.

Instructions: Take the temperature.h from this page and write a build.rs that generates bindings without any allowlist_* calls, then build. Observe how much extra code (e.g. items pulled in from <stdint.h>) appears in $OUT_DIR/bindings.rs. Then add allowlist_function("temp_.*") and the two allowlist_type calls and compare. Which approach would you ship?

Solution

1
// build.rs — the allowlisted version (what you should ship).
2
use std::env;
3
use std::path::PathBuf;
4

5
fn main() {
6
    cc::Build::new()
7
        .file("csrc/temperature.c")
8
        .include("csrc")
9
        .compile("temperature");
10
    println!("cargo:rerun-if-changed=csrc/temperature.h");
11
    println!("cargo:rerun-if-changed=csrc/temperature.c");
12

13
    let bindings = bindgen::Builder::default()
14
        .header("csrc/temperature.h")
15
        .allowlist_function("temp_.*")
16
        .allowlist_type("Reading")
17
        .allowlist_type("TempUnit")
18
        .rustified_enum("TempUnit")
19
        .generate()
20
        .expect("unable to generate bindings");
21

22
    let out = PathBuf::from(env::var("OUT_DIR").unwrap());
23
    bindings
24
        .write_to_file(out.join("bindings.rs"))
25
        .expect("couldn't write bindings");
26
}

Without the allowlist calls, bindgen emits declarations for everything reachable from the header, including types dragged in by #include <stdint.h>. The allowlisted version emits only TempUnit, Reading, temp_convert, and temp_conversion_count. Always ship the allowlisted version: smaller output, faster compiles, and a clearer contract.

Exercise 2: A safe rounding wrapper

Difficulty: Intermediate

Objective: Build a safe API over a generated binding and add a Rust ergonomic feature.

Instructions: Using the temperature library, add a safe function convert_rounded(value: f64, from: Unit, to: Unit, decimals: u32) -> f64 that calls the C temp_convert through the bindings and rounds the result to decimals decimal places. Keep the unsafe call confined to a wrapper and write a test asserting convert_rounded(98.6, Unit::Fahrenheit, Unit::Celsius, 2) == 37.0.

Solution

1
// src/main.rs (additions)
2
/// Convert and round to `decimals` decimal places.
3
pub fn convert_rounded(value: f64, from: Unit, to: Unit, decimals: u32) -> f64 {
4
    let raw = convert(value, from, to); // convert() already wraps the unsafe call
5
    let factor = 10f64.powi(decimals as i32);
6
    (raw * factor).round() / factor
7
}
8

9
#[cfg(test)]
10
mod tests {
11
    use super::*;
12

13
    #[test]
14
    fn rounds_to_two_places() {
15
        assert_eq!(convert_rounded(98.6, Unit::Fahrenheit, Unit::Celsius, 2), 37.0);
16
    }
17
}

1
$ cargo test --quiet
2
running 1 test
3
.
4
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

The key idea: convert_rounded never writes unsafe itself — it builds on the already-safe convert, so the unsafe surface stays as small as possible.

Exercise 3: Choose the right enum representation

Difficulty: Advanced

Objective: Understand why .rustified_enum() can be unsound for values that come from C, and pick a safe representation.

Instructions: Suppose a C function TempUnit detect_unit(const char *label); returns a TempUnit parsed from user input, and a buggy or hostile C implementation could return 99 for unknown labels. Explain why binding this enum with .rustified_enum("TempUnit") and matching on the result is undefined behavior, and rewrite the bindgen configuration to make it sound. Show how the safe wrapper would validate the returned value.

Solution

A Rust enum may only ever hold one of its declared discriminants — holding any other bit pattern is instant undefined behavior. With .rustified_enum("TempUnit"), detect_unit is typed to return the Rust enum TempUnit, so if C returns 99 you have already constructed an invalid enum before you even match on it. The cure is to not rustify enums whose values originate in C; use the default (or .newtype_enum()), receive the value as a plain integer, and validate it:

1
// build.rs — drop .rustified_enum() and use newtype_enum instead.
2
let bindings = bindgen::Builder::default()
3
    .header("csrc/temperature.h")
4
    .allowlist_function("temp_.*")
5
    .allowlist_function("detect_unit")
6
    .allowlist_type("Reading")
7
    .allowlist_type("TempUnit")
8
    .newtype_enum("TempUnit") // a #[repr(transparent)] wrapper, not a Rust enum
9
    .generate()
10
    .expect("unable to generate bindings");

1
// src/main.rs — validate the C-provided value before trusting it.
2
pub fn detect_unit(label: &str) -> Option<Unit> {
3
    let c_label = std::ffi::CString::new(label).ok()?;
4
    // SAFETY: `c_label` is a valid NUL-terminated string for the call's duration.
5
    let raw = unsafe { ffi::detect_unit(c_label.as_ptr()) };
6
    match raw {
7
        ffi::TempUnit::TEMP_CELSIUS => Some(Unit::Celsius),
8
        ffi::TempUnit::TEMP_FAHRENHEIT => Some(Unit::Fahrenheit),
9
        ffi::TempUnit::TEMP_KELVIN => Some(Unit::Kelvin),
10
        _ => None, // an unknown discriminant like 99 is handled, not UB
11
    }
12
}

With newtype_enum, TempUnit is a #[repr(transparent)] struct wrapping an integer plus the known-variant constants, so receiving 99 is a perfectly valid value that your match rejects safely — no undefined behavior, ever.

Generating Bindings with bindgen

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

Key Differences

Common Pitfalls

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1: Allowlist the noise away

Exercise 2: A safe rounding wrapper

Exercise 3: Choose the right enum representation