diff options
Diffstat (limited to 'Help')
38 files changed, 423 insertions, 103 deletions
diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index 52536bb..f3df631 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -118,8 +118,35 @@ target using the commands: and then it is used as an argument to :command:`target_link_libraries` like any other target. -An interface library has no source files itself and is not included -as a target in the generated buildsystem. +An interface library created with the above signature has no source files +itself and is not included as a target in the generated buildsystem. + +Since CMake 3.19, an interface library target may be created with +source files: + +.. code-block:: cmake + + add_library(<name> INTERFACE [<source>...] [EXCLUDE_FROM_ALL]) + +Source files may be listed directly in the ``add_library`` call or added +later by calls to :command:`target_sources` with the ``PRIVATE`` or +``PUBLIC`` keywords. + +If an interface library has source files (i.e. the :prop_tgt:`SOURCES` +target property is set), it will appear in the generated buildsystem +as a build target much like a target defined by the +:command:`add_custom_target` command. It does not compile any sources, +but does contain build rules for custom commands created by the +:command:`add_custom_command` command. + +.. note:: + In most command signatures where the ``INTERFACE`` keyword appears, + the items listed after it only become part of that target's usage + requirements and are not part of the target's own settings. However, + in this signature of ``add_library``, the ``INTERFACE`` keyword refers + to the library type only. Sources listed after it in the ``add_library`` + call are ``PRIVATE`` to the interface library and do not appear in its + :prop_tgt:`INTERFACE_SOURCES` target property. Imported Libraries ^^^^^^^^^^^^^^^^^^ diff --git a/Help/command/add_test.rst b/Help/command/add_test.rst index a77ba37..2b4d082 100644 --- a/Help/command/add_test.rst +++ b/Help/command/add_test.rst @@ -10,8 +10,9 @@ Add a test to the project to be run by :manual:`ctest(1)`. [WORKING_DIRECTORY <dir>] [COMMAND_EXPAND_LISTS]) -Adds a test called ``<name>``. The test name may not contain spaces, -quotes, or other characters special in CMake syntax. The options are: +Adds a test called ``<name>``. The test name may contain arbitrary +characters, expressed as a :ref:`Quoted Argument` or :ref:`Bracket Argument` +if necessary. See policy :policy:`CMP0110`. The options are: ``COMMAND`` Specify the test command-line. If ``<command>`` specifies an diff --git a/Help/command/file.rst b/Help/command/file.rst index 2cf938b..953172b 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -449,7 +449,7 @@ modified. file(GENERATE OUTPUT output-file <INPUT input-file|CONTENT content> - [CONDITION expression]) + [CONDITION expression] [TARGET target]) Generate an output file for each build configuration supported by the current :manual:`CMake Generator <cmake-generators(7)>`. Evaluate @@ -479,6 +479,10 @@ from the input content to produce the output content. The options are: with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. See policy :policy:`CMP0070`. +``TARGET <target>`` + Specify target which to use when evaluating generator expressions. Enables + use of generator expressions requiring a target. + Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific ``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``. Generated files are modified and their timestamp updated on subsequent cmake diff --git a/Help/cpack_gen/wix.rst b/Help/cpack_gen/wix.rst index 7fb5a12..5b880ba 100644 --- a/Help/cpack_gen/wix.rst +++ b/Help/cpack_gen/wix.rst @@ -286,3 +286,11 @@ Windows using WiX. When unspecified CPack will try to locate a WiX Toolset installation via the ``WIX`` environment variable instead. + +.. variable:: CPACK_WIX_CUSTOM_XMLNS + + This variable provides a list of custom namespace declarations that are necessary + for using WiX extensions. Each declaration should be in the form name=url, where + name is the plain namespace without the usual xmlns: prefix and url is an unquoted + namespace url. A list of commonly known WiX schemata can be found here: + https://wixtoolset.org/documentation/manual/v3/xsd/ diff --git a/Help/dev/review.rst b/Help/dev/review.rst index f2a91c0..8326e70 100644 --- a/Help/dev/review.rst +++ b/Help/dev/review.rst @@ -264,6 +264,7 @@ fixed, it is preferable to link to the issue instead. If relevant, add the first release tag of CMake containing the commit after the ``<date>``, i.e., ``commit <shorthash> (<subject>, <date>, <tag>)``. +Or, use the output of ``git describe --contains <commit>`` as the ``<tag>``. Alternatively, the full commit ``<hash>`` may be used. diff --git a/Help/generator/Visual Studio 14 2015.rst b/Help/generator/Visual Studio 14 2015.rst index 401845d..5b319bb 100644 --- a/Help/generator/Visual Studio 14 2015.rst +++ b/Help/generator/Visual Studio 14 2015.rst @@ -45,3 +45,19 @@ via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. By default this generator uses the 32-bit variant even on a 64-bit host. .. include:: VS_TOOLSET_HOST_ARCH.txt + +.. _`Windows 10 SDK Maximum Version for VS 2015`: + +Windows 10 SDK Maximum Version for VS 2015 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Microsoft stated in a "Windows 10 October 2018 Update" blog post that Windows +10 SDK versions (15063, 16299, 17134, 17763) are not supported by VS 2015 and +are only supported by VS 2017 and later. Therefore by default CMake +automatically ignores Windows 10 SDKs beyond ``10.0.14393.0``. + +However, there are other recommendations for certain driver/Win32 builds that +indicate otherwise. A user can override this behavior by either setting the +:variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` to a false value +or setting the :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` to +the string value of the required maximum (e.g. ``10.0.15063.0``). diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index d8142a2..7008383 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -96,6 +96,9 @@ Apple Frameworks A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK` target property to create an macOS or iOS Framework Bundle. +A library with the ``FRAMEWORK`` target property should also set the +:prop_tgt:`FRAMEWORK_VERSION` target property. This property is typically +set to the value of "A" by macOS conventions. The ``MACOSX_FRAMEWORK_IDENTIFIER`` sets ``CFBundleIdentifier`` key and it uniquely identifies the bundle. @@ -104,7 +107,7 @@ and it uniquely identifies the bundle. add_library(MyFramework SHARED MyFramework.cpp) set_target_properties(MyFramework PROPERTIES FRAMEWORK TRUE - FRAMEWORK_VERSION A + FRAMEWORK_VERSION A # Version "A" is macOS convention MACOSX_FRAMEWORK_IDENTIFIER org.cmake.MyFramework ) @@ -115,7 +118,10 @@ Object Libraries The ``OBJECT`` library type defines a non-archival collection of object files resulting from compiling the given source files. The object files collection -may be used as source inputs to other targets: +may be used as source inputs to other targets by using the syntax +``$<TARGET_OBJECTS:name>``. This is a +:manual:`generator expression <cmake-generator-expressions(7)>` that can be +used to supply the ``OBJECT`` library content to other targets: .. code-block:: cmake @@ -373,8 +379,12 @@ position-independent-code, so a diagnostic is issued. The ``lib1`` and ``lib2`` requirements are not "compatible". One of them requires that consumers are built as position-independent-code, while the other requires that consumers are not built as position-independent-code. -Because ``exe2`` links to both and they are in conflict, a diagnostic is -issued. +Because ``exe2`` links to both and they are in conflict, a CMake error message +is issued:: + + CMake Error: The INTERFACE_POSITION_INDEPENDENT_CODE property of "lib2" does + not agree with the value of POSITION_INDEPENDENT_CODE already determined + for "exe2". To be "compatible", the :prop_tgt:`POSITION_INDEPENDENT_CODE` property, if set must be either the same, in a boolean sense, as the @@ -732,7 +742,7 @@ As the value of the :prop_tgt:`POSITION_INDEPENDENT_CODE` property of the ``exe1`` target is dependent on the linked libraries (``lib3``), and the edge of linking ``exe1`` is determined by the same :prop_tgt:`POSITION_INDEPENDENT_CODE` property, the dependency graph above -contains a cycle. :manual:`cmake(1)` issues a diagnostic in this case. +contains a cycle. :manual:`cmake(1)` issues an error message. .. _`Output Artifacts`: @@ -922,8 +932,8 @@ property from it: Interface Libraries ------------------- -An ``INTERFACE`` target has no :prop_tgt:`LOCATION` and is mutable, but is -otherwise similar to an :prop_tgt:`IMPORTED` target. +An ``INTERFACE`` library target does not compile sources and does not +produce a library artifact on disk, so it has no :prop_tgt:`LOCATION`. It may specify usage requirements such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, @@ -937,11 +947,22 @@ Only the ``INTERFACE`` modes of the :command:`target_include_directories`, :command:`target_sources`, and :command:`target_link_libraries` commands may be used with ``INTERFACE`` libraries. +Since CMake 3.19, an ``INTERFACE`` library target may optionally contain +source files. An interface library that contains source files will be +included as a build target in the generated buildsystem. It does not +compile sources, but may contain custom commands to generate other sources. +Additionally, IDEs will show the source files as part of the target for +interactive reading and editing. + A primary use-case for ``INTERFACE`` libraries is header-only libraries. .. code-block:: cmake - add_library(Eigen INTERFACE) + add_library(Eigen INTERFACE + src/eigen.h + src/vector.h + src/matrix.h + ) target_include_directories(Eigen INTERFACE $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src> $<INSTALL_INTERFACE:include/Eigen> @@ -975,25 +996,17 @@ This way, the build specification of ``exe1`` is expressed entirely as linked targets, and the complexity of compiler-specific flags is encapsulated in an ``INTERFACE`` library target. -The properties permitted to be set on or read from an ``INTERFACE`` library -are: - -* Properties matching ``INTERFACE_*`` -* Built-in properties matching ``COMPATIBLE_INTERFACE_*`` -* ``EXPORT_NAME`` -* ``EXPORT_PROPERTIES`` -* ``IMPORTED`` -* ``MANUALLY_ADDED_DEPENDENCIES`` -* ``NAME`` -* Properties matching ``IMPORTED_LIBNAME_*`` -* Properties matching ``MAP_IMPORTED_CONFIG_*`` - ``INTERFACE`` libraries may be installed and exported. Any content they refer to must be installed separately: .. code-block:: cmake - add_library(Eigen INTERFACE) + set(Eigen_headers + src/eigen.h + src/vector.h + src/matrix.h + ) + add_library(Eigen INTERFACE ${Eigen_headers}) target_include_directories(Eigen INTERFACE $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src> $<INSTALL_INTERFACE:include/Eigen> @@ -1003,9 +1016,6 @@ to must be installed separately: install(EXPORT eigenExport NAMESPACE Upstream:: DESTINATION lib/cmake/Eigen ) - install(FILES - ${CMAKE_CURRENT_SOURCE_DIR}/src/eigen.h - ${CMAKE_CURRENT_SOURCE_DIR}/src/vector.h - ${CMAKE_CURRENT_SOURCE_DIR}/src/matrix.h + install(FILES ${Eigen_headers} DESTINATION include/Eigen ) diff --git a/Help/manual/cmake-file-api.7.rst b/Help/manual/cmake-file-api.7.rst index 34edc56..6876e1c 100644 --- a/Help/manual/cmake-file-api.7.rst +++ b/Help/manual/cmake-file-api.7.rst @@ -650,7 +650,8 @@ with members: ``type`` A string specifying the type of the target. The value is one of ``EXECUTABLE``, ``STATIC_LIBRARY``, ``SHARED_LIBRARY``, - ``MODULE_LIBRARY``, ``OBJECT_LIBRARY``, or ``UTILITY``. + ``MODULE_LIBRARY``, ``OBJECT_LIBRARY``, ``INTERFACE_LIBRARY``, + or ``UTILITY``. ``backtrace`` Optional member that is present when a CMake language backtrace to diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 3ceb1df..ce8969b 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,12 +51,14 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used to determine whether to report an error on use of deprecated macros or functions. -Policies Introduced by CMake 3.18 +Policies Introduced by CMake 3.19 ================================= .. toctree:: :maxdepth: 1 + CMP0111: An imported target with a missing location fails during generation. </policy/CMP0111> + CMP0110: add_test() supports arbitrary characters in test names. </policy/CMP0110> CMP0109: find_program() requires permission to execute but not to read. </policy/CMP0109> Policies Introduced by CMake 3.18 diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index bdd2333..644e87b 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -308,6 +308,7 @@ Properties on Targets /prop_tgt/OBJCXX_EXTENSIONS /prop_tgt/OBJCXX_STANDARD /prop_tgt/OBJCXX_STANDARD_REQUIRED + /prop_tgt/OPTIMIZE_DEPENDENCIES /prop_tgt/OSX_ARCHITECTURES_CONFIG /prop_tgt/OSX_ARCHITECTURES /prop_tgt/OUTPUT_NAME_CONFIG diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 4515cc3..082e2d5 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -124,6 +124,7 @@ Variables that Provide Information /variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE /variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION + /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM /variable/CMAKE_XCODE_GENERATE_SCHEME /variable/CMAKE_XCODE_PLATFORM_TOOLSET /variable/PROJECT-NAME_BINARY_DIR @@ -158,6 +159,7 @@ Variables that Change Behavior /variable/CMAKE_AUTOMOC_RELAXED_MODE /variable/CMAKE_BACKWARDS_COMPATIBILITY /variable/CMAKE_BUILD_TYPE + /variable/CMAKE_CLANG_VFS_OVERLAY /variable/CMAKE_CODEBLOCKS_COMPILER_ID /variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES /variable/CMAKE_CODELITE_USE_TARGETS @@ -436,6 +438,7 @@ Variables that Control the Build /variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX /variable/CMAKE_NO_BUILTIN_CHRPATH /variable/CMAKE_NO_SYSTEM_FROM_IMPORTED + /variable/CMAKE_OPTIMIZE_DEPENDENCIES /variable/CMAKE_OSX_ARCHITECTURES /variable/CMAKE_OSX_DEPLOYMENT_TARGET /variable/CMAKE_OSX_SYSROOT diff --git a/Help/policy/CMP0110.rst b/Help/policy/CMP0110.rst new file mode 100644 index 0000000..bc198aa --- /dev/null +++ b/Help/policy/CMP0110.rst @@ -0,0 +1,24 @@ +CMP0110 +------- + +:command:`add_test` supports arbitrary characters in test names. + +:command:`add_test` can now (officially) create tests with whitespace and +other special characters in its name. Before CMake version 3.19 that was not +allowed, however, it was possible to work around this limitation by explicitly +putting escaped quotes arount the test's name in the ``add_test`` command. + +Although never officially supported several projects in the wild found and +implemented this workaround. However, the new change which officially allows +the ``add_test`` command to support whitespace and other special characters in +test names now breaks that workaround. In order for these projects to work +smoothly with newer CMake versions, this policy was introduced. + +The ``OLD`` behavior of this policy is to still prevent ``add_test`` from +handling whitespace and special characters properly (if not using the +mentioned workaround). The ``NEW`` behavior on the other hand allows names +with whitespace and special characters for tests created by ``add_test``. + +This policy was introduced in CMake version 3.19. CMake version |release| +warns when the policy is not set and uses ``OLD`` behavior. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. diff --git a/Help/policy/CMP0111.rst b/Help/policy/CMP0111.rst new file mode 100644 index 0000000..37e5ad5 --- /dev/null +++ b/Help/policy/CMP0111.rst @@ -0,0 +1,20 @@ +CMP0111 +------- + +.. versionadded:: 3.19 + +An imported target with a missing location fails during generation. + +Prior to this the location would be generated as ``<TARGET_NAME>-NOTFOUND``, +which would result in build failures. + +The ``OLD`` behavior of this policy is to generate the location of an imported +unknown, static or shared library target as ``<TARGET_NAME>-NOTFOUND`` if not +set. +The ``NEW`` behavior is to raise an error. + +This policy was introduced in CMake version 3.19. CMake version |release| +warns when the policy is not set and uses ``OLD`` behavior. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst index 9b53282..bac3274 100644 --- a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst @@ -13,8 +13,14 @@ The features listed here may be used with the :command:`target_compile_features` command. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. +The features known to this version of CMake are listed below. -The features known to this version of CMake are: +High level meta features indicating C++ standard support +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following meta features indicate general support for the associated +language standard. It reflects the language support claimed by the compiler, +but it does not necessarily imply complete conformance to that standard. ``cxx_std_98`` Compiler mode is at least C++ 98. @@ -31,10 +37,29 @@ The features known to this version of CMake are: ``cxx_std_20`` Compiler mode is at least C++ 20. -``cxx_aggregate_default_initializers`` - Aggregate default initializers, as defined in N3605_. - .. _N3605: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3605.html +Low level individual compile features +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For C++ 11 and C++ 14, compilers were sometimes slow to implement certain +language features. CMake provided some individual compile features to help +projects determine whether specific features were available. These individual +features are now less relevant and projects should generally prefer to use the +high level meta features instead. Individual compile features are not provided +for C++ 17 or later. + +See the :manual:`cmake-compile-features(7)` manual for further discussion of +the use of individual compile features. + +Individual features from C++ 98 +""""""""""""""""""""""""""""""" + +``cxx_template_template_parameters`` + Template template parameters, as defined in ``ISO/IEC 14882:1998``. + + +Individual features from C++ 11 +""""""""""""""""""""""""""""""" ``cxx_alias_templates`` Template aliases, as defined in N2258_. @@ -56,30 +81,16 @@ The features known to this version of CMake are: .. _N2761: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2761.pdf -``cxx_attribute_deprecated`` - ``[[deprecated]]`` attribute, as defined in N3760_. - - .. _N3760: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3760.html - ``cxx_auto_type`` Automatic type deduction, as defined in N1984_. .. _N1984: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1984.pdf -``cxx_binary_literals`` - Binary literals, as defined in N3472_. - - .. _N3472: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3472.pdf - ``cxx_constexpr`` Constant expressions, as defined in N2235_. .. _N2235: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2235.pdf -``cxx_contextual_conversions`` - Contextual conversions, as defined in N3323_. - - .. _N3323: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3323.pdf ``cxx_decltype_incomplete_return_types`` Decltype on incomplete return types, as defined in N3276_. @@ -91,11 +102,6 @@ The features known to this version of CMake are: .. _N2343: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2343.pdf -``cxx_decltype_auto`` - ``decltype(auto)`` semantics, as defined in N3638_. - - .. _N3638: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3638.html - ``cxx_default_function_template_args`` Default template arguments for function templates, as defined in DR226_ @@ -121,11 +127,6 @@ The features known to this version of CMake are: .. _N2346: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm -``cxx_digit_separators`` - Digit separators, as defined in N3781_. - - .. _N3781: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3781.pdf - ``cxx_enum_forward_declarations`` Enum forward declarations, as defined in N2764_. @@ -163,11 +164,6 @@ The features known to this version of CMake are: .. _N2672: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2672.htm -``cxx_generic_lambdas`` - Generic lambdas, as defined in N3649_. - - .. _N3649: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3649.html - ``cxx_inheriting_constructors`` Inheriting constructors, as defined in N2540_. @@ -183,11 +179,6 @@ The features known to this version of CMake are: .. _N2927: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2927.pdf -``cxx_lambda_init_captures`` - Initialized lambda captures, as defined in N3648_. - - .. _N3648: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3648.html - ``cxx_local_type_template_args`` Local and unnamed types as template arguments, as defined in N2657_. @@ -236,16 +227,6 @@ The features known to this version of CMake are: .. _N2439: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2439.htm -``cxx_relaxed_constexpr`` - Relaxed constexpr, as defined in N3652_. - - .. _N3652: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3652.html - -``cxx_return_type_deduction`` - Return type deduction on normal functions, as defined in N3386_. - - .. _N3386: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3386.html - ``cxx_right_angle_brackets`` Right angle bracket parsing, as defined in N1757_. @@ -301,11 +282,6 @@ The features known to this version of CMake are: .. _N2765: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2765.pdf -``cxx_variable_templates`` - Variable templates, as defined in N3651_. - - .. _N3651: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3651.pdf - ``cxx_variadic_macros`` Variadic macros, as defined in N1653_. @@ -316,5 +292,61 @@ The features known to this version of CMake are: .. _N2242: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2242.pdf -``cxx_template_template_parameters`` - Template template parameters, as defined in ``ISO/IEC 14882:1998``. + +Individual features from C++ 14 +""""""""""""""""""""""""""""""" + +``cxx_aggregate_default_initializers`` + Aggregate default initializers, as defined in N3605_. + + .. _N3605: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3605.html + +``cxx_attribute_deprecated`` + ``[[deprecated]]`` attribute, as defined in N3760_. + + .. _N3760: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3760.html + +``cxx_binary_literals`` + Binary literals, as defined in N3472_. + + .. _N3472: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3472.pdf + +``cxx_contextual_conversions`` + Contextual conversions, as defined in N3323_. + + .. _N3323: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3323.pdf + +``cxx_decltype_auto`` + ``decltype(auto)`` semantics, as defined in N3638_. + + .. _N3638: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3638.html + +``cxx_digit_separators`` + Digit separators, as defined in N3781_. + + .. _N3781: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3781.pdf + +``cxx_generic_lambdas`` + Generic lambdas, as defined in N3649_. + + .. _N3649: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3649.html + +``cxx_lambda_init_captures`` + Initialized lambda captures, as defined in N3648_. + + .. _N3648: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3648.html + +``cxx_relaxed_constexpr`` + Relaxed constexpr, as defined in N3652_. + + .. _N3652: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3652.html + +``cxx_return_type_deduction`` + Return type deduction on normal functions, as defined in N3386_. + + .. _N3386: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3386.html + +``cxx_variable_templates`` + Variable templates, as defined in N3651_. + + .. _N3651: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3651.pdf diff --git a/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst b/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst index 4f85c16..836d953 100644 --- a/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst +++ b/Help/prop_tgt/AUTOMOC_PATH_PREFIX.rst @@ -15,7 +15,7 @@ the ``-p`` path prefix option. ``moc`` usually generates a relative include path in that case. :prop_tgt:`AUTOMOC_PATH_PREFIX` is initialized from the variable -:variable:`CMAKE_AUTOMOC_PATH_PREFIX`, which is ``ON`` by default. +:variable:`CMAKE_AUTOMOC_PATH_PREFIX`, which is ``OFF`` by default. See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. @@ -26,8 +26,7 @@ Reproducible builds For reproducible builds it is recommended to keep headers that are ``moc`` compiled in one of the target :command:`include directories <target_include_directories>` and set -:prop_tgt:`AUTOMOC_PATH_PREFIX` to ``ON`` (which is the default). This ensures -that: +:prop_tgt:`AUTOMOC_PATH_PREFIX` to ``ON``. This ensures that: - ``moc`` output files are identical on different build setups, - ``moc`` output files will compile correctly when the source and/or diff --git a/Help/prop_tgt/EXPORT_PROPERTIES.rst b/Help/prop_tgt/EXPORT_PROPERTIES.rst index 34c054f..2d54f8b 100644 --- a/Help/prop_tgt/EXPORT_PROPERTIES.rst +++ b/Help/prop_tgt/EXPORT_PROPERTIES.rst @@ -14,3 +14,11 @@ Properties starting with ``INTERFACE_`` or ``IMPORTED_`` are not allowed as they are reserved for internal CMake use. Properties containing generator expressions are also not allowed. + +.. note:: + + Since CMake 3.19, :ref:`Interface Libraries` may have arbitrary + target properties. If a project exports an interface library + with custom properties, the resulting package may not work with + dependents configured by older versions of CMake that reject the + custom properties. diff --git a/Help/prop_tgt/Fortran_MODULE_DIRECTORY.rst b/Help/prop_tgt/Fortran_MODULE_DIRECTORY.rst index e061863..84029e4 100644 --- a/Help/prop_tgt/Fortran_MODULE_DIRECTORY.rst +++ b/Help/prop_tgt/Fortran_MODULE_DIRECTORY.rst @@ -11,6 +11,14 @@ corresponding to the target's source directory. If the variable :variable:`CMAKE_Fortran_MODULE_DIRECTORY` is set when a target is created its value is used to initialize this property. +When using one of the :ref:`Visual Studio Generators` with the Intel Fortran +plugin installed in Visual Studio, a subdirectory named after the +configuration will be appended to the path where modules are created. +For example, if ``Fortran_MODULE_DIRECTORY`` is set to ``C:/some/path``, +modules will end up in ``C:/some/path/Debug`` (or +``C:/some/path/Release`` etc.) when an Intel Fortran ``.vfproj`` file is +generated, and in ``C:/some/path`` when any other generator is used. + Note that some compilers will automatically search the module output directory for modules USEd during compilation but others will not. If your sources USE modules their location must be specified by diff --git a/Help/prop_tgt/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM.rst b/Help/prop_tgt/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM.rst index dc73807..f7e366a 100644 --- a/Help/prop_tgt/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM.rst +++ b/Help/prop_tgt/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM.rst @@ -1,15 +1,15 @@ IMPLICIT_DEPENDS_INCLUDE_TRANSFORM ---------------------------------- -Specify #include line transforms for dependencies in a target. +Specify ``#include`` line transforms for dependencies in a target. -This property specifies rules to transform macro-like #include lines +This property specifies rules to transform macro-like ``#include`` lines during implicit dependency scanning of C and C++ source files. The list of rules must be semicolon-separated with each entry of the form -"A_MACRO(%)=value-with-%" (the % must be literal). During dependency -scanning occurrences of A_MACRO(...) on #include lines will be +``A_MACRO(%)=value-with-%`` (the ``%`` must be literal). During dependency +scanning occurrences of ``A_MACRO(...)`` on ``#include`` lines will be replaced by the value given with the macro argument substituted for -'%'. For example, the entry +``%``. For example, the entry :: diff --git a/Help/prop_tgt/IOS_INSTALL_COMBINED.rst b/Help/prop_tgt/IOS_INSTALL_COMBINED.rst index 23a86e6..92d60dc 100644 --- a/Help/prop_tgt/IOS_INSTALL_COMBINED.rst +++ b/Help/prop_tgt/IOS_INSTALL_COMBINED.rst @@ -10,4 +10,10 @@ either be built with the device SDK or the simulator SDK depending on the SDK set. But if this property is set to true then the target will at install time also be built for the corresponding SDK and combined into one library. +.. note:: + + If a selected architecture is available for both: device SDK and simulator + SDK it will be built for the SDK selected by :variable:`CMAKE_OSX_SYSROOT` + and removed from the corresponding SDK. + This feature requires at least Xcode version 6. diff --git a/Help/prop_tgt/OPTIMIZE_DEPENDENCIES.rst b/Help/prop_tgt/OPTIMIZE_DEPENDENCIES.rst new file mode 100644 index 0000000..533cf6a --- /dev/null +++ b/Help/prop_tgt/OPTIMIZE_DEPENDENCIES.rst @@ -0,0 +1,38 @@ +OPTIMIZE_DEPENDENCIES +--------------------- + +Activates dependency optimization of static and object libraries. + +When this property is set to true, some dependencies for a static or object +library may be removed at generation time if they are not necessary to build +the library, since static and object libraries don't actually link against +anything. + +If a static or object library has dependency optimization enabled, it first +discards all dependencies. Then, it looks through all of the direct and +indirect dependencies that it initially had, and adds them back if they meet +any of the following criteria: + +* The dependency was added to the library by :command:`add_dependencies`. +* The dependency was added to the library through a source file in the library + generated by a custom command that uses the dependency. +* The dependency has any ``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` custom + commands associated with it. +* The dependency contains any source files that were generated by a custom + command. +* The dependency contains any languages which produce side effects that are + relevant to the library. Currently, all languages except C, C++, Objective-C, + Objective-C++, assembly, and CUDA are assumed to produce side effects. + However, side effects from one language are assumed not to be relevant to + another (for example, a Fortran library is assumed to not have any side + effects that are relevant for a Swift library.) + +As an example, assume you have a static Fortran library which depends on a +static C library, which in turn depends on a static Fortran library. The +top-level Fortran library has optimization enabled, but the middle C library +does not. If you build the top Fortran library, the bottom Fortran library will +also build, but not the middle C library, since the C library does not have any +side effects that are relevant for the Fortran library. However, if you build +the middle C library, the bottom Fortran library will also build, even though +it does not have any side effects that are relevant to the C library, since the +C library does not have optimization enabled. diff --git a/Help/prop_tgt/WIN32_EXECUTABLE.rst b/Help/prop_tgt/WIN32_EXECUTABLE.rst index 060d166..eac28ae 100644 --- a/Help/prop_tgt/WIN32_EXECUTABLE.rst +++ b/Help/prop_tgt/WIN32_EXECUTABLE.rst @@ -11,3 +11,7 @@ configure use of the Microsoft Foundation Classes (MFC) for WinMain executables. This property is initialized by the value of the :variable:`CMAKE_WIN32_EXECUTABLE` variable if it is set when a target is created. + +This property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`, except if the +target is managed (contains C# code.) diff --git a/Help/release/3.18.rst b/Help/release/3.18.rst index ba80d2b..099e9b5 100644 --- a/Help/release/3.18.rst +++ b/Help/release/3.18.rst @@ -264,6 +264,11 @@ Other * :manual:`ccmake(1)` learned to read a :envvar:`CCMAKE_COLORS` environment variable to customize colors. +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + is now aware of the availability of C11 features in MSVC 19.27 and 19.28, + including support for the ``c_restrict``, ``c_static_assert`` features and + the ``-std:c11`` flag. + Deprecated and Removed Features =============================== @@ -339,3 +344,20 @@ Changes made since CMake 3.18.0 include the following. that were using manual quoting or escaping to work around the prior limitation. This fix has been reverted in 3.18.1, but may be re-introduced in future versions of CMake with a policy for compatibility. + +3.18.2 +------ + +* The default value of :variable:`CMAKE_AUTOMOC_PATH_PREFIX` was changed to + ``OFF`` because this feature can break existing projects that have + identically named header files in different include directories. + This restores compatibility with behavior of CMake 3.15 and below. + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + was updated for MSVC 19.27 as mentioned above (``c_restrict``). + +3.18.3 +------ + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + was updated for MSVC 19.28 as mentioned above (``c_static_assert``). diff --git a/Help/release/dev/add_test-special-chars-in-name.rst b/Help/release/dev/add_test-special-chars-in-name.rst new file mode 100644 index 0000000..5bb9a23 --- /dev/null +++ b/Help/release/dev/add_test-special-chars-in-name.rst @@ -0,0 +1,6 @@ +add_test-special-chars-in-name +------------------------------ + +* The :command:`add_test` command now (officially) supports whitespace and + other special characters in the name for the test it creates. + See policy :policy:`CMP0110`. diff --git a/Help/release/dev/asm-osx-architectures.rst b/Help/release/dev/asm-osx-architectures.rst new file mode 100644 index 0000000..d8d0660 --- /dev/null +++ b/Help/release/dev/asm-osx-architectures.rst @@ -0,0 +1,5 @@ +asm-osx-architectures +--------------------- + +* The :prop_tgt:`OSX_ARCHITECTURES` target property is now respected for the + ``ASM`` language. diff --git a/Help/release/dev/build-interface-targets.rst b/Help/release/dev/build-interface-targets.rst new file mode 100644 index 0000000..37bded4 --- /dev/null +++ b/Help/release/dev/build-interface-targets.rst @@ -0,0 +1,6 @@ +build-interface-targets +----------------------- + +* :ref:`Interface Libraries` may now have source files added via + :command:`add_library` or :command:`target_sources`. Those + with sources will be generated as part of the build system. diff --git a/Help/release/dev/clang-cl-vfs.rst b/Help/release/dev/clang-cl-vfs.rst new file mode 100644 index 0000000..40b19ef --- /dev/null +++ b/Help/release/dev/clang-cl-vfs.rst @@ -0,0 +1,6 @@ +clang-cl-vfs +------------ + +* A :variable:`CMAKE_CLANG_VFS_OVERLAY` variable was added to tell + Clang to use a VFS overlay to support the Windows SDK when + cross-compiling from hosts with case-sensitive filesystems. diff --git a/Help/release/dev/cpack-wix-custom-xmlns.rst b/Help/release/dev/cpack-wix-custom-xmlns.rst new file mode 100644 index 0000000..84934cb --- /dev/null +++ b/Help/release/dev/cpack-wix-custom-xmlns.rst @@ -0,0 +1,5 @@ +cpack-wix-custom-xmlns +---------------------- + +* The :cpack_gen:`CPack WIX Generator` gained a + :variable:`CPACK_WIX_CUSTOM_XMLNS` option to specify custom XML namespaces. diff --git a/Help/release/dev/file-generate-target.rst b/Help/release/dev/file-generate-target.rst new file mode 100644 index 0000000..09fb460 --- /dev/null +++ b/Help/release/dev/file-generate-target.rst @@ -0,0 +1,5 @@ +file-generate-target +-------------------- + +* The :command:`file(GENERATE)` command gained a new ``TARGET`` keyword to + support resolving target-dependent generator expressions. diff --git a/Help/release/dev/imported-target-location-required.rst b/Help/release/dev/imported-target-location-required.rst new file mode 100644 index 0000000..3625242 --- /dev/null +++ b/Help/release/dev/imported-target-location-required.rst @@ -0,0 +1,5 @@ +imported-target-location-required +--------------------------------- + +* An imported target with a missing location now fails during generation if the + location is used. See policy :policy:`CMP0111`. diff --git a/Help/release/dev/optimize-link-dependencies.rst b/Help/release/dev/optimize-link-dependencies.rst new file mode 100644 index 0000000..cfda826 --- /dev/null +++ b/Help/release/dev/optimize-link-dependencies.rst @@ -0,0 +1,7 @@ +optimize-link-dependencies +-------------------------- + +* A new target property, :prop_tgt:`OPTIMIZE_DEPENDENCIES`, was added to + avoid unnecessarily building dependencies for a static library. +* A new variable, :variable:`CMAKE_OPTIMIZE_DEPENDENCIES`, was added to + initialize the :prop_tgt:`OPTIMIZE_DEPENDENCIES` target property. diff --git a/Help/release/dev/vs-win-sdk-custom-max.rst b/Help/release/dev/vs-win-sdk-custom-max.rst new file mode 100644 index 0000000..bd19fc8 --- /dev/null +++ b/Help/release/dev/vs-win-sdk-custom-max.rst @@ -0,0 +1,6 @@ +vs-win-sdk-custom-max +--------------------- + +* A :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` variable + was added to tell the :ref:`Visual Studio Generators` what maximumm + version of the Windows SDK to choose. diff --git a/Help/release/dev/win32-executable-genex.rst b/Help/release/dev/win32-executable-genex.rst new file mode 100644 index 0000000..f03203d --- /dev/null +++ b/Help/release/dev/win32-executable-genex.rst @@ -0,0 +1,5 @@ +win32-executable-genex +---------------------- + +* The :prop_tgt:`WIN32_EXECUTABLE` target property now supports + :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/variable/CMAKE_AUTOMOC_PATH_PREFIX.rst b/Help/variable/CMAKE_AUTOMOC_PATH_PREFIX.rst index 07a6cc8..42f48b4 100644 --- a/Help/variable/CMAKE_AUTOMOC_PATH_PREFIX.rst +++ b/Help/variable/CMAKE_AUTOMOC_PATH_PREFIX.rst @@ -10,4 +10,4 @@ This variable is used to initialize the :prop_tgt:`AUTOMOC_PATH_PREFIX` property on all the targets. See that target property for additional information. -The default value is ``ON``. +The default value is ``OFF``. diff --git a/Help/variable/CMAKE_CLANG_VFS_OVERLAY.rst b/Help/variable/CMAKE_CLANG_VFS_OVERLAY.rst new file mode 100644 index 0000000..56ac328 --- /dev/null +++ b/Help/variable/CMAKE_CLANG_VFS_OVERLAY.rst @@ -0,0 +1,9 @@ +CMAKE_CLANG_VFS_OVERLAY +----------------------- + +.. versionadded:: 3.19 + +When cross compiling for windows with clang-cl, this variable can be an +absolute path pointing to a clang virtual file system yaml file, which +will enable clang-cl to resolve windows header names on a case sensitive +file system. diff --git a/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst index 07342b5..d5fcb7d 100644 --- a/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst +++ b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst @@ -3,9 +3,9 @@ CMAKE_CUDA_HOST_COMPILER .. versionadded:: 3.10 -When :variable:`CMAKE_CUDA_COMPILER <CMAKE_<LANG>_COMPILER>` is set to -NVIDIA ``nvcc``, ``CMAKE_CUDA_HOST_COMPILER`` selects the compiler -executable to use when compiling host code for ``CUDA`` language files. +When :variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` is +``NVIDIA``, ``CMAKE_CUDA_HOST_COMPILER`` selects the compiler executable to use +when compiling host code for ``CUDA`` language files. This maps to the ``nvcc -ccbin`` option. The ``CMAKE_CUDA_HOST_COMPILER`` variable may be set explicitly before CUDA is @@ -20,6 +20,6 @@ is read-only and changes to it are undefined behavior. .. note:: Since ``CMAKE_CUDA_HOST_COMPILER`` is meaningful only when the - ``CMAKE_CUDA_COMPILER`` is ``nvcc``, it does not make sense to - set ``CMAKE_CUDA_HOST_COMPILER`` explicitly without also setting - ``CMAKE_CUDA_COMPILER`` explicitly to be sure it is ``nvcc``. + :variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` is ``NVIDIA``, + it does not make sense to set ``CMAKE_CUDA_HOST_COMPILER`` without also + setting ``CMAKE_CUDA_COMPILER`` to NVCC. diff --git a/Help/variable/CMAKE_OPTIMIZE_DEPENDENCIES.rst b/Help/variable/CMAKE_OPTIMIZE_DEPENDENCIES.rst new file mode 100644 index 0000000..eed352a --- /dev/null +++ b/Help/variable/CMAKE_OPTIMIZE_DEPENDENCIES.rst @@ -0,0 +1,4 @@ +CMAKE_OPTIMIZE_DEPENDENCIES +--------------------------- + +Initializes the :prop_tgt:`OPTIMIZE_DEPENDENCIES` target property. diff --git a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst index cb55bc2..eb71049 100644 --- a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst +++ b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst @@ -17,3 +17,5 @@ One may set a ``CMAKE_WINDOWS_KITS_10_DIR`` *environment variable* to an absolute path to tell CMake to look for Windows 10 SDKs in a custom location. The specified directory is expected to contain ``Include/10.0.*`` directories. + +See also :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM`. diff --git a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.rst b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.rst new file mode 100644 index 0000000..591ea91 --- /dev/null +++ b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.rst @@ -0,0 +1,14 @@ +CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM +------------------------------------------------ + +.. versionadded:: 3.19 + +Override the :ref:`Windows 10 SDK Maximum Version for VS 2015`. + +The :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` variable may +be set to a false value (e.g. ``OFF``, ``FALSE``, or ``0``) or the SDK version +to use as the maximum (e.g. ``10.0.14393.0``). If unset, the default depends +on which version of Visual Studio is targeted by the current generator. + +This can be used in conjunction with :variable:`CMAKE_SYSTEM_VERSION`, which +CMake uses to select :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION`. |