Generar bindings: bindgen y cbindgen en vez de declarar a mano

Declarar abs y strlen a mano es didáctico. Ponerse a transcribir SQLite —cientos de funciones, decenas de struct, constantes, enum, macros— a mano es una forma lenta de fabricar undefined behavior: cada firma copiada mal, cada c_int donde iba c_long, cada campo en el orden equivocado es una corrupción silenciosa que el compilador no puede detectar porque, como ya sabes, no ve el otro lado. La respuesta profesional no es “tener más cuidado”: es no escribir las declaraciones a mano en absoluto. Dos herramientas automatizan cada dirección de la frontera. bindgen lee las cabeceras .h de C y emite las declaraciones Rust equivalentes —los bloques unsafe extern, los #[repr(C)], los alias, las constantes—. cbindgen hace lo inverso: lee tu API Rust exportada y produce la cabecera .h que un consumidor de C necesita. El lema del nivel es: generar, no transcribir.

bindgen: de las cabeceras C a Rust

El patrón canónico es el crate -sys: un crate cuya única misión es exponer las declaraciones crudas de una biblioteca C. bindgen se declara como dependencia de compilación y se invoca desde build.rs, que escribe el resultado en OUT_DIR:

[build-dependencies]
bindgen = "0.70"

// build.rs
use std::{env, path::PathBuf};

fn main() {
    println!("cargo:rustc-link-lib=foo");   // enlaza libfoo
    let bindings = bindgen::Builder::default()
        .header("wrapper.h")                 // cabecera que incluye lo que quieres
        .generate()
        .expect("no se pudieron generar los bindings");
    let salida = PathBuf::from(env::var("OUT_DIR").unwrap());
    bindings.write_to_file(salida.join("bindings.rs")).unwrap();
}

El fichero wrapper.h no es más que un #include de las cabeceras que te interesan. Y el crate incorpora el resultado con una macro include!:

// lib.rs
#![allow(non_upper_case_globals, non_camel_case_types, non_snake_case)]
include!(concat!(env!("OUT_DIR"), "/bindings.rs"));

bindgen usa libclang para parsear C de verdad —no una heurística— y emite el unsafe extern "C", los struct con #[repr(C)], los alias de tipo y las constantes, todo ajustado a la plataforma de destino. Generarlo en build.rs garantiza que los anchos y el layout se recalculan en cada máquina donde compilas.

cbindgen: de Rust a la cabecera C

La dirección inversa, la que corona la lección anterior. Escribiste una biblioteca Rust con funciones #[unsafe(no_mangle)] pub extern "C"; cbindgen la escanea y genera el .h con los prototipos, los struct y los enum correspondientes:

cbindgen --config cbindgen.toml --crate mi_crate --output mi_crate.h

También puede invocarse desde build.rs para regenerar la cabecera en cada compilación. Con ese .h en la mano, cualquier programa de C o C++ puede consumir tu biblioteca Rust sin que tú escribas el prototipo a mano ni corras el riesgo de que la cabecera se desincronice de la firma real.

flowchart TB
H[Cabecera C punto h] -->|bindgen mas libclang| R[bindings.rs con unsafe extern C]
R --> W[Wrapper seguro escrito a mano]
A[API Rust con extern C] -->|cbindgen| G[Cabecera C generada]
G --> Cc[Consumidor en C o C plus plus]
style H fill:#fab387,color:#11111b
style R fill:#89b4fa,color:#11111b
style W fill:#a6e3a1,color:#11111b
style G fill:#cba6f7,color:#11111b

Lo que la herramienta no decide

Aquí está el punto que separa usar bindgen de entenderlo. Lo que genera es una traducción cruda y uno-a-uno: el crate -sys. Reproduce la sintaxis de las firmas con fidelidad mecánica, pero no conoce la semántica. No sabe quién libera cada puntero, cuáles pueden ser nulos, qué función exige que llames antes a otra, ni qué invariantes debe cumplir un struct. Todo eso vive en la documentación y en la cabeza de quien escribió la biblioteca, no en los tipos de C. Por eso las declaraciones generadas son todas unsafe: la herramienta te da la ABI correcta, no la seguridad.

De ahí la convención de dos capas que verás en todo el ecosistema:

Afinar bindgen: no traduzcas la biblioteca entera

Por defecto bindgen traduce todo lo que alcanza desde la cabecera, y eso arrastra media libc por culpa de los #include transitivos. En la práctica se acota con listas de permitidos y se refinan los tipos generados:

let bindings = bindgen::Builder::default()
    .header("wrapper.h")
    .allowlist_function("foo_.*")   // solo lo que empieza por foo_
    .allowlist_type("Foo.*")
    .newtype_enum("FooStatus")      // enum C como newtype con constantes
    .derive_default(true)           // deriva Default donde sea posible
    .generate()
    .unwrap();

allowlist_function y allowlist_type recortan la superficie a lo que de verdad usas; newtype_enum evita el peligro de tratar un enum de C como exhaustivo cuando C puede devolver un valor fuera del conjunto declarado. Afinar bindgen no es cosmética: un binding más pequeño es menos superficie unsafe que auditar.