README.md
1[](https://crates.io/crates/bindgen)
2[](https://docs.rs/bindgen/)
3
4# `bindgen`
5
6**`bindgen` automatically generates Rust FFI bindings to C (and some C++) libraries.**
7
8For example, given the C header `doggo.h`:
9
10```c
11typedef struct Doggo {
12 int many;
13 char wow;
14} Doggo;
15
16void eleven_out_of_ten_majestic_af(Doggo* pupper);
17```
18
19`bindgen` produces Rust FFI code allowing you to call into the `doggo` library's
20functions and use its types:
21
22```rust
23/* automatically generated by rust-bindgen 0.99.9 */
24
25#[repr(C)]
26pub struct Doggo {
27 pub many: ::std::os::raw::c_int,
28 pub wow: ::std::os::raw::c_char,
29}
30
31extern "C" {
32 pub fn eleven_out_of_ten_majestic_af(pupper: *mut Doggo);
33}
34```
35
36## Users Guide
37
38[�� Read the `bindgen` users guide here! ��](https://rust-lang.github.io/rust-bindgen)
39
40## MSRV
41
42The minimum supported Rust version is **1.46**.
43
44No MSRV bump policy has been established yet, so MSRV may increase in any release.
45
46## API Reference
47
48[API reference documentation is on docs.rs](https://docs.rs/bindgen)
49
50## Environment Variables
51
52In addition to the [library API](https://docs.rs/bindgen) and [executable command-line API][bindgen-cmdline],
53`bindgen` can be controlled through environment variables.
54
55End-users should set these environment variables to modify `bindgen`'s behavior without modifying the source code of direct consumers of `bindgen`.
56
57- `BINDGEN_EXTRA_CLANG_ARGS`: extra arguments to pass to `clang`
58 - Arguments are whitespace-separated
59 - Use shell-style quoting to pass through whitespace
60 - Examples:
61 - Specify alternate sysroot: `--sysroot=/path/to/sysroot`
62 - Add include search path with spaces: `-I"/path/with spaces"`
63- `BINDGEN_EXTRA_CLANG_ARGS_<TARGET>`: similar to `BINDGEN_EXTRA_CLANG_ARGS`,
64 but used to set per-target arguments to pass to clang. Useful to set system include
65 directories in a target-specific way in cross-compilation environments with multiple targets.
66 Has precedence over `BINDGEN_EXTRA_CLANG_ARGS`.
67
68Additionally, `bindgen` uses `libclang` to parse C and C++ header files.
69To modify how `bindgen` searches for `libclang`, see the [`clang-sys` documentation][clang-sys-env].
70For more details on how `bindgen` uses `libclang`, see the [`bindgen` users guide][bindgen-book-clang].
71
72## Releases
73
74We don't follow a specific release calendar, but if you need a release please
75file an issue requesting that (ping `@emilio` for increased effectiveness).
76
77## Contributing
78
79[See `CONTRIBUTING.md` for hacking on `bindgen`!](./CONTRIBUTING.md)
80
81[bindgen-cmdline]: https://rust-lang.github.io/rust-bindgen/command-line-usage.html
82[clang-sys-env]: https://github.com/KyleMayes/clang-sys#environment-variables
83[bindgen-book-clang]: https://rust-lang.github.io/rust-bindgen/requirements.html#clang
84
){kind=link}
){kind=link}