Remove qmltc compilation command in favor of qt_add_qml_module()

[ChangeLog][CMake] The qmltc compilation functionality provided by
qt6_target_compile_qml_to_cpp() is merged into qt6_add_qml_module()
command and is available through ENABLE_TYPE_COMPILER argument. The
qt6_target_compile_qml_to_cpp() function does nothing and is left
only to highlight that users must migrate away from it.

Fixes: QTBUG-100215
Change-Id: Ie7d6b82564dff86176194fce35039ba0d93c0977
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>

10 files changed, 120 insertions, 142 deletions

diff --git a/src/qml/Qt6QmlBuildInternals.cmake b/src/qml/Qt6QmlBuildInternals.cmake
index ad42596931..7ff542b7c7 100644
--- a/src/qml/Qt6QmlBuildInternals.cmake
+++ b/src/qml/Qt6QmlBuildInternals.cmake
@@ -18,6 +18,7 @@ macro(qt_internal_get_internal_add_qml_module_keywords
         NO_GENERATE_QMLDIR
         NO_LINT
         NO_CACHEGEN
+        ENABLE_TYPE_COMPILER
         __QT_INTERNAL_STATIC_MODULE
         __QT_INTERNAL_SYSTEM_MODULE
     )
@@ -29,6 +30,7 @@ macro(qt_internal_get_internal_add_qml_module_keywords
         CLASS_NAME
         CLASSNAME  # TODO: Remove once all other repos have been updated to use
                    #       CLASS_NAME instead.
+        TYPE_COMPILER_NAMESPACE
     )
     set(${multi_args}
         QML_FILES
@@ -306,6 +308,11 @@ function(qt_internal_add_qml_module target)
         list(APPEND add_qml_module_args NAMESPACE ${qt_namespace})
     endif()
 
+    if (arg_ENABLE_TYPE_COMPILER AND NOT arg_TYPE_COMPILER_NAMESPACE)
+        # if qmltc namespace is not specified explicitly, use Qt's namespace
+        list(APPEND add_qml_module_args TYPE_COMPILER_NAMESPACE ${qt_namespace})
+    endif()
+
     # Update the backing and plugin targets with qml-specific things.
     qt6_add_qml_module(${target}
         ${add_qml_module_args}
@@ -437,55 +444,3 @@ function(qt_internal_add_qml_module target)
         endif()
     endif()
 endfunction()
-
-# This function is an internal wrapper around qt6_target_compile_qml_to_cpp().
-# It sets up some pre-defined Qt-specific arguments when calling the
-# qt6_target_compile_qml_to_cpp(). All keywords supported by
-# qt6_target_compile_qml_to_cpp() can be used.
-#
-# Unlike the public command version, the following changes are present:
-# - NAMESPACE argument is set to QT_NAMESPACE by default
-#
-# See qt6_target_compile_qml_to_cpp() for the full set of supported keywords.
-function(qt_internal_target_compile_qml_to_cpp target)
-    set(option_args "")
-    set(single_args NAMESPACE)
-    set(multi_args QML_FILES IMPORT_PATHS)
-    qt_parse_all_arguments(arg "qt_internal_target_compile_qml_to_cpp"
-        "${option_args}"
-        "${single_args}"
-        "${multi_args}"
-        ${ARGN}
-    )
-
-    # internal-only logic:
-    if(NOT arg_NAMESPACE)
-        # NB: assume Qt Core is present. we're in an internal function, so it's
-        # a safe enough assumption
-
-        # Apparently, -DQT_NAMESPACE only exists within qtbase or qt5's
-        # top-level build. Thus, in many other cases that option is unspecified.
-        # To avoid dealing with this, we can query the QT_NAMESPACE for QtCore's
-        # compile definitions (because we have it there).
-        get_target_property(arg_NAMESPACE ${QT_CMAKE_EXPORT_NAMESPACE}::Core _qt_namespace)
-    endif()
-
-    set(target_compile_qml_to_cpp_args "")
-    # Pass through options if given (these are present/absent, not true/false)
-    foreach(opt IN LISTS option_args)
-        if(arg_${opt})
-            list(APPEND target_compile_qml_to_cpp_args ${opt})
-        endif()
-    endforeach()
-    # Pass through single and multi-value args as provided.
-    foreach(arg IN LISTS single_args multi_args)
-        if(DEFINED arg_${arg})
-            list(APPEND target_compile_qml_to_cpp_args ${arg} ${arg_${arg}})
-        endif()
-    endforeach()
-
-    qt6_target_compile_qml_to_cpp(${target}
-        ${target_compile_qml_to_cpp_args}
-    )
-
-endfunction()
diff --git a/src/qml/Qt6QmlMacros.cmake b/src/qml/Qt6QmlMacros.cmake
index e9b379f403..b8b5408b34 100644
--- a/src/qml/Qt6QmlMacros.cmake
+++ b/src/qml/Qt6QmlMacros.cmake
@@ -28,6 +28,7 @@ function(qt6_add_qml_module target)
         NO_IMPORT_SCAN
         # TODO: Remove once all usages have also been removed
         SKIP_TYPE_REGISTRATION
+        ENABLE_TYPE_COMPILER
 
         # Used only by _qt_internal_qml_type_registration()
         # TODO: Remove this once qt6_extract_metatypes does not install by default.
@@ -57,6 +58,7 @@ function(qt6_add_qml_module target)
         RESOURCE_EXPORT
         INSTALL_DIRECTORY
         INSTALL_LOCATION
+        TYPE_COMPILER_NAMESPACE
     )
 
     set(args_multi
@@ -152,6 +154,13 @@ function(qt6_add_qml_module target)
             )
     endif()
 
+    if (DEFINED arg_TYPE_COMPILER_NAMESPACE AND NOT arg_ENABLE_TYPE_COMPILER)
+        message(WARNING
+            "TYPE_COMPILER_NAMESPACE is set, but ENABLE_TYPE_COMPILER is not specified. "
+            "The TYPE_COMPILER_NAMESPACE value will be ignored."
+        )
+    endif()
+
     set(is_executable FALSE)
     if(TARGET ${target})
         if(arg_STATIC OR arg_SHARED)
@@ -634,6 +643,14 @@ function(qt6_add_qml_module target)
         endif()
     endif()
 
+    if (arg_ENABLE_TYPE_COMPILER)
+        _qt_internal_target_enable_qmltc(${target}
+            QML_FILES ${arg_QML_FILES}
+            IMPORT_PATHS ${arg_IMPORT_PATH}
+            NAMESPACE ${arg_TYPE_COMPILER_NAMESPACE}
+        )
+    endif()
+
     if(arg_OUTPUT_TARGETS)
         set(${arg_OUTPUT_TARGETS} ${output_targets} PARENT_SCOPE)
     endif()
@@ -1094,7 +1111,7 @@ function(_qt_internal_qml_get_qt_framework_path_moc_option target out_var)
 endfunction()
 
 # Compile Qml files (.qml) to C++ source files with Qml Type Compiler (qmltc).
-function(qt6_target_compile_qml_to_cpp target)
+function(_qt_internal_target_enable_qmltc target)
     set(args_option "")
     set(args_single NAMESPACE)
     set(args_multi QML_FILES IMPORT_PATHS)
@@ -1129,7 +1146,6 @@ function(qt6_target_compile_qml_to_cpp target)
     set(generated_sources_other_scope)
 
     set(compiled_files) # compiled files list to be used to generate MOC C++
-    set(non_qml_files) # non .qml files to warn about
     set(qmltc_executable "$<TARGET_FILE:${QT_CMAKE_EXPORT_NAMESPACE}::qmltc>")
     if(CMAKE_GENERATOR STREQUAL "Ninja Multi-Config" AND CMAKE_VERSION VERSION_GREATER_EQUAL "3.20")
         set(qmltc_executable "$<COMMAND_CONFIG:${qmltc_executable}>")
@@ -1211,7 +1227,10 @@ function(qt6_target_compile_qml_to_cpp target)
 
     foreach(qml_file_src IN LISTS arg_QML_FILES)
         if(NOT qml_file_src MATCHES "\\.(qml)$")
-            list(APPEND non_qml_files ${qml_file_src})
+            continue()
+        endif()
+        get_source_file_property(skip_qmltc ${qml_file_src} QT_QML_SKIP_TYPE_COMPILER)
+        if(skip_qmltc)
             continue()
         endif()
 
@@ -1315,15 +1334,14 @@ function(qt6_target_compile_qml_to_cpp target)
         )
     endif()
 
