bindgen

Example Code

```rust
// The example consists of five files:
// 1. Cargo.toml: Defines project dependencies.
// 2. src/my_c_lib.h: A simple C header file.
// 3. src/my_c_lib.c: The C implementation file.
// 4. build.rs: The build script that uses bindgen to generate Rust bindings.
// 5. src/main.rs: The main Rust application that uses the generated bindings.

// --- Cargo.toml ---
// Add these to your Cargo.toml
// For a new project, run `cargo new rust_bindgen_example`
// and then modify the generated Cargo.toml

[package]
name = "rust_bindgen_example"
version = "0.1.0"
edition = "2021"

[build-dependencies]
bindgen = "0.69.4" # Use the latest stable version
cc = "1.0.87"    # For compiling the C code

[dependencies]
# No direct dependencies needed for the main app for this simple example


// --- src/my_c_lib.h ---
// This is the C header file that bindgen will parse.

#ifndef MY_C_LIB_H
#define MY_C_LIB_H

// A simple C function to greet a name
void greet(const char* name);

// A simple C function to add two integers
int add(int a, int b);

// A C struct
typedef struct {
    int x;
    int y;
} Point;

// A C function that takes and returns a struct
Point create_point(int x, int y);

#endif // MY_C_LIB_H


// --- src/my_c_lib.c ---
// This is the C implementation file.

#include "my_c_lib.h"
#include <stdio.h>

void greet(const char* name) {
    printf("Hello from C, %s!\n", name);
}

int add(int a, int b) {
    return a + b;
}

Point create_point(int x, int y) {
    Point p = { x, y };
    return p;
}


// --- build.rs ---
// This script uses bindgen to generate Rust FFI bindings for my_c_lib.h
// and `cc` to compile my_c_lib.c into a static library.

extern crate bindgen;
extern crate cc;

use std::env;
use std::path::PathBuf;

fn main() {
    // Tell cargo to re-run this build script if the C header or source changes.
    println!("cargo:rerun-if-changed=src/my_c_lib.h");
    println!("cargo:rerun-if-changed=src/my_c_lib.c");

    // Compile the C library using the `cc` crate.
    // This will create a static library (e.g., `libmy_c_lib.a` on Linux)
    // in Cargo's target directory.
    cc::Build::new()
        .file("src/my_c_lib.c")
        .compile("my_c_lib"); // The name of the resulting static library file (e.g., `libmy_c_lib.a`)

    // Generate the Rust bindings using `bindgen`.
    let bindings = bindgen::Builder::default()
        // The input C header file we want to generate bindings for.
        .header("src/my_c_lib.h")
        // Tell cargo to invalidate the built crate whenever any of the
        // included header files changed. This is crucial for keeping bindings up-to-date.
        .parse_callbacks(Box::new(bindgen::CargoCallbacks))
        // Finish the builder and generate the bindings.
        .generate()
        .expect("Unable to generate bindings");

    // Write the generated bindings to a file in Cargo's `$OUT_DIR`.
    // The `OUT_DIR` environment variable points to a directory managed by Cargo
    // for build artifacts.
    let out_path = PathBuf::from(env::var("OUT_DIR").unwrap());
    bindings
        .write_to_file(out_path.join("bindings.rs"))
        .expect("Couldn't write bindings!");
}


// --- src/main.rs ---
// This is the main Rust application that uses the generated FFI bindings.

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

// Include the generated bindings. This macro loads the content of
// the `bindings.rs` file created by `build.rs`.
// `env!("OUT_DIR")` provides the path to Cargo's output directory.
include!(concat!(env!("OUT_DIR"), "/bindings.rs"));

fn main() {
    // --- Calling C functions ---

    // Prepare a C string from a Rust string for `greet` function.
    // CString ensures null termination.
    let name = CString::new("Rustacean").expect("CString::new failed");

    // FFI calls are inherently unsafe because Rust's safety guarantees
    // cannot be enforced on external C code. Thus, they must be wrapped in `unsafe`.
    unsafe {
        // Call the C greet function
        greet(name.as_ptr());
    }

    // Call the C add function
    let a = 10;
    let b = 20;
    let sum = unsafe { add(a, b) };
    println!("Result from C add: {} + {} = {}", a, b, sum);

    // --- Using C structs ---

    // Create a Point struct using the C function.
    let p = unsafe { create_point(5, 10) };
    println!("Created C Point: x={}, y={}", p.x, p.y);

    // You can also create a Point struct directly, though it's less common
    // if C provides creation functions.
    let mut p2 = Point { x: 100, y: 200 };
    println!("Directly created C Point: x={}, y={}", p2.x, p2.y);
    p2.x = 150; // Modify a field
    println!("Modified C Point: x={}, y={}", p2.x, p2.y);

    // Example of using a C string from a C function (if `greet` were to return one)
    // (Not directly used here, but demonstrates the pattern)
    // let c_str_ptr = unsafe { some_c_function_returning_a_string() };
    // let rust_str = unsafe { CStr::from_ptr(c_str_ptr) }.to_string_lossy().into_owned();
    // println!("String from C: {}", rust_str);
}
```

To run this example:
1.  Create a new Rust project: `cargo new rust_bindgen_example`
2.  Navigate into the directory: `cd rust_bindgen_example`
3.  Replace the `Cargo.toml` content with the one provided above.
4.  Create `src/my_c_lib.h` and `src/my_c_lib.c` with the content above.
5.  Create `build.rs` (in the project root, next to `src/` and `Cargo.toml`) with the content above.
6.  Replace `src/main.rs` content with the one provided above.
7.  Run the project: `cargo run`

This will trigger the `build.rs` script, which compiles `my_c_lib.c` and generates `bindings.rs`. Then, `src/main.rs` is compiled and executed, using the generated bindings to call the C functions.