CMake: Error out when using CMake < 3.19 with qml app deployment

App qml deployment fails at install time when using CMake < 3.19
because the _qt_internal_generate_deploy_qml_imports_script finalizer
is not executed. It is not executed because the Qml dependency is
added later than qt_add_executable, and qt_add_executable immediately
finalizes with a lower CMake version.

We can detect this situation and issue a warning to the user that they
should manually finalize their target in that case.
Adjust documentation to mention that.

Task-number: QTBUG-98545
Change-Id: I862b2fad35c8128dbb043cea972c8e36958308f4
Reviewed-by: Alexey Edelev <alexey.edelev@qt.io>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
(cherry picked from commit 0d276381135ed5724464cb784f3d17775ac4d764)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

5 files changed, 27 insertions, 1 deletions

diff --git a/src/qml/Qt6QmlDeploySupport.cmake b/src/qml/Qt6QmlDeploySupport.cmake
index 58ca93b5fa..dc16261170 100644
--- a/src/qml/Qt6QmlDeploySupport.cmake
+++ b/src/qml/Qt6QmlDeploySupport.cmake
@@ -50,7 +50,9 @@ function(qt_deploy_qml_imports)
         message(FATAL_ERROR
             "No QML imports information recorded for target ${arg_TARGET}. "
             "The target must be an executable and qt_add_qml_module() must "
-            "have been called with it. Missing file:\n    ${filename}"
+            "have been called with it. If using a CMake version lower than 3.19, ensure "
+            "that the executable is manually finalized with qt_finalize_target(). "
+            "Missing file:\n    ${filename}"
         )
     endif()
     include(${filename})
diff --git a/src/qml/Qt6QmlMacros.cmake b/src/qml/Qt6QmlMacros.cmake
index 41269ff634..e256c46796 100644
--- a/src/qml/Qt6QmlMacros.cmake
+++ b/src/qml/Qt6QmlMacros.cmake
@@ -2682,6 +2682,22 @@ function(qt6_generate_deploy_qml_app_script)
         message(FATAL_ERROR "FILENAME_VARIABLE must be specified")
     endif()
 
+    # Check that the target was defer-finalized, and not immediately finalized when using
+    # CMake < 3.19. This is important because if it's immediately finalized, Qt::Qml is likely
+    # not in the dependency list, and thus _qt_internal_generate_deploy_qml_imports_script will
+    # not be executed, leading to an error at install time
+    # 'No QML imports information recorded for target X'.
+    # _qt_is_immediately_finalized is set by qt6_add_executable.
+    # TODO: Remove once minimum required CMAKE_VERSION is 3.19+.
+    get_target_property(is_immediately_finalized "${arg_TARGET}" _qt_is_immediately_finalized)
+    if(is_immediately_finalized)
+        message(FATAL_ERROR
+            "QML app deployment requires CMake version 3.19, or later, or manual executable "
+            "finalization. For manual finalization, pass the MANUAL_FINALIZATION option to "
+            "qt_add_executable() and then call qt_finalize_target(${arg_TARGET}) just before
+            calling qt_generate_deploy_qml_app_script().")
+    endif()
+
     # Create a file name that will be unique for this target and the combination
     # of arguments passed to this command. This allows the project to call us
     # multiple times with different arguments for the same target (e.g. to
diff --git a/src/qml/doc/src/cmake/qt_deploy_qml_imports.qdoc b/src/qml/doc/src/cmake/qt_deploy_qml_imports.qdoc
index 641003a701..9d7f33e7bd 100644
--- a/src/qml/doc/src/cmake/qt_deploy_qml_imports.qdoc
+++ b/src/qml/doc/src/cmake/qt_deploy_qml_imports.qdoc
@@ -42,6 +42,8 @@ project.
 
 \preliminarycmakecommand
 
+\include cmake-qml-qt-finalize-target-warning.cmake
+
 \section1 Synopsis
 
 \badcode
diff --git a/src/qml/doc/src/cmake/qt_generate_deploy_qml_app_script.qdoc b/src/qml/doc/src/cmake/qt_generate_deploy_qml_app_script.qdoc
index c4c568bf43..98ea30caa7 100644
--- a/src/qml/doc/src/cmake/qt_generate_deploy_qml_app_script.qdoc
+++ b/src/qml/doc/src/cmake/qt_generate_deploy_qml_app_script.qdoc
@@ -39,6 +39,8 @@
 \cmakecommandsince 6.3
 \preliminarycmakecommand
 
+\include cmake-qml-qt-finalize-target-warning.cmake
+
 \section1 Synopsis
 
 \badcode
diff --git a/src/qml/doc/src/includes/cmake-qml-qt-finalize-target-warning.cmake b/src/qml/doc/src/includes/cmake-qml-qt-finalize-target-warning.cmake
new file mode 100644
index 0000000000..d3c7383d2e
--- /dev/null
+++ b/src/qml/doc/src/includes/cmake-qml-qt-finalize-target-warning.cmake
@@ -0,0 +1,4 @@
+\warning If you are using a CMake version lower than 3.19, make sure that you
+pass the \c MANUAL_FINALIZATION option to
+\l{qt_add_executable}{qt6_add_executable()}, and then call
+\l{qt_finalize_target}{qt6_finalize_target()} before calling this function.