CMake: Fix docs and implementation of qt_generate_foreign_qml_types

Renamed doc file not to contain the version number like the rest of the
doc files.
Clarified description of what the function does.
Adjusted doc page title and contents of the function.
Fixed synopsis.
Added Technical Preview note.
Renamed function arguments for clarity.
Fixed incorrect COMMENT and DEPENDS target usage.
Added mention to QmlIntegration and qt_generate_foreign_qml_types on
the Qml module page.

Amends 96c1337aef41694c1af4863ad6f0d4d1f961363a
Amends 3b1ae2f598d6013e5d262262002820d6eb76805b

Pick-to: 6.3
Fixes: QTBUG-100216
Change-Id: I5c48616a7836c4ddb3f5ca36b7e82f1364995f2f
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>

4 files changed, 38 insertions, 19 deletions

diff --git a/src/qml/Qt6QmlMacros.cmake b/src/qml/Qt6QmlMacros.cmake
index 73517b40c9..0f7d57f370 100644
--- a/src/qml/Qt6QmlMacros.cmake
+++ b/src/qml/Qt6QmlMacros.cmake
@@ -2064,22 +2064,24 @@ if(NOT QT_NO_CREATE_VERSIONLESS_FUNCTIONS)
     endfunction()
 endif()
 
-function(qt6_generate_foreign_qml_types lib_target qml_target)
-
-    qt6_extract_metatypes(${lib_target})
-    get_target_property(target_metatypes_json_file ${lib_target} INTERFACE_QT_META_TYPES_BUILD_FILE)
+# This function is currently in Technical Preview.
+# It's signature and behavior might change.
+function(qt6_generate_foreign_qml_types source_target destination_qml_target)
+    qt6_extract_metatypes(${source_target})
+    get_target_property(target_metatypes_json_file ${source_target}
+                        INTERFACE_QT_META_TYPES_BUILD_FILE)
     if (NOT target_metatypes_json_file)
         message(FATAL_ERROR "Need target metatypes.json file")
     endif()
 
-    set(registration_files_base ${lib_target}_${qml_target})
+    set(registration_files_base ${source_target}_${destination_qml_target})
     set(additional_sources ${registration_files_base}.cpp ${registration_files_base}.h)
 
     add_custom_command(
         OUTPUT
             ${additional_sources}
         DEPENDS
-            ${target}
+            ${source_target}
             ${target_metatypes_json_file}
             ${QT_CMAKE_EXPORT_NAMESPACE}::qmltyperegistrar
         COMMAND
@@ -2088,14 +2090,13 @@ function(qt6_generate_foreign_qml_types lib_target qml_target)
             "--extract"
             -o ${registration_files_base}
             ${target_metatypes_json_file}
-        COMMENT "Generate QML registration code for target ${target}"
+        COMMENT "Generate QML registration code for target ${source_target}"
     )
 
-    target_sources(${qml_target} PRIVATE ${additional_sources})
-    qt6_wrap_cpp(${additional_sources} TARGET ${qml_target})
+    target_sources(${destination_qml_target} PRIVATE ${additional_sources})
+    qt6_wrap_cpp(${additional_sources} TARGET ${destination_qml_target})
 endfunction()
 
-
 if(NOT QT_NO_CREATE_VERSIONLESS_FUNCTIONS)
     if(QT_DEFAULT_MAJOR_VERSION EQUAL 6)
         function(qt_generate_foreign_qml_types)
diff --git a/src/qml/doc/snippets/code/doc_src_qtqml.cmake b/src/qml/doc/snippets/code/doc_src_qtqml.cmake
index c312201ff8..30ff8981a9 100644
--- a/src/qml/doc/snippets/code/doc_src_qtqml.cmake
+++ b/src/qml/doc/snippets/code/doc_src_qtqml.cmake
@@ -2,3 +2,9 @@
 find_package(Qt6 REQUIRED COMPONENTS Qml)
 target_link_libraries(mytarget PRIVATE Qt6::Qml)
 #! [0]
+
+#! [1]
+find_package(Qt6 REQUIRED COMPONENTS QmlIntegration)
+target_link_libraries(mytarget PRIVATE Qt6::QmlIntegration)
+#! [1]
+
diff --git a/src/qml/doc/src/cmake/qt6_generate_foreign_qml_types.qdoc b/src/qml/doc/src/cmake/qt_generate_foreign_qml_types.qdoc
index 07cdd92543..8f1d6522be 100644
--- a/src/qml/doc/src/cmake/qt6_generate_foreign_qml_types.qdoc
+++ b/src/qml/doc/src/cmake/qt_generate_foreign_qml_types.qdoc
@@ -26,20 +26,24 @@
 ****************************************************************************/
 
 /*!
-\page qt6_generate_foreign_qml_types.html
+\page qt_generate_foreign_qml_types.html
 \ingroup cmake-commands-qtqml
 
-\title qt6_generate_foreign_qml_types
+\title qt_generate_foreign_qml_types
 \target qt6_generate_foreign_qml_types
 
 \summary{Registers types from one target in a QML module.}
 
+\include cmake-find-package-qml.qdocinc
+
+\preliminarycmakecommand
+
 \section1 Synopsis
 
 \badcode
-qt_add_qml_module(
-    foreign_target
-    qml_lib_target
+qt_generate_foreign_qml_types(
+    source_target
+    destination_qml_target
 )
 
 \endcode
@@ -48,8 +52,9 @@ qt_add_qml_module(
 
 \section1 Description
 
-\c qt6_generate_foreign_qml_types enables the registration of types marked via QML registration
-macros (like \l QML_ELEMENT) in \c foreign_lib in the QML module \c qml_lib_target.
+\c qt_generate_foreign_qml_types extracts types marked via QML registration
+macros (like \l QML_ELEMENT) from \c source_target and registers them as foreign
+types in the QML module \c destination_qml_target.
 
 This can be useful when one wants to create a library with optional QML integration, without
 depending directly on QML.
@@ -70,14 +75,14 @@ class MyClass : public QObject
 \badcode
 # CMakeLists.txt
 qt_add_library(mylib myclass.h ...)
-target_link_libraries(mylib Qt::Core Qt::QmlIntegration)
+target_link_libraries(mylib PRIVATE Qt::Core Qt::QmlIntegration)
 
 qt_add_qml_module(mylib_declarative
   VERSION 1.0
   URI "mylib"
   ...
 )
-qt6_generate_foreign_qml_types(mylib mylib_declarative)
+qt_generate_foreign_qml_types(mylib mylib_declarative)
 \endcode
 
 \note In the example above, \c mylib does not depend on QtQml or QtQuick, but only on the
diff --git a/src/qml/doc/src/qtqml.qdoc b/src/qml/doc/src/qtqml.qdoc
index 4de3115511..de4fa16e29 100644
--- a/src/qml/doc/src/qtqml.qdoc
+++ b/src/qml/doc/src/qtqml.qdoc
@@ -69,6 +69,13 @@ Use the \c find_package() command to locate the needed module components in the
 
 \snippet code/doc_src_qtqml.cmake 0
 
+To provide foreign QML type support for a non-QML library, locate
+the \c QmlIntegration module as follows:
+
+\snippet code/doc_src_qtqml.cmake 1
+
+See \l{qt6_generate_foreign_qml_types} for details.
+
 See also the \l{Build with CMake} overview.
 
 \section3 Building with qmake