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.