Crate bindgen_helpers

Expand description

§Rust bindgen helpers

Utilities to rename, change case, and fix Rust code generated from the C headers using bindgen. Renamer implements a bindgen callback trait, and currently handles struct/enum/typedef type renames with a string->string hashmap. Additionally, it can rename the enum variant names by removing regex matches, and change identifier case to PascalCase to be consistent with the Rust canonical style.

§Usage

# Cargo.toml
[build-dependencies]
# Bindgen_helpers re-exports all of bindgen's public API at the root level
# Do not use bindgen directly to avoid some version conflicts
bindgen_helpers = "0.3"

// build.rs
use bindgen_helpers::{Builder, Renamer, rename_enum};

fn main() {
  // true to enable debug output as warnings
  let mut renamer = Renamer::new(true);

  // rename a single item, e.g. a struct, enum, or a typedef
  renamer.rename_item("my_struct", "MyStruct");

  // rename an enum and its values
  rename_enum!(
    renamer,
    "my_enum" => "MyEnum", // rename the enum itself
    remove: "^I_SAID_",    // optionally any number of "remove" regexes
    remove: "_ENUM$",
    case: Pascal,          // optionally set case convert, defaults to "PascalCase"
    "MV_IT" => "Value1",   // rename a specific value after pattern removal
    "MV_IT2" => "Value2",  // more specific value renames
  );

  let bindings = Builder::default()
    // in real code, use .header("path/to/header.h")
    .header_contents("test.h", r#"

struct my_struct {
    int a;
};

enum my_enum {
    I_SAID_YES_ENUM,
    I_SAID_NO_ENUM,
    I_SAID_MV_IT_ENUM,
    I_SAID_MV_IT2_ENUM,
};

"#)
    // note that generated regex str includes all the renames, not just enums
    .rustified_enum(renamer.get_regex_str())
    .parse_callbacks(Box::new(renamer))
    .generate().unwrap();
}

//
// This is the approximate code that would be generated by the above:
//

#[repr(C)]
#[derive(Debug, Copy, Clone)]
pub struct MyStruct {
  pub a: ::std::os::raw::c_int,
}

#[repr(u32)]
#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
pub enum MyEnum {
  Yes = 0,
  No = 1,
  Value1 = 2,
  Value2 = 3,
}

See the list of all case variants supported by the convert_case crate.

§Development

This project is easier to develop with just, a modern alternative to make. Install it with cargo install just.
To get a list of available commands, run just.
To run tests, use just test.

§License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT) at your option.

§Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual-licensed as above, without any additional terms or conditions.

Modules§

callbacks: A public API for more fine-grained customization of bindgen behavior.

Macros§

rename_enum: Macro to help define renaming rules for an enum and its values. See an example in the Renamer documentation.

Structs§

Bindings: Generated Rust bindings.
Builder: Configure and generate Rust bindings for a C/C++ header.
CargoCallbacks: A ParseCallbacks implementation that will act on file includes by echoing a rerun-if-changed line and on env variable usage by echoing a rerun-if-env-changed line
ClangVersion: Extracted Clang version data
CodegenConfig: A type used to indicate which kind of items we have to generate.
IdentRenamer: Define the rules how a C identifier should be renamed.
Regex: A compiled regular expression for searching Unicode haystacks.
Renamer: Renamer is a struct that implements the ParseCallbacks trait. It is used to rename C items like enums, structs, and typedefs in the generated Rust bindings.
RustTarget: Represents the version of the Rust language to target.

Enums§

Abi: A valid rust ABI.
AliasVariation: Enum for how aliases should be translated.
BindgenError: Error type for rust-bindgen.
Case: Defines the case of an identifier.
EnumVariation: A helper type that represents different enum variations.
FieldVisibilityKind: What kind of visibility modifier should be used for a struct or field?
Formatter: Formatting tools that can be used to format the bindings
MacroTypeVariation: Enum for the default type of macro constants.
NonCopyUnionStyle: Enum for how non-Copy unions should be translated.
RustEdition: Represents Rust Edition for the generated bindings

Constants§

CargoCallbacksDeprecated: Create a new CargoCallbacks value with CargoCallbacks::rerun_on_header_files disabled.
DEFAULT_ANON_FIELDS_PREFIX: Default prefix for the anon fields.
LATEST_STABLE_RUST: Latest stable release of Rust that is supported by bindgen

Functions§

builder: Construct a new Builder.
clang_version: Get the major and the minor semver numbers of Clang’s version

Crate bindgen_helpersCopy item path