Merge topic 'use_folders_on_by_default'

d3acd22380 USE_FOLDERS: Treat as on by default

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Amir Masoud Abdol <amirmasoudabdol@icloud.com>
Merge-request: !7830

Help/manual/cmake-policies.7.rst

@@ -51,6 +51,13 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used
 to determine whether to report an error on use of deprecated macros or
 functions.
 
+Policies Introduced by CMake 3.26
+=================================
+
+.. toctree::
+   :maxdepth: 1
+
+   CMP0143: USE_FOLDERS global property is treated as ON by default. </policy/CMP0143>
 
 Policies Introduced by CMake 3.25
 =================================

Help/policy/CMP0143.rst

@@ -0,0 +1,30 @@
+CMP0143
+-------
+
+.. versionadded:: 3.26
+
+:prop_gbl:`USE_FOLDERS` global property is treated as ``ON`` by default.
+
+When using CMake 3.25 and below, :prop_gbl:`USE_FOLDERS` is treated
+as ``OFF`` by default unless projects enable the feature.  For example:
+
+.. code-block:: cmake
+
+  cmake_minimum_required(VERSION 3.25)
+  project(foobar LANGUAGES CXX)
+  set_property(GLOBAL PROPERTY USE_FOLDERS ON)
+
+CMake 3.26 and later prefer to enable the feature by default.
+
+This policy provides compatibility with projects that have not been updated
+to expect enabling of folders.  Enabling folders causes projects to appear
+differently in IDEs.
+
+This policy was introduced in CMake version 3.26.  Use the
+:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
+Unlike many policies, CMake version |release| does *not* warn
+when this policy is not set and simply uses ``OLD`` behavior.
+The policy setting must be in scope at the end of the top-level
+``CMakeLists.txt`` file of the project and has global effect.
+
+.. include:: DEPRECATED.txt

Help/prop_gbl/USE_FOLDERS.rst

@@ -4,7 +4,16 @@ USE_FOLDERS
 Use the :prop_tgt:`FOLDER` target property to organize targets into
 folders.
 
-If not set, CMake treats this property as ``OFF`` by default.  CMake
-generators that are capable of organizing into a hierarchy of folders
+.. versionchanged:: 3.26
+
+  CMake treats this property as ``ON`` by default.
+  See policy :policy:`CMP0143`.
+
+CMake generators that are capable of organizing into a hierarchy of folders
 use the values of the :prop_tgt:`FOLDER` target property to name those
-folders. See also the documentation for the :prop_tgt:`FOLDER` target property.
+folders. (i.e.: Visual Studio / XCode)
+
+IDE's can also take advantage of this property to organize CMake targets.
+Regardless of generator support.
+
+See also the documentation for the :prop_tgt:`FOLDER` target property.

Help/release/dev/use-folder-on-by-default.rst

@@ -0,0 +1,5 @@
+use-folder-on-by-default
+------------------------
+
+* Global property :prop_gbl:`USE_FOLDERS` is treated as ``ON`` by default.
+  See policy :policy:`CMP0143`.