diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/try_compile.rst | 23 | ||||
| -rw-r--r-- | Help/manual/cmake-policies.7.rst | 2 | ||||
| -rw-r--r-- | Help/manual/cmake-properties.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 2 | ||||
| -rw-r--r-- | Help/policy/CMP0141.rst | 55 | ||||
| -rw-r--r-- | Help/policy/CMP0142.rst | 27 | ||||
| -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/release/dev/add_tasking_compiler.rst | 8 | ||||
| -rw-r--r-- | Help/release/dev/xcode-lib-dirs.rst | 6 | ||||
| -rw-r--r-- | Help/variable/CMAKE_LANG_COMPILER_ID.rst | 2 | ||||
| -rw-r--r-- | Help/variable/CMAKE_MSVC_DEBUG_INFORMATION_FORMAT.rst | 36 | ||||
| -rw-r--r-- | Help/variable/CMAKE_TASKING_TOOLSET.rst | 31 |
14 files changed, 246 insertions, 2 deletions
diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 73dd9d3..97ad481 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -14,10 +14,15 @@ Try Compiling Whole Projects .. code-block:: cmake - try_compile(<resultVar> <bindir> <srcdir> - <projectName> [<targetName>] [CMAKE_FLAGS <flags>...] + try_compile(<resultVar> PROJECT <projectName> + SOURCE_DIR <srcdir> + [BINARY_DIR <bindir>] + [TARGET <targetName>] + [CMAKE_FLAGS <flags>...] [OUTPUT_VARIABLE <var>]) +.. versionadded:: 3.25 + Try building a project. The success or failure of the ``try_compile``, i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``<resultVar>``. @@ -34,6 +39,15 @@ below for the meaning of other options. Previously this was only done by the :ref:`source file <Try Compiling Source Files>` signature. +This command also supports an alternate signature +which was present in older versions of CMake: + +.. code-block:: cmake + + try_compile(<resultVar> <bindir> <srcdir> + <projectName> [<targetName>] [CMAKE_FLAGS <flags>...] + [OUTPUT_VARIABLE <var>]) + .. _`Try Compiling Source Files`: Try Compiling Source Files @@ -244,3 +258,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..d6a30ff 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -58,6 +58,8 @@ Policies Introduced by CMake 3.25 .. toctree:: :maxdepth: 1 + CMP0142: The Xcode generator does not append per-config suffixes to library search paths. </policy/CMP0142> + 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 6533ca5..02efc9c 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/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 @@ -510,6 +511,7 @@ Variables that Control the Build /variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG /variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_STATIC_LINKER_FLAGS_INIT + /variable/CMAKE_TASKING_TOOLSET /variable/CMAKE_TRY_COMPILE_CONFIGURATION /variable/CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES /variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES 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/policy/CMP0142.rst b/Help/policy/CMP0142.rst new file mode 100644 index 0000000..1f928f0 --- /dev/null +++ b/Help/policy/CMP0142.rst @@ -0,0 +1,27 @@ +CMP0142 +------- + +.. versionadded:: 3.25 + +The :generator:`Xcode` generator does not append per-config suffixes to +library search paths. + +In CMake 3.24 and below, the :generator:`Xcode` generator preceded each +entry of a library search path with a copy of itself appended with +``$(CONFIGURATION)$(EFFECTIVE_PLATFORM_NAME)``. This was left from +very early versions of CMake in which per-config directories were not well +modeled. Such paths often do not exist, resulting in warnings from the +toolchain. CMake 3.25 and above prefer to not add such library search +paths. This policy provides compatibility for projects that may have been +accidentally relying on the old behavior. + +The ``OLD`` behavior for this policy is to append +``$(CONFIGURATION)$(EFFECTIVE_PLATFORM_NAME)`` to all library search paths. +The ``NEW`` behavior is to not modify library search paths. + +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/release/dev/add_tasking_compiler.rst b/Help/release/dev/add_tasking_compiler.rst new file mode 100644 index 0000000..705f923 --- /dev/null +++ b/Help/release/dev/add_tasking_compiler.rst @@ -0,0 +1,8 @@ +add_tasking_compiler +-------------------- + + * Support for the `Tasking compiler toolsets`_ (SmartCode, TriCore, + Standalone: ARM, MCS, 8051) was added with compiler id ``Tasking``. + See the :variable:`CMAKE_TASKING_TOOLSET` variable. + +.. _`Tasking compiler toolsets`: https://tasking.com diff --git a/Help/release/dev/xcode-lib-dirs.rst b/Help/release/dev/xcode-lib-dirs.rst new file mode 100644 index 0000000..fc1fe1b --- /dev/null +++ b/Help/release/dev/xcode-lib-dirs.rst @@ -0,0 +1,6 @@ +xcode-lib-dirs +-------------- + +* The :generator:`Xcode` generator no longer adds the per-config suffix + ``$(CONFIGURATION)$(EFFECTIVE_PLATFORM_NAME)`` to library search paths. + See policy :policy:`CMP0142`. diff --git a/Help/variable/CMAKE_LANG_COMPILER_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_ID.rst index f0534ba..0dbc0a0 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_ID.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_ID.rst @@ -44,6 +44,7 @@ Value Name ``XL``, ``VisualAge``, ``zOS`` IBM XL ``XLClang`` IBM Clang-based XL ``IBMClang`` IBM LLVM-based Compiler +``Tasking`` `Tasking Compiler Toolsets`_ =============================== =============================================== This variable is not guaranteed to be defined for all compilers or @@ -63,3 +64,4 @@ languages. .. _Open Watcom: https://open-watcom.github.io .. _Small Device C Compiler: http://sdcc.sourceforge.net .. _Tiny C Compiler: https://bellard.org/tcc +.. _Tasking Compiler Toolsets: https://tasking.com 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. diff --git a/Help/variable/CMAKE_TASKING_TOOLSET.rst b/Help/variable/CMAKE_TASKING_TOOLSET.rst new file mode 100644 index 0000000..430207e --- /dev/null +++ b/Help/variable/CMAKE_TASKING_TOOLSET.rst @@ -0,0 +1,31 @@ +CMAKE_TASKING_TOOLSET +--------------------- + +.. versionadded:: 3.25 + +Select the Tasking toolset which provides the compiler + +Architecture compilers are provided by different toolchains with +incompatible versioning schemes. Set this variable in a +:variable:`toolchain file <CMAKE_TOOLCHAIN_FILE>` so CMake can detect +the compiler and version correctly. If no toolset is specified, +``Standalone`` is assumed. + +Projects, that can be build with different architectures and/or toolsets, must +take :variable:`CMAKE_TASKING_TOOLSET` and +:variable:`CMAKE_<LANG>_COMPILER_ARCHITECTURE_ID` into account to qualify +:variable:`CMAKE_<LANG>_COMPILER_VERSION`. + +``TriCore`` + Compilers are provided by the TriCore toolset. + +``SmartCode`` + Compilers are provided by the SmartCode toolset. + +``Standalone`` + Compilers are provided by the standalone toolsets. + + .. note:: + + For the TriCore architecture, the compiler from the TriCore toolset is + selected as standalone compiler. |