Update Changelog and documentation

Author: LeonMatthesKDAB

CHANGELOG.md

@@ -26,6 +26,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Allow creating a `QImage` from an `image::RgbaImage`.
 - Support for `cfg` attributes through to C++ generation
 - CXX-Qt-build: Improved compile time and propagation of initializers between crates
+- CXX-Qt-build: Multi-crate projects are now possible with Cargo and CMake (see `examples/qml_multi_crates`)
+- CXX-Qt-build: Allow forcing initialization of crates/QML modules (`cxx_qt::init_crate!`/`cxx_qt::init_qml_module!`)
 
 ### Fixed
 

book/src/internals/build-system.md

@@ -19,46 +19,17 @@ Qt code often contains initialization code that is called by a static variable t
 
 However, when linking into a static library, and then linking into the main executable, the linker will discard everything from the library that isn't used by the main executable, including these static initializers, as they're never actually used and just exist to run their constructor code.
 
-There are multiple ways to solve this:
-
-- Export an object file and link that to the main binary. Object files are always included completely
-- Use the whole-archive linker flag which forces inclusion of every object within the static library.
-  - If we include the entire static lib generated by cargo, then we'll likely get duplicate symbols, as this really includes **everything** that your Rust code **may** need, even if you don't use it.
-  - This has caused some recent regressions with Rust 1.78+, where MSVC could no longer link CXX-Qt due to duplicate symbols
-  - The way to solve this is to only export the static initializers as a library and link that into CMake.
-- Manually calling the static initializer code
-  - This is basically what Q_INIT_RESOURCE and Q_IMPORT_PLUGIN do
-  - They call the registration method directly, which circumvents the static initializers and forces the static initializers to be linked if they would otherwise be discarded.
-
-At the moment we employ a mix of all methods.
-
-First and foremost, we wrap all our initializers into functions with well-defined names (starting with `cxx_qt_init`) and C-compatible signatures.
-This allows us to manually call the initializers from any point in the linker chain, which forces their inclusion.
-These initializer functions call the initializer functions from their upstream dependencies so that the entire dependency tree is initialized.
-
-However, we don't want to have to call the initializers manually in every resulting binary.
-To solve this, we use static initializers that simply call the initializer function of the crate/Qml module, thereby initializing all dependencies.
-As noted earlier, these static initializers are routinely optimized out by the linker.
-
-For Cargo builds we prevent this by linking all initializers with +whole-archive which forces all of them to be included.
-Experience has shown that this gives us the best compatibility overall, as linking object files to Cargo builds turned out to be quite finicky.
-As the initializers contain very few symbols themselves, this should also rarely lead to issues with duplicate symbols.
-
-In CMake we mirror Qts behavior, which is to build the static initializer as an `OBJECT` library.
-The initializer functions themselves are still built into the Rust static library and the `OBJECT` library must therefore link to it.
-This is taken care of by the `cxx_qt_import_crate`/`_import_qml_module` functions.
-
 ### Header files
 
 We want to make the generated headers available, not just to CMake, but also within dependents in the cargo build chain (e.g. your crate will probably want to depend on the headers produced by cxx-qt-lib).
 
 For this we need to export them to a stable directory so that both CMake and Cargo can find them.
 
-### (Optional) Integration with CMake
+# (Optional) Integration with CMake
 
 Somehow, all of this should be compatible with both CMake, and Cargo-only builds.
 
-## The plan (for now)
+# The plan (for now)
 
 After many rounds of refactoring this, we believe that we need to be able to share data between build scripts for this to work halfway ergonomically.
 
@@ -97,6 +68,37 @@ Next to the crates directory, there should be a `qml_modules` directory, which c
 
 Each module should include a `plugin_init.o`, `.qmltypes`, `qmldir`, and any other necessary files.
 
+## Initializers with Cargo and CMake
+
+There are multiple ways to solve the issues presented by static initializers:
+
+- Export an object file and link that to the main binary. Object files are always included completely.
+- Use the whole-archive linker flag which forces inclusion of every object within the static library.
+  - If we include the entire static lib generated by cargo, then we'll likely get duplicate symbols, as this really includes **everything** that your Rust code **may** need, even if you don't use it.
+  - This has caused some recent regressions with Rust 1.78+, where MSVC could no longer link CXX-Qt due to duplicate symbols
+  - The way to solve this is to only export the static initializers as a library and link that into CMake.
+- Manually calling the static initializer code
+  - This is basically what Q_INIT_RESOURCE and Q_IMPORT_PLUGIN do
+  - They call the registration method directly, which circumvents the static initializers and forces the static initializers to be linked if they would otherwise be discarded.
+
+At the moment we employ a mix of all methods.
+
+First and foremost, we wrap all our initializers into functions with well-defined names (starting with `cxx_qt_init`) and C-compatible signatures.
+This allows us to manually call the initializers from any point in the linker chain, which forces their inclusion.
+These initializer functions call the initializer functions from their upstream dependencies so that the entire dependency tree is initialized.
+
+However, we don't want to have to call the initializers manually in every resulting binary.
+To solve this, we use static initializers that simply call the initializer function of the crate/Qml module, thereby initializing all dependencies.
+As noted earlier, these static initializers are routinely optimized out by the linker.
+
+For Cargo builds we prevent this by linking all initializers with +whole-archive which forces all of them to be included.
+Experience has shown that this gives us the best compatibility overall, as linking object files to Cargo builds turned out to be quite finicky.
+As the initializers contain very few symbols themselves, this should also rarely lead to issues with duplicate symbols.
+
+In CMake we mirror Qts behavior, which is to build the static initializer as an `OBJECT` library.
+The initializer functions themselves are still built into the Rust static library and the `OBJECT` library must therefore link to it.
+This is taken care of by the `cxx_qt_import_crate`/`_import_qml_module` functions.
+
 ## Integration with CMake
 
 Via the `CXXQT_EXPORT_DIR` environment variable CMake should be able to change the location of the "target" directory.