CMake: Put Qt-internal targets into a dedicated FOLDER

When loading a Qt CMake project in an IDE like Visual Studio, many
Qt-internal targets are visible, right next to the user's targets.  This
is inconvenient and confusing.

Use CMake's FOLDER concept, and put Qt-internal targets into a dedicated
FOLDER.

For that we introduce the new global property QT_TARGETS_FOLDER that,
analoguous to AUTOGEN_TARGETS_FOLDER, is the folder name for Qt-internal
targets.  By default, it's not set, nor is folder support enabled.

Change qt_standard_project_setup() to
- enable folder support
- initialize QT_TARGETS_FOLDER if unset
- initialize AUTOGEN_TARGETS_FOLDER to the same value if unset

Set the FOLDER property of qtbase's internal targets for user projects
to the value of QT_TARGETS_FOLDER.

Task-number: QTBUG-99808
Change-Id: I880ac7731f88faa83a384dcdec98b1b88ac6cc2e
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>

4 files changed, 77 insertions, 0 deletions

diff --git a/src/corelib/Qt6CoreMacros.cmake b/src/corelib/Qt6CoreMacros.cmake
index 1612d23b10..188520ae11 100644
--- a/src/corelib/Qt6CoreMacros.cmake
+++ b/src/corelib/Qt6CoreMacros.cmake
@@ -1459,6 +1459,13 @@ if(NOT QT_NO_CREATE_VERSIONLESS_FUNCTIONS)
     endfunction()
 endif()
 
+function(_qt_internal_assign_to_internal_targets_folder target)
+    get_property(folder_name GLOBAL PROPERTY QT_TARGETS_FOLDER)
+    if(NOT "${folder_name}" STREQUAL "")
+        set_property(TARGET ${target} PROPERTY FOLDER "${folder_name}")
+    endif()
+endfunction()
+
 function(qt6_extract_metatypes target)
 
     get_target_property(existing_meta_types_file ${target} INTERFACE_QT_META_TYPES_BUILD_FILE)
@@ -1586,6 +1593,7 @@ function(qt6_extract_metatypes target)
                 COMMAND_EXPAND_LISTS
             )
             add_dependencies(${target}_automoc_json_extraction ${target}_autogen)
