mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-01 19:30:13 -06:00
Code Issues Packages Projects Releases Wiki Activity

Help: Improve wording of FOLDER-related properties and policies

Browse Source
This commit is contained in:
Craig Scott
2023-02-25 17:15:17 +11:00
parent 030c70f92a
commit 9f1360ae19
3 changed files with 25 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
Help/policy/CMP0143.rst
View File

@@ -5,7 +5,7 @@ CMP0143
: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
When using CMake 3.25 or earlier, :prop_gbl:`USE_FOLDERS` is treated
as ``OFF`` by default unless projects enable the feature. For example:
.. code-block:: cmake
@@ -16,15 +16,15 @@ as ``OFF`` by default unless projects enable the feature. For example:
CMake 3.26 and later prefer to enable the feature by default.
Note that it is the policy setting at the `end` of the top level
``CMakeLists.txt`` file that matters. The policy setting applies globally
to the whole project.
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
differently in IDEs. The 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

18
Help/prop_gbl/USE_FOLDERS.rst
View File

@@ -1,19 +1,17 @@
USE_FOLDERS
-----------
Use the :prop_tgt:`FOLDER` target property to organize targets into
folders.
Controls whether to use the :prop_tgt:`FOLDER` target property to organize
targets into folders. The value of ``USE_FOLDERS`` at the end of the top level
``CMakeLists.txt`` file is what determines the behavior.
.. 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. (i.e.: ``Visual Studio`` or ``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.
Not all CMake generators support recording folder details for targets.
The :generator:`Xcode` and :ref:`Visual Studio <Visual Studio Generators>`
generators are examples of generators that do. Similarly, not all IDEs
support presenting targets using folder hierarchies, even if the CMake
generator used provides the necessary information.

18
Help/prop_tgt/FOLDER.rst
View File

@@ -1,16 +1,20 @@
FOLDER
------
Set the folder name. Use to organize targets in an IDE.
For IDEs that present targets using a folder hierarchy, this property
specifies the name of the folder to place the target under.
To nest folders, use ``FOLDER`` values such as ``GUI/Dialogs`` with ``/``
characters separating folder levels. Targets with no ``FOLDER`` property
will appear as top level entities. Targets with the same ``FOLDER``
property value will appear in the same folder as siblings.
Targets with no ``FOLDER`` property will appear as top level entities in
IDEs like Visual Studio. Targets with the same ``FOLDER`` property value
will appear next to each other in a folder of that name. To nest
folders, use ``FOLDER`` values such as 'GUI/Dialogs' with '/' characters
separating folder levels.
Only some CMake generators honor the ``FOLDER`` property
(e.g. :generator:`Xcode` or any of the
:ref:`Visual Studio <Visual Studio Generators>` generators).
Those generators that don't will simply ignore it.
This property is initialized by the value of the variable
:variable:`CMAKE_FOLDER` if it is set when a target is created.
The global property :prop_gbl:`USE_FOLDERS` must be set to ON, otherwise
The global property :prop_gbl:`USE_FOLDERS` must be set to true, otherwise
the ``FOLDER`` property is ignored.