CMake 3.16 Release Notes¶
Contents
Changes made since CMake 3.15 include the following.
New Features¶
Languages¶
CMake learned to support the Objective C (
OBJC) and Objective C++ (OBJCXX) languages. They may be enabled via theproject()andenable_language()commands. WhenOBJCorOBJCXXis enabled, source files with the.mor.mm, respectively, will be compiled as Objective C or C++. Otherwise they will be treated as plain C++ sources as they were before.
Compilers¶
The
Clangcompiler is now supported onSolaris.
Platforms¶
On AIX, executables using the
ENABLE_EXPORTStarget property now produce a linker import file with a.impextension in addition to the executable file. Plugins (created viaadd_library()with theMODULEoption) that usetarget_link_libraries()to link to the executable for its symbols are now linked using the import file. Theinstall(TARGETS)command now installs the import file as anARCHIVEartifact.On AIX, runtime linking is no longer enabled by default. CMake provides the linker enough information to resolve all symbols up front. One may manually enable runtime linking for shared libraries and/or loadable modules by adding
-Wl,-Gto their link flags (e.g. in theCMAKE_SHARED_LINKER_FLAGSorCMAKE_MODULE_LINKER_FLAGSvariable). One may manually enable runtime linking for executables by adding-Wl,-brtlto their link flags (e.g. in theCMAKE_EXE_LINKER_FLAGSvariable).
Command-Line¶
cmake(1)-Enow supportstrueandfalsecommands, which do nothing while returning exit codes of 0 and 1, respectively.cmake(1)gained a--trace-redirect=<file>command line option that can be used to redirect--traceoutput to a file instead ofstderr.The
cmake(1)--loglevelcommand line option has been renamed to--log-levelto make it consistent with the naming of other command line options. The--logleveloption is still supported to preserve backward compatibility.
Commands¶
The
add_test()command learned the optionCOMMAND_EXPAND_LISTSwhich causes lists in theCOMMANDargument to be expanded, including lists created by generator expressions.The
file()command learned a new sub-command,GET_RUNTIME_DEPENDENCIES, which allows you to recursively get the list of libraries linked by an executable or library. This sub-command is intended as a replacement forGetPrerequisites.The
find_file(),find_library(),find_path(),find_package(), andfind_program()commands have learned to check the following variables to control the default behavior for groups of search locations:CMAKE_FIND_USE_PACKAGE_ROOT_PATH- Controls the default behavior of searching the<PackageName>_ROOTvariables.CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH- Controls the default behavior of searching the CMake-specific environment variables.CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH- Controls the default behavior of searching the standard system environment variables.CMAKE_FIND_USE_CMAKE_PATH- Controls the default behavior of searching the CMake-specific cache variables.CMAKE_FIND_USE_CMAKE_SYSTEM_PATH- Controls the default behavior of searching the platform-specific CMake variables.
The
find_package()command has learned to check theCMAKE_FIND_USE_PACKAGE_REGISTRYvariable to control the default behavior of searching the CMake user package registry and to check theCMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRYvariable to control the default behavior of searching the CMake system package registry.The
message()command learned indentation control with the newCMAKE_MESSAGE_INDENTvariable.The
target_precompile_headers()command was added to specify a list of headers to precompile for faster compilation times.
Variables¶
The
CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLSvariable has been introduced to optionally initialize theCUDA_RESOLVE_DEVICE_SYMBOLStarget property.The
CMAKE_ECLIPSE_RESOURCE_ENCODINGvariable was added to specify the resource encoding for the theEclipse CDT4extra generator.The
CMAKE_UNITY_BUILDvariable was added to initialize theUNITY_BUILDtarget property to tell generators to batch include source files for faster compilation times.
Properties¶
The
BUILD_RPATHandINSTALL_RPATHtarget properties now supportgenerator expressions.The
INSTALL_REMOVE_ENVIRONMENT_RPATHtarget property was added to remove compiler-definedRPATHentries from a target. This property is initialized by theCMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATHvariable.The
PRECOMPILE_HEADERStarget property was added to specify a list of headers to precompile for faster compilation times. Set it using thetarget_precompile_headers()command.The
UNITY_BUILDtarget property was added to tell generators to batch include source files for faster compilation times.The
VS_CONFIGURATION_TYPEtarget property now supportsgenerator expressions.The
VS_DPI_AWAREtarget property was added to tell Visual Studio Generators to set theEnableDpiAwarenessproperty in.vcxprojfiles.The
XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONINGtarget property was added to tell theXcodegenerator to set the value of theAllow debugging when using document Versions Browserschema option.
Modules¶
The
FindDoxygenmoduledoxygen_add_docs()command gained a newUSE_STAMP_FILEoption. When this option present, the custom target created by the command will only re-run Doxygen if any of the source files have changed since the last successful run.The
FindGnuTLSmodule now provides an imported target.The
FindPackageHandleStandardArgsmodulefind_package_handle_standard_args()command gained a newREASON_FAILURE_MESSAGEoption to specify a message giving the reason for the failure.The
FindPkgConfigmodulepkg_search_module()macro now defines a<prefix>_MODULE_NAMEresult variable containing the first matching module name.The
FindPython3andFindPythonmodules gained options to control whichABIswill be searched.The
FindPython3,FindPython2, andFindPythonmodules now support direct specification of artifacts via cache entries.
Autogen¶
When using
AUTOMOC, the newCMAKE_AUTOMOC_PATH_PREFIXvariable orAUTOMOC_PATH_PREFIXtarget property may be enabled to generate the-ppath prefix option formoc. This ensures thatmocoutput files are identical on different build setups (given, that the headers compiled bymocare in aninclude directory). Also it ensures thatmocoutput files will compile correctly when the source and/or build directory is a symbolic link.
CTest¶
ctest(1)now has the ability to schedule tests based on resource requirements for each test. See Resource Allocation for details.A new test property,
SKIP_REGULAR_EXPRESSION, has been added. This property is similar toFAIL_REGULAR_EXPRESSIONandPASS_REGULAR_EXPRESSION, but with the same meaning asSKIP_RETURN_CODE. This is useful, for example, in cases where the user has no control over the return code of the test. For example, in Catch2, the return value is the number of assertion failed, therefore it is impossible to use it forSKIP_RETURN_CODE.
CPack¶
cpack(1)learned support for multiple configurations for-Coption.The
CPack DEB Generatoris now able to format generic text (usually used as the description for multiple CPack generators) according to the Debian Policy Manual. See theCPACK_PACKAGE_DESCRIPTION_FILEandCPACK_DEBIAN_<COMPONENT>_DESCRIPTIONvariables.The
CPack Archive Generatorlearned to generate.tar.zstpackages with Zstandard compression.
Deprecated and Removed Features¶
An explicit deprecation diagnostic was added for policy
CMP0067(CMP0066and below were already deprecated). Thecmake-policies(7)manual explains that the OLD behaviors of all policies are deprecated and that projects should port to the NEW behaviors.The
CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRYvariable has been deprecated. Use theCMAKE_FIND_USE_PACKAGE_REGISTRYvariable instead.The
GetPrerequisitesmodule has been deprecated, as it has been superceded byfile(GET_RUNTIME_DEPENDENCIES).The
CPACK_INSTALL_SCRIPTvariable has been deprecated in favor of the new, more accurately namedCPACK_INSTALL_SCRIPTSvariable.
Other Changes¶
The
cmake(1)-C <initial-cache>option now evaluates the initial cache script withCMAKE_SOURCE_DIRandCMAKE_BINARY_DIRset to the top-level source and build trees.The
cmake(1)-E remove_directorycommand-line tool, when given the path to a symlink to a directory, now removes just the symlink. It no longer removes content of the linked directory.The
ctest(1)--build-makeprogramcommand-line option now specifies the make program used when configuring a project with theNinjagenerator or the Makefile Generators.The
ExternalProjectmoduleExternalProject_Add()command has been updated so thatGIT_SUBMODULES ""initializes no submodules. See policyCMP0097.The
FindGTestmodule has been updated to recognize MSVC build trees generated by GTest 1.8.1.The
project()command no longer strips leading zeros in version components. See policyCMP0096.The Qt Compressed Help file is now named
CMake.qch, which no longer contains the release version in the file name. When CMake is upgraded in-place, the name and location of this file will remain constant. Tools such as IDEs, help viewers, etc. should now be able to refer to this file at a fixed location that remains valid across CMake upgrades.RPATHentries are properly escaped in the generated CMake scripts used for installation. See policyCMP0095.When using
CMAKE_WINDOWS_EXPORT_ALL_SYMBOLSon Windows the auto-generated exports are now updated only when the object files providing the symbols are updated.
Updates¶
Changes made since CMake 3.16.0 include the following.
3.16.2¶
CMake 3.16.0 and 3.16.1 processed
.hhfiles withAUTOMOC. This was a behavior change from CMake 3.15 and below that can break existing projects, so it has been reverted as of 3.16.2.
3.16.5¶
The
FindPython,FindPython2, andFindPython3modules no longer create cache entries forPython{,2,3}_LIBRARY_RELEASEandPython{,2,3}_LIBRARY_DEBUG. Those values are always computed from other results and so should not be cached. The entries were created by CMake 3.16.0 through 3.16.4 but were alwaysFORCE-set and could not be meaningfully edited by users.Additionally, the modules no longer expose their internal
_Python*cache entries publicly. CMake 3.16.0 through 3.16.4 accidentally made them visible as advanced cache entries.
3.16.7¶
Selection of the Objective C or C++ compiler now considers the
CCorCXXenvironment variable if theOBJCorOBJCXXenvironment variable is not set.The
FindPkgConfigmodule now extracts include directories prefixed with-isysteminto the*_INCLUDE_DIRSvariables andINTERFACE_INCLUDE_DIRECTORIEStarget properties. Previously they would be places in*_CFLAGS_OTHERvariables andINTERFACE_COMPILE_OPTIONStarget properties.
3.16.9¶
The default value of
CMAKE_AUTOMOC_PATH_PREFIXwas changed toOFFbecause 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.