From 10972e467d24cecfe446c2ea57696ec170032d1b Mon Sep 17 00:00:00 2001 From: Be Wilson Date: Wed, 29 Nov 2023 02:21:30 -0600 Subject: [PATCH] book: document splitting a project into crates --- book/src/concepts/build_systems.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/book/src/concepts/build_systems.md b/book/src/concepts/build_systems.md index 657d0f305..150206cc5 100644 --- a/book/src/concepts/build_systems.md +++ b/book/src/concepts/build_systems.md @@ -28,3 +28,18 @@ When using QML with CXX-Qt [QML modules](https://doc.qt.io/qt-6/qtqml-writing-a- This allows for attributes such as `#[qml_element]` to register the QObject with the QML type system without any C++ code. See [`QmlModule` documentation](https://docs.rs/cxx-qt-build/latest/cxx_qt_build/struct.QmlModule.html) for more details. + +## Splitting a project into multiple crates + +As your project grows, it can be helpful to organize your code into multiple Rust crates. If your `main` function is +in Rust ([Cargo is your only build system](../getting-started/4-cargo-executable.md)), simply add the crates as +dependencies of the top level binary crate in its Cargo.toml file. + +If your `main` function is in C++, you can only link one staticlib Rust crate into C++, otherwise linking +would fail with duplicate symbol errors from multiple Rust runtimes. So, create one top level staticlib crate to link +into the C++ application. Specify your other crates as normal Rust library (rlib) dependencies +in the staticlib crate's Cargo.toml. You must reference the symbols of the Rust dependencies within the staticlib crate; +if you don't need those symbols in Rust code, you can add `pub use crate_name;` statements in the staticlib's lib.rs file. +Refer to the [meta_project example](https://github.com/KDAB/cxx-qt/blob/main/examples/meta_project) for how to set this up. +Note that this requires Rust compiler features that were [stabilized](https://github.com/rust-lang/rust/pull/113301) +in Rust 1.74.