Merge topic 'MsvcDebugInformationFormatAbstraction'

a858466aac MSVC: Add test for debug information format
0e96a20478 MSVC: Add abstraction for debug information format
d4c8111da4 Clang/Windows: Clarify name of internal runtime library flags variables

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

Help/command/try_compile.rst

@@ -244,3 +244,8 @@ a build configuration.
 .. versionadded:: 3.24
   The :variable:`CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable may be
   set to disable passing platform variables into the test project.
+
+.. versionadded:: 3.25
+  If :policy:`CMP0141` is set to ``NEW``, one can use
+  :variable:`CMAKE_MSVC_DEBUG_INFORMATION_FORMAT` to specify MSVC debug
+  information format.

Help/manual/cmake-policies.7.rst

@@ -58,6 +58,7 @@ Policies Introduced by CMake 3.25
 .. toctree::
    :maxdepth: 1
 
+   CMP0141: MSVC debug information format flags are selected by an abstraction. </policy/CMP0141>
    CMP0140: The return() command checks its arguments. </policy/CMP0140>
 
 Policies Introduced by CMake 3.24

Help/manual/cmake-properties.7.rst

@@ -340,6 +340,7 @@ Properties on Targets
    /prop_tgt/MACOSX_RPATH
    /prop_tgt/MANUALLY_ADDED_DEPENDENCIES
    /prop_tgt/MAP_IMPORTED_CONFIG_CONFIG
+   /prop_tgt/MSVC_DEBUG_INFORMATION_FORMAT
    /prop_tgt/MSVC_RUNTIME_LIBRARY
    /prop_tgt/NAME
    /prop_tgt/NO_SONAME

Help/manual/cmake-variables.7.rst

@@ -484,6 +484,7 @@ Variables that Control the Build
    /variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT
    /variable/CMAKE_MODULE_LINKER_FLAGS_INIT
    /variable/CMAKE_MSVCIDE_RUN_PATH
+   /variable/CMAKE_MSVC_DEBUG_INFORMATION_FORMAT
    /variable/CMAKE_MSVC_RUNTIME_LIBRARY
    /variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX
    /variable/CMAKE_NO_BUILTIN_CHRPATH

Help/policy/CMP0141.rst

@@ -0,0 +1,55 @@
+CMP0141
+-------
+
+.. versionadded:: 3.25
+
+MSVC debug information format flags are selected by an abstraction.
+
+Compilers targeting the MSVC ABI have flags to select the debug information
+format. Debug information format selection typically varies with build
+configuration.
+
+In CMake 3.24 and below, debug information format flags are added to
+the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache entries by CMake
+automatically.  This allows users to edit their cache entries to adjust the
+flags.  However, the presence of such default flags is problematic for
+projects that want to choose a different runtime library programmatically.
+In particular, it requires string editing of the
+:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variables with knowledge of the
+CMake builtin defaults so they can be replaced.
+
+CMake 3.25 and above prefer to leave the debug information format flags
+out of the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` values and instead
+offer a first-class abstraction.  The
+:variable:`CMAKE_MSVC_DEBUG_INFORMATION_FORMAT` variable and
+:prop_tgt:`MSVC_DEBUG_INFORMATION_FORMAT` target property may be set to
+select the MSVC debug information format.  If they are not set, CMake
+enables debug information in debug configurations using the default value
+``$<$<CONFIG:Debug,RelWithDebInfo>:ProgramDatabase>``, if supported by the
+compiler, and otherwise ``$<$<CONFIG:Debug,RelWithDebInfo>:Embedded>``.
+
+This policy provides compatibility with projects that have not been updated
+to be aware of the abstraction.  The policy setting takes effect as of the
+first :command:`project` or :command:`enable_language` command that enables
+a language whose compiler targets the MSVC ABI.
+
+.. note::
+
+  Once the policy has taken effect at the top of a project, that choice
+  will be used throughout the tree.  In projects that have nested projects
+  in subdirectories, be sure to confirm if everything is working with the
+  selected policy behavior.
+
+The ``OLD`` behavior for this policy is to place MSVC debug information
+format flags in the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache
+entries and ignore the :variable:`CMAKE_MSVC_DEBUG_INFORMATION_FORMAT`
+abstraction.  The ``NEW`` behavior for this policy is to *not* place MSVC
+debug information format flags flags in the default cache entries and use
+the abstraction instead.
+
+This policy was introduced in CMake version 3.25.  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.
+
+.. include:: DEPRECATED.txt

Help/prop_tgt/MSVC_DEBUG_INFORMATION_FORMAT-VALUES.txt