-    if(non_qml_files)
-        list(JOIN non_qml_files "\n  " file_list)
-        message(WARNING
-            "Only .qml files should be added with this function. "
-            "The following files were not processed:"
-            "\n  ${file_list}"
-        )
-    endif()
+endfunction()
 
+function(qt6_target_compile_qml_to_cpp target)
+    message(WARNING
+        "qt6_target_compile_qml_to_cpp() can no longer be used standalone and is planned to be "
+        "removed in a future Qt release. To enable qmltc compilation, use:\n"
+        "qt6_add_qml_module(${target} ... ENABLE_TYPE_COMPILER)"
+    )
 endfunction()
 
 if(NOT QT_NO_CREATE_VERSIONLESS_FUNCTIONS)
diff --git a/src/qml/doc/snippets/qmltc/CMakeLists.txt b/src/qml/doc/snippets/qmltc/CMakeLists.txt
index 671db0e30d..aa5fa8e230 100644
--- a/src/qml/doc/snippets/qmltc/CMakeLists.txt
+++ b/src/qml/doc/snippets/qmltc/CMakeLists.txt
@@ -45,16 +45,14 @@ qt6_add_qml_module(${application_name}
     VERSION 1.0
     URI QmltcExample
     QML_FILES ${application_qml_files}
+
+    # Compile qml files (listed in QML_FILES) to C++ using qmltc and add these
+    # files to the application binary:
+    ENABLE_TYPE_COMPILER
 )
 #! [qmltc-add-qml-module]
 
 #! [qmltc-compile-to-cpp]
 # (qmltc-specific) Link *private* libraries that correspond to QML modules:
 target_link_libraries(${application_name} PRIVATE Qt::QmlPrivate Qt::QuickPrivate)
