cxx-qt-build: add Cargo feature to toggle linking Qt's .o files

Unfortunately, there is no way to get linking to work in every case
without conditional compilation. This feature needs to be enabled
for bin crates or when running `cargo test` for library crates. The
feature must not be enabled when builing a staticlib then linking
it with CMake because CMake will also link the .o files, which
makes linking fail with duplicate symbol errors.

Author: Be-ing

CMakeLists.txt

@@ -195,9 +195,9 @@ endif()
 set(CARGO_TARGET_DIR "${CMAKE_BINARY_DIR}/${BUILD_DIR}/cargo/build")
 
 # Add CMake tests for `cargo test/clippy/fmt/doc`.
-add_test(NAME cargo_tests COMMAND cargo test --all-targets --target-dir
+add_test(NAME cargo_tests COMMAND cargo test --features link_qt_object_files --all-targets --target-dir
                                   ${CARGO_TARGET_DIR})
-add_test(NAME cargo_doc_tests COMMAND cargo test --doc --target-dir
+add_test(NAME cargo_doc_tests COMMAND cargo test --features link_qt_object_files --doc --target-dir
                                       ${CARGO_TARGET_DIR})
 add_test(NAME cargo_doc COMMAND cargo doc --workspace --target-dir ${CARGO_TARGET_DIR})
 add_test(NAME cargo_clippy COMMAND cargo clippy --all-targets --target-dir

crates/cxx-qt-build/Cargo.toml

@@ -29,3 +29,4 @@ default = ["qt_gui", "qt_qml"]
 qt_gui = ["cxx-qt-lib-headers/qt_gui"]
 qt_qml = ["cxx-qt-lib-headers/qt_qml"]
 link_qt_external = []
+link_qt_object_files = ["qt-build-utils/link_qt_object_files"]

crates/qt-build-utils/Cargo.toml

@@ -16,3 +16,16 @@ repository.workspace = true
 cc = "1.0.74"
 versions = "4.1.0"
 thiserror = "1.0"
+
+[features]
+# When Cargo links an executable, whether a bin crate or test executable,
+# and Qt 6 is linked statically, this feature must be enabled to link
+# unarchived .o files with static symbols that Qt ships (for example
+# to initialize Qt resources embedded within Qt libraries).
+#
+# CMake also links those .o files when linking Qt's targets, so this
+# feature must be disabled for staticlib crates. Otherwise, linking
+# will fail with duplicate symbol errors.
+#
+# When linking Qt dynamically, this makes no difference.
+link_qt_object_files = []

crates/qt-build-utils/src/parse_cflags.rs

@@ -8,8 +8,12 @@
 //! It has been decoupled from the pkg-config crate because qt-build-utils reads Qt's .prl files instead, which
 //! does not require a pkg-config executable to be available.
 
-use std::{collections::HashSet, env, sync::OnceLock};
+use std::env;
 
+#[cfg(feature = "link_qt_object_files")]
+use std::{collections::HashSet, sync::OnceLock};
+
+#[cfg(feature = "link_qt_object_files")]
 static mut LINKED_OBJECT_FILES: OnceLock<HashSet<String>> = OnceLock::new();
 
 /// Extract the &str to pass to cargo:rustc-link-lib from a filename (just the file name, not including directories)
@@ -108,7 +112,7 @@ fn split_flags(link_args: &[u8]) -> Vec<String> {
 pub(crate) fn parse_libs_cflags(
     name: &str,
     link_args: &[u8],
-    builder: &mut Option<&mut cc::Build>,
+    _builder: &mut Option<&mut cc::Build>,
 ) {
     let mut is_msvc = false;
     let target = env::var("TARGET");
@@ -171,8 +175,10 @@ pub(crate) fn parse_libs_cflags(
                     if let (Some(dir), Some(file_name), Ok(target)) =
                         (path.parent(), path.file_name(), &target)
                     {
-                        if file_name.to_string_lossy().ends_with(".o") {
-                            if let Some(builder) = builder {
+                        let file_name = file_name.to_string_lossy();
+                        if file_name.ends_with(".o") {
+                            #[cfg(feature = "link_qt_object_files")]
+                            if let Some(builder) = _builder {
                                 let path_string = path.to_string_lossy().to_string();
                                 unsafe {
                                     // Linking will fail with duplicate symbol errors if the same .o file is linked twice.
@@ -192,7 +198,7 @@ pub(crate) fn parse_libs_cflags(
                                 }
                             }
                         } else {
-                            match extract_lib_from_filename(target, &file_name.to_string_lossy()) {
+                            match extract_lib_from_filename(target, &file_name) {
                                 Some(lib_basename) => {
                                     println!("cargo:rustc-link-search={}", dir.display());
                                     println!("cargo:rustc-link-lib={lib_basename}");

examples/cargo_without_cmake/Cargo.toml

@@ -27,5 +27,6 @@ cxx-qt-lib.workspace = true
 
 [build-dependencies]
 # Use `cxx-qt-build = "0.5"` here instead!
-cxx-qt-build.workspace = true
+# The link_qt_object_files feature is required for statically linking Qt 6.
+cxx-qt-build = { workspace = true, features = [ "link_qt_object_files" ] }
 # ANCHOR_END: book_cargo_toml_no_cmake

examples/demo_threading/rust/Cargo.toml

@@ -25,3 +25,6 @@ uuid = { version = "1.2", features = ["serde", "v4"] }
 
 [build-dependencies]
 cxx-qt-build.workspace = true
+
+[features]
+link_qt_object_files = [ "cxx-qt-build/link_qt_object_files" ]

examples/qml_extension_plugin/plugin/rust/Cargo.toml

@@ -22,3 +22,6 @@ serde_json.workspace = true
 
 [build-dependencies]
 cxx-qt-build.workspace = true
+
+[features]
+link_qt_object_files = [ "cxx-qt-build/link_qt_object_files" ]

examples/qml_features/rust/Cargo.toml

@@ -22,3 +22,6 @@ serde_json.workspace = true
 
 [build-dependencies]
 cxx-qt-build.workspace = true
+
+[features]
+link_qt_object_files = [ "cxx-qt-build/link_qt_object_files" ]

examples/qml_minimal/rust/Cargo.toml

@@ -38,6 +38,10 @@ cxx-qt-lib.workspace = true
 [build-dependencies]
 # Use `cxx-qt-build = "0.5"` here instead!
 cxx-qt-build.workspace = true
+
+[features]
+# This feature must be enabled for `cargo test` when linking Qt 6 statically.
+link_qt_object_files = [ "cxx-qt-build/link_qt_object_files" ]
 # ANCHOR_END: book_build_dependencies
 
 # ANCHOR_END: book_all