Help/policy/CMP0141.rst

   1 CMP0141
   2 -------
   3
   4 .. versionadded:: 3.25
   5
   6 MSVC debug information format flags are selected by an abstraction.
   7
   8 Compilers targeting the MSVC ABI have flags to select the debug information
   9 format. Debug information format selection typically varies with build
  10 configuration.
  11
  12 In CMake 3.24 and below, debug information format flags are added to
  13 the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache entries by CMake
  14 automatically.  This allows users to edit their cache entries to adjust the
  15 flags.  However, the presence of such default flags is problematic for
  16 projects that want to choose a different runtime library programmatically.
  17 In particular, it requires string editing of the
  18 :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variables with knowledge of the
  19 CMake builtin defaults so they can be replaced.
  20
  21 CMake 3.25 and above prefer to leave the debug information format flags
  22 out of the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` values and instead
  23 offer a first-class abstraction.  The
  24 :variable:`CMAKE_MSVC_DEBUG_INFORMATION_FORMAT` variable and
  25 :prop_tgt:`MSVC_DEBUG_INFORMATION_FORMAT` target property may be set to
  26 select the MSVC debug information format.  If they are not set, CMake
  27 enables debug information in debug configurations using the default value
  28 ``$<$<CONFIG:Debug,RelWithDebInfo>:ProgramDatabase>``, if supported by the
  29 compiler, and otherwise ``$<$<CONFIG:Debug,RelWithDebInfo>:Embedded>``.
  30
  31 This policy provides compatibility with projects that have not been updated
  32 to be aware of the abstraction.  The policy setting takes effect as of the
  33 first :command:`project` or :command:`enable_language` command that enables
  34 a language whose compiler targets the MSVC ABI.
  35
  36 .. note::
  37
  38   Once the policy has taken effect at the top of a project, that choice
  39   will be used throughout the tree.  In projects that have nested projects
  40   in subdirectories, be sure to confirm if everything is working with the
  41   selected policy behavior.
  42
  43 The ``OLD`` behavior for this policy is to place MSVC debug information
  44 format flags in the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache
  45 entries and ignore the :variable:`CMAKE_MSVC_DEBUG_INFORMATION_FORMAT`
  46 abstraction.  The ``NEW`` behavior for this policy is to *not* place MSVC
  47 debug information format flags in the default cache entries and use
  48 the abstraction instead.
  49
  50 This policy was introduced in CMake version 3.25.  Use the
  51 :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
  52 Unlike many policies, CMake version |release| does *not* warn
  53 when this policy is not set and simply uses ``OLD`` behavior.
  54
  55 .. include:: DEPRECATED.txt