Lines Matching +full:rust +full:- +full:src
1 …hub]](https://github.com/dtolnay/cxx) [![crates-io]](https://crates.io/crates/cxx) [![do…
3 //! [github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo…
4 //! [crates-io]: https://img.shields.io/badge/crates.io-fc8d62?style=for-the-badge&labelColor=55555…
5 //! [docs-rs]: https://img.shields.io/badge/docs.rs-66c2a5?style=for-the-badge&labelColor=555555&lo…
9 //! This library provides a **safe** mechanism for calling C++ code from Rust
10 //! and Rust code from C++, not subject to the many ways that things can go
11 //! wrong when using bindgen or cbindgen to generate unsafe C-style bindings.
14 //! a project, you would be on the hook for auditing all the unsafe Rust code
17 //! the Rust side can be 100% safe.
36 //! embedded together in one Rust module (the next section shows an example).
38 //! analyses against the types and function signatures to uphold both Rust's and
44 //! correctness. On the Rust side this code generator is simply an attribute
54 //! please, such as Rust's `String` or C++'s `std::string`, Rust's `Box` or
55 //! C++'s `std::unique_ptr`, Rust's `Vec` or C++'s `std::vector`, etc in any
56 //! combination. CXX guarantees an ABI-compatible signature that both sides
59 //! when manipulating a C++ string from Rust, its `len()` method becomes a call
60 //! of the `size()` member function defined by C++; when manipulation a Rust
61 //! string from C++, its `size()` member function calls Rust's `len()`.
67 //! In this example we are writing a Rust application that wishes to take
68 //! advantage of an existing C++ client for a large-file blobstore service. The
87 //! extern "Rust" {
89 //! // only Rust can see the fields.
92 //! // Functions implemented in Rust.
93 //! fn next_chunk(buf: &mut MultiBuf) -> &[u8];
107 //! fn new_blobstore_client() -> UniquePtr<BlobstoreClient>;
108 //! fn put(&self, parts: &mut MultiBuf) -> u64;
110 //! fn metadata(&self, blobid: u64) -> BlobMetadata;
116 //! # fn next_chunk(_buf: &mut MultiBuf) -> &[u8] {
123 //! Now we simply provide Rust definitions of all the things in the `extern
124 //! "Rust"` block and C++ definitions of all the things in the `extern "C++"`
129 //! - [demo/src/main.rs](https://github.com/dtolnay/cxx/blob/master/demo/src/main.rs)
130 //! - [demo/build.rs](https://github.com/dtolnay/cxx/blob/master/demo/build.rs)
131 //! - [demo/include/blobstore.h](https://github.com/dtolnay/cxx/blob/master/demo/include/blobstore.…
132 //! - [demo/src/blobstore.cc](https://github.com/dtolnay/cxx/blob/master/demo/src/blobstore.cc)
138 //! # run Rust code generator and print to stdout
139 //! # (requires https://github.com/dtolnay/cargo-expand)
140 //! $ cargo expand --manifest-path demo/Cargo.toml
143 //! $ cargo run --manifest-path gen/cmd/Cargo.toml -- demo/src/main.rs
153 //! - **Shared structs** — their fields are made visible to both
157 //! - **Opaque types** — their fields are secret from the other language.
159 //! indirection, such as a reference `&`, a Rust `Box`, or a `UniquePtr`. Can
160 //! be a type alias for an arbitrarily complicated generic language-specific
163 //! - **Functions** — implemented in either language, callable from the
166 //! Within the `extern "Rust"` part of the CXX bridge we list the types and
167 //! functions for which Rust is the source of truth. These all implicitly refer
170 //! super::MultiBuf` and `use super::next_chunk` except re-exported to C++. The
177 //! the future it's possible that this section could be generated bindgen-style
181 //! Your function implementations themselves, whether in C++ or Rust, *do not*
190 //! they are typed out once where the implementation is defined (in C++ or Rust)
191 //! and again inside the cxx::bridge module, though compile-time assertions
196 //! [bindgen]: https://github.com/rust-lang/rust-bindgen
203 //! higher level bindgen-like tool on top of CXX which consumes a C++ header
204 //! and/or Rust module (and/or IDL like Thrift) as source of truth and generates
211 //! API in C-style raw pointer functions, applying bindgen to get unsafe raw
212 //! pointer Rust functions, and replicating the API again to expose those
213 //! idiomatically in Rust. That's a much worse form of repetition because it is
217 //! rather than `extern "C"` C-style signatures as the shared understanding,
229 //! # Cargo-based setup
244 //! [build-dependencies]
245 //! cxx-build = "1.0"
252 //! cxx_build::bridge("src/main.rs") // returns a cc::Build
253 //! .file("src/demo.cc")
254 //! .flag_if_supported("-std=c++11")
255 //! .compile("cxxbridge-demo");
257 //! println!("cargo:rerun-if-changed=src/main.rs");
258 //! println!("cargo:rerun-if-changed=src/demo.cc");
259 //! println!("cargo:rerun-if-changed=include/demo.h");
265 //! # Non-Cargo setup
267 //! For use in non-Cargo builds like Bazel or Buck, CXX provides an alternate
269 //! The tool is packaged as the `cxxbridge-cmd` crate on crates.io or can be
273 //! $ cargo install cxxbridge-cmd
275 //! $ cxxbridge src/main.rs --header > path/to/mybridge.h
276 //! $ cxxbridge src/main.rs > path/to/mybridge.cc
293 //! - By design, our paired code generators work together to control both sides
294 //! of the FFI boundary. Ordinarily in Rust writing your own `extern "C"`
295 //! blocks is unsafe because the Rust compiler has no way to know whether the
300 //! - Our static analysis detects and prevents passing types by value that
301 //! shouldn't be passed by value from C++ to Rust, for example because they
302 //! may contain internal pointers that would be screwed up by Rust's move
305 //! - To many people's surprise, it is possible to have a struct in Rust and a
309 //! correct-looking code ([rust-lang/rust-bindgen#778]). CXX knows about this
310 //! and can insert the necessary zero-cost workaround transparently where
315 //! - Template instantiations: for example in order to expose a UniquePtr\<T\>
316 //! type in Rust backed by a real C++ unique\_ptr, we have a way of using a
317 //! Rust trait to connect the behavior back to the template instantiations
320 //! [rust-lang/rust-bindgen#778]: https://github.com/rust-lang/rust-bindgen/issues/778
331 //! <tr><th>name in Rust</th><th>name in C++</th><th>restrictions</th></tr>
332 //! <tr><td>String</td><td>rust::String</td><td></td></tr>
333 //! <tr><td>&str</td><td>rust::Str</td><td></td></tr>
334 //! <tr><td>&[T]</td><td>rust::Slice<const T></td><td><sup><i>cannot hold opaque C++ type…
335 //! <tr><td>&mut [T]</td><td>rust::Slice<T></td><td><sup><i>cannot hold opaque C++ type</…
337 //! <tr><td>Box<T></td><td>rust::Box<T></td><td><sup><i>cannot hold opaque C++ type</i>…
338 …;</a></td><td>std::unique_ptr<T></td><td><sup><i>cannot hold opaque Rust type</i></sup></td>…
339 …;</a></td><td>std::shared_ptr<T></td><td><sup><i>cannot hold opaque Rust type</i></sup></td>…
341 //! <tr><td>Vec<T></td><td>rust::Vec<T></td><td><sup><i>cannot hold opaque C++ type</i>…
342 …or<T></td><td><sup><i>cannot be passed by value, cannot hold opaque Rust type</i></sup></td>…
344 //! <tr><td>fn(T, U) -> V</td><td>rust::Fn<V(T, U)></td><td><sup><i>only passing from Rust…
348 //! The C++ API of the `rust` namespace is defined by the *include/cxx.h* file
354 //! it's a matter of designing a nice API for each in its non-native language.
357 //! <tr><th>name in Rust</th><th>name in C++</th></tr>
437 /// To avoid confusion with Rust's standard library string you probably
444 /// To avoid confusion with Rust's standard library vector you probably