## File: README.md

[](https://crates.io/crates/bindgen)
[](https://docs.rs/bindgen/)

# `bindgen`

**`bindgen` automatically generates Rust FFI bindings to C (and some C++) libraries.**

For example, given the C header `doggo.h`:

```c
typedef struct Doggo {
    int many;
    char wow;
} Doggo;

void eleven_out_of_ten_majestic_af(Doggo* pupper);
```

`bindgen` produces Rust FFI code allowing you to call into the `doggo` library's
functions and use its types:

```rust
/* automatically generated by rust-bindgen 0.99.9 */

#[repr(C)]
pub struct Doggo {
    pub many: ::std::os::raw::c_int,
    pub wow: ::std::os::raw::c_char,
}

extern "C" {
    pub fn eleven_out_of_ten_majestic_af(pupper: *mut Doggo);
}
```

## Users Guide

[📚 Read the `bindgen` users guide here! 📚](https://rust-lang.github.io/rust-bindgen)

## MSRV

The `bindgen` minimum supported Rust version is **1.71.0**.

The `bindgen-cli` minimum supported Rust version is **1.71.0**.

No MSRV bump policy has been established yet, so MSRV may increase in any release.

The MSRV is the minimum Rust version that can be used to *compile* each crate. However, `bindgen` and `bindgen-cli` can generate bindings that are compatible with Rust versions below the current MSRV.

Most of the time, the `bindgen-cli` crate will have a more recent MSRV than `bindgen` as crates such as `clap` require it. 

## API Reference

[API reference documentation is on docs.rs](https://docs.rs/bindgen)

## Environment Variables

In addition to the [library API](https://docs.rs/bindgen) and [executable command-line API][bindgen-cmdline],
`bindgen` can be controlled through environment variables.

End-users should set these environment variables to modify `bindgen`'s behavior without modifying the source code of direct consumers of `bindgen`.

- `BINDGEN_EXTRA_CLANG_ARGS`: extra arguments to pass to `clang`
    - Arguments are whitespace-separated
    - Use shell-style quoting to pass through whitespace
    - Examples:
        - Specify alternate sysroot: `--sysroot=/path/to/sysroot`
        - Add include search path with spaces: `-I"/path/with spaces"`
- `BINDGEN_EXTRA_CLANG_ARGS_<TARGET>`: similar to `BINDGEN_EXTRA_CLANG_ARGS`,
   but used to set per-target arguments to pass to clang. Useful to set system include
   directories in a target-specific way in cross-compilation environments with multiple targets.
   Has precedence over `BINDGEN_EXTRA_CLANG_ARGS`.

Additionally, `bindgen` uses `libclang` to parse C and C++ header files.
To modify how `bindgen` searches for `libclang`, see the [`clang-sys` documentation][clang-sys-env].
For more details on how `bindgen` uses `libclang`, see the [`bindgen` users guide][bindgen-book-clang].

## Releases

We don't follow a specific release calendar, but if you need a release please
file an issue requesting that (ping `@emilio` for increased effectiveness).

## Contributing

[See `CONTRIBUTING.md` for hacking on `bindgen`!](./CONTRIBUTING.md)

[bindgen-cmdline]: https://rust-lang.github.io/rust-bindgen/command-line-usage.html
[clang-sys-env]: https://github.com/KyleMayes/clang-sys#environment-variables
[bindgen-book-clang]: https://rust-lang.github.io/rust-bindgen/requirements.html#clang

---

## File: csmith-fuzzing/README.md

# Fuzzing `bindgen` with `csmith`

[`csmith`][csmith] generates random C and C++ programs that can be used as test
cases for compilers. When testing `bindgen` with `csmith`, we interpret the
generated programs as header files, and emit Rust bindings to them. If `bindgen`
panics, the emitted bindings won't compile with `rustc`, or the generated layout
tests in the bindings fail, then we report an issue containing the test case!





- [Prerequisites](#prerequisites)
- [Running the Fuzzer](#running-the-fuzzer)
- [Reporting Issues](#reporting-issues)



## Prerequisites

Requires `python3`, `csmith`, and `creduce` to be in `$PATH`.

Many OS package managers have `csmith` and `creduce` packages:

```
$ sudo apt install csmith creduce
$ brew install csmith creduce
$ # Etc...
```

## Running the Fuzzer

Run `csmith` and test `bindgen` on the generated test cases with this command:

```
$ ./driver.py
```

The driver will keep running until it encounters an error in `bindgen`.

Each invocation of `./driver.py` will use its own temporary directories, so
running it in multiple terminals in parallel is supported.

`csmith` is run with `--no-checksum --nomain --max-block-size 1
--max-block-depth 1` which disables the `main` function, and makes function
bodies as simple as possible as `bindgen` does not care about them, but they
cannot be completely disabled in `csmith`. Run `csmith --help` to see what
exactly those options do.

## Reporting Issues

Once the fuzz driver finds a test case that causes some kind of error in
`bindgen` or its emitted bindings, it is helpful to
[run C-Reduce on the test case][creducing] to remove the parts that are
irrelevant to reproducing the error. This is ***very*** helpful for the folks
who further investigate the issue and come up with a fix!

Additionally, mention that you discovered the issue via `csmith` and we will add
the `A-csmith` label. You can find all the issues discovered with `csmith`, and
related to fuzzing with `csmith`, by looking up
[all issues tagged with the `A-csmith` label][csmith-issues].

[csmith]: https://github.com/csmith-project/csmith
[creducing]: ../CONTRIBUTING.md#using-creduce-to-minimize-test-cases
[csmith-issues]: https://github.com/rust-lang/rust-bindgen/issues?q=label%3AA-csmith