Struct bindgen::Builder

pub struct Builder { /* fields omitted */ }

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 = try!(builder().header("path/to/input/header")
                             .whitelisted_type("SomeCoolClass")
                             .whitelisted_function("do_some_cool_thing")
                             .generate());

// Write the generated bindings to an output file.
try!(bindings.write_to_file("path/to/output.rs"));

Methods

impl Builder

pub fn command_line_flags(&self) -> Vec<String>

Generates the command line flags use for creating 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();

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.

pub fn rust_target(self, rust_target: RustTarget) -> Self

Specify the rust target

The default is the latest stable Rust version

pub fn emit_ir_graphviz<T: Into<String>>(self, path: T) -> Builder

Set the output graphviz file.

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

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 responsiblity 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(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

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.

pub fn hide_type<T: AsRef<str>>(self, arg: T) -> Builder

Deprecated:

Use blacklist_type instead

Hide the given type from the generated bindings. Regular expressions are supported.

pub fn blacklist_type<T: AsRef<str>>(self, arg: T) -> Builder

Hide the given type from the generated bindings. Regular expressions are supported.

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.

pub fn whitelisted_type<T: AsRef<str>>(self, arg: T) -> Builder

Deprecated:

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>>(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.

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.

pub fn whitelisted_function<T: AsRef<str>>(self, arg: T) -> Builder

Deprecated:

use whitelist_function instead

Whitelist the given function.

Deprecated: use whitelist_function instead.

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.

pub fn whitelisted_var<T: AsRef<str>>(self, arg: T) -> Builder

Deprecated:

use whitelist_var instead

Whitelist the given variable.

Deprecated: use whitelist_var instead.

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.

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.

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.

pub fn raw_line<T: Into<String>>(self, arg: T) -> Builder

Add a string to prepend to the generated bindings. The string is passed through without any modification.

pub fn clang_arg<T: Into<String>>(self, arg: T) -> Builder

Add an argument to be passed straight through to clang.

pub fn clang_args<I>(self, iter: I) -> Builder where
    I: IntoIterator,
    I::Item: AsRef<str>, 

Add arguments to be passed straight through to clang.

pub fn link<T: Into<String>>(self, library: T) -> Builder

Make the generated bindings link the given shared library.

pub fn link_static<T: Into<String>>(self, library: T) -> Builder

Make the generated bindings link the given static library.

pub fn link_framework<T: Into<String>>(self, library: T) -> Builder

Make the generated bindings link the given framework.

pub fn emit_builtins(self) -> Builder

Emit bindings for builtin definitions (for example __builtin_va_list) in the generated Rust.

pub fn no_convert_floats(self) -> Self

Avoid converting floats to f32/f64 by default.

pub fn layout_tests(self, doit: bool) -> Self

Set whether layout tests should be generated.

pub fn impl_debug(self, doit: bool) -> Self

Set whether Debug should be implemented, if it can not be derived automatically.

pub fn impl_partialeq(self, doit: bool) -> Self

Set whether PartialEq should be implemented, if it can not be derived automatically.

pub fn derive_copy(self, doit: bool) -> Self

Set whether Copy should be derived by default.

pub fn derive_debug(self, doit: bool) -> Self

Set whether Debug should be derived by default.

pub fn derive_default(self, doit: bool) -> Self

Set whether Default should be derived by default.

pub fn derive_hash(self, doit: bool) -> Self

Set whether Hash should be derived by default.

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.

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.

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.

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.

pub fn time_phases(self, doit: bool) -> Self

Set whether or not to time bindgen phases, and print information to stderr.

pub fn emit_clang_ast(self) -> Builder

Emit Clang AST.

pub fn emit_ir(self) -> Builder

Emit IR.

pub fn enable_cxx_namespaces(self) -> Builder

Enable C++ namespaces.

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.

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.

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.

pub fn ignore_functions(self) -> Builder

Ignore functions.

pub fn ignore_methods(self) -> Builder

Ignore methods.

pub fn unstable_rust(self, doit: bool) -> Self

Deprecated:

please use rust_target instead

Avoid generating any unstable Rust, such as Rust unions, in the generated bindings.

pub fn use_core(self) -> Builder

Use core instead of libstd in the generated bindings.

pub fn ctypes_prefix<T: Into<String>>(self, prefix: T) -> Builder

Use the given prefix for the raw types instead of ::std::os::raw.

pub fn parse_callbacks(self, cb: Box<dyn ParseCallbacks>) -> Self

Allows configuring types in different situations, see the ParseCallbacks documentation.

pub fn with_codegen_config(self, config: CodegenConfig) -> Self

Choose what to generate using a CodegenConfig.

pub fn prepend_enum_name(self, doit: bool) -> Self

Prepend the enum name to constant or bitfield variants.

pub fn rustfmt_bindings(self, doit: bool) -> Self

Set whether rustfmt should format the generated bindings.

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.

pub fn generate(self) -> Result<Bindings, ()>

Generate the Rust bindings using the options built up thus far.

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

pub fn no_partialeq(self, arg: String) -> Builder

Don't derive PartialEq for a given type. Regular expressions are supported.

pub fn no_copy(self, arg: String) -> Self

Don't derive Copy for a given type. Regular expressions are supported.

pub fn no_hash(self, arg: String) -> Builder

Don't derive Hash for a given type. Regular expressions are supported.

Trait Implementations

impl Debug for Builder

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Default for Builder

fn default() -> Builder

Returns the "default value" for a type.