Lines Matching +full:crate +full:- +full:example
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…
11 //! wrong when using bindgen or cbindgen to generate unsafe C-style bindings.
29 //! example code.
36 //! embedded together in one Rust module (the next section shows an example).
56 //! combination. CXX guarantees an ABI-compatible signature that both sides
58 //! expose an idiomatic API on those types to the other language. For example
65 //! # Example
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
70 //! example we might be uploading snapshots of a circular buffer which would
74 //! A runnable version of this example is provided under the *demo* directory of
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] {
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)
134 //! To look at the code generated in both languages for the example by the CXX
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
150 //! As seen in the example, the language of the FFI boundary involves 3 kinds of
153 //! - **Shared structs** — their fields are made visible to both
157 //! - **Opaque types** — their fields are secret from the other language.
160 //! be a type alias for an arbitrarily complicated generic language-specific
163 //! - **Functions** — implemented in either language, callable from the
169 //! the two items listed in the example above as being like `use
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
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
211 //! API in C-style raw pointer functions, applying bindgen to get unsafe raw
217 //! rather than `extern "C"` C-style signatures as the shared understanding,
229 //! # Cargo-based setup
233 //! any other C++ code for your crate.
236 //! [`cc::Build`] instance (from the usual widely used `cc` crate) on which you
244 //! [build-dependencies]
245 //! cxx-build = "1.0"
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
293 //! - By design, our paired code generators work together to control both sides
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
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\>
320 //! [rust-lang/rust-bindgen#778]: https://github.com/rust-lang/rust-bindgen/issues/778
344 //! <tr><td>fn(T, U) -> V</td><td>rust::Fn<V(T, U)></td><td><sup><i>only passing from Rust…
354 //! it's a matter of designing a nice API for each in its non-native language.
396 …clippy::transmute_undefined_repr, // clippy bug: https://github.com/rust-lang/rust-clippy/issues/8…
402 extern crate link_cplusplus;
404 extern crate self as cxx;
407 pub extern crate core;
411 pub extern crate alloc;
414 extern crate core as alloc;
418 pub extern crate std;
421 // a compile-time error on edition 2018+.
423 extern crate core as std;
427 …t build with at least one of feature="std", feature="alloc", or RUSTFLAGS='--cfg cxx_experimental_…
470 pub use crate::cxx_vector::CxxVector;
472 pub use crate::exception::Exception;
473 pub use crate::extern_type::{kind, ExternType};
474 pub use crate::shared_ptr::SharedPtr;
475 pub use crate::string::CxxString;
476 pub use crate::unique_ptr::UniquePtr;
477 pub use crate::weak_ptr::WeakPtr;
497 pub use crate::c_char::c_char;
498 pub use crate::cxx_vector::VectorElement;
499 pub use crate::extern_type::{verify_extern_kind, verify_extern_type};
500 pub use crate::function::FatFunction;
501 pub use crate::hash::hash;
502 pub use crate::opaque::Opaque;
504 pub use crate::result::{r#try, Result};
505 pub use crate::rust_slice::RustSlice;
506 pub use crate::rust_str::RustStr;
508 pub use crate::rust_string::RustString;
509 pub use crate::rust_type::{ImplBox, ImplVec, RustType};
511 pub use crate::rust_vec::RustVec;
512 pub use crate::shared_ptr::SharedPtrTarget;
513 pub use crate::string::StackString;
514 pub use crate::unique_ptr::UniquePtrTarget;
515 pub use crate::unwind::prevent_unwind;
516 pub use crate::weak_ptr::WeakPtrTarget;