pub struct Builder { /* private fields */ }
Expand description
Configure and generate Rust bindings for a C/C++ header.
This is the main entry point to the library.
use bindgen::builder;
// Configure and generate bindings.
let bindings = builder().header("path/to/input/header")
.whitelisted_type("SomeCoolClass")
.whitelisted_function("do_some_cool_thing")
.generate()?;
// Write the generated bindings to an output file.
bindings.write_to_file("path/to/output.rs")?;
Enums
Bindgen can map C/C++ enums into Rust in different ways. The way bindgen maps enums depends on the pattern passed to several methods:
For each C enum, bindgen tries to match the pattern in the following order:
- Constified enum module
- Bitfield enum
- Rustified enum
If none of the above patterns match, then bindgen will generate a set of Rust constants.
Implementations§
source§impl Builder
impl Builder
sourcepub fn command_line_flags(&self) -> Vec<String> ⓘ
pub fn command_line_flags(&self) -> Vec<String> ⓘ
Generates the command line flags use for creating Builder
.
sourcepub fn header<T: Into<String>>(self, header: T) -> Builder
pub fn header<T: Into<String>>(self, header: T) -> Builder
Add an input C/C++ header to generate bindings for.
This can be used to generate bindings to a single header:
let bindings = bindgen::Builder::default()
.header("input.h")
.generate()
.unwrap();
Or you can invoke it multiple times to generate bindings to multiple headers:
let bindings = bindgen::Builder::default()
.header("first.h")
.header("second.h")
.header("third.h")
.generate()
.unwrap();
sourcepub fn header_contents(self, name: &str, contents: &str) -> Builder
pub fn header_contents(self, name: &str, contents: &str) -> Builder
Add contents
as an input C/C++ header named name
.
The file name
will be added to the clang arguments.
sourcepub fn rust_target(self, rust_target: RustTarget) -> Self
pub fn rust_target(self, rust_target: RustTarget) -> Self
Specify the rust target
The default is the latest stable Rust version
sourcepub fn disable_untagged_union(self) -> Self
pub fn disable_untagged_union(self) -> Self
Disable support for native Rust unions, if supported.
sourcepub fn emit_ir_graphviz<T: Into<String>>(self, path: T) -> Builder
pub fn emit_ir_graphviz<T: Into<String>>(self, path: T) -> Builder
Set the output graphviz file.
sourcepub fn generate_comments(self, doit: bool) -> Self
pub fn generate_comments(self, doit: bool) -> Self
Whether the generated bindings should contain documentation comments or not.
This ideally will always be true, but it may need to be false until we implement some processing on comments to work around issues as described in:
https://github.com/rust-lang-nursery/rust-bindgen/issues/426
sourcepub fn whitelist_recursively(self, doit: bool) -> Self
pub fn whitelist_recursively(self, doit: bool) -> Self
Whether to whitelist recursively or not. Defaults to true.
Given that we have explicitly whitelisted the “initiate_dance_party” function in this C header:
typedef struct MoonBoots {
int bouncy_level;
} MoonBoots;
void initiate_dance_party(MoonBoots* boots);
We would normally generate bindings to both the initiate_dance_party
function and the MoonBoots
struct that it transitively references. By
configuring with whitelist_recursively(false)
, bindgen
will not emit
bindings for anything except the explicitly whitelisted items, and there
would be no emitted struct definition for MoonBoots
. However, the
initiate_dance_party
function would still reference MoonBoots
!
Disabling this feature will almost certainly cause bindgen
to emit
bindings that will not compile! If you disable this feature, then it
is your responsibility to provide definitions for every type that is
referenced from an explicitly whitelisted item. One way to provide the
definitions is by using the Builder::raw_line
method, another would be to define them in Rust and then include!(...)
the bindings immediately afterwards.
sourcepub fn objc_extern_crate(self, doit: bool) -> Self
pub fn objc_extern_crate(self, doit: bool) -> Self
Generate #[macro_use] extern crate objc;
instead of use objc;
in the prologue of the files generated from objective-c files
sourcepub fn generate_block(self, doit: bool) -> Self
pub fn generate_block(self, doit: bool) -> Self
Generate proper block signatures instead of void pointers.
sourcepub fn block_extern_crate(self, doit: bool) -> Self
pub fn block_extern_crate(self, doit: bool) -> Self
Generate #[macro_use] extern crate block;
instead of use block;
in the prologue of the files generated from apple block files
sourcepub fn trust_clang_mangling(self, doit: bool) -> Self
pub fn trust_clang_mangling(self, doit: bool) -> Self
Whether to use the clang-provided name mangling. This is true by default and probably needed for C++ features.
However, some old libclang versions seem to return incorrect results in some cases for non-mangled functions, see 1, so we allow disabling it.
sourcepub fn hide_type<T: AsRef<str>>(self, arg: T) -> Builder
👎Deprecated: Use blacklist_type instead
pub fn hide_type<T: AsRef<str>>(self, arg: T) -> Builder
Hide the given type from the generated bindings. Regular expressions are supported.
sourcepub fn blacklist_type<T: AsRef<str>>(self, arg: T) -> Builder
pub fn blacklist_type<T: AsRef<str>>(self, arg: T) -> Builder
Hide the given type from the generated bindings. Regular expressions are supported.
sourcepub fn blacklist_function<T: AsRef<str>>(self, arg: T) -> Builder
pub fn blacklist_function<T: AsRef<str>>(self, arg: T) -> Builder
Hide the given function from the generated bindings. Regular expressions are supported.
sourcepub fn blacklist_item<T: AsRef<str>>(self, arg: T) -> Builder
pub fn blacklist_item<T: AsRef<str>>(self, arg: T) -> Builder
Hide the given item from the generated bindings, regardless of whether it’s a type, function, module, etc. Regular expressions are supported.
sourcepub fn opaque_type<T: AsRef<str>>(self, arg: T) -> Builder
pub fn opaque_type<T: AsRef<str>>(self, arg: T) -> Builder
Treat the given type as opaque in the generated bindings. Regular expressions are supported.
sourcepub fn whitelisted_type<T: AsRef<str>>(self, arg: T) -> Builder
👎Deprecated: use whitelist_type instead
pub fn whitelisted_type<T: AsRef<str>>(self, arg: T) -> Builder
Whitelist the given type so that it (and all types that it transitively refers to) appears in the generated bindings. Regular expressions are supported.
sourcepub fn whitelist_type<T: AsRef<str>>(self, arg: T) -> Builder
pub fn whitelist_type<T: AsRef<str>>(self, arg: T) -> Builder
Whitelist the given type so that it (and all types that it transitively refers to) appears in the generated bindings. Regular expressions are supported.
sourcepub fn whitelist_function<T: AsRef<str>>(self, arg: T) -> Builder
pub fn whitelist_function<T: AsRef<str>>(self, arg: T) -> Builder
Whitelist the given function so that it (and all types that it transitively refers to) appears in the generated bindings. Regular expressions are supported.
sourcepub fn whitelisted_function<T: AsRef<str>>(self, arg: T) -> Builder
👎Deprecated: use whitelist_function instead
pub fn whitelisted_function<T: AsRef<str>>(self, arg: T) -> Builder
Whitelist the given function.
Deprecated: use whitelist_function instead.
sourcepub fn whitelist_var<T: AsRef<str>>(self, arg: T) -> Builder
pub fn whitelist_var<T: AsRef<str>>(self, arg: T) -> Builder
Whitelist the given variable so that it (and all types that it transitively refers to) appears in the generated bindings. Regular expressions are supported.
sourcepub fn whitelisted_var<T: AsRef<str>>(self, arg: T) -> Builder
👎Deprecated: use whitelist_var instead
pub fn whitelisted_var<T: AsRef<str>>(self, arg: T) -> Builder
Whitelist the given variable.
Deprecated: use whitelist_var instead.
sourcepub fn default_enum_style(self, arg: EnumVariation) -> Builder
pub fn default_enum_style(self, arg: EnumVariation) -> Builder
Set the default style of code to generate for enums
sourcepub fn bitfield_enum<T: AsRef<str>>(self, arg: T) -> Builder
pub fn bitfield_enum<T: AsRef<str>>(self, arg: T) -> Builder
Mark the given enum (or set of enums, if using a pattern) as being bitfield-like. Regular expressions are supported.
This makes bindgen generate a type that isn’t a rust enum
. Regular
expressions are supported.
sourcepub fn rustified_enum<T: AsRef<str>>(self, arg: T) -> Builder
pub fn rustified_enum<T: AsRef<str>>(self, arg: T) -> Builder
Mark the given enum (or set of enums, if using a pattern) as a Rust enum.
This makes bindgen generate enums instead of constants. Regular expressions are supported.
Use this with caution. You should not be using Rust enums unless you have complete control of the C/C++ code that you’re binding to. Take a look at https://github.com/rust-lang/rust/issues/36927 for more information.
sourcepub fn constified_enum<T: AsRef<str>>(self, arg: T) -> Builder
pub fn constified_enum<T: AsRef<str>>(self, arg: T) -> Builder
Mark the given enum (or set of enums, if using a pattern) as a set of constants that are not to be put into a module.
sourcepub fn constified_enum_module<T: AsRef<str>>(self, arg: T) -> Builder
pub fn constified_enum_module<T: AsRef<str>>(self, arg: T) -> Builder
Mark the given enum (or set of enums, if using a pattern) as a set of constants that should be put into a module.
This makes bindgen generate modules containing constants instead of just constants. Regular expressions are supported.
sourcepub fn raw_line<T: Into<String>>(self, arg: T) -> Self
pub fn raw_line<T: Into<String>>(self, arg: T) -> Self
Add a string to prepend to the generated bindings. The string is passed through without any modification.
sourcepub fn module_raw_line<T, U>(self, mod_: T, line: U) -> Selfwhere
T: Into<String>,
U: Into<String>,
pub fn module_raw_line<T, U>(self, mod_: T, line: U) -> Selfwhere
T: Into<String>,
U: Into<String>,
Add a given line to the beginning of module mod
.
sourcepub fn module_raw_lines<T, I>(self, mod_: T, lines: I) -> Selfwhere
T: Into<String>,
I: IntoIterator,
I::Item: Into<String>,
pub fn module_raw_lines<T, I>(self, mod_: T, lines: I) -> Selfwhere
T: Into<String>,
I: IntoIterator,
I::Item: Into<String>,
Add a given set of lines to the beginning of module mod
.
sourcepub fn clang_arg<T: Into<String>>(self, arg: T) -> Builder
pub fn clang_arg<T: Into<String>>(self, arg: T) -> Builder
Add an argument to be passed straight through to clang.
sourcepub fn clang_args<I>(self, iter: I) -> Builderwhere
I: IntoIterator,
I::Item: AsRef<str>,
pub fn clang_args<I>(self, iter: I) -> Builderwhere
I: IntoIterator,
I::Item: AsRef<str>,
Add arguments to be passed straight through to clang.
sourcepub fn emit_builtins(self) -> Builder
pub fn emit_builtins(self) -> Builder
Emit bindings for builtin definitions (for example __builtin_va_list
)
in the generated Rust.
sourcepub fn no_convert_floats(self) -> Self
pub fn no_convert_floats(self) -> Self
Avoid converting floats to f32
/f64
by default.
sourcepub fn layout_tests(self, doit: bool) -> Self
pub fn layout_tests(self, doit: bool) -> Self
Set whether layout tests should be generated.
sourcepub fn impl_debug(self, doit: bool) -> Self
pub fn impl_debug(self, doit: bool) -> Self
Set whether Debug
should be implemented, if it can not be derived automatically.
sourcepub fn impl_partialeq(self, doit: bool) -> Self
pub fn impl_partialeq(self, doit: bool) -> Self
Set whether PartialEq
should be implemented, if it can not be derived automatically.
sourcepub fn derive_copy(self, doit: bool) -> Self
pub fn derive_copy(self, doit: bool) -> Self
Set whether Copy
should be derived by default.
sourcepub fn derive_debug(self, doit: bool) -> Self
pub fn derive_debug(self, doit: bool) -> Self
Set whether Debug
should be derived by default.
sourcepub fn derive_default(self, doit: bool) -> Self
pub fn derive_default(self, doit: bool) -> Self
Set whether Default
should be derived by default.
sourcepub fn derive_hash(self, doit: bool) -> Self
pub fn derive_hash(self, doit: bool) -> Self
Set whether Hash
should be derived by default.
sourcepub fn derive_partialord(self, doit: bool) -> Self
pub fn derive_partialord(self, doit: bool) -> Self
Set whether PartialOrd
should be derived by default.
If we don’t compute partialord, we also cannot compute
ord. Set the derive_ord to false
when doit is false
.
sourcepub fn derive_ord(self, doit: bool) -> Self
pub fn derive_ord(self, doit: bool) -> Self
Set whether Ord
should be derived by default.
We can’t compute Ord
without computing PartialOrd
,
so we set the same option to derive_partialord.
sourcepub fn derive_partialeq(self, doit: bool) -> Self
pub fn derive_partialeq(self, doit: bool) -> Self
Set whether PartialEq
should be derived by default.
If we don’t derive PartialEq
, we also cannot derive Eq
, so deriving
Eq
is also disabled when doit
is false
.
sourcepub fn derive_eq(self, doit: bool) -> Self
pub fn derive_eq(self, doit: bool) -> Self
Set whether Eq
should be derived by default.
We can’t derive Eq
without also deriving PartialEq
, so we also
enable deriving PartialEq
when doit
is true
.
sourcepub fn time_phases(self, doit: bool) -> Self
pub fn time_phases(self, doit: bool) -> Self
Set whether or not to time bindgen phases, and print information to stderr.
sourcepub fn emit_clang_ast(self) -> Builder
pub fn emit_clang_ast(self) -> Builder
Emit Clang AST.
sourcepub fn enable_cxx_namespaces(self) -> Builder
pub fn enable_cxx_namespaces(self) -> Builder
Enable C++ namespaces.
sourcepub fn disable_name_namespacing(self) -> Builder
pub fn disable_name_namespacing(self) -> Builder
Disable name auto-namespacing.
By default, bindgen mangles names like foo::bar::Baz
to look like
foo_bar_Baz
instead of just Baz
.
This method disables that behavior.
Note that this intentionally does not change the names used for whitelisting and blacklisting, which should still be mangled with the namespaces.
Note, also, that this option may cause bindgen to generate duplicate names.
sourcepub fn conservative_inline_namespaces(self) -> Builder
pub fn conservative_inline_namespaces(self) -> Builder
Treat inline namespaces conservatively.
This is tricky, because in C++ is technically legal to override an item defined in an inline namespace:
inline namespace foo {
using Bar = int;
}
using Bar = long;
Even though referencing Bar
is a compiler error.
We want to support this (arguably esoteric) use case, but we don’t want to make the rest of bindgen users pay an usability penalty for that.
To support this, we need to keep all the inline namespaces around, but
then bindgen usage is a bit more difficult, because you cannot
reference, e.g., std::string
(you’d need to use the proper inline
namespace).
We could complicate a lot of the logic to detect name collisions, and if
not detected generate a pub use inline_ns::*
or something like that.
That’s probably something we can do if we see this option is needed in a lot of cases, to improve it’s usability, but my guess is that this is not going to be too useful.
sourcepub fn generate_inline_functions(self, doit: bool) -> Self
pub fn generate_inline_functions(self, doit: bool) -> Self
Whether inline functions should be generated or not.
Note that they will usually not work. However you can use
-fkeep-inline-functions
or -fno-inline-functions
if you are
responsible of compiling the library to make them callable.
sourcepub fn ignore_functions(self) -> Builder
pub fn ignore_functions(self) -> Builder
Ignore functions.
sourcepub fn ignore_methods(self) -> Builder
pub fn ignore_methods(self) -> Builder
Ignore methods.
sourcepub fn unstable_rust(self, doit: bool) -> Self
👎Deprecated: please use rust_target
instead
pub fn unstable_rust(self, doit: bool) -> Self
rust_target
insteadAvoid generating any unstable Rust, such as Rust unions, in the generated bindings.
sourcepub fn ctypes_prefix<T: Into<String>>(self, prefix: T) -> Builder
pub fn ctypes_prefix<T: Into<String>>(self, prefix: T) -> Builder
Use the given prefix for the raw types instead of ::std::os::raw
.
sourcepub fn parse_callbacks(self, cb: Box<dyn ParseCallbacks>) -> Self
pub fn parse_callbacks(self, cb: Box<dyn ParseCallbacks>) -> Self
Allows configuring types in different situations, see the
ParseCallbacks
documentation.
sourcepub fn with_codegen_config(self, config: CodegenConfig) -> Self
pub fn with_codegen_config(self, config: CodegenConfig) -> Self
Choose what to generate using a
CodegenConfig
.
sourcepub fn prepend_enum_name(self, doit: bool) -> Self
pub fn prepend_enum_name(self, doit: bool) -> Self
Prepend the enum name to constant or bitfield variants.
sourcepub fn rustfmt_bindings(self, doit: bool) -> Self
pub fn rustfmt_bindings(self, doit: bool) -> Self
Set whether rustfmt should format the generated bindings.
sourcepub fn rustfmt_configuration_file(self, path: Option<PathBuf>) -> Self
pub fn rustfmt_configuration_file(self, path: Option<PathBuf>) -> Self
Set the absolute path to the rustfmt configuration file, if None, the standard rustfmt options are used.
sourcepub fn with_rustfmt<P: Into<PathBuf>>(self, path: P) -> Self
pub fn with_rustfmt<P: Into<PathBuf>>(self, path: P) -> Self
Sets an explicit path to rustfmt, to be used when rustfmt is enabled.
sourcepub fn generate(self) -> Result<Bindings, ()>
pub fn generate(self) -> Result<Bindings, ()>
Generate the Rust bindings using the options built up thus far.
sourcepub fn dump_preprocessed_input(&self) -> Result<()>
pub fn dump_preprocessed_input(&self) -> Result<()>
Preprocess and dump the input header files to disk.
This is useful when debugging bindgen, using C-Reduce, or when filing
issues. The resulting file will be named something like __bindgen.i
or
__bindgen.ii
sourcepub fn no_partialeq<T: Into<String>>(self, arg: T) -> Builder
pub fn no_partialeq<T: Into<String>>(self, arg: T) -> Builder
Don’t derive PartialEq
for a given type. Regular
expressions are supported.