mirror of
https://github.com/Kitware/CMake.git
synced 2026-04-21 13:48:33 -05:00
Glen Chung
0e96a20478
Replace our hard-coded default for `/Zi` with a first-class abstraction to select the debug information format an enumeration of logical names. We've long hesitated to do this because the idea of "debug information format" touches on related concepts on several platforms. Avoid that scope creep by simply defining an abstraction that applies only when targeting the MSVC ABI on Windows. Removing the old default flag requires a policy because existing projects may rely on string processing to edit them and choose a runtime library under the old behavior. Add policy CMP0141 to provide compatibility. Fixes: #10189
56 lines
2.6 KiB
ReStructuredText
56 lines
2.6 KiB
ReStructuredText
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
|