1<div class="badges">
2<a href="https://github.com/dtolnay/cxx"><img src="https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github" alt="github" height="28" class="badge"></a><a href="https://crates.io/crates/cxx"><img src="https://img.shields.io/badge/crates.io-fc8d62?style=for-the-badge&labelColor=555555&logo=rust" alt="crates-io" height="28" class="badge"></a><a href="https://docs.rs/cxx"><img src="https://img.shields.io/badge/docs.rs-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs" alt="docs-rs" height="28" class="badge"></a>
3</div>
4
5# CXX — safe interop between Rust and C++
6
7This library provides a safe mechanism for calling C++ code from Rust and Rust
8code from C++. It carves out a regime of commonality where Rust and C++ are
9semantically very similar and guides the programmer to express their language
10boundary effectively within this regime. CXX fills in the low level stuff so
11that you get a safe binding, preventing the pitfalls of doing a foreign function
12interface over unsafe C-style signatures.
13
14<div style="height:190px;width=718px;padding:44px 0 44px">
15<object type="image/svg+xml" data="overview.svg"></object>
16</div>
17
18From a high level description of the language boundary, CXX uses static analysis
19of the types and function signatures to protect both Rust's and C++'s
20invariants. Then it uses a pair of code generators to implement the boundary
21efficiently on both sides together with any necessary static assertions for
22later in the build process to verify correctness.
23
24The resulting FFI bridge operates at zero or negligible overhead, i.e. no
25copying, no serialization, no memory allocation, no runtime checks needed.
26
27The FFI signatures are able to use native data structures from whichever side
28they please. In addition, CXX provides builtin bindings for key standard library
29types like strings, vectors, Box, unique\_ptr, etc to expose an idiomatic API on
30those types to the other language.
31
32## Example
33
34In this example we are writing a Rust application that calls a C++ client of a
35large-file blobstore service. The blobstore supports a `put` operation for a
36discontiguous buffer upload. For example we might be uploading snapshots of a
37circular buffer which would tend to consist of 2 pieces, or fragments of a file
38spread across memory for some other reason (like a rope data structure).
39
40```rust,noplayground
41#[cxx::bridge]
42mod ffi {
43    extern "Rust" {
44        type MultiBuf;
45
46        fn next_chunk(buf: &mut MultiBuf) -> &[u8];
47    }
48
49    unsafe extern "C++" {
50        include!("example/include/blobstore.h");
51
52        type BlobstoreClient;
53
54        fn new_blobstore_client() -> UniquePtr<BlobstoreClient>;
55        fn put(self: &BlobstoreClient, buf: &mut MultiBuf) -> Result<u64>;
56    }
57}
58```
59
60Now we simply provide Rust definitions of all the things in the `extern "Rust"`
61block and C++ definitions of all the things in the `extern "C++"` block, and get
62to call back and forth safely.
63
64The [***Tutorial***](tutorial.md) chapter walks through a fleshed out version of
65this blobstore example in full detail, including all of the Rust code and all of
66the C++ code. The code is also provided in runnable form in the *demo* directory
67of <https://github.com/dtolnay/cxx>. To try it out, run `cargo run` from that
68directory.
69
70- [demo/src/main.rs](https://github.com/dtolnay/cxx/blob/master/demo/src/main.rs)
71- [demo/include/blobstore.h](https://github.com/dtolnay/cxx/blob/master/demo/include/blobstore.h)
72- [demo/src/blobstore.cc](https://github.com/dtolnay/cxx/blob/master/demo/src/blobstore.cc)
73
74The key takeaway, which is enabled by the CXX library, is that the Rust code in
75main.rs is 100% ordinary safe Rust code working idiomatically with Rust types
76while the C++ code in blobstore.cc is 100% ordinary C++ code working
77idiomatically with C++ types. The Rust code feels like Rust and the C++ code
78feels like C++, not like C-style "FFI glue".
79
80<br>
81
82***Chapter outline:** See the hamburger menu in the top left if you are on a
83small screen and it didn't open with a sidebar by default.*
84