Write a book or guide or something

[dtolnay]

We're in stable enough shape now to put together some better teaching material.

So far the main ways to learn about the intended functionality of this library are:

• The introductory demo project, which is nice but covers only some of the functionality;
• The test suite, which doesn't come with explanations of the concepts;
• Issues and PRs;
• Release notes.

It's worth starting to work on something that would meet roughly the thoroughness of https://rust-lang.github.io/rust-bindgen.

[dtolnay]

#222 (comment):

In particular it' be very helpful to see an example of how to write a simple binding to a c++ shared library.

[dtolnay]

I grabbed https://cxx.rs to host stuff. It gets published automatically using mdbook from the master branch of https://github.com/dtolnay/cxx/tree/master/book.

Now we just need to write the content. :)

[adetaylor]

I am on the cusp of volunteering to do this, but I know if I did that, it would be instead of my https://github.com/google/autocxx experiments, and I feel I need to keep digging into those for now. But, if I get stalled there, and if you don't make progress on this in the next couple of months, I might be tempted to have a crack at it. I like writing. That doesn't mean I'm any good at it, of course :)

Meanwhile, thoughts so far:

• Need something explaining the context of cxx relative to bindgen, cbindgen, cc. Specifically, start from user scenarios. If user has 99% Rust and a single C++ function that they need to call, which should they use? What if they have an expansive C++ codebase?
• Ideally need a chapter on linking mixed codebases. I tried to make a small improvement here: Explaining how to link mixed C/Rust binaries. rust-lang/reference#838 but was slightly spurned (sniffle)
• Need something on ABIs. I've seen objections to cxx on the basis that teams don't want to maintain a stable C++ ABI. Yet, cxx doesn't rely on a stable C++ ABI. A nice diagram explaining the Rust and C++ side wrappers would go a long way here.
• Need something on safety. Controversial! Whoever writes this needs danger money.
• Error handling
• 'Using existing C++ types'. (decision process for making them opaque or visible to cxx)
• Chapter on extern types.
• Efficiency. For instance you can pass a slice of u8s from C++ into Rust, parse in serde_json, then have callbacks to C++ with the parsed data, with zero copies at any point. On the other hand, strings passing from C++ to Rust need to be utf-checked. We probably need to write something about that. We probably need to mention cross-language LTO.
• C++ build environments.
• Something that I definitely wouldn't be able to write: design patterns for using cxx in a large codebase.

[dtolnay]

Thank you, your list is very helpful.

• Need something on safety. Controversial! Whoever writes this needs danger money.

Definitely needs a page. At this point I think the controversy is 100% resolved by https://www.reddit.com/r/rust/comments/ielvxu/the_cxx_debate/g2i1r7a/ which I implemented in rust-lang/rust#75857 and will be available in rust 1.48 -- we'll release 0.(n+1) when it hits the stable compiler to require either unsafe mod or unsafe extern "C++" around any safe extern C++ signature. But we need documentation which is extremely clear about the programmer's responsibility in that case.