Add an "internals" section to the book

CHANGELOG.md

@@ -38,10 +38,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `#[qobject]` attribute is now optional on types in `extern "RustQt"`
 - `#[qobject]` attribute is now required on types in `extern "C++Qt"`
 - `#[qenum]`s now resolve their namespace independently from their associated QObject
+- Reworked cxx-qt-build and the integration with CMake
+  - Dependencies are now automatically detected and configured by cxx-qt-build
+  - Libraries can pass build information to cxx-qt-build in the form of a `cxx_qt_build::Interface`
+  - Add CMake wrappers around corrosion to simplify importing crates and qml modules that were built with cxx-qt-build
 
 ### Removed
 
 - `qt_gui` and `qt_qml` features from `cxx-qt-build` they are only used in `cxx-qt-lib(-headers)` now
+- `cxx-qt-lib-headers` and `cxx-qt-lib-extras-headers` are now merged into their respective base crates
+- `BuildOpts` are replaced by the `Interface` type which does not need to be reiterated by downstream dependencies
 
 ## [0.6.1](https://github.com/KDAB/cxx-qt/compare/v0.6.0...v0.6.1) - 2024-04-19
 

book/src/SUMMARY.md

@@ -26,3 +26,5 @@ SPDX-License-Identifier: MIT OR Apache-2.0
   - [Shared types](./bridge/shared_types.md)
   - [Attributes](./bridge/attributes.md)
   - [Traits](./bridge/traits.md)
+- [For Contributors: CXX-Qt Internals](./internals/index.md)
+  - [Build System](./internals/build-system.md)

book/src/internals/build-system.md

@@ -0,0 +1,98 @@
+<!--
+SPDX-FileCopyrightText: 2024 Klarälvdalens Datakonsult AB, a KDAB Group company <info@kdab.com>
+SPDX-FileContributor: Leon Matthes <leon.matthes@kdab.com>
+
+SPDX-License-Identifier: MIT OR Apache-2.0
+-->
+
+# The CXX-Qt Build System
+
+Building with CXX-Qt is somewhat more complicated than it may sound at first.
+
+## The problems (or "challenges" if you prefer corporate jargon 😉)
+
+We unfortunately cannot simply link your Rust code into a static library and link to it for the following reasons:
+
+### Static Initializers
+
+Qt code often contains initialization code that is called by a static variable that runs the initialization code in its constructor.
+
+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 two 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.
+
+### 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
+
+Somehow, all of this should be compatible with both CMake, and Cargo-only builds.
+
+## The plan (for now)
+
+After many rounds of refactoring this, we believe the best way to go is to not rely on cargos OUT_DIR exclusivly.
+Not being able to share artifacts between crates is very limiting.
+
+We want to use a similar approach to CXX, which stores its data within either:
+
+- Cargos `target/` directory under the `cxxbridge` subfolder.
+- A custom `scratch` directory
+
+See: [https://github.com/dtolnay/cxx/blob/afd4aa3f3d4e5d5e9a3a41d09df3408f5f86a469/gen/build/src/target.rs#L10](https://github.com/dtolnay/cxx/blob/afd4aa3f3d4e5d5e9a3a41d09df3408f5f86a469/gen/build/src/target.rs#L10) \
+and: [https://github.com/dtolnay/cxx/blob/afd4aa3f3d4e5d5e9a3a41d09df3408f5f86a469/gen/build/src/lib.rs#L178](https://github.com/dtolnay/cxx/blob/afd4aa3f3d4e5d5e9a3a41d09df3408f5f86a469/gen/build/src/lib.rs#L178).
+
+We will likely mirror this and use the `cxxqtbridge` naming.
+
+## Contents of `cxxqtbridge`
+
+### `crates` directory
+
+Inside cxxqtbridge, there should be a `crates` folder with one subfolder per crate.
+Each crates subfolder should contain the following:
+
+- `include/`
+  - `crate-name` - A folder for all headers that are exported by this crate
+  - `cxx-qt-lib -> ../../cxx-qt-lib/include` - Symbolic links for every dependency
+- `manifest.json` - This file describes which headers this library makes available, if it needs any Qt modules, etc.
+- `initializers.o` - The initializers of this crate + all it's dependencies to be linked in by CMake
+
+When building with cxx-qt-build, you may simply specify that your code depends on another crate.
+However, we also need to make sure that the order in which the build scripts are run works out, as e.g. the build script of cxx-qt-lib needs to run **before** any dependents build scripts run.
+
+For this use-case, Cargo has the `links` key (see the documentation [here](https://doc.rust-lang.org/cargo/reference/build-scripts.html#the-links-manifest-key)).
+It allows us to ensure the correct order, and also to pass metadata between build scripts.
+We specifically use this to let downstream dependents know where to find our manifest.json.
+Via the `manifest.json`, we are then able to figure out which header paths of this dependency to include, which Qt modules to link, etc.
+
+To make sure the correct data ends up in the manifest.json, we provide the `cxx_qt_build::Interface` struct which uses the builder pattern to specify all the necessary data.
+
+### `qml_modules` directory
+
+Next to the crates directory, there should be a `qml_modules` directory, which contains one directory per declared QML module.
+
+Each module should include a `plugin_init.o`, `.qmltypes`, `qmldir`, and any other necessary files.
+
+## Integration with CMake
+
+Via the `CXXQT_EXPORT_DIR` environment variable CMake should be able to change the location of the `cxxqtbridge` directory.
+CMake can then expect required artifacts to exist at pre-defined locations, which can be added as dependency, include directories, objects, etc. to the Crate target.
+
+We will rely on Corrosion to import the crate and provide targets for it.
+
+However, we also want to provide some custom functions that wrap corrosion and set up the import of our own artifacts.
+
+Currently we plan to provide two functions:
+
+- cxxqt_import_crate
+  - A wrapper over corrosion_import_crate that defines the `CXXQT_EXPORT_DIR`, imports the initializers object files, etc.
+- cxxqt_import_qml_module
+  - Import a given QML module by URI from the given SOURCE_CRATE and provide it as a target.

book/src/internals/index.md

@@ -0,0 +1,12 @@
+<!--
+SPDX-FileCopyrightText: 2024 Klarälvdalens Datakonsult AB, a KDAB Group company <info@kdab.com>
+SPDX-FileContributor: Leon Matthes <leon.matthes@kdab.com>
+
+SPDX-License-Identifier: MIT OR Apache-2.0
+-->
+
+# CXX-Qt Internals
+
+This chapter explains some of CXX-Qts internal architecture and design decisions.
+
+The sections are mostly meant for CXX-Qt contributors, but may be interesting for a more comprehensive view for users of CXX-Qt as well.