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.

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.

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.

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.