@@ -0,0 +1,15 @@
+``Embedded``
+  Compile with ``-Z7`` or equivalent flag(s) to produce object files
+  with full symbolic debugging information.
+``ProgramDatabase``
+  Compile with ``-Zi`` or equivalent flag(s) to produce a program
+  database that contains all the symbolic debugging information.
+``EditAndContinue``
+  Compile with ``-ZI`` or equivalent flag(s) to produce a program
+  database that supports the Edit and Continue feature.
+
+The value is ignored on non-MSVC compilers but an unsupported value will
+be rejected as an error when using a compiler targeting the MSVC ABI.
+
+The value may also be the empty string (``""``) in which case no debug
+information format flag will be added explicitly by CMake.

Help/prop_tgt/MSVC_DEBUG_INFORMATION_FORMAT.rst

@@ -0,0 +1,33 @@
+MSVC_DEBUG_INFORMATION_FORMAT
+-----------------------------
+
+.. versionadded:: 3.25
+
+Select debug information format targeting the MSVC ABI.
+
+The allowed values are:
+
+.. include:: MSVC_DEBUG_INFORMATION_FORMAT-VALUES.txt
+
+Use :manual:`generator expressions <cmake-generator-expressions(7)>` to
+support per-configuration specification.  For example, the code:
+
+.. code-block:: cmake
+
+  add_executable(foo foo.c)
+  set_property(TARGET foo PROPERTY
+    MSVC_DEBUG_INFORMATION_FORMAT "$<$<CONFIG:Debug,RelWithDebInfo>:ProgramDatabase>")
+
+selects for the target ``foo`` the program database debug information format
+for the Debug configuration.
+
+If this property is not set, CMake selects a debug information format using
+the default value ``$<$<CONFIG:Debug,RelWithDebInfo>:ProgramDatabase>``, if
+supported by the compiler, and otherwise
+``$<$<CONFIG:Debug,RelWithDebInfo>:Embedded>``.
+
+.. note::
+
+  This property has effect only when policy :policy:`CMP0141` is set to ``NEW``
+  prior to the first :command:`project` or :command:`enable_language` command
+  that enables a language using a compiler targeting the MSVC ABI.

Help/release/dev/MsvcDebugInformationFormatAbstraction.rst

@@ -0,0 +1,7 @@
+MsvcDebugInformationFormatAbstraction
+-------------------------------------
+
+* The :variable:`CMAKE_MSVC_DEBUG_INFORMATION_FORMAT` variable and
+  :prop_tgt:`MSVC_DEBUG_INFORMATION_FORMAT` target property were introduced
+  to select the debug information format for compilers targeting the MSVC ABI.
+  See policy :policy:`CMP0141`.

Help/variable/CMAKE_MSVC_DEBUG_INFORMATION_FORMAT.rst

@@ -0,0 +1,36 @@
+CMAKE_MSVC_DEBUG_INFORMATION_FORMAT
+-----------------------------------
+
+.. versionadded:: 3.25
+
+Select the MSVC debug information format targeting the MSVC ABI.
+This variable is used to initialize the
+:prop_tgt:`MSVC_DEBUG_INFORMATION_FORMAT` property on all targets as they are
+created.  It is also propagated by calls to the :command:`try_compile` command
+into the test project.
+
+The allowed values are:
+
+.. include:: ../prop_tgt/MSVC_DEBUG_INFORMATION_FORMAT-VALUES.txt
+
+Use :manual:`generator expressions <cmake-generator-expressions(7)>` to
+support per-configuration specification.  For example, the code:
+
+.. code-block:: cmake
+
+  set(CMAKE_MSVC_DEBUG_INFORMATION_FORMAT "$<$<CONFIG:Debug,RelWithDebInfo>:ProgramDatabase>")
+
+selects for all following targets the program database debug information format
+for the Debug configuration.
+
+If this variable is not set, the :prop_tgt:`MSVC_DEBUG_INFORMATION_FORMAT`
+target property will not be set automatically.  If that property is not set,
+CMake selects a debug information format using the default value
+``$<$<CONFIG:Debug,RelWithDebInfo>:ProgramDatabase>``, if supported by the
+compiler, and otherwise ``$<$<CONFIG:Debug,RelWithDebInfo>:Embedded>``.
+
+.. note::
+
+  This variable has effect only when policy :policy:`CMP0141` is set to ``NEW``
+  prior to the first :command:`project` or :command:`enable_language` command
+  that enables a language using a compiler targeting the MSVC ABI.