Lines Matching +full:- +full:- +full:cxx
1 CXX — safe FFI between Rust and C++
4 …lds.io/badge/github-dtolnay/cxx-8da0cb?style=for-the-badge&labelColor=555555&logo=github" height="…
5 …ps://img.shields.io/crates/v/cxx.svg?style=for-the-badge&color=fc8d62&logo=rust" height="20">](htt…
6 …img.shields.io/badge/docs.rs-cxx-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs" height…
7 …ctions/workflow/status/dtolnay/cxx/ci.yml?branch=master&style=for-the-badge" height="20">](https:/…
11 using bindgen or cbindgen to generate unsafe C-style bindings.
21 cxx = "1.0"
23 [build-dependencies]
24 cxx-build = "1.0"
28 *[Release notes](https://github.com/dtolnay/cxx/releases)*
34 Please see **<https://cxx.rs>** for a tutorial, reference material, and example
43 this, CXX receives a complete picture of the boundary to perform static analyses
47 If everything checks out statically, then CXX uses a pair of code generators to
62 CXX guarantees an ABI-compatible signature that both sides understand, based on
74 of an existing C++ client for a large-file blobstore service. The blobstore
83 #[cxx::bridge]
97 fn next_chunk(buf: &mut MultiBuf) -> &[u8];
111 fn new_blobstore_client() -> UniquePtr<BlobstoreClient>;
112 fn put(&self, parts: &mut MultiBuf) -> u64;
114 fn metadata(&self, blobid: u64) -> BlobMetadata;
125 - [demo/src/main.rs](demo/src/main.rs)
126 - [demo/build.rs](demo/build.rs)
127 - [demo/include/blobstore.h](demo/include/blobstore.h)
128 - [demo/src/blobstore.cc](demo/src/blobstore.cc)
130 To look at the code generated in both languages for the example by the CXX code
135 # (requires https://github.com/dtolnay/cargo-expand)
136 $ cargo expand --manifest-path demo/Cargo.toml
139 $ cargo run --manifest-path gen/cmd/Cargo.toml -- demo/src/main.rs
149 - **Shared structs** — their fields are made visible to both languages.
150 The definition written within cxx::bridge is the single source of truth.
152 - **Opaque types** — their fields are secret from the other language.
155 for an arbitrarily complicated generic language-specific type depending on
158 - **Functions** — implemented in either language, callable from the other
161 Within the `extern "Rust"` part of the CXX bridge we list the types and
163 the `super` module, the parent module of the CXX bridge. You can think of the
165 `use super::next_chunk` except re-exported to C++. The parent module will either
171 it's possible that this section could be generated bindgen-style from the
176 to be defined as `extern "C"` ABI or no\_mangle. CXX will put in the right shims
183 Notice that with CXX there is repetition of all the function signatures: they
185 again inside the cxx::bridge module, though compile-time assertions guarantee
190 [bindgen]: https://github.com/rust-lang/rust-bindgen
193 This is because CXX fills a somewhat different role. It is a lower level tool
197 bindgen-like tool on top of CXX which consumes a C++ header and/or Rust module
198 (and/or IDL like Thrift) as source of truth and generates the cxx::bridge,
200 guarantees of CXX.
202 But note in other ways CXX is higher level than the bindgens, with rich support
204 with an idiomatic C++ API we would end up manually wrapping that API in C-style
209 By using a CXX bridge as the shared understanding between the languages, rather
210 than `extern "C"` C-style signatures as the shared understanding, common FFI use
213 It would also be reasonable to mix and match, using CXX bridge for the 95% of
215 the old fashioned way with bindgen and cbindgen, if for some reason CXX's static
222 ## Cargo-based setup
225 CXX's C++ code generator and compiles the resulting C++ code along with any
237 [build-dependencies]
238 cxx-build = "1.0"
247 .flag_if_supported("-std=c++11")
248 .compile("cxxbridge-demo");
250 println!("cargo:rerun-if-changed=src/main.rs");
251 println!("cargo:rerun-if-changed=src/demo.cc");
252 println!("cargo:rerun-if-changed=include/demo.h");
258 ## Non-Cargo setup
260 For use in non-Cargo builds like Bazel or Buck, CXX provides an alternate way of
262 packaged as the `cxxbridge-cmd` crate on crates.io or can be built from the
266 $ cargo install cxxbridge-cmd
268 $ cxxbridge src/main.rs --header > path/to/mybridge.h
281 practice to use CXX bridge effectively as it won't work in all the ways that you
286 - By design, our paired code generators work together to control both sides of
290 language. With CXX we achieve that visibility and know what's on the other
293 - Our static analysis detects and prevents passing types by value that shouldn't
297 - To many people's surprise, it is possible to have a struct in Rust and a
300 bindgen bug that leads to segfaults in absolutely correct-looking code
301 ([rust-lang/rust-bindgen#778]). CXX knows about this and can insert the
302 necessary zero-cost workaround transparently where needed, so go ahead and
306 - Template instantiations: for example in order to expose a UniquePtr\<T\> type
311 [rust-lang/rust-bindgen#778]: https://github.com/rust-lang/rust-bindgen/issues/778
327 <tr><td><a href="https://docs.rs/cxx/1.0/cxx/struct.CxxString.html">CxxString</a></td><td>std::stri…
329 <tr><td><a href="https://docs.rs/cxx/1.0/cxx/struct.UniquePtr.html">UniquePtr<T></a></td><td>…
330 <tr><td><a href="https://docs.rs/cxx/1.0/cxx/struct.SharedPtr.html">SharedPtr<T></a></td><td>…
333 <tr><td><a href="https://docs.rs/cxx/1.0/cxx/struct.CxxVector.html">CxxVector<T></a></td><td>…
335 <tr><td>fn(T, U) -> V</td><td>rust::Fn<V(T, U)></td><td><sup><i>only passing from Rust to …
339 The C++ API of the `rust` namespace is defined by the *include/cxx.h* file in
345 matter of designing a nice API for each in its non-native language.
361 This is still early days for CXX; I am releasing it as a minimum viable product
378 Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
379 2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
386 for inclusion in this project by you, as defined in the Apache-2.0 license,