76 lines
2.8 KiB
Markdown
76 lines
2.8 KiB
Markdown
{{#title Other build systems — Rust ♡ C++}}
|
|
# Some other build system
|
|
|
|
You will need to achieve at least these three things:
|
|
|
|
- Produce the CXX-generated C++ bindings code.
|
|
- Compile the generated C++ code.
|
|
- Link the resulting objects together with your other C++ and Rust objects.
|
|
|
|
### Producing the generated code
|
|
|
|
CXX's Rust code generation automatically happens when the `#[cxx::bridge]`
|
|
procedural macro is expanded during the normal Rust compilation process, so no
|
|
special build steps are required there.
|
|
|
|
But the C++ side of the bindings needs to be generated. Your options are:
|
|
|
|
- Use the `cxxbridge` command, which is a standalone command line interface to
|
|
the CXX C++ code generator. Wire up your build system to compile and invoke
|
|
this tool.
|
|
|
|
```console
|
|
$ cxxbridge src/bridge.rs --header > path/to/bridge.rs.h
|
|
$ cxxbridge src/bridge.rs > path/to/bridge.rs.cc
|
|
```
|
|
|
|
It's packaged as the `cxxbridge-cmd` crate on crates.io or can be built from
|
|
the *gen/cmd/* directory of the CXX GitHub repo.
|
|
|
|
- Or, build your own code generator frontend on top of the [cxx-gen] crate. This
|
|
is currently unofficial and unsupported.
|
|
|
|
[cxx-gen]: https://docs.rs/cxx-gen
|
|
|
|
### Compiling C++
|
|
|
|
However you like. We can provide no guidance.
|
|
|
|
### Linking the C++ and Rust together
|
|
|
|
When linking a binary which contains mixed Rust and C++ code, you will have to
|
|
choose between using the Rust toolchain (`rustc`) or the C++ toolchain which you
|
|
may already have extensively tuned.
|
|
|
|
Rust does not generate simple standalone `.o` files, so you can't just throw the
|
|
Rust-generated code into your existing C++ toolchain linker. Instead you need to
|
|
choose one of these options:
|
|
|
|
* Use `rustc` as the final linker. Pass any non-Rust libraries using `-L
|
|
<directory>` and `-l<library>` rustc arguments, and/or `#[link]` directives in
|
|
your Rust code. If you need to link against C/C++ `.o` files you can use
|
|
`-Clink-arg=file.o`.
|
|
|
|
* Use your C++ linker. In this case, you first need to use `rustc` and/or
|
|
`cargo` to generate a _single_ Rust `staticlib` target and pass that into your
|
|
foreign linker invocation.
|
|
|
|
* If you need to link multiple Rust subsystems, you will need to generate a
|
|
_single_ `staticlib` perhaps using lots of `extern crate` statements to
|
|
include multiple Rust `rlib`s. Multiple Rust `staticlib` files are likely
|
|
to conflict.
|
|
|
|
Passing Rust `rlib`s directly into your non-Rust linker is not supported (but
|
|
apparently sometimes works).
|
|
|
|
See the [Rust reference's *Linkage*][linkage] page for some general information
|
|
here.
|
|
|
|
[linkage]: https://doc.rust-lang.org/reference/linkage.html
|
|
|
|
The following open rust-lang issues might hold more recent guidance or
|
|
inspiration: [rust-lang/rust#73632], [rust-lang/rust#73295].
|
|
|
|
[rust-lang/rust#73632]: https://github.com/rust-lang/rust/issues/73632
|
|
[rust-lang/rust#73295]: https://github.com/rust-lang/rust/issues/73295
|