|
|
@@ -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.
|
Brad King