diff options
| -rw-r--r-- | Help/policy/CMP0143.rst | 12 | ||||
| -rw-r--r-- | Help/prop_gbl/USE_FOLDERS.rst | 18 | ||||
| -rw-r--r-- | Help/prop_tgt/FOLDER.rst | 18 | ||||
| -rw-r--r-- | Help/release/3.26.rst | 11 |
4 files changed, 30 insertions, 29 deletions
diff --git a/Help/policy/CMP0143.rst b/Help/policy/CMP0143.rst index 7a7aee7..24fdc27 100644 --- a/Help/policy/CMP0143.rst +++ b/Help/policy/CMP0143.rst @@ -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 diff --git a/Help/prop_gbl/USE_FOLDERS.rst b/Help/prop_gbl/USE_FOLDERS.rst index f3d7791..6f5a083 100644 --- a/Help/prop_gbl/USE_FOLDERS.rst +++ b/Help/prop_gbl/USE_FOLDERS.rst @@ -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. diff --git a/Help/prop_tgt/FOLDER.rst b/Help/prop_tgt/FOLDER.rst index 3155d90..616b962 100644 --- a/Help/prop_tgt/FOLDER.rst +++ b/Help/prop_tgt/FOLDER.rst @@ -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. diff --git a/Help/release/3.26.rst b/Help/release/3.26.rst index ff2e208..ee98a98 100644 --- a/Help/release/3.26.rst +++ b/Help/release/3.26.rst @@ -87,7 +87,7 @@ Properties initialize this property. * The :prop_tgt:`XCODE_EMBED_EXTENSIONKIT_EXTENSIONS <XCODE_EMBED_<type>>` - target property was added to tell the :generator:`Xcode` generator to + target property was added to tell the :generator:`Xcode` generator to embed ExtensionKit-based extensions such as extensions using the Background Assets framework. Aspects of the embedding can be customized with: @@ -98,7 +98,7 @@ Properties Modules ------- -* The :module:`ExternalProject` module :command:`ExternalProject_Add` command +* The :module:`ExternalProject` module's :command:`ExternalProject_Add` command gained an ``INSTALL_BYPRODUCTS`` option to specify files generated by the ``install`` step. @@ -113,7 +113,7 @@ Modules * The :module:`FindPython3` and :module:`FindPython` modules gained support for the `Stable Application Binary Interface`_. -* The :module:`UseSWIG` module gained the support for the ``perl5`` language. +* The :module:`UseSWIG` module gained support for the ``perl5`` language. .. _`Stable Application Binary Interface`: https://docs.python.org/3/c-api/stable.html @@ -135,11 +135,10 @@ Deprecated and Removed Features =============================== * The ``CMakeFiles/CMakeOutput.log`` and ``CMakeFiles/CMakeError.log`` - files are no longer populated by CMake's builtin modules, and + files are no longer populated by CMake's built-in modules. :manual:`cmake(1)` no longer suggests looking at them after a ``CMake Error`` occurs. Information previously logged to those - files is instead logged to ``CMakeFiles/CMakeConfigureLog.yaml``, - the :manual:`cmake-configure-log(7)`. + files is instead logged to the :manual:`cmake-configure-log(7)`. * On CYGWIN, the undocumented ``CMAKE_LEGACY_CYGWIN_WIN32`` mode for compatibility with CMake versions older than 2.8.4 has been removed. |