CMake: Add new signature to qt6_wrap_cpp

* Introduce a new signature to qt6_wrap_cpp so that it accepts a target
name as the first parameter.
* Update the qt_wrap_cpp documentation.
* Show a warning message when the previous signature is used.
* Amends dc4159286b8571a3f3543e457fe1b51b9f5965b7 because it deleted
the `qt_wrap_cpp_3` example by mistake.

[ChangeLog][Build System] A new target-based signature was added for
qt_wrap_cpp. The usage of the previous output-variable signature is
deprecated and will issue a warning.

Fixes: QTBUG-126460
Change-Id: I85b7c516d6aebd8bbfda441fb6c68999e4898479
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
(cherry picked from commit f3d29dfb89f3e35623edd7e5bca934a1e85a6c35)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

src/corelib/Qt6CoreMacros.cmake

@@ -175,10 +175,27 @@ if(NOT QT_NO_CREATE_VERSIONLESS_FUNCTIONS)
     endfunction()
 endif()
 
+function(qt6_wrap_cpp)
+    # check if the first argument is a target
+    if(TARGET ${ARGV0})
+        _qt_internal_wrap_cpp(dummy TARGET ${ARGV})
+    else()
+        if(NOT QT_NO_SHOW_OLD_QT_WRAP_CPP_WARNING)
+            message(WARNING "You are using the output-variable signature of "
+                            "qt6_wrap_cpp(), which is deprecated. Instead, use "
+                            "the newer signature that takes the target as the "
+                            "first argument. To silence this warning pass "
+                            "-DQT_NO_SHOW_OLD_QT_WRAP_CPP_WARNING=ON")
+        endif()
+        set(output_parameter ${ARGV0})
+        _qt_internal_wrap_cpp(${ARGV})
+        set(${output_parameter} "${${output_parameter}}" PARENT_SCOPE)
+    endif()
+endfunction()
 
-# qt6_wrap_cpp(outfiles inputfile ... )
+# _qt_internal_wrap_cpp(outfiles inputfile ... )
 
-function(qt6_wrap_cpp outfiles )
+function(_qt_internal_wrap_cpp outfiles)
     # get include dirs
     _qt_internal_get_moc_flags(moc_flags)
 

src/corelib/doc/snippets/cmake-macros/examples.cmake

@@ -30,7 +30,7 @@ target_compile_definitions(myapp PRIVATE "$<$<CONFIG:Debug>:MY_OPTION_FOR_DEBUG>
 
 #! [qt_wrap_cpp_4]
 qt_add_executable(myapp myapp.cpp main.cpp)
-qt_wrap_cpp("" myapp.cpp TARGET myapp)
+qt_wrap_cpp(myapp myapp.cpp)
 #! [qt_wrap_cpp_4]
 
 #! [qt_add_resources]

src/corelib/doc/src/cmake/qt_wrap_cpp.qdoc

@@ -16,6 +16,18 @@
 
 \section1 Synopsis
 
+\c{qt_wrap_cpp} supports two signatures. The first signature was added in Qt 6.8
+and has the following form:
+
+\badcode
+qt_wrap_cpp(<TARGET> src_file1 [src_file2 ...]
+            [OPTIONS ...]
+            [DEPENDS ...])
+\endcode
+
+\note The signature above is recommended over the older signature, which is
+deprecated since Qt 6.8.
+
 \badcode
 qt_wrap_cpp(<VAR> src_file1 [src_file2 ...]
             [TARGET target]
@@ -64,6 +76,18 @@ Q_PLUGIN_METADATA() macro.
 
 \section1 Examples
 
+Since Qt 6.8:
+
+\snippet cmake-macros/examples.cmake qt_wrap_cpp_4
+\br
+\snippet cmake-macros/examples.cpp qt_wrap_cpp_4
+
+In the above file, \c{myapp.moc} is included in \c{myapp.cpp}.
+To generate the \c{myapp.moc} file, the \c{qt_wrap_cpp} macro is used with the
+\c{TARGET} parameter. The \c{.moc} file and its path will be added to the
+target's sources and include directories by the \c{qt_wrap_cpp} macro.
+
+The old version:
 \snippet cmake-macros/examples.cmake qt_wrap_cpp_1
 
 In the following example, the generator expressions passed to \c{OPTIONS}
@@ -75,16 +99,6 @@ avoid syntax errors in the generator expressions.
 The following example uses \l{https://cmake.org/cmake/help/latest/command/target_compile_definitions.html}{target_compile_definitions}
 to set \l{https://cmake.org/cmake/help/latest/prop_tgt/COMPILE_DEFINITIONS.html}{COMPILE_DEFINITIONS} which will be added to
 \c{OPTIONS}.
+\snippet cmake-macros/examples.cmake qt_wrap_cpp_3
 
-\snippet cmake-macros/examples.cmake qt_wrap_cpp_4
-
-\snippet cmake-macros/examples.cpp qt_wrap_cpp_4
-
-In the above file, \c{myapp.moc} is included in \c{myapp.cpp}.
-To generate the \c{myapp.moc} file, the \c{qt_wrap_cpp} macro is used with the
-\c{TARGET} parameter. The first parameter is empty because the \c{.moc} file
-and its path will be added to the target's sources and include directories by
-the \c{qt_wrap_cpp} macro.
-
-\snippet cmake-macros/examples.cmake qt_wrap_cpp_4
 */

tests/auto/cmake/CMakeLists.txt

@@ -213,6 +213,7 @@ _qt_internal_test_expect_pass(test_add_resource_prefix BINARY test_add_resource_
 _qt_internal_test_expect_build_fail(test_add_resource_options)
 _qt_internal_test_expect_build_fail(test_wrap_cpp_options)
 _qt_internal_test_expect_pass(test_wrap_cpp_moc)
+_qt_internal_test_expect_pass(test_wrap_cpp_moc_target)
 _qt_internal_test_expect_pass(test_platform_defs_include)
 _qt_internal_test_expect_pass(test_qtmainwin_library)
 

tests/auto/cmake/test_wrap_cpp_moc_target/CMakeLists.txt

@@ -0,0 +1,14 @@
+# Copyright (C) 2024 The Qt Company Ltd.
+# SPDX-License-Identifier: BSD-3-Clause
+
+cmake_minimum_required(VERSION 3.16)
+
+project(test_wrap_cpp_moc_target)
+
+find_package(Qt6Core REQUIRED)
+
+add_executable(example main.cpp)
+
+qt_wrap_cpp(example main.cpp)
+
+target_link_libraries(example PRIVATE Qt::Core)

tests/auto/cmake/test_wrap_cpp_moc_target/main.cpp

@@ -0,0 +1,17 @@
+// Copyright (C) 2024 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only
+
+#include <QObject>
+
+class MyObject2 : public QObject {
+    Q_OBJECT
+public:
+    MyObject2() = default;
+};
+
+#include "main.moc"
+
+int main()
+{
+    return 0;
+}