From 99546ef4259765a9313f2164120164ba7063d798 Mon Sep 17 00:00:00 2001 From: Peter Kokot Date: Sat, 15 Mar 2025 14:13:50 +0100 Subject: [PATCH] Help: Improve DEBUG_CONFIGURATIONS documentation and usage This adds a short example demonstrating how to set this property. Additionally, a paragraph is added to the target_link_libraries() and its debug/optimized keywords to mention that imported targets with IMPORTED_CONFIGURATIONS property may provide better alternative for linking. --- Help/command/target_link_libraries.rst | 14 ++++++++----- Help/prop_gbl/DEBUG_CONFIGURATIONS.rst | 27 +++++++++++++++++++++++--- 2 files changed, 33 insertions(+), 8 deletions(-) diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index ab01307c44..4a1140ba48 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -127,11 +127,15 @@ Each ```` may be: in the :prop_gbl:`DEBUG_CONFIGURATIONS` global property if it is set). The ``optimized`` keyword corresponds to all other configurations. The ``general`` keyword corresponds to all configurations, and is purely - optional. Higher granularity may be achieved for per-configuration - rules by creating and linking to - :ref:`IMPORTED library targets `. - These keywords are interpreted immediately by this command and therefore - have no special meaning when produced by a generator expression. + optional. These keywords are interpreted immediately by this command and + therefore have no special meaning when produced by a generator expression. + + Alternatively, generator expressions like :genex:`$` provide finer + per-configuration linking of ````. For a more structured approach, + higher granularity can be achieved by creating and linking to + :ref:`IMPORTED library targets ` with the + :prop_tgt:`IMPORTED_CONFIGURATIONS` property set, particularly in find + modules. Items containing ``::``, such as ``Foo::Bar``, are assumed to be :ref:`IMPORTED ` or :ref:`ALIAS ` library diff --git a/Help/prop_gbl/DEBUG_CONFIGURATIONS.rst b/Help/prop_gbl/DEBUG_CONFIGURATIONS.rst index fec6fdac86..6ce6da7cb5 100644 --- a/Help/prop_gbl/DEBUG_CONFIGURATIONS.rst +++ b/Help/prop_gbl/DEBUG_CONFIGURATIONS.rst @@ -1,13 +1,34 @@ DEBUG_CONFIGURATIONS -------------------- -Specify which configurations are for debugging. +This property specifies which :ref:`Build Configurations` are for debugging. -The value must be a semi-colon separated list of configuration names. +The value must be a :ref:`semicolon-separated list ` of +build configuration names. Currently this property is used only by the :command:`target_link_libraries` command. Additional uses may be defined in the future. This property must be set at the top level of the project and before the first :command:`target_link_libraries` command invocation. If any entry in -the list does not match a valid configuration for the project the +the list does not match a valid configuration for the project, the behavior is undefined. + +By default, this property is **not set**. + +Examples +^^^^^^^^ + +The following example adds a custom configuration to non-optimized debug +configurations while preserving any existing ones. If the project uses the +default ``Debug`` configuration, it should be included as well. + +.. code-block:: cmake + + set_property(GLOBAL APPEND PROPERTY DEBUG_CONFIGURATIONS Debug CustomBuild) + +See Also +^^^^^^^^ + +* The :prop_tgt:`MAP_IMPORTED_CONFIG_` target property, which maps build + configurations when linking to :ref:`Imported Targets` that have the + :prop_tgt:`IMPORTED_CONFIGURATIONS` property set.