Struct Builder

pub struct Builder<'a, BuilderContext> { /* private fields */ }

An object to allow building of bindings from a build.rs file.

It would be unusual to create this directly - see the autocxx_build or autocxx_gen crates.

Once you’ve got one of these objects, you may set some configuration options but then you’re likely to want to call the [build] method.

Setting C++ version

Ensure you use [extra_clang_args] as well as giving an appropriate option to the cc::Build which you receive from the [build] function.

Implementations

impl<CTX: BuilderContext> Builder<'_, CTX>

pub fn new( rs_file: impl AsRef<Path>, autocxx_incs: impl IntoIterator<Item = impl AsRef<OsStr>>, ) -> Self

Create a new Builder object. You’ll need to pass in the Rust file which contains the bindings (typically an include_cpp! macro though autocxx can also handle manually-crafted cxx::bridge bindings), and a list of include directories which should be searched by autocxx as it tries to hunt for the include files specified within the include_cpp! macro.

Usually after this you’d call [build].

pub fn extra_clang_args(self, extra_clang_args: &[&str]) -> Self

Specify extra arguments for clang. These are used when parsing C++ headers. For example, you might want to provide -std=c++17 to specify C++17.

pub fn custom_gendir(self, custom_gendir: PathBuf) -> Self

Where to generate the code.

pub fn cpp_codegen_options<F>(self, modifier: F) -> Self

where F: FnOnce(&mut CppCodegenOptions<'_>),

Update C++ code generation options. See CppCodegenOptions for details.

pub fn auto_allowlist(self, do_it: bool) -> Self

Automatically discover uses of the C++ ffi mod and generate the allowlist from that. This is a highly experimental option, not currently recommended. It doesn’t work in the following cases:

• Static function calls on types within the FFI mod.
• Anything inside a macro invocation.
• You’re using a different name for your ffi mod
• You’re using multiple FFI mods
• You’ve got usages scattered across files beyond that with the include_cpp invocation
• You’re using use statements to rename mods or items. If this

proves to be a promising or helpful direction, autocxx would be happy to accept pull requests to remove some of these limitations.

pub fn suppress_system_headers(self, do_it: bool) -> Self

Whether to suppress inclusion of system headers (memory, string etc.) from generated C++ bindings code. This should not normally be used, but can occasionally be useful if you’re reducing a test case and you have a preprocessed header file which already contains absolutely everything that the bindings could ever need.

pub fn cxx_impl_annotations(self, cxx_impl_annotations: Option<String>) -> Self

An annotation optionally to include on each C++ function. For example to export the symbol from a library.

pub fn build(self) -> Result<BuilderBuild, BuilderError>

Build autocxx C++ files and return a cc::Build you can use to build more from a build.rs file.

The error type returned by this function supports miette::Diagnostic, so if you use the miette crate and its fancy feature, then simply return a miette::Result from your main function, you should get nicely printed diagnostics.

As this is a cc::Build there are lots of options you can apply to the resulting options, but please bear in mind that these only apply to the build process for the generated code - such options will not influence autocxx’s process for parsing header files.

For example, if you wish to set the C++ version to C++17, you might be tempted to use cc::Build::flag_if_supported to add the -std=c++17 flag. However, this won’t affect the header parsing which autocxx does internally (by means of bindgen) so you additionally should call [extra_clang_args] with that same option.

pub fn build_listing_files(self) -> Result<BuilderSuccess, BuilderError>

For use in tests only, this does the build and returns additional information about the files generated which can subsequently be examined for correctness. In production, please use simply [build].