Crate autocxx

Autocxx

This project is a tool for calling C++ from Rust in a heavily automated, but safe, fashion.

The intention is that it has all the fluent safety from cxx whilst generating interfaces automatically from existing C++ headers using a variant of bindgen. Think of autocxx as glue which plugs bindgen into cxx.

For full documentation, see the manual.

Overview

autocxx::include_cpp! {
    #include "url/origin.h"
    generate!("url::Origin")
    safety!(unsafe_ffi)
}

fn main() {
    let o = ffi::url::Origin::CreateFromNormalizedTuple("https",
        "google.com", 443);
    let uri = o.Serialize();
    println!("URI is {}", uri.to_str().unwrap());
}

License and usage notes

This is not an officially supported Google product.

^{Licensed under either of Apache License, Version 2.0 or MIT license at your option.}

Re-exports

pub use rvalue_param::RValueParamHandler;

pub use value_param::ValueParamHandler;

pub use moveit;

pub use cxx;

Modules

extern_rust

Tools to export Rust code to C++.

prelude

Imports which you’re likely to want to use.

subclass

Module to make Rust subclasses of C++ classes. See CppSubclass for details.

Macros

block

Entirely block some type from appearing in the generated code. This can be useful if there is a type which is not understood by bindgen or autocxx, and incorrect code is otherwise generated. This is ‘greedy’ in the sense that any functions/methods which take or return such a type will also be blocked. See also opaque.

block_constructors

Avoid generating implicit constructors for this type. The rules for when to generate C++ implicit constructors are complex, and if autocxx gets it wrong, you can block such constructors using this.

concrete

A concrete type to make, for example concrete!("Container<Contents>"). All types must already be on the allowlist by having used generate! or similar.

exclude_impls

Whether to avoid generating cxx::UniquePtr and cxx::Vector implementations. This is primarily useful for reducing test cases and shouldn’t be used in normal operation.

exclude_utilities

Skip the normal generation of a make_string function and other utilities which we might generate normally. A directive to be included inside include_cpp - see include_cpp for general information.

extern_cpp_opaque_type

Indicates that a C++ type is not to be generated by autocxx in this case, but instead should refer to some pre-existing Rust type. Unlike extern_cpp_type!, there’s no need for the size and alignment of this type to be correct.

extern_cpp_type

Indicates that a C++ type is not to be generated by autocxx in this case, but instead should refer to some pre-existing Rust type.

extern_rust_type

See extern_rust::extern_rust_type.

generate

Generate Rust bindings for the given C++ type or function. A directive to be included inside include_cpp - see include_cpp for general information. See also generate_pod.

generate_all

Generate Rust bindings for all C++ types and functions found. Highly experimental and not recommended. A directive to be included inside include_cpp - see include_cpp for general information. See also generate.

generate_ns

Generate Rust bindings for all C++ types and functions in a given namespace. A directive to be included inside include_cpp - see include_cpp for general information. See also generate.

generate_pod

Generate as “plain old data” and add to allowlist. Generate Rust bindings for the given C++ type such that it can be passed and owned by value in Rust. This only works for C++ types which have trivial move constructors and no destructor - you’ll encounter a compile error otherwise. If your type doesn’t match that description, use generate instead, and own the type using UniquePtr. A directive to be included inside include_cpp - see include_cpp for general information.

include

Include a C++ header. A directive to be included inside include_cpp - see include_cpp for details

include_cpp

Include some C++ headers in your Rust project.

instantiable

Indicates that a C++ type can definitely be instantiated. This has effect only in a very specific case:

name

The name of the mod to be generated with the FFI code. The default is ffi.

opaque

Instruct bindgen to generate a type as an opaque type - that is, without fields inside it. This should be used only when there’s a need to workaround some bindgen issue where it’s incorrectly generating the type. See the bindgen documentation for what exactly this means.

pod

Generate as “plain old data”. For use with generate_all and similarly experimental.

rust_typeDeprecated

Deprecated - use extern_rust_type instead.

safety

Specifies a global safety policy for functions generated from these headers. By default (without such a safety! directive) all such functions are marked as unsafe and therefore can only be called within an unsafe {} block or some unsafe function which you create.

subclass

See subclass::subclass.

Structs

BindingGenerationFailure

autocxx couldn’t generate these bindings. If you come across a method, type or function which refers to this type, it indicates that autocxx couldn’t generate that binding. A documentation comment should be attached indicating the reason.

CppLtRef

A CppRef with an associated lifetime. This can be used in place of any CppRef due to a Deref implementation.

CppMutLtRef

CppMutRef

A C++ non-const reference. These are different from Rust’s &mut T in that several C++ references can exist to the same underlying data (“aliasing”) and that’s not permitted for regular Rust references.

CppPin

A newtype wrapper which causes the contained object to obey C++ reference semantics rather than Rust reference semantics. That is, multiple aliasing mutable C++ references may exist to the contents.

CppRef

A C++ const reference. These are different from Rust’s &T in that these may exist even while the object is mutated elsewhere. See also CppMutRef for the mutable equivalent.

CppUniquePtrPin

Any newtype wrapper which causes the contained UniquePtr target to obey C++ reference semantics rather than Rust reference semantics. That is, multiple aliasing mutable C++ references may exist to the contents.

c_char16_t

A C++ char16_t

c_int

Newtype wrapper for an int

c_long

Newtype wrapper for a long

c_longlong

Newtype wrapper for a long long

c_short

Newtype wrapper for an short

c_uchar

Newtype wrapper for an unsigned char

c_uint

Newtype wrapper for an unsigned int

c_ulong

Newtype wrapper for an unsigned long

c_ulonglong

Newtype wrapper for an unsigned long long

c_ushort

Newtype wrapper for an unsigned short

c_void

Newtype wrapper for a C void. Only useful as a *c_void

Traits

AsCppMutRef

Any type which can return a C++ reference to its contents.

AsCppRef

Any type which can return a C++ reference to its contents.

PinMut

Equivalent to std::convert::AsMut, but returns a pinned mutable reference such that cxx methods can be called on it.

RValueParam

A trait representing a parameter to a C++ function which is received by rvalue (i.e. by move).

ValueParam

A trait representing a parameter to a C++ function which is received by value.

WithinBox

Provides utility functions to emplace any moveit::New into a Box. Automatically imported by the autocxx prelude and implemented by any (autocxx-related) moveit::New.

WithinBoxTrivial

Emulates the WithinBox trait, but for trivial (plain old data) types. This allows such types to behave identically if a type is changed from generate! to generate_pod!.

WithinUniquePtr

Provides utility functions to emplace any moveit::New into a cxx::UniquePtr. Automatically imported by the autocxx prelude and implemented by any (autocxx-related) moveit::New.

WithinUniquePtrTrivial

Emulates the WithinUniquePtr trait, but for trivial (plain old data) types. This allows such types to behave identically if a type is changed from generate! to generate_pod!.

Functions

as_copy

Explicitly force a value parameter to be taken by copy.

as_mov

Explicitly force a value parameter to be taken using C++ move semantics.

as_new

Explicitly force a value parameter to be taken using any type of crate::moveit::new::New, i.e. a constructor.