1# Frequently Asked Questions 2 3<!-- START doctoc generated TOC please keep comment here to allow auto update --> 4<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> 5 6- [Why isn't `bindgen` generating methods for this allowlisted class?](#why-isnt-bindgen-generating-methods-for-this-allowlisted-class) 7- [Why isn't `bindgen` generating bindings to inline functions?](#why-isnt-bindgen-generating-bindings-to-inline-functions) 8- [Does `bindgen` support the C++ Standard Template Library (STL)?](#does-bindgen-support-the-c-standard-template-library-stl) 9- [How to deal with bindgen generated padding fields?](#how-to-deal-with-bindgen-generated-padding-fields) 10- [How to generate bindings for a custom target?](#how-to-generate-bindings-for-a-custom-target) 11- [How can I normalize `#[doc]` attributes?](#how-can-i-normalize-doc-attributes) 12 13<!-- END doctoc generated TOC please keep comment here to allow auto update --> 14 15### Why isn't `bindgen` generating methods for this allowlisted class? 16 17Are the methods `inline` methods, or defined inline in the class? For example: 18 19```c++ 20class Dooder { 21 public: 22 // Function defined inline in the class. 23 int example_one() { return 1; } 24 25 // `inline` function whose definition is supplied later in the header, or in 26 // another header. 27 inline bool example_two(); 28}; 29 30inline bool Dooder::example_two() { 31 return true; 32} 33``` 34 35If so, see 36["Why isn't `bindgen` generating bindings to inline functions?"](#why-isnt-bindgen-generating-bindings-to-inline-functions) 37 38If not, consider filing an issue! 39 40### Why isn't `bindgen` generating bindings to inline functions? 41 42These functions don't typically end up in object files or shared libraries with 43symbols that we can reliably link to, since they are instead inlined into each 44of their call sites. Therefore, we don't generate bindings to them, since that 45creates linking errors. 46 47However, if you are compiling the C/C++ yourself (rather than using a system 48shared library, for example), then you can pass `-fkeep-inline-functions` or 49`-fno-inline-functions` to `gcc` or `clang`, and invoke `bindgen` with either 50the `bindgen::Builder::generate_inline_functions` method or the 51`--generate-inline-functions` flag. 52 53Note that these functions and methods are usually marked inline for a reason: 54they tend to be hot. The above workaround makes them an out-of-line call, which 55might not provide acceptable performance. 56 57### Does `bindgen` support the C++ Standard Template Library (STL)? 58 59Sort of. A little. Depends what you mean by "support". 60 61Most functions, methods, constructors, and destructors are inline in the 62STL. That ties our hands when it comes to linking: ["Why isn't `bindgen` generating bindings to inline functions?"](#why-isnt-bindgen-generating-bindings-to-inline-functions) 63 64As far as generating opaque blobs of bytes with the correct size and alignment, 65`bindgen` can do pretty well. This is typically enough to let you use types that 66transitively contain STL things. We generally recommend marking `std::.*` as 67opaque, and then allowlisting only the specific things you need from the library 68you're binding to that is pulling in STL headers. 69 70### How to deal with bindgen generated padding fields? 71 72Depending the architecture, toolchain versions and source struct, it is 73possible that bindgen will generate padding fields named `__bindgen_padding_N`. 74As these fields might be present when compiling for one architecture but not 75for an other, you should not initialize these fields manually when initializing 76the struct. Instead, use the `Default` trait. You can either enable this when 77constructing the `Builder` using the `derive_default` method, or you can 78implement this per struct using: 79 80```rust,ignore 81impl Default for SRC_DATA { 82 fn default() -> Self { 83 unsafe { std::mem::zeroed() } 84 } 85} 86``` 87 88This makes it possible to initialize `SRC_DATA` by: 89 90```rust,ignore 91SRC_DATA { 92 field_a: "foo", 93 field_b: "bar", 94 ..Default::default() 95} 96``` 97 98In the case bindgen generates a padding field, then this field will 99be automatically initialized by `..Default::default()`. 100 101### How to generate bindings for a custom target? 102 103To generate bindings for a custom target you only need to pass the `--target` 104argument to `libclang`. For example, if you want to generate bindings for the 105`armv7a-none-eabi` target using the command line, you need to invoke `bindgen` 106like so: 107```bash 108$ bindgen <input_headers> -- --target=armv7a-none-eabi 109``` 110If you are using `bindgen` as a library, you should call 111`builder.clang_arg("--target=armv7a-none-eabi")` on your `builder`. 112 113### How can I normalize `#[doc]` attributes? 114 115`bindgen` emits all the documentation using `#[doc]` attributes by default. If 116you want to use the more user-friendly `///` syntax, you have to create a 117`rustfmt.toml` file with the following contents: 118 119```toml 120normalize_doc_attributes = true 121``` 122 123Then, you have set up bindgen so it passes this file to `rustfmt`. Given that 124the `normalize_doc_attributes` option is 125[unstable](https://github.com/rust-lang/rustfmt/issues/3351), you also have to 126set up bindgen to use a `nightly` release of `rustfmt`. Please check the [code 127formatting](./code-formatting.md) section for further information. 128