-
-# Compile qml files (listed in QML_FILES) to C++ using qmltc and add these files
-# to the application binary:
-qt6_target_compile_qml_to_cpp(${application_name}
-    QML_FILES ${application_qml_files}
-)
 #! [qmltc-compile-to-cpp]
diff --git a/src/qml/doc/src/cmake/cmake-properties.qdoc b/src/qml/doc/src/cmake/cmake-properties.qdoc
index eccc815eca..7cbc1e04f2 100644
--- a/src/qml/doc/src/cmake/cmake-properties.qdoc
+++ b/src/qml/doc/src/cmake/cmake-properties.qdoc
@@ -183,5 +183,23 @@ version after the \c{.0} release, specify those versions using this property.
 Use this property to specify a non-default \c .h and \c .cpp file name, which helps to resolve
 conflicting file names.
 
-\sa{qt_target_compile_qml_to_cpp}
+\sa{qmltc-cmake}
+*/
+
+/*!
+\page cmake-source-file-property-QT_QML_SKIP_TYPE_COMPILER.html
+\ingroup cmake-source-file-properties-qtqml
+
+\title QT_QML_SKIP_TYPE_COMPILER
+\target cmake-source-file-property-QT_QML_SKIP_TYPE_COMPILER
+
+\summary {Excludes a file from being compiled to C++ using qmltc.}
+
+\cmakepropertysince 6.4
+\preliminarycmakeproperty
+
+Set this property to \c TRUE to prevent the \c{.qml} file from being compiled to
+C++ during qmltc compilation.
+
+\sa{qmltc-cmake}
 */
