Object type declarations in qmldir-files (#1349)

* added BlueRect.qml to the qml_multi_crates example.

Added the file to the sub1 subproject and a call to it in main.qml.

* now the qmldir generator output object type declarations

* Use local paths for qml files in QmlDirBuilder

The QmlDirBuilder should only build the contents of the qmldir files,
and not modify any files on disk.
Ensuring the files are in the correct (relative) paths of the QML module
is the responsibility of register_qml_module.

* Add license header to BlueRect.qml

* Do not use OsStr::display due to MSRV

* Remove version form QmlDirBuilder

These should be specified per-file, and not for the entire module

---------

Co-authored-by: Leon Matthes <leon.matthes@kdab.com>

Author: pml76

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

@@ -49,6 +49,7 @@ mod utils;
 
 use std::{
     env,
+    ffi::OsStr,
     fs::File,
     path::{Path, PathBuf},
 };
@@ -171,11 +172,22 @@ impl QtBuild {
         // Generate qmldir file
         let qmldir_file_path = qml_module_dir.join("qmldir");
         {
+            let qml_type_files = qml_files.iter().filter(|path| {
+                // Qt by default only includes uppercase files in the qmldir file.
+                // Mirror this behavior.
+                path.as_ref()
+                    .file_name()
+                    .and_then(OsStr::to_str)
+                    .and_then(|file_name| file_name.chars().next())
+                    .map(char::is_uppercase)
+                    .unwrap_or_default()
+            });
             let mut file = File::create(&qmldir_file_path).expect("Could not create qmldir file");
             QmlDirBuilder::new(uri.clone())
                 .plugin(plugin_name, true)
                 .class_name(&plugin_class_name)
                 .type_info(plugin_type_info)
+                .qml_files(qml_type_files)
                 .write(&mut file)
                 .expect("Could not write qmldir file");
         }

crates/qt-build-utils/src/qml/qmldir.rs

@@ -5,7 +5,9 @@
 
 use crate::QmlUri;
 
+use std::ffi::OsStr;
 use std::io;
+use std::path::{Path, PathBuf};
 
 /// QML module definition files builder
 ///
@@ -16,6 +18,7 @@ pub struct QmlDirBuilder {
     plugin: Option<(bool, String)>,
     type_info: Option<String>,
     uri: QmlUri,
+    qml_files: Vec<PathBuf>,
 }
 
 impl QmlDirBuilder {
@@ -27,6 +30,7 @@ impl QmlDirBuilder {
             depends: vec![],
             plugin: None,
             type_info: None,
+            qml_files: vec![],
             uri,
         }
     }
@@ -58,7 +62,31 @@ impl QmlDirBuilder {
         }
 
         // Prefer is always specified for now
-        writeln!(writer, "prefer :/qt/qml/{}/", self.uri.as_dirs())
+        writeln!(writer, "prefer :/qt/qml/{}/", self.uri.as_dirs())?;
+
+        for qml_file in &self.qml_files {
+            let is_qml_file = qml_file
+                .extension()
+                .map(|ext| ext.eq_ignore_ascii_case("qml"))
+                .unwrap_or_default();
+
+            if !is_qml_file {
+                panic!("QML file does not end with .qml: {}", qml_file.display(),);
+            }
+
+            let path = qml_file.display();
+            let qml_component_name = qml_file
+                .file_stem()
+                .and_then(OsStr::to_str)
+                .expect("Could not get qml file stem");
+
+            // Qt6 simply uses version 254.0 if no specific version is provided
+            // Until we support versions of individal qml files, we will use 254.0
+            writeln!(writer, "{qml_component_name} 254.0 {path}",)
+                .expect("Could not write qmldir file");
+        }
+
+        Ok(())
     }
 
     /// Provides the class name of the C++ plugin used by the module.
@@ -110,6 +138,15 @@ impl QmlDirBuilder {
         self
     }
 
+    /// Declares a list of .qml files that are part of the module.
+    pub fn qml_files(mut self, qml_files: impl IntoIterator<Item = impl AsRef<Path>>) -> Self {
+        self.qml_files = qml_files
+            .into_iter()
+            .map(|p| p.as_ref().to_owned())
+            .collect();
+        self
+    }
+
     /// Declares a type description file for the module that can be read by QML
     /// tools such as Qt Creator to access information about the types defined
     /// by the module's plugins. File is the (relative) file name of a
@@ -139,6 +176,7 @@ mod test {
             .depends(["QtQuick", "com.kdab.a"])
             .plugin("P", true)
             .type_info("T")
+            .qml_files(&["qml/Test.qml"])
             .write(&mut result)
             .unwrap();
         assert_eq!(
@@ -150,6 +188,7 @@ typeinfo T
 depends QtQuick
 depends com.kdab.a
 prefer :/qt/qml/com/kdab/
+Test 254.0 qml/Test.qml
 "
         );
     }

examples/qml_multi_crates/qml/main.qml

@@ -18,6 +18,10 @@ ApplicationWindow {
     title: qsTr("CXX-Qt: Hello World")
     visible: true
 
+    BlueRect {
+        id: blueRect
+    }
+
     MainObject {
         id: main
     }

examples/qml_multi_crates/rust/sub1/build.rs

@@ -6,9 +6,11 @@
 use cxx_qt_build::{CxxQtBuilder, QmlModule};
 
 fn main() {
-    CxxQtBuilder::new_qml_module(QmlModule::new("com.kdab.cxx_qt.demo.sub1"))
-        .qt_module("Network")
-        .files(["src/sub1_object.rs"])
-        .build()
-        .export();
+    CxxQtBuilder::new_qml_module(
+        QmlModule::new("com.kdab.cxx_qt.demo.sub1").qml_file("qml/BlueRect.qml"),
+    )
+    .qt_module("Network")
+    .files(["src/sub1_object.rs"])
+    .build()
+    .export();
 }

examples/qml_multi_crates/rust/sub1/qml/BlueRect.qml

@@ -0,0 +1,12 @@
+// SPDX-FileCopyrightText: 2025 Klarälvdalens Datakonsult AB, a KDAB Group company <info@kdab.com>
+//
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+import QtQuick
+
+Rectangle {
+    anchors.centerIn: parent
+    height: 100
+    width: 100
+    color: "blue"
+}