Struct bindgen::Builder [−][src]
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") .whitelist_type("SomeCoolClass") .whitelist_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
- Newtype enum
- Rustified enum
If none of the above patterns match, then bindgen will generate a set of Rust constants.
Clang arguments
Extra arguments can be passed to with clang:
clang_arg()
: takes a single argumentclang_args()
: takes an iterator of argumentsBINDGEN_EXTRA_CLANG_ARGS
environment variable: whitespace separate environment variable of arguments
Clang arguments specific to your crate should be added via the
clang_arg()
/clang_args()
methods.
End-users of the crate may need to set the BINDGEN_EXTRA_CLANG_ARGS
environment variable to
add additional arguments. For example, to build against a different sysroot a user could set
BINDGEN_EXTRA_CLANG_ARGS
to --sysroot=/path/to/sysroot
.
Implementations
impl Builder
[src]
pub fn command_line_flags(&self) -> Vec<String>ⓘ
[src]
Generates the command line flags use for creating Builder
.
pub fn header<T: Into<String>>(mut self: Self, header: T) -> Builder
[src]
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();
pub fn header_contents(mut self: Self, name: &str, contents: &str) -> Builder
[src]
Add contents
as an input C/C++ header named name
.
The file name
will be added to the clang arguments.
pub fn rust_target(mut self: Self, rust_target: RustTarget) -> Self
[src]
Specify the rust target
The default is the latest stable Rust version
pub fn disable_untagged_union(mut self: Self) -> Self
[src]
Disable support for native Rust unions, if supported.
pub fn disable_header_comment(mut self: Self) -> Self
[src]
Disable insertion of bindgen's version identifier into generated bindings.
pub fn emit_ir_graphviz<T: Into<String>>(mut self: Self, path: T) -> Builder
[src]
Set the output graphviz file.
pub fn generate_comments(mut self: Self, doit: bool) -> Self
[src]
Whether the generated bindings should contain documentation comments (docstrings) 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 rust-bindgen issue #426.
Note that clang by default excludes comments from system headers, pass
-fretain-comments-from-system-headers
as
clang_arg
to include them. It can also be told
to process all comments (not just documentation ones) using the
-fparse-all-comments
flag. See slides on clang comment parsing for
background and examples.
pub fn whitelist_recursively(mut self: Self, doit: bool) -> Self
[src]
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.
pub fn objc_extern_crate(mut self: Self, doit: bool) -> Self
[src]
Generate #[macro_use] extern crate objc;
instead of use objc;
in the prologue of the files generated from objective-c files
pub fn generate_block(mut self: Self, doit: bool) -> Self
[src]
Generate proper block signatures instead of void pointers.
pub fn block_extern_crate(mut self: Self, doit: bool) -> Self
[src]
Generate #[macro_use] extern crate block;
instead of use block;
in the prologue of the files generated from apple block files
pub fn trust_clang_mangling(mut self: Self, doit: bool) -> Self
[src]
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.
pub fn hide_type<T: AsRef<str>>(self, arg: T) -> Builder
[src]
Use blacklist_type instead
Hide the given type from the generated bindings. Regular expressions are supported.
pub fn blacklist_type<T: AsRef<str>>(mut self: Self, arg: T) -> Builder
[src]
Hide the given type from the generated bindings. Regular expressions are supported.
To blacklist types prefixed with "mylib" use "mylib_.*"
.
For more complicated expressions check
regex docs
pub fn blacklist_function<T: AsRef<str>>(mut self: Self, arg: T) -> Builder
[src]
Hide the given function from the generated bindings. Regular expressions are supported.
To blacklist functions prefixed with "mylib" use "mylib_.*"
.
For more complicated expressions check
regex docs
pub fn blacklist_item<T: AsRef<str>>(mut self: Self, arg: T) -> Builder
[src]
Hide the given item from the generated bindings, regardless of whether it's a type, function, module, etc. Regular expressions are supported.
To blacklist items prefixed with "mylib" use "mylib_.*"
.
For more complicated expressions check
regex docs
pub fn opaque_type<T: AsRef<str>>(mut self: Self, arg: T) -> Builder
[src]
Treat the given type as opaque in the generated bindings. Regular expressions are supported.
To change types prefixed with "mylib" into opaque, use "mylib_.*"
.
For more complicated expressions check
regex docs
pub fn whitelisted_type<T: AsRef<str>>(self, arg: T) -> Builder
[src]
use whitelist_type instead
Whitelist the given type so that it (and all types that it transitively refers to) appears in the generated bindings. Regular expressions are supported.
pub fn whitelist_type<T: AsRef<str>>(mut self: Self, arg: T) -> Builder
[src]
Whitelist the given type so that it (and all types that it transitively refers to) appears in the generated bindings. Regular expressions are supported.
To whitelist types prefixed with "mylib" use "mylib_.*"
.
For more complicated expressions check
regex docs
pub fn whitelist_function<T: AsRef<str>>(mut self: Self, arg: T) -> Builder
[src]
Whitelist the given function so that it (and all types that it transitively refers to) appears in the generated bindings. Regular expressions are supported.
To whitelist functions prefixed with "mylib" use "mylib_.*"
.
For more complicated expressions check
regex docs
pub fn whitelisted_function<T: AsRef<str>>(self, arg: T) -> Builder
[src]
use whitelist_function instead
Whitelist the given function.
Deprecated: use whitelist_function instead.
pub fn whitelist_var<T: AsRef<str>>(mut self: Self, arg: T) -> Builder
[src]
Whitelist the given variable so that it (and all types that it transitively refers to) appears in the generated bindings. Regular expressions are supported.
To whitelist variables prefixed with "mylib" use "mylib_.*"
.
For more complicated expressions check
regex docs
pub fn whitelisted_var<T: AsRef<str>>(self, arg: T) -> Builder
[src]
use whitelist_var instead
Whitelist the given variable.
Deprecated: use whitelist_var instead.
pub fn default_enum_style(mut self: Self, arg: EnumVariation) -> Builder
[src]
Set the default style of code to generate for enums
pub fn bitfield_enum<T: AsRef<str>>(mut self: Self, arg: T) -> Builder
[src]
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.
This is similar to the newtype enum style, but with the bitwise operators implemented.
pub fn newtype_enum<T: AsRef<str>>(mut self: Self, arg: T) -> Builder
[src]
Mark the given enum (or set of enums, if using a pattern) as a newtype. Regular expressions are supported.
This makes bindgen generate a type that isn't a Rust enum
. Regular
expressions are supported.
pub fn rustified_enum<T: AsRef<str>>(mut self: Self, arg: T) -> Builder
[src]
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, creating this in unsafe code (including FFI) with an invalid value will invoke undefined behaviour. You may want to use the newtype enum style instead.
pub fn rustified_non_exhaustive_enum<T: AsRef<str>>(
mut self: Self,
arg: T
) -> Builder
[src]
mut self: Self,
arg: T
) -> Builder
Mark the given enum (or set of enums, if using a pattern) as a Rust
enum with the #[non_exhaustive]
attribute.
This makes bindgen generate enums instead of constants. Regular expressions are supported.
Use this with caution, creating this in unsafe code (including FFI) with an invalid value will invoke undefined behaviour. You may want to use the newtype enum style instead.
pub fn constified_enum<T: AsRef<str>>(mut self: Self, arg: T) -> Builder
[src]
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.
pub fn constified_enum_module<T: AsRef<str>>(mut self: Self, arg: T) -> Builder
[src]
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.
pub fn default_macro_constant_type(
mut self: Self,
arg: MacroTypeVariation
) -> Builder
[src]
mut self: Self,
arg: MacroTypeVariation
) -> Builder
Set the default type for macro constants
pub fn default_alias_style(mut self: Self, arg: AliasVariation) -> Builder
[src]
Set the default style of code to generate for typedefs
pub fn type_alias<T: AsRef<str>>(mut self: Self, arg: T) -> Builder
[src]
Mark the given typedef alias (or set of aliases, if using a pattern) to use regular Rust type aliasing.
This is the default behavior and should be used if default_alias_style
was set to NewType or NewTypeDeref and you want to override it for a
set of typedefs.
pub fn new_type_alias<T: AsRef<str>>(mut self: Self, arg: T) -> Builder
[src]
Mark the given typedef alias (or set of aliases, if using a pattern) to be generated as a new type by having the aliased type be wrapped in a #[repr(transparent)] struct.
Used to enforce stricter type checking.
pub fn new_type_alias_deref<T: AsRef<str>>(mut self: Self, arg: T) -> Builder
[src]
Mark the given typedef alias (or set of aliases, if using a pattern) to
be generated as a new type by having the aliased type be wrapped in a
#[repr(transparent)] struct and also have an automatically generated
impl's of Deref
and DerefMut
to their aliased type.
pub fn raw_line<T: Into<String>>(mut self: Self, arg: T) -> Self
[src]
Add a string to prepend to the generated bindings. The string is passed through without any modification.
pub fn module_raw_line<T, U>(mut self: Self, mod_: T, line: U) -> Self where
T: Into<String>,
U: Into<String>,
[src]
T: Into<String>,
U: Into<String>,
Add a given line to the beginning of module mod
.
pub fn module_raw_lines<T, I>(mut self: Self, mod_: T, lines: I) -> Self where
T: Into<String>,
I: IntoIterator,
I::Item: Into<String>,
[src]
T: Into<String>,
I: IntoIterator,
I::Item: Into<String>,
Add a given set of lines to the beginning of module mod
.
pub fn clang_arg<T: Into<String>>(mut self: Self, arg: T) -> Builder
[src]
Add an argument to be passed straight through to clang.
pub fn clang_args<I>(mut self: Self, iter: I) -> Builder where
I: IntoIterator,
I::Item: AsRef<str>,
[src]
I: IntoIterator,
I::Item: AsRef<str>,
Add arguments to be passed straight through to clang.
pub fn emit_builtins(mut self: Self) -> Builder
[src]
Emit bindings for builtin definitions (for example __builtin_va_list
)
in the generated Rust.
pub fn no_convert_floats(mut self: Self) -> Self
[src]
Avoid converting floats to f32
/f64
by default.
pub fn layout_tests(mut self: Self, doit: bool) -> Self
[src]
Set whether layout tests should be generated.
pub fn impl_debug(mut self: Self, doit: bool) -> Self
[src]
Set whether Debug
should be implemented, if it can not be derived automatically.
pub fn impl_partialeq(mut self: Self, doit: bool) -> Self
[src]
Set whether PartialEq
should be implemented, if it can not be derived automatically.
pub fn derive_copy(mut self: Self, doit: bool) -> Self
[src]
Set whether Copy
should be derived by default.
pub fn derive_debug(mut self: Self, doit: bool) -> Self
[src]
Set whether Debug
should be derived by default.
pub fn derive_default(mut self: Self, doit: bool) -> Self
[src]
Set whether Default
should be derived by default.
pub fn derive_hash(mut self: Self, doit: bool) -> Self
[src]
Set whether Hash
should be derived by default.
pub fn derive_partialord(mut self: Self, doit: bool) -> Self
[src]
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
.
pub fn derive_ord(mut self: Self, doit: bool) -> Self
[src]
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.
pub fn derive_partialeq(mut self: Self, doit: bool) -> Self
[src]
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
.
pub fn derive_eq(mut self: Self, doit: bool) -> Self
[src]
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
.
pub fn time_phases(mut self: Self, doit: bool) -> Self
[src]
Set whether or not to time bindgen phases, and print information to stderr.
pub fn emit_clang_ast(mut self: Self) -> Builder
[src]
Emit Clang AST.
pub fn emit_ir(mut self: Self) -> Builder
[src]
Emit IR.
pub fn enable_cxx_namespaces(mut self: Self) -> Builder
[src]
Enable C++ namespaces.
pub fn enable_function_attribute_detection(mut self: Self) -> Self
[src]
Enable detecting must_use attributes on C functions.
This is quite slow in some cases (see #1465), so it's disabled by default.
Note that for this to do something meaningful for now at least, the rust
target version has to have support for #[must_use]
.
pub fn disable_name_namespacing(mut self: Self) -> Builder
[src]
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.
pub fn disable_nested_struct_naming(mut self: Self) -> Builder
[src]
Disable nested struct naming.
The following structs have different names for C and C++. In case of C
they are visible as foo
and bar
. In case of C++ they are visible as
foo
and foo::bar
.
struct foo {
struct bar {
} b;
};
Bindgen wants to avoid duplicate names by default so it follows C++ naming
and it generates foo
/foo_bar
instead of just foo
/bar
.
This method disables this behavior and it is indented to be used only for headers that were written for C.
pub fn conservative_inline_namespaces(mut self: Self) -> Builder
[src]
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.
pub fn generate_inline_functions(mut self: Self, doit: bool) -> Self
[src]
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.
pub fn ignore_functions(mut self: Self) -> Builder
[src]
Ignore functions.
pub fn ignore_methods(mut self: Self) -> Builder
[src]
Ignore methods.
pub fn unstable_rust(self, doit: bool) -> Self
[src]
please use rust_target
instead
Avoid generating any unstable Rust, such as Rust unions, in the generated bindings.
pub fn use_core(mut self: Self) -> Builder
[src]
Use core instead of libstd in the generated bindings.
pub fn ctypes_prefix<T: Into<String>>(mut self: Self, prefix: T) -> Builder
[src]
Use the given prefix for the raw types instead of ::std::os::raw
.
pub fn anon_fields_prefix<T: Into<String>>(mut self: Self, prefix: T) -> Builder
[src]
Use the given prefix for the anon fields.
pub fn parse_callbacks(mut self: Self, cb: Box<dyn ParseCallbacks>) -> Self
[src]
Allows configuring types in different situations, see the
ParseCallbacks
documentation.
pub fn with_codegen_config(mut self: Self, config: CodegenConfig) -> Self
[src]
Choose what to generate using a
CodegenConfig
.
pub fn detect_include_paths(mut self: Self, doit: bool) -> Self
[src]
Whether to detect include paths using clang_sys.
pub fn fit_macro_constants(mut self: Self, doit: bool) -> Self
[src]
Whether to try to fit macro constants to types smaller than u32/i32
pub fn prepend_enum_name(mut self: Self, doit: bool) -> Self
[src]
Prepend the enum name to constant or newtype variants.
pub fn size_t_is_usize(mut self: Self, is: bool) -> Self
[src]
Set whether size_t
should be translated to usize
automatically.
pub fn rustfmt_bindings(mut self: Self, doit: bool) -> Self
[src]
Set whether rustfmt should format the generated bindings.
pub fn record_matches(mut self: Self, doit: bool) -> Self
[src]
Set whether we should record matched items in our regex sets.
pub fn rustfmt_configuration_file(mut self: Self, path: Option<PathBuf>) -> Self
[src]
Set the absolute path to the rustfmt configuration file, if None, the standard rustfmt options are used.
pub fn with_rustfmt<P: Into<PathBuf>>(mut self: Self, path: P) -> Self
[src]
Sets an explicit path to rustfmt, to be used when rustfmt is enabled.
pub fn generate(mut self: Self) -> Result<Bindings, ()>
[src]
Generate the Rust bindings using the options built up thus far.
pub fn dump_preprocessed_input(&self) -> Result<()>
[src]
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
pub fn no_partialeq<T: Into<String>>(mut self: Self, arg: T) -> Builder
[src]
Don't derive PartialEq
for a given type. Regular
expressions are supported.
pub fn no_copy<T: Into<String>>(mut self: Self, arg: T) -> Self
[src]
Don't derive Copy
for a given type. Regular
expressions are supported.
pub fn no_debug<T: Into<String>>(mut self: Self, arg: T) -> Self
[src]
Don't derive Debug
for a given type. Regular
expressions are supported.
pub fn no_default<T: Into<String>>(mut self: Self, arg: T) -> Self
[src]
Don't derive/impl Default
for a given type. Regular
expressions are supported.
pub fn no_hash<T: Into<String>>(mut self: Self, arg: T) -> Builder
[src]
Don't derive Hash
for a given type. Regular
expressions are supported.
pub fn array_pointers_in_arguments(mut self: Self, doit: bool) -> Self
[src]
Set whether arr[size]
should be treated as *mut T
or *mut [T; size]
(same for mut)
pub fn wasm_import_module_name<T: Into<String>>(
mut self: Self,
import_name: T
) -> Self
[src]
mut self: Self,
import_name: T
) -> Self
Set the wasm import module name
pub fn dynamic_library_name<T: Into<String>>(
mut self: Self,
dynamic_library_name: T
) -> Self
[src]
mut self: Self,
dynamic_library_name: T
) -> Self
Specify the dynamic library name if we are generating bindings for a shared library.
pub fn respect_cxx_access_specs(mut self: Self, doit: bool) -> Self
[src]
Generate bindings as pub
only if the bound item is publically accessible by C++.
Trait Implementations
Auto Trait Implementations
impl !RefUnwindSafe for Builder
[src]
impl !Send for Builder
[src]
impl !Sync for Builder
[src]
impl Unpin for Builder
[src]
impl UnwindSafe for Builder
[src]
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,