diff --git a/src/qml/doc/src/cmake/qt_add_qml_module.qdoc b/src/qml/doc/src/cmake/qt_add_qml_module.qdoc
index 00381d086d..01ee2bbeff 100644
--- a/src/qml/doc/src/cmake/qt_add_qml_module.qdoc
+++ b/src/qml/doc/src/cmake/qt_add_qml_module.qdoc
@@ -71,6 +71,8 @@ qt_add_qml_module(
     [NO_CACHEGEN]
     [NO_RESOURCE_TARGET_PATH]
     [NO_IMPORT_SCAN]
+    [ENABLE_TYPE_COMPILER]
+    [TYPE_COMPILER_NAMESPACE namespace]
 )
 
 \endcode
@@ -297,6 +299,40 @@ to the QML file containing the \c {pragma Singleton} statement.
 See \l{qt_target_qml_sources_example}{qt_target_qml_sources()} for an example on
 how to set the \c QT_QML_SINGLETON_TYPE property.
 
+\target qmltc-cmake
+\section2 Compiling QML to C++ with QML Type Compiler
+
+If a QML module has \c{.qml} files, you can compile them to C++ using \l{QML
+Type Compiler}{qmltc}. Unlike \l{qmlcachegen-auto}{bytecode compilation}, you
+have to explicitly enable qmltc via \l{ENABLE_TYPE_COMPILER} argument. In which
+case, \c{.qml} files specified under \c{QML_FILES} would be compiled. Files
+ending with \c{.js} and \c{.mjs} are ignored as qmltc does not compile
+JavaScript code. Additionally, files marked with QT_QML_SKIP_TYPE_COMPILER
+source file property are also skipped.
+
+By default, qmltc creates lower-case \c{.h} and \c{.cpp} files for a given
+\c{.qml} file. For example, \c{Foo.qml} ends up being compiled into \c{foo.h}
+and \c{foo.cpp}.
+
+The created C++ files are placed into a dedicated \c{.qmltc/<target>/}
+sub-directory of the \c BINARY_DIR of the \c target. These files are then
+automatically added to the target sources and compiled as Qt C++ code along with
+other source files.
+
+While processing QML_FILES, the following source file properties are respected:
+\list
+    \li \c{QT_QMLTC_FILE_BASENAME}: use this source file property to specify a
+        non-default .h and .cpp file name, which might be useful to e.g. resolve
+        conflicting file names (imagine you have main.qml that is being
+        compiled, but main.h already exists, so #include "main.h" might not do
+        what you expect it to do). QT_QMLTC_FILE_BASENAME is expected to be a
+        file name (without extension), so any preceding directory is ignored.
+        Unlike in the case of default behavior, the QT_QMLTC_FILE_BASENAME is
+        not lower-cased.
+    \li \c{QT_QML_SKIP_TYPE_COMPILER}: use this source file property to
+        specify that a QML file must be ignored by qmltc.
+\endlist
+
 \section1 Arguments
 
 The \c target specifies the name of the backing target for the QML module.
