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>

5 files changed, 76 insertions, 73 deletions

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