Merge topic 'vs-UseDebugLibraries'

721d8b192a VS: Add UseDebugLibraries to vcxproj files by default
47136b6959 VS: Suppress more MSBuild defaults affected by UseDebugLibraries
82a174182a cmVisualStudioGeneratorOptions: Add UsingDebugRuntime method
f498032141 cmVisualStudioGeneratorOptions: Rename {IsDebug => UsingDebugInfo}

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: buildbot <buildbot@kitware.com>
Merge-request: !9275

5 files changed, 65 insertions, 4 deletions

diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index bb6cfd4..ba74e68 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -51,6 +51,14 @@ 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.30
+=================================
+
+.. toctree::
+   :maxdepth: 1
+
+   CMP0162: Visual Studio generators add UseDebugLibraries indicators by default. </policy/CMP0162>
+
 Policies Introduced by CMake 3.29
 =================================
 
diff --git a/Help/policy/CMP0162.rst b/Help/policy/CMP0162.rst
new file mode 100644
index 0000000..df46d96
--- /dev/null
+++ b/Help/policy/CMP0162.rst
@@ -0,0 +1,47 @@
+CMP0162
+-------
+
+.. versionadded:: 3.30
+
+:ref:`Visual Studio Generators` add ``UseDebugLibraries`` indicators by default.
+
+The "Use Debug Libraries" setting in Visual Studio projects indicates what
+configurations are considered debug configurations.  In standalone projects,
+this may affect MSBuild's default selection of MSVC runtime library,
+optimization flags, runtime checks, and similar settings.  CMake typically
+generates all those settings explicitly based on the project's specification,
+so CMake 3.29 and below do not write any ``UseDebugLibraries`` indicators to
+``.vcxproj`` files.
+
+CMake 3.30 and above prefer to write ``UseDebugLibraries`` indicators because
+they are useful for reference by both humans and tools, and may also affect
+the behavior of platform-specific SDKs.  The indicator for each configuration
+of a target is determined as follows:
+
+* If the target compiles sources for a known MSVC runtime library
+  (such as that specified by :prop_tgt:`MSVC_RUNTIME_LIBRARY`),
+  then ``UseDebugLibraries`` is ``true`` for configurations that
+  compile for a "Debug" runtime library, and ``false`` for others.
+
+* Otherwise, such as in targets created by :command:`add_custom_target`,
+  ``UseDebugLibraries`` is ``true`` for the ``Debug`` configuration,
+  and ``false`` for others.
+
+This policy provides compatibility for projects that have not been updated to
+expect the indicators.  The policy setting is recorded by each target as it is
+created and used to determine the default behavior for that target's
+``.vcxproj`` file.
+
+The ``OLD`` behavior for this policy is to not generate ``UseDebugLibraries``
+indicators by default.  The ``NEW`` behavior for this policy is to generate
+``UseDebugLibraries`` indicators by default.
+
+If the :variable:`CMAKE_VS_USE_DEBUG_LIBRARIES` variable and/or
+:prop_tgt:`VS_USE_DEBUG_LIBRARIES` target property is set, it explicitly
+controls ``UseDebugLibraries`` generation regardless of this policy.
+
+.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.30
+.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
+.. include:: STANDARD_ADVICE.txt
+
+.. include:: DEPRECATED.txt
diff --git a/Help/prop_tgt/VS_USE_DEBUG_LIBRARIES.rst b/Help/prop_tgt/VS_USE_DEBUG_LIBRARIES.rst
index 78ad36a..3d5ada4 100644
--- a/Help/prop_tgt/VS_USE_DEBUG_LIBRARIES.rst
+++ b/Help/prop_tgt/VS_USE_DEBUG_LIBRARIES.rst
@@ -23,5 +23,6 @@ to be non-debug configurations.
 
 The property is initialized from the value of the
 :variable:`CMAKE_VS_USE_DEBUG_LIBRARIES` variable, if it is set.
-If the property is not set, then CMake does not generate any
-``UseDebugLibraries`` indicator.
+If the property is not set then CMake generates ``UseDebugLibraries`` using
+heuristics to determine which configurations are debug configurations.
+See policy :policy:`CMP0162`.
diff --git a/Help/release/dev/vs-UseDebugLibraries.rst b/Help/release/dev/vs-UseDebugLibraries.rst
index 477c385..b3774a9 100644
--- a/Help/release/dev/vs-UseDebugLibraries.rst
+++ b/Help/release/dev/vs-UseDebugLibraries.rst
@@ -1,6 +1,10 @@
 vs-UseDebugLibraries
 --------------------
 
+* :ref:`Visual Studio Generators` now add ``UseDebugLibraries`` indicators to
+  ``.vcxproj`` files to denote which configurations are debug configurations.
+  See policy :policy:`CMP0162`.
+
 * The :variable:`CMAKE_VS_USE_DEBUG_LIBRARIES` variable and corresponding
   :prop_tgt:`VS_USE_DEBUG_LIBRARIES` target property were added to explicitly
   control ``UseDebugLibraries`` indicators in ``.vcxproj`` files.
diff --git a/Help/variable/CMAKE_VS_USE_DEBUG_LIBRARIES.rst b/Help/variable/CMAKE_VS_USE_DEBUG_LIBRARIES.rst
index 45d3eff..35d94bc 100644
--- a/Help/variable/CMAKE_VS_USE_DEBUG_LIBRARIES.rst
+++ b/Help/variable/CMAKE_VS_USE_DEBUG_LIBRARIES.rst
@@ -24,5 +24,6 @@ property on all targets as they are created.  It is also propagated by
 calls to the :command:`try_compile` command into its test project.
 
 If this variable is not set then the :prop_tgt:`VS_USE_DEBUG_LIBRARIES`
-property will not be set automatically.  If that property is not set
-then CMake does not generate any ``UseDebugLibraries`` indicator.
+property will not be set automatically.  If that property is not set then
+CMake generates ``UseDebugLibraries`` using heuristics to determine which
+configurations are debug configurations.  See policy :policy:`CMP0162`.