+            _qt_internal_assign_to_internal_targets_folder(${target}_automoc_json_extraction)
         else()
             set(cmake_autogen_timestamp_file
                 "${target_binary_dir}/${target}_autogen/timestamp"
@@ -2648,6 +2656,7 @@ function(qt6_add_plugin target)
     if(target_type STREQUAL "MODULE_LIBRARY")
         if(NOT TARGET qt_internal_plugins)
             add_custom_target(qt_internal_plugins)
+            _qt_internal_assign_to_internal_targets_folder(qt_internal_plugins)
         endif()
         add_dependencies(qt_internal_plugins ${target})
     endif()
@@ -3097,6 +3106,22 @@ macro(qt6_standard_project_setup)
                 set(CMAKE_AUTO${auto_set} TRUE)
             endif()
         endforeach()
+
+        # Enable folder support for IDEs. A future CMake version might enable this by default.
+        # See CMake issue #21695.
+        get_property(__qt_use_folders GLOBAL PROPERTY USE_FOLDERS)
+        if(__qt_use_folders OR "${__qt_use_folders}" STREQUAL "")
+            set_property(GLOBAL PROPERTY USE_FOLDERS ON)
+            get_property(__qt_qt_targets_folder GLOBAL PROPERTY QT_TARGETS_FOLDER)
+            if("${__qt_qt_targets_folder}" STREQUAL "")
+                set(__qt_qt_targets_folder QtInternalTargets)
+                set_property(GLOBAL PROPERTY QT_TARGETS_FOLDER ${__qt_qt_targets_folder})
+            endif()
+            get_property(__qt_autogen_targets_folder GLOBAL PROPERTY AUTOGEN_TARGETS_FOLDERS)
+            if("${__qt_autogen_targets_folder}" STREQUAL "")
+                set_property(GLOBAL PROPERTY AUTOGEN_TARGETS_FOLDER ${__qt_qt_targets_folder})
+            endif()
+        endif()
     endif()
 endmacro()
 
diff --git a/src/corelib/doc/src/cmake/cmake-properties.qdoc b/src/corelib/doc/src/cmake/cmake-properties.qdoc
index bbb948aec2..a07b7a0d93 100644
--- a/src/corelib/doc/src/cmake/cmake-properties.qdoc
+++ b/src/corelib/doc/src/cmake/cmake-properties.qdoc
@@ -425,6 +425,42 @@ For more information, see \l{https://emscripten.org/docs/porting/pthreads.html}{
 */
 
 /*!
+\group cmake-global-properties-qtcore
+\title CMake Global Properties in Qt6 Core
+
+\l{CMake Commands in Qt6 Core}{CMake Commands} know about the following global
+CMake properties:
+
+\sa{CMake Property Reference}
+*/
+
+/*!
+\page cmake-global-property-QT_TARGETS_FOLDER.html
+\ingroup cmake-properties-qtcore
+\ingroup cmake-global-properties-qtcore
+
+\title QT_TARGETS_FOLDER
+\target cmake-global-property-QT_TARGETS_FOLDER
+
+\brief Sets the FOLDER property for Qt-internal targets.
+
+\cmakepropertysince 6.5
+\preliminarycmakeproperty
+
+Name of the \l FOLDER for internal targets that are added by Qt's CMake
+commands.
+
+By default, this property is not set.
+
+This property only has an effect if CMake's \l USE_FOLDERS property is \c{ON}.
+
+You can use the \l{qt6_standard_project_setup}{qt_standard_project_setup}
+function to enable folder support and initialize the \c{QT_TARGETS_FOLDER}.
+
+\sa{qt6_standard_project_setup}{qt_standard_project_setup}
+*/
+
+/*!
 \page cmake-target-property-QT_WASM_INITIAL_MEMORY.html
 \ingroup cmake-properties-qtcore
 \ingroup cmake-target-properties-qtcore
diff --git a/src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc b/src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc
index b94d688e49..63e78d1275 100644
--- a/src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc
+++ b/src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc
@@ -42,6 +42,9 @@ have been defined. It does the following things:
     \c{${CMAKE_CURRENT_BINARY_DIR}}.
 \li When target platforms other than Apple or Windows, \c{CMAKE_INSTALL_RPATH}
     will be augmented as described below.
+\li CMake's \l USE_FOLDERS property is set to \c{ON}, and \l QT_TARGET_FOLDER is
+    set to \c{QtInternalTargets}. IDEs that support folders will display
+    Qt-internal targets in this folder.
 \endlist
 
 On platforms that support \c{RPATH} (other than Apple platforms), two values
@@ -57,6 +60,9 @@ will find their link-time dependencies, assuming projects install them to the
 default locations the \l{install(TARGETS)} command uses when no destination is
 explicitly provided.
 
+To disable folder support for IDEs, set \l USE_FOLDERS to \c OFF before or after
+the call to \c{qt_standard_project_setup}.
+
 The \c{qt_standard_project_setup()} command can effectively be disabled by
 setting the \l{QT_NO_STANDARD_PROJECT_SETUP} variable to true.
 
diff --git a/src/corelib/doc/src/external-resources.qdoc b/src/corelib/doc/src/external-resources.qdoc
index 7e8977dbd9..ecda025820 100644
--- a/src/corelib/doc/src/external-resources.qdoc
+++ b/src/corelib/doc/src/external-resources.qdoc
@@ -121,3 +121,13 @@
     \externalpage https://cmake.org/cmake/help/latest/module/FetchContent.html#command:fetchcontent_makeavailable
     \title FetchContent_MakeAvailable()
 */
+
+/*!
+    \externalpage https://cmake.org/cmake/help/latest/prop_gbl/USE_FOLDERS.html
+    \title USE_FOLDERS
+*/
+
+/*!
+    \externalpage https://cmake.org/cmake/help/latest/prop_tgt/FOLDER.html
+    \title FOLDER
+*/