integration.md

Maybe we can add a short subsection, under the "Crates" section of crates.md, that simply tells you what you're facing if you decide to integrate Rust into a large C++ project. It would look like this:

Integrating Rust code into an existing C++ project

• calling from C++ to Rust (the easy direction)
  • building a Rust shared object or static library is easy
  • unwinding from Rust into C++ is undefined behavior (use catch_unwind)
  • you need to either generate a C++ header from Rust (use Cheddar) or generate Rust bindings from C++ (use bindgen). Either way, these projects are young. The experience is rough, at least for the next year or two.
  • how to compile & link C++ code against your Rust library (largely a matter of knowing where the headers and libs are)
    • you should unit-test your bindings which means compiling and linking C++ unit tests with your Rust library
• calling from Rust to C++
  • forward reference to unsafe and extern "C"
  • generating the extern "C" declarations from C++ headers (bindgen)
  • expect limitations (an example or two of stuff that doesn't work currently, C++ language features bindgen can't handle)
  • compiling and linking (rustc -L libdir -l static=foo and so forth; Cargo.toml equivalents; tests)
• circular dependencies between Rust and C++
• other stuff you need to think about
  • do you have to support unusual architectures?
  • libstd is statically linked into every Rust crate
  • doing without Cargo
    • can Cargo deal with your environment? if not:
    • how to use make to drive rustc (generating make dependencies, etc.) (?)
    • how to do testing if cargo can't build the whole project (?)
  • build and test automation infra
    • if Rust has to be installed on VMs as part of the build, builds may be slower
    • if not, you may have to make custom images or something (?)
    • and you may end up updating more often—Rust ships a minor version every 6 weeks
  • training for your team

It's a lot, and I don't know all the details.