Bindgen: automatically generate Rust FFI bindings to C and C++ libraries

announcements
4

Announcing bindgen 0.31.0

bindgen automatically generates Rust FFI bindings to C and C++ libraries.

Upgrade to this release by updating your Cargo.toml:

bindgen = "0.31.0"

Changelog

Added

  • :tada: A new bindgen reviewer: @pepyakin :tada: You can ask @pepyakin to review all your future pull requests with r? @pepyakin from now on :smile:

  • Timers for seeing which phases bindgen is spending its time in. On the command line, use the --time-phases flag. From a builder, use the bindgen::Builder::time_phases(true) method. #938

  • You can now disable #[derive(Copy)] for all types with --no-derive-copy and bindgen::Builder::derive_copy(false). #948

  • We now have an overview of bindgen's code base and architecture for newcomers in CONTRIBUTING.md. #988

  • Derive PartialOrd with the --with-derive-partialord CLI flag or bindgen::Builder::derive_partialord(true) builder method. #882

  • Derive Ord with the --with-derive-ord CLI flag or bindgen::Builder::derive_ord(true) builder method. #884

  • When PartialEq cannot be derived because of an array larger than Rust's array-derive limit, bindgen can emit an impl PartialEq for ... block. Enable this behavior with the --impl-partialeq CLI flag or the bindgen::Builder::impl_partialeq(true) method. #1012

  • When deriving PartialEq for all types, you can now specify particular types that shouldn't derive(PartialEq) with the --no-partialeq <regex> CLI flag or bindgen::Builder::no_partialeq("<regex>") builder method. #996

  • Specify types that should not derive Copy with the --no-copy <regex> CLI flag or bindgen::Builder::no_copy("<regex>") builder method. This functionality was previously only available via comment annotations in the header sources. #1099

  • When deriving Hash for all types, you can now specify particular types that shouldn't derive(Hash) with the --no-hash <regex> CLI flag or bindgen::Builder::no_hash("<regex>") builder method. #1105

  • The bindgen users guide now has an FAQ section! If you have any FAQ suggestions to put up there, please open a pull request. [#1020]

  • Added csmith fuzzing infrastructure. csmith generates random C and C++ programs, we feed those into bindgen as headers to generate bindings to, then test that the generated bindings compile and that their layout tests pass. This infrastructure landed in many small bits.

    We <3 folks who help us find and fix issues via fuzzing! hint hint

  • Added experimental support for the thiscall ABI when targetting Rust nightly. #1065

Changed

  • If the user does not explicitly pass a --target argument for libclang, bindgen will insert such an argument itself. See #942, #947, and #953 for details.

  • C/C++ enums are now translated into constants by default, rather than Rust enums. The old behavior was a big footgun because rustc assumes that the only values of an enum are its variants, whereas a lot of C/C++ code uses random values as enums. Put these two things and it leads to undefined behavior. Translating C/C++ enums into Rust enums is still available with the --rustified-enum <regex> CLI flag and bindgen::Builder::rustified_enum("<regex>") builder method. #758

  • Generated bindings are now pretty printed with rustfmt by default. Previously, this option existed, but was off by default because syntex did an OK job at pretty printing the bindings. Now that we are using quote! { ... } instead of syntex, we lost that pretty printing, and now rely on rustfmt. You can disable rustfmting with --no-rustfmt-bindings or bindgen::Builder::rustfmt_bindings(false). See #925 and #1022 for details.

Deprecated

  • bindgen::Builder::hide_type is deprecated in favor of bindgen::Builder::blacklist_type. #987

  • bindgen::Builder::whitelisted_type is deprecated in favor of bindgen::Builder::whitelist_type. #987

  • bindgen::Builder::whitelisted_function is deprecated in favor of bindgen::Builder::whitelist_function. #985

  • bindgen::Builder::whitelisted_var is deprecated in favor of bindgen::Builder::whitelist_var. #989

Removed

  • Removed the dependency on (unmaintained) syntex, and build times are cut in half!

    Before:

    $ cargo clean; cargo build
<snip>
    Finished dev [unoptimized + debuginfo] target(s) in 98.75 secs

    After:

    $ cargo clean; cargo build
<snip>
    Finished dev [unoptimized + debuginfo] target(s) in 46.26 secs

    #925

  • The BindgenOptions type is no longer public. It had been deprecated in previous releases. Use bindgen::Builder instead. #1000

Fixed

  • Under certain conditions, a globally scoped enum could end up with bindings in the wrong namespace module. #888

  • Blacklisted types were incorrectly assumed to always be Copyable (and assumed to implement other traits as well). bindgen is now conservatively pessimistic about the traits that blacklisted types implement. #944

  • When bitfields have a ridiculously large number of bits (for example, unsigned : 632;) then bindgen was incorrectly deriving traits that couldn't be derived, resulting in errors when compiling the bindings, and was also generating structs with an incorrect layout. Both issues have been fixed. #982

  • _ is a valid identifier in some C++ contexts, but can't be referenced in Rust, as it is the "throwaway identifier" (a term I just made up, if you use it now, then you owe me money). bindgen will now translate _ into __ so that it can be used on the Rust side. #1008

  • Nested class definitions were sometimes being emitted in the wrong namespace module in the generated bindings. #1048

  • bindgen was mis-handling unions that contained bitfield members. This has been fixed. #744

  • Unsigned constants that were greater than u32::MAX were being mis-translated by bindgen. This is now fixed. #1040

  • When given a directory as an input file, or a file to which we don't have read permissions, then bindgen will print a more useful error message now. #1029

  • bindgen previously attempted to derive Hash for structures with flexibly-sized array members, but knowing how many elements exist in such arrays requires program-specific knowledge that bindgen cannot have. #1094

Friends

Thanks to everyone who contributed to this release!

  • Alexey Zabelin
  • Andrew Gaspar
  • Bastien Orivel
  • Cldfire
  • e
  • Emilio Cobos Álvarez
  • Glyn Normington
  • Harlan Haskins
  • Jackson O'Donnell
  • Jeff Muizelaar
  • KC
  • Liran Ringel
  • Manas Karekar
  • mchlrhw
  • Nick Fitzgerald
  • Oliver Geller
  • seemyvest
  • Sergey Pepyakin
  • Taylor Foxhall
  • Trevor Reiff
  • Zhiting Zhu

Contributing

Join us in our impl period gitter channel: WG-dev-tools-bindgen

Want to join us? Check out our CONTRIBUTING.md and take a look at some of these issues:

Want to help improve our documentation? Check out the issues labeled "docs".

Found a bug with bindgen? File an issue here.

9 Likes