Rust Bindgen

Overview

These rules are for using Bindgen to generate Rust bindings to C (and some C++) libraries.

See the bindgen example for a more complete example of use.

Setup

To use the Rust bindgen rules, add the following to your WORKSPACE file to add the external repositories for the Rust bindgen toolchain (in addition to the rust rules setup):

load("@rules_rust//bindgen:repositories.bzl", "rust_bindgen_dependencies", "rust_bindgen_register_toolchains")

rust_bindgen_dependencies()

rust_bindgen_register_toolchains()

load("@rules_rust//bindgen:transitive_repositories.bzl", "rust_bindgen_transitive_dependencies")

rust_bindgen_transitive_dependencies()

Bindgen aims to be as hermetic as possible so will end up building libclang from llvm-project from source. If this is found to be undesirable then no Bindgen related calls should be added to your WORKSPACE and instead users should define their own repositories using something akin to crate_universe and define their own toolchains following the instructions for rust_bindgen_toolchain.



rust_bindgen

rust_bindgen(name, bindgen_flags, cc_lib, clang_flags, header, wrap_static_fns)

Generates a rust source file from a cc_library and a header.

ATTRIBUTES

NameDescriptionTypeMandatoryDefault
nameA unique name for this target.Namerequired
bindgen_flagsFlags to pass directly to the bindgen executable. See https://rust-lang.github.io/rust-bindgen/ for details.List of stringsoptional[]
cc_libThe cc_library that contains the .h file. This is used to find the transitive includes.Labelrequired
clang_flagsFlags to pass directly to the clang executable.List of stringsoptional[]
headerThe .h file to generate bindings for.Labelrequired
wrap_static_fnsWhether to create a separate .c file for static fns. Requires nightly toolchain, and a header that actually needs this feature (otherwise bindgen won't generate the file and Bazel complains).BooleanoptionalFalse

rust_bindgen_toolchain

rust_bindgen_toolchain(name, bindgen, clang, default_rustfmt, libclang, libstdcxx)

The tools required for the rust_bindgen rule.

This rule depends on the bindgen binary crate, and it in turn depends on both a clang binary and the clang library. To obtain these dependencies, rust_bindgen_dependencies imports bindgen and its dependencies.

load("@rules_rust//bindgen:defs.bzl", "rust_bindgen_toolchain")

rust_bindgen_toolchain(
    name = "bindgen_toolchain_impl",
    bindgen = "//my/rust:bindgen",
    clang = "//my/clang:clang",
    libclang = "//my/clang:libclang.so",
    libstdcxx = "//my/cpp:libstdc++",
)

toolchain(
    name = "bindgen_toolchain",
    toolchain = "bindgen_toolchain_impl",
    toolchain_type = "@rules_rust//bindgen:toolchain_type",
)

This toolchain will then need to be registered in the current WORKSPACE. For additional information, see the Bazel toolchains documentation.

ATTRIBUTES

NameDescriptionTypeMandatoryDefault
nameA unique name for this target.Namerequired
bindgenThe label of a bindgen executable.LabeloptionalNone
clangThe label of a clang executable.LabeloptionalNone
default_rustfmtIf set, rust_bindgen targets will always format generated sources with rustfmt.BooleanoptionalTrue
libclangA cc_library that provides bindgen's runtime dependency on libclang.LabeloptionalNone
libstdcxxA cc_library that satisfies libclang's libstdc++ dependency. This is used to make the execution of clang hermetic. If None, system libraries will be used instead.LabeloptionalNone

rust_bindgen_dependencies

rust_bindgen_dependencies()

Declare dependencies needed for bindgen.

RETURNS

list[struct(repo=str, is_dev_dep=bool)]: A list of the repositories defined by this macro.

rust_bindgen_library

rust_bindgen_library(name, header, cc_lib, bindgen_flags, bindgen_features, clang_flags,
                     wrap_static_fns, kwargs)

Generates a rust source file for header, and builds a rust_library.

Arguments are the same as rust_bindgen, and kwargs are passed directly to rust_library.

PARAMETERS

NameDescriptionDefault Value
nameA unique name for this target.none
headerThe label of the .h file to generate bindings for.none
cc_libThe label of the cc_library that contains the .h file. This is used to find the transitive includes.none
bindgen_flagsFlags to pass directly to the bindgen executable. See https://rust-lang.github.io/rust-bindgen/ for details.None
bindgen_featuresThe features attribute for the rust_bindgen target.None
clang_flagsFlags to pass directly to the clang executable.None
wrap_static_fnsWhether to create a separate .c file for static fns. Requires nightly toolchain, and a header that actually needs this feature (otherwise bindgen won't generate the file and Bazel complains",False
kwargsArguments to forward to the underlying rust_library rule.none

rust_bindgen_register_toolchains

rust_bindgen_register_toolchains(register_toolchains)

Registers the default toolchains for the rules_rust bindgen rules.

PARAMETERS

NameDescriptionDefault Value
register_toolchainsWhether or not to register toolchains.True