CMake 3.11 Release Notes¶
Contents
Changes made since CMake 3.10 include the following.
New Features¶
Generators¶
The
CodeBlocksextra generator learned to check aCMAKE_CODEBLOCKS_COMPILER_IDvariable for a custom compiler identification value to place in the project file.The Makefile Generators and the
Ninjagenerator learned to add compiler launcher tools along with the compiler for theFortranlanguage (C,CXX, andCUDAwere supported previously). See theCMAKE_<LANG>_COMPILER_LAUNCHERvariable and<LANG>_COMPILER_LAUNCHERtarget property for details.Visual Studio Generators learned to support the
COMPILE_LANGUAGEgenerator expressionin target-wideCOMPILE_DEFINITIONS,INCLUDE_DIRECTORIES,COMPILE_OPTIONS, andfile(GENERATE). See generator expression documentation for caveats.The
Xcodegenerator learned to support theCOMPILE_LANGUAGEgenerator expressionin target-wideCOMPILE_DEFINITIONSandINCLUDE_DIRECTORIES. It previously supported onlyCOMPILE_OPTIONSandfile(GENERATE). See generator expression documentation for caveats.
Commands¶
add_library()andadd_executable()commands can now be called without any sources and will not complain as long as sources are added later via thetarget_sources()command.The
file(DOWNLOAD)andfile(UPLOAD)commands gainedNETRCandNETRC_FILEoptions to specify use of a.netrcfile.The
target_compile_definitions()command learned to set theINTERFACE_COMPILE_DEFINITIONSproperty on Imported Targets.The
target_compile_features()command learned to set theINTERFACE_COMPILE_FEATURESproperty on Imported Targets.The
target_compile_options()command learned to set theINTERFACE_COMPILE_OPTIONSproperty on Imported Targets.The
target_include_directories()command learned to set theINTERFACE_INCLUDE_DIRECTORIESproperty on Imported Targets.The
target_sources()command learned to set theINTERFACE_SOURCESproperty on Imported Targets.The
target_link_libraries()command learned to set theINTERFACE_LINK_LIBRARIESproperty on Imported Targets.
Variables¶
A
CMAKE_GENERATOR_INSTANCEvariable was introduced to hold the selected instance of the generator's corresponding native tools if multiple are available. This is used by theVisual Studio 15 2017generator to hold the selected instance of Visual Studio persistently.A
CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONSvariable was added to enable setting of default permissions for directories created implicitly during installation of files byinstall()andfile(INSTALL), e.g. duringmake install.A
CMAKE_JOB_POOLSvariable was added specify a value to use for theJOB_POOLSproperty. This enables control over build parallelism with command line configuration parameters when using the Ninja generator.The
CMAKE_NETRCandCMAKE_NETRC_FILEvariables were added to specify use of a.netrcfile by thefile(DOWNLOAD)andfile(UPLOAD)commands and theExternalProjectmodule.A
CMAKE_CUDA_SEPARABLE_COMPILATIONvariable was added to initialize theCUDA_SEPARABLE_COMPILATIONtarget property on targets when they are created.
Properties¶
The
COMPILE_DEFINITIONSsource file property learned to supportgenerator expressions.A
COMPILE_OPTIONSsource file property was added to manage list of options to pass to the compiler.An
IMPORTED_GLOBALtarget property was added to indicate whether an IMPORTED target is globally visible. It is automatically set to a true value for targets created with theGLOBALoption toadd_library()oradd_executable(). Additionally, project code may now promote a local imported target to be globally visible by setting this property toTRUE.An
INCLUDE_DIRECTORIESsource file property was added to specify list of preprocessor include file search directories.Source file properties
VS_SHADER_DISABLE_OPTIMIZATIONSandVS_SHADER_ENABLE_DEBUGhave been added to specify more details of.hlslsources with Visual Studio Generators.
Modules¶
The
CheckIncludeFilesmoduleCHECK_INCLUDE_FILES()command gained aLANGUAGEoption to specify whether to check using theCorCXXcompiler.The
CMakePackageConfigHelpersmodulewrite_basic_package_version_file()command learned a newSameMinorVersionmode for theCOMPATIBILITYargument.The
ExternalProjectmodule learned to substitute<DOWNLOAD_DIR>in comments, commands, working directory and byproducts.The
ExternalProjectmodule gainedNETRCandNETRC_FILEoptions to specify use of a.netrcfile.A new
FetchContentmodule was added which supports populating content at configure time using any of the download/update methods supported byExternalProject_Add(). This allows the content to be used immediately during the configure stage, such as withadd_subdirectory(), etc. Hierarchical project structures are well supported, allowing parent projects to override the content details of child projects and ensuring content is not populated multiple times throughout the whole project tree.The
FindBLASandFindLAPACKmodules learned to support FLAMEblisandlibflame.The
FindDoxygenmoduledoxygen_add_docs()function now supports a newDOXYGEN_VERBATIM_VARSlist variable. AnyDOXYGEN_...variable contained in that list will bypass the automatic quoting logic, leaving its contents untouched when transferring them to the outputDoxyfile.A
FindIconvmodule was added to locate iconv support.The
GenerateExportHeadermoduleGENERATE_EXPORT_HEADERcommand gained anINCLUDE_GUARD_NAMEoption to change the name of the include guard symbol written to the generated export header. Additionally, it now adds a comment after the closing#endifon the generated export header's include guard.The
UseJavamoduleadd_jarcommand gained aGENERATE_NATIVE_HEADERSoption to generate native header files usingjavac -hforjavac1.8 or above. This supersedescreate_javah, which no longer works with JDK 1.10 and above due to removal of thejavahtool by JEP 313.
Autogen¶
When using
AUTOMOCorAUTOUIC, CMake now starts multiple parallelmocoruicprocesses to reduce the build time. A newCMAKE_AUTOGEN_PARALLELvariable andAUTOGEN_PARALLELtarget property may be set to specify the number of parallelmocoruicprocesses to start. The default is derived from the number of CPUs on the host.
CTest¶
The
ctest_start()command no longer setsCTEST_RUN_CURRENT_SCRIPTdue to issues with scoping if it is called from inside a function. Instead, it sets an internal variable in CTest. However, settingCTEST_RUN_CURRENT_SCRIPTto 0 at the global scope still prevents the script from being re-run at the end.
CPack¶
cpack(1)gained--traceand--trace-expandoptions.The
CPack IFW Generatorgained newCPACK_IFW_PACKAGE_REMOVE_TARGET_DIRvariable to control if the target directory should not be deleted when uninstalling.The
CPack RPM Generatorlearned to enable enforcing of execute privileges on programs and shared libraries. SeeCPACK_RPM_INSTALL_WITH_EXECvariable.A
CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONSvariable was added which serves the same purpose during packaging (e.g.make package) as theCMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONSvariable serves during installation (e.g.make install).
Other¶
Alias Targets may now alias Imported Targets that are created with the
GLOBALoption toadd_library().Interface Libraries may now have custom properties set on them if they start with either an underscore (
_) or a lowercase ASCII character. The original intention was to only allow properties which made sense forINTERFACElibraries, but it also blocked usage of custom properties.The
cmake(1)--open <dir>command-line option was added to open generated IDE projects like Visual Studio solutions or Xcode projects.
Deprecated and Removed Features¶
An explicit deprecation diagnostic was added for policies
CMP0037throughCMP0054(CMP0036and 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
KDevelop3generator has been removed.
Other Changes¶
Policy
CMP0037no longer reserves target names associated with optional features, such astestandpackage, unless the corresponding feature is enabled.The
FindOpenGLmodule now prefers GLVND libraries if available. See policyCMP0072.The minimum deployment target set in the
CMAKE_OSX_DEPLOYMENT_TARGETvariable used to be only applied for macOS regardless of the selected SDK. It is now properly set for the target platform selected byCMAKE_OSX_SYSROOT. For example, if the sysroot variable specifies an iOS SDK then the value inCMAKE_OSX_DEPLOYMENT_TARGETis interpreted as minimum iOS version.The
Xcodegenerator behavior of generating one project file perproject()command may now be controlled with theCMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLYvariable. This could be useful to speed up the CMake generation step for large projects and to work-around a bug in theZERO_CHECKlogic.Since the
CMakeCache.txtformat does not support newlines in values, values containing newlines are now truncated before writing to the file. In addition, a warning comment is written to the cache file, and a warning message is displayed to the user on the console.
Updates¶
Changes made since CMake 3.11.0 include the following.
3.11.1¶
The
CheckIncludeFilemodulecheck_include_filemacro,CheckIncludeFileCXXmodulecheck_include_file_cxxmacro, andCheckIncludeFilesmodulecheck_include_filesmacro were taught to honor theCMAKE_REQUIRED_LIBRARIESvariable in CMake 3.11.0. This has been reverted due to changing behavior of checks for existing projects. It may be restored in the future with a policy for compatibility.
3.11.2¶
Calling
add_library()to create an alias of an imported target that is not globally visible now causes an error again as it did prior to 3.11.0. This diagnostic was accidentally dropped from CMake 3.11.0 and 3.11.1 by the change to allow globally visible imported targets to be aliased.The
FindQt4moduleqt4_wrap_cpp,qt4_wrap_uiandqt4_add_resourcesmacros now setSKIP_AUTOMOCandSKIP_AUTOUICon their generated files. These files never need to be processed by moc or uic, and we must say so explicitly to account for policyCMP0071.