@@ -560,4 +596,13 @@ to provide the information needed by deployment scripts (see
 responsibility of ensuring all required plugins are instantiated and linked for
 static builds. For non-static builds the project must manually work out
 and deploy all QML modules used by an executable target.
+
+\target ENABLE_TYPE_COMPILER
+\c ENABLE_TYPE_COMPILER can be used to compile \c{.qml} files to C++ source code
+with \l{QML Type Compiler}{qmltc}.
+
+\c TYPE_COMPILER_NAMESPACE argument defines a namespace, in which the generated
+C++ code resides. By default, no namespace is specified for user projects. The
+code generated from Qt's own sources is put under a QT_NAMESPACE namespace.
+
 */
diff --git a/src/qml/doc/src/cmake/qt_target_compile_qml_to_cpp.qdoc b/src/qml/doc/src/cmake/qt_target_compile_qml_to_cpp.qdoc
index 2d1da9efe8..ae0515403f 100644
--- a/src/qml/doc/src/cmake/qt_target_compile_qml_to_cpp.qdoc
+++ b/src/qml/doc/src/cmake/qt_target_compile_qml_to_cpp.qdoc
@@ -32,64 +32,7 @@
 \title qt_target_compile_qml_to_cpp
 \target qt6_target_compile_qml_to_cpp
 
-\brief Compiles QML files (.qml) to C++ source code with \l{Qml Type Compiler}{qmltc}.
-
-\section1 Synopsis
-
-\badcode
-qt_target_compile_qml_to_cpp(
-    target
-    QML_FILES ...
-    [NAMESPACE namespace]
-    [IMPORT_PATHS ...]
-)
-
-\endcode
-
-\versionlessCMakeCommandsNote qt6_target_compile_qml_to_cpp()
-
-\section1 Description
-
-By default, \l{Qml Type Compiler}{qmltc} creates lower-case \c{.h} and \c{.cpp}
-files for a given \c{.qml} file. For example, \c{Foo.qml} ends up being compiled
-into \c{foo.h} and \c{foo.cpp}.
-
-The created C++ files are placed into a dedicated \c{.qmltc/<target>/}
-sub-directory of the \c BINARY_DIR of the \c target passed as an argument to
-this command. These files are then automatically added to the target sources and
-compiled as Qt C++ code along with other source files.
-
-\note This command is in technology preview and may change in future releases.
-
-\section1 Arguments
-
-The \c target specifies the name of the binary that the QML files belong to. In
-order for the compilation to succeed, the target is expected to be a valid QML
-module, defined with qt_add_qml_module() command.
-
-\c QML_FILES lists the \c{.qml} files that are going to be compiled into C++. In
-most cases, all the target's QML files would be specified in the QML_FILES. This
-way, QML_FILES argument of this command is equivalent to QML_FILES argument of
-the qt_add_qml_module() command.
-
-\c NAMESPACE argument defines a namespace, in which the generated C++ code
-resides. By default, no namespace is specified for user projects. The code
-generated from Qt's own sources is put under a QT_NAMESPACE namespace.
-
-\c IMPORT_PATHS can be used to add locations that contain QML modules. The
-specified entries are passed to qmltc and allow to correctly import modules that
-do not reside under the location specified by QLibraryInfo::QmlImportsPath.
-
-While processing QML_FILES, the following source file properties are respected:
-\list
-    \li \c{QT_QMLTC_FILE_BASENAME}: use this source file property to specify a
-        non-default .h and .cpp file name, which might be useful to e.g. resolve
-        conflicting file names (imagine you have main.qml that is being
-        compiled, but main.h already exists, so #include "main.h" might not do
-        what you expect it to do). QT_QMLTC_FILE_BASENAME is expected to be a
-        file name (without extension), so any preceding directory is ignored.
-        Unlike in the case of default behavior, the QT_QMLTC_FILE_BASENAME is
-        not lower-cased.
-\endlist
+This command is removed in Qt 6.4 in favor of \l{qt6_add_qml_module} which can
+now invoke qmltc internally as described in the \l{qmltc-cmake}{qmltc section}.
 
 */
diff --git a/src/qml/doc/src/qtqml-tool-qmltc.qdoc b/src/qml/doc/src/qtqml-tool-qmltc.qdoc
index 1bdeae098c..ad8f6d4972 100644
--- a/src/qml/doc/src/qtqml-tool-qmltc.qdoc
+++ b/src/qml/doc/src/qtqml-tool-qmltc.qdoc
@@ -48,8 +48,7 @@ In order to enable qmltc:
 \list
     \li Create a \l{qt_add_qml_module}{proper QML module} for your application.
 
-    \li Invoke qmltc, for example, through the \l{qt_target_compile_qml_to_cpp}
-    {CMake API}.
+    \li Invoke qmltc, for example, through the \l{qmltc-cmake}{CMake API}.
 
     \li \c{#include} the generated header file(s) in the application source
     code.
@@ -99,8 +98,8 @@ require a CMake-driven build flow as well since this flow is centered around
 proper QML modules and their infrastructure.
 
 The easy way to add qmltc compilation is by using the dedicated
-\l{qt_target_compile_qml_to_cpp}{CMake API} as part of a QML module creation for
-the application. Consider a simple application directory structure:
+\l{qmltc-cmake}{CMake API} as part of a QML module creation for the application.
+Consider a simple application directory structure:
 
 \badcode
 .
@@ -170,7 +169,7 @@ import path to scan for - would be completely ignored by the ahead-of-time qmltc
 procedure.
 
 \note To add import paths to the qmltc compilation, consider using a relevant
-argument of the \l{qt_target_compile_qml_to_cpp}{CMake command} instead.
+argument of the \l{qmltc-cmake}{CMake command} instead.
 
 Generally, you can think of it this way: QQmlEngine involves the application
 process to run, while qmltc does not as it operates \e{before} your application
@@ -196,8 +195,8 @@ inspecting the corresponding QML document.
 However, the generated code is still somewhat confusing, especially given that
 your application should use the qmltc output on the C++ side directly. There are
 two parts of the generated code: CMake build files structure and the generated
-C++ format. The former is covered in the \l{qt_target_compile_qml_to_cpp}{CMake
-API of qmltc} and the latter is covered here.
+C++ format. The former is covered in the \l{qmltc-cmake}{CMake API of qmltc} and
+the latter is covered here.
 
 Consider a simple HelloWorld type, that has a \c hello property, a function to
 print that property, and a signal emitted when the object of that type is
diff --git a/src/quick/doc/src/guidelines/qtquick-toolsnutilities.qdoc b/src/quick/doc/src/guidelines/qtquick-toolsnutilities.qdoc
index 9d1ff64f81..db35c37a0b 100644
--- a/src/quick/doc/src/guidelines/qtquick-toolsnutilities.qdoc
+++ b/src/quick/doc/src/guidelines/qtquick-toolsnutilities.qdoc
@@ -121,7 +121,7 @@ either via command line options or by using a settings file.
 Its generated output acts as an alternative to the QQmlComponent-based object
 creation.
 
-Once enabled through \l{qt_target_compile_qml_to_cpp}{CMake}, \c qmltc runs
+Once enabled through \l{qmltc-cmake}{CMake}, \c qmltc runs
 ahead of time during your project build phase.
 
 To make use of the compiled C++, you \e must modify your application-side C++
diff --git a/tests/auto/qml/qmltc/data/CMakeLists.txt b/tests/auto/qml/qmltc/data/CMakeLists.txt
index 49856a86b5..395463aabe 100644
--- a/tests/auto/qml/qmltc/data/CMakeLists.txt
+++ b/tests/auto/qml/qmltc/data/CMakeLists.txt
@@ -82,6 +82,8 @@ set(qml_sources
     LocalWithOnCompleted.qml
     LocallyImported_context.qml
 #   SingletonThing.qml
+
+    badFile.qml
 )
 
 set(js_sources
@@ -99,6 +101,8 @@ set(common_libraries
 set_source_files_properties(NameConflict.qml PROPERTIES
     QT_QMLTC_FILE_BASENAME ResolvedNameConflict)
 
+set_source_files_properties(badFile.qml PROPERTIES QT_QML_SKIP_TYPE_COMPILER TRUE)
+
 # set_source_files_properties(SingletonThing.qml PROPERTIES
 #    QT_QML_SINGLETON_TYPE true)
 
@@ -119,11 +123,8 @@ qt6_add_qml_module(qmltc_test_module
         ${js_sources}
     DEPENDENCIES
         QtQuick
-)
-qt_internal_target_compile_qml_to_cpp(qmltc_test_module
-    NAMESPACE QmltcTest
-    QML_FILES
-        ${qml_sources}
+    ENABLE_TYPE_COMPILER
+    TYPE_COMPILER_NAMESPACE QmltcTest
 )
 
 qt_autogen_tools_initial_setup(qmltc_test_moduleplugin)
diff --git a/tests/auto/qml/qmltc/data/badFile.qml b/tests/auto/qml/qmltc/data/badFile.qml
new file mode 100644
index 0000000000..d041a3b5e5
--- /dev/null
+++ b/tests/auto/qml/qmltc/data/badFile.qml
@@ -0,0 +1 @@
+UnknownType {}