diff options
Diffstat (limited to 'Help/release/3.21.rst')
| -rw-r--r-- | Help/release/3.21.rst | 291 |
1 files changed, 291 insertions, 0 deletions
diff --git a/Help/release/3.21.rst b/Help/release/3.21.rst new file mode 100644 index 0000000..04354db --- /dev/null +++ b/Help/release/3.21.rst @@ -0,0 +1,291 @@ +CMake 3.21 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.20 include the following. + +New Features +============ + +Presets +------- + +* :manual:`cmake-presets(7)` gained support for specifying the install prefix + in a configure preset. + +* :manual:`cmake-presets(7)` gained support for conditional enabling of presets. + +* :manual:`cmake-presets(7)` gained support for a ``${hostSystemName}`` macro. + +* :manual:`cmake-presets(7)` gained support for omitting the ``generator`` and + ``binaryDir`` fields. + +Generators +---------- + +* The :ref:`Makefile Generators` and the :generator:`Ninja` generator + learned to add linker launcher tools along with the linker for ``C``, + ``CXX``, ``OBJC``, and ``OBJCXX`` languages. + See the :variable:`CMAKE_<LANG>_LINKER_LAUNCHER` variable + and :prop_tgt:`<LANG>_LINKER_LAUNCHER` target property for details. + +Languages +--------- + +* CMake learned to support ``HIP`` as a first-class language that can be + enabled via the :command:`project` and :command:`enable_language` commands. + +* :prop_tgt:`C_STANDARD`, :prop_tgt:`OBJC_STANDARD`, and the + :manual:`Compile Features <cmake-compile-features(7)>` functionality gained + support for C17 and C23. + +* Source file extensions ``.ixx`` and ``.cppm`` are now treated as C++. + +Command-Line +------------ + +* :manual:`cmake(1)` gained the ``--install-prefix <dir>`` + command-line option to specify the location of the install prefix. + +* :manual:`cmake(1)` gained the ``--toolchain <path/to/file>`` + command-line option to specify a toolchain file. + +* :manual:`cmake(1)` ``-E capabilities`` output now contains for each + generator a ``supportedPlatforms`` field listing platforms known to + be supported in :variable:`CMAKE_GENERATOR_PLATFORM`. + +* Messages printed to a terminal now may be colored by message type. + +Compilers +--------- + +* The Fujitsu compiler is now supported using compiler id ``Fujitsu`` + in traditional (``Trad``) mode, and compiler id ``FujitsuClang`` + in ``Clang`` mode. + +Platforms +--------- + +* CMake now supports the MSYS runtime environment, much like CYGWIN. + +File-Based API +-------------- + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field + has been updated to 2.3. + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 gained a + new "directory" object containing directory-level information. + This includes a list of installers generated by the :command:`install` + command. + +Commands +-------- + +* The :command:`add_custom_command` command ``DEPFILE`` option: + + * may now use + :manual:`generator expressions <cmake-generator-expressions(7)>`, + + * is now supported by :ref:`Visual Studio Generators` for VS 2012 + and above, and + + * is now supported by the :generator:`Xcode` generator. + +* The :command:`add_custom_command(TARGET)` command + (for :ref:`Build Events <add_custom_command(TARGET)>`) + gained support for resolving target-dependent generator expressions. + +* The :command:`build_command` command gained a ``PARALLEL_LEVEL`` option. + +* The :command:`file(COPY_FILE)` command was added to copy a single file. + +* The :command:`file(GET_RUNTIME_DEPENDENCIES)` command gained new + ``POST_INCLUDE_FILES`` and ``POST_EXCLUDE_FILES`` arguments. + +* The :command:`file(REAL_PATH)` command gained the option ``EXPAND_TILDE`` to + replace any leading tilde with the path to the user's home directory. + +* The :command:`file(RENAME)` command learned to optionally capture + failure in a result variable. It also gained a ``NO_REPLACE`` + option to fail if the destination exists. + +* The :command:`install` command gained a new ``IMPORTED_RUNTIME_ARTIFACTS`` + mode, which can be used to install the runtime artifacts of imported targets. + +* The :command:`install` command gained a new ``RUNTIME_DEPENDENCY_SET`` mode, + which can be used to install runtime dependencies using + :command:`file(GET_RUNTIME_DEPENDENCIES)`. + +* The :command:`install(TARGETS)` command gained new ``RUNTIME_DEPENDENCIES`` + and ``RUNTIME_DEPENDENCY_SET`` arguments, which can be used to install + runtime dependencies using :command:`file(GET_RUNTIME_DEPENDENCIES)`. + +* The :command:`install(SCRIPT|CODE)` command + supports a new option ``ALL_COMPONENTS`` which allows + the corresponding code to run for every component of + a per component installation. + +* The :command:`project` command now sets variables + :variable:`PROJECT_IS_TOP_LEVEL` and :variable:`<PROJECT-NAME>_IS_TOP_LEVEL` + to indicate whether it was called in a top-level ``CMakeLists.txt`` file. + +Variables +--------- + +* The :envvar:`CMAKE_TOOLCHAIN_FILE` environment variable was added to + provide a default value for the :variable:`CMAKE_TOOLCHAIN_FILE` variable. + +Properties +---------- + +* The :prop_dir:`IMPORTED_TARGETS` directory property was added to + get a list of :ref:`Imported Targets` created in the current + directory. + +* The :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS <XCODE_EMBED_<type>>` target property + was added to tell the :generator:`Xcode` generator to embed app extensions + such as iMessage sticker packs. + Aspects of the embedding can be customized with the + :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_PATH <XCODE_EMBED_<type>>`, + :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_CODE_SIGN_ON_COPY <XCODE_EMBED_<type>_CODE_SIGN_ON_COPY>` and + :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPY <XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY>` + properties. + +Modules +------- + +* The :module:`FindBLAS` and :module:`FindLAPACK` modules learned to support + the serial ``Fujitsu_SSL2`` and parallel ``Fujitsu_SSL2BLAMP`` libraries. + +* The :module:`FindDevIL` module now provides imported targets. + +* The :module:`FindIconv` module now has version support. + +* The :module:`FindIntl` module now has version support. + +* The :module:`FindMPI` module learned to support ``Fujitsu`` and + ``FujitsuClang`` in both host and cross compiling modes. + +* The :module:`FindMsys` module was added to find MSYS installations. + Like :module:`FindCygwin`, it is used automatically by some other + find modules to locate UNIX-style tools on Windows. + +* The :module:`FindOpenMP` module learned to support ``Fujitsu`` and + ``FujitsuClang``. + +* The :module:`FindVulkan` module gained imported targets + ``Vulkan::Headers`` and ``Vulkan::glslangValidator``. + +* The :module:`UseJava` module command ``add_jar`` gained a ``RESOURCES`` + option to allow explicit naming of resources with non-optional namespace. + +* The :module:`UseSWIG` module use now standard library naming conventions + for the ``CSharp`` language. See policy :policy:`CMP0122`. + +* The :module:`UseSWIG` module now supports using the ``swig`` tool to + generate implicit dependencies with the :generator:`Xcode` generator. + +Generator Expressions +--------------------- + +* A new :genex:`TARGET_RUNTIME_DLLS` generator expression was added. + +CTest +----- + +* :manual:`ctest(1)` gained documentation for its ability to capture + :ref:`Additional Test Measurements`. + +* :manual:`ctest(1)` learned to recognize files attached to a test at run time. + Previously it was only possible to attach files to tests at configure time + by using the :prop_test:`ATTACHED_FILES` or + :prop_test:`ATTACHED_FILES_ON_FAIL` test properties. + See :ref:`Additional Test Measurements` for more information. + +* :manual:`ctest(1)` gained a ``--output-junit`` option to write test results + to a JUnit XML file. + +* The :command:`ctest_build` command gained a ``PARALLEL_LEVEL`` option. + +CPack +----- + +* The :cpack_gen:`CPack DragNDrop Generator` gained option + :variable:`CPACK_DMG_FILESYSTEM` to control the ``.dmg`` filesystem. + +* The :cpack_gen:`CPack IFW Generator` now supports hyphens in names + given to :command:`cpack_ifw_configure_component` or + :command:`cpack_ifw_configure_component_group` as ``DEPENDS`` or + ``DEPENDENCIES`` arguments. This requires QtIFW 3.1 or later. + +* The :cpack_gen:`CPack NSIS Generator` gained a new + :variable:`CPACK_NSIS_EXECUTABLE` variable to specify the ``makensis`` + executable to use instead of the default one. + +* The :variable:`CPACK_CUSTOM_INSTALL_VARIABLES` variable was added to set + variables in ``cmake_install.cmake`` script invocations made by CPack. + +Deprecated and Removed Features +=============================== + +* Undocumented :variable:`CMAKE_SYSTEM_NAME` version-stripping behavior has + been removed entirely. If it is set by a ``-D`` flag or by a + :manual:`toolchain file <cmake-toolchains(7)>`, it is left unaltered, + even if it still contains a version number. + Similar :variable:`CMAKE_HOST_SYSTEM_NAME` version-stripping behavior, + also undocumented, has been moved earlier, before :command:`project` or + :command:`enable_language` is called. + +* ``ARMClang`` cpu/arch compile and link flags are no longer added + automatically based on the :variable:`CMAKE_SYSTEM_PROCESSOR` + variable or the undocumented ``CMAKE_SYSTEM_ARCH`` variable. + They must be specified explicitly. See policy :policy:`CMP0123`. + +Other Changes +============= + +* The :command:`find_file`, :command:`find_path`, :command:`find_program`, + and :command:`find_library` commands handle cache variables in the same way + regardless how they are defined. See policy :policy:`CMP0125` for details. + +* The :command:`find_file`, :command:`find_path`, :command:`find_program`, + and :command:`find_library` commands gained the option ``NO_CACHE`` to store + find result in normal variable. + +* The :command:`foreach` command now isolates loop variables in the loop scope. + See policy :policy:`CMP0124` for details. + +* The :command:`list` command's ``GET``, ``INSERT``, ``SUBLIST``, and + ``REMOVE_AT`` subcommands now error with invalid (i.e., non-integer) values + are given as any of their index arguments based on the setting of policy + :policy:`CMP0121`. + +* The :command:`set(CACHE)` command no longer removes a normal variable + of the same name, if any. See policy :policy:`CMP0126`. + +* :command:`target_link_libraries` calls referencing object libraries + via the :genex:`TARGET_OBJECTS` generator expression now place the + object files before all libraries on the link line, regardless of + their specified order. See documentation on + :ref:`Linking Object Libraries via \$\<TARGET_OBJECTS\>` for details. + +* The :ref:`Ninja Generators` now pass source files and include directories + to the compiler using absolute paths. This makes diagnostic messages and + debug symbols more consistent, and matches the :ref:`Makefile Generators`. + +* The :generator:`NMake Makefiles` generator now encodes the generated + makefiles as UTF-8 with a BOM when using ``nmake`` from VS 9 or above. + +* The :ref:`Visual Studio Generators` for VS 2010 and above now place + per-source preprocessor definitions after target-wide preprocssor + definitions. This makes VS consistent with the :ref:`Ninja Generators` + and the :ref:`Makefile Generators`. + +* The precompiled binaries provided on + `cmake.org <https://cmake.org/download/>`_ now support + ``liblzma`` multi-threading. See the :variable:`CPACK_THREADS` and + :variable:`CPACK_ARCHIVE_THREADS` variables. |