1{{#title Other build systems — Rust ♡ C++}} 2# Some other build system 3 4You will need to achieve at least these three things: 5 6- Produce the CXX-generated C++ bindings code. 7- Compile the generated C++ code. 8- Link the resulting objects together with your other C++ and Rust objects. 9 10### Producing the generated code 11 12CXX's Rust code generation automatically happens when the `#[cxx::bridge]` 13procedural macro is expanded during the normal Rust compilation process, so no 14special build steps are required there. 15 16But the C++ side of the bindings needs to be generated. Your options are: 17 18- Use the `cxxbridge` command, which is a standalone command line interface to 19 the CXX C++ code generator. Wire up your build system to compile and invoke 20 this tool. 21 22 ```console 23 $ cxxbridge src/bridge.rs --header > path/to/bridge.rs.h 24 $ cxxbridge src/bridge.rs > path/to/bridge.rs.cc 25 ``` 26 27 It's packaged as the `cxxbridge-cmd` crate on crates.io or can be built from 28 the *gen/cmd/* directory of the CXX GitHub repo. 29 30- Or, build your own code generator frontend on top of the [cxx-gen] crate. This 31 is currently unofficial and unsupported. 32 33[cxx-gen]: https://docs.rs/cxx-gen 34 35### Compiling C++ 36 37However you like. We can provide no guidance. 38 39### Linking the C++ and Rust together 40 41When linking a binary which contains mixed Rust and C++ code, you will have to 42choose between using the Rust toolchain (`rustc`) or the C++ toolchain which you 43may already have extensively tuned. 44 45Rust does not generate simple standalone `.o` files, so you can't just throw the 46Rust-generated code into your existing C++ toolchain linker. Instead you need to 47choose one of these options: 48 49* Use `rustc` as the final linker. Pass any non-Rust libraries using `-L 50 <directory>` and `-l<library>` rustc arguments, and/or `#[link]` directives in 51 your Rust code. If you need to link against C/C++ `.o` files you can use 52 `-Clink-arg=file.o`. 53 54* Use your C++ linker. In this case, you first need to use `rustc` and/or 55 `cargo` to generate a _single_ Rust `staticlib` target and pass that into your 56 foreign linker invocation. 57 58 * If you need to link multiple Rust subsystems, you will need to generate a 59 _single_ `staticlib` perhaps using lots of `extern crate` statements to 60 include multiple Rust `rlib`s. Multiple Rust `staticlib` files are likely 61 to conflict. 62 63Passing Rust `rlib`s directly into your non-Rust linker is not supported (but 64apparently sometimes works). 65 66See the [Rust reference's *Linkage*][linkage] page for some general information 67here. 68 69[linkage]: https://doc.rust-lang.org/reference/linkage.html 70 71The following open rust-lang issues might hold more recent guidance or 72inspiration: [rust-lang/rust#73632], [rust-lang/rust#73295]. 73 74[rust-lang/rust#73632]: https://github.com/rust-lang/rust/issues/73632 75[rust-lang/rust#73295]: https://github.com/rust-lang/rust/issues/73295 76