diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/try_compile.rst | 5 | ||||
| -rw-r--r-- | Help/manual/cmake-policies.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-properties.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 1 | ||||
| -rw-r--r-- | Help/policy/CMP0141.rst | 55 | ||||
| -rw-r--r-- | Help/prop_tgt/MSVC_DEBUG_INFORMATION_FORMAT-VALUES.txt | 15 | ||||
| -rw-r--r-- | Help/prop_tgt/MSVC_DEBUG_INFORMATION_FORMAT.rst | 33 | ||||
| -rw-r--r-- | Help/release/dev/MsvcDebugInformationFormatAbstraction.rst | 7 | ||||
| -rw-r--r-- | Help/variable/CMAKE_MSVC_DEBUG_INFORMATION_FORMAT.rst | 36 |
9 files changed, 154 insertions, 0 deletions
diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 73dd9d3..710fd21 100644 --- a/Help/command/try_compile.rst +++ b/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. diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index a1133b9..c0c37d1 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/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 diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index d98f7cc..09c3c88 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/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 diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index ad6bfbc..02706d8 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -486,6 +486,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 diff --git a/Help/policy/CMP0141.rst b/Help/policy/CMP0141.rst new file mode 100644 index 0000000..51fa5fd --- /dev/null +++ b/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 diff --git a/Help/prop_tgt/MSVC_DEBUG_INFORMATION_FORMAT-VALUES.txt b/Help/prop_tgt/MSVC_DEBUG_INFORMATION_FORMAT-VALUES.txt new file mode 100644 index 0000000..9a68460 --- /dev/null +++ b/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. diff --git a/Help/prop_tgt/MSVC_DEBUG_INFORMATION_FORMAT.rst b/Help/prop_tgt/MSVC_DEBUG_INFORMATION_FORMAT.rst new file mode 100644 index 0000000..2314cff --- /dev/null +++ b/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. diff --git a/Help/release/dev/MsvcDebugInformationFormatAbstraction.rst b/Help/release/dev/MsvcDebugInformationFormatAbstraction.rst new file mode 100644 index 0000000..d0c077c --- /dev/null +++ b/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`. diff --git a/Help/variable/CMAKE_MSVC_DEBUG_INFORMATION_FORMAT.rst b/Help/variable/CMAKE_MSVC_DEBUG_INFORMATION_FORMAT.rst new file mode 100644 index 0000000..80df8fc --- /dev/null +++ b/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. |