code:
CMake 3.5 Release Notes
***********************

.. only:: html

  .. contents::

Changes made since CMake 3.4 include the following.

New Features
============

GUI
---

* The :manual:`cmake-gui(1)` gained options to control warnings about
  deprecated functionality.

* The :manual:`cmake-gui(1)` learned an option to set the toolset
  to be used with VS IDE and Xcode generators, much like the
  existing ``-T`` option to :manual:`cmake(1)`.

* The :manual:`cmake-gui(1)` gained a Regular Expression Explorer which
  may be used to create and evaluate regular expressions in real-time.
  The explorer window is available via the ``Tools`` menu.

Command-Line
------------

* The ``-Wdev`` and ``-Wno-dev`` :manual:`cmake(1)` options now also enable
  and suppress the deprecated warnings output by default.

* The suppression of developer warnings as errors can now be controlled with
  the new ``-Werror=dev`` and ``-Wno-error=dev`` :manual:`cmake(1)` options.

* The :manual:`cmake(1)` ``-E`` command-line tools ``copy``,
  ``copy_if_different``, ``copy_directory``, and ``make_directory``
  learned to support multiple input files or directories.

Commands
--------

* The :command:`cmake_parse_arguments` command is now implemented natively.
  The :module:`CMakeParseArguments` module remains as an empty placeholder
  for compatibility.

* The :command:`install(DIRECTORY)` command learned to support
  :manual:`generator expressions <cmake-generator-expressions(7)>`
  in the list of directories.

Variables
---------

* The :variable:`CMAKE_ERROR_DEPRECATED` variable can now be set using the
  ``-Werror=deprecated`` and ``-Wno-error=deprecated`` :manual:`cmake(1)`
  options.

* The :variable:`CMAKE_WARN_DEPRECATED` variable can now be set using the
  ``-Wdeprecated`` and ``-Wno-deprecated`` :manual:`cmake(1)` options.

Properties
----------

* The :prop_tgt:`VS_GLOBAL_<variable>` target property is now implemented
  for VS 2010 and above.  Previously it worked only in VS 2008 and below.

Modules
-------

* The :module:`ExternalProject` module learned a new ``GIT_REMOTE_NAME``
  option to control the ``git clone --origin`` value.

* The :module:`FindBoost` module now provides imported targets
  such as ``Boost::boost`` and ``Boost::filesystem``.

* The :module:`FindFLEX` module ``FLEX_TARGET`` macro learned a
  new ``DEFINES_FILE`` option to specify a custom output header
  to be generated.

* The :module:`FindGTest` module now provides imported targets.

* The :module:`FindGTK2` module, when ``GTK2_USE_IMPORTED_TARGETS`` is
  enabled, now sets ``GTK2_LIBRARIES`` to contain the list of imported
  targets instead of the paths to the libraries.  Moreover it now sets
  a new ``GTK2_TARGETS`` variable containing all the targets imported.

* The :module:`FindOpenMP` module learned to support Clang.

* The :module:`FindOpenSSL` module gained a new
  ``OPENSSL_MSVC_STATIC_RT`` option to search for libraries using
  the MSVC static runtime.

* The :module:`FindPNG` module now provides imported targets.

* The :module:`FindTIFF` module now provides imported targets.

* A :module:`FindXalanC` module was introduced to find the
  Apache Xalan-C++ XSL transform processing library.

* The :module:`FindXercesC` module now provides imported targets.

Platforms
---------

* Support was added for the ARM Compiler (arm.com) with compiler id ``ARMCC``.

* A new platform file for cross-compiling in the Cray Linux Environment to
  target compute nodes was added.  See
  :ref:`Cross Compiling for the Cray Linux Environment <Cray Cross-Compile>`
  for usage details.

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
  is now aware of features supported by Clang compilers on Windows (MinGW).

* When building for embedded Apple platforms like iOS CMake learned to build and
  install combined targets which contain both a device and a simulator build.
  This behavior can be enabled by setting the :prop_tgt:`IOS_INSTALL_COMBINED`
  target property.

CPack
-----

* The :cpack_gen:`CPack DragNDrop Generator` learned new variable to
  specify AppleScript file run to customize appearance of ``DragNDrop``
  installer folder, including background image setting using supplied
  PNG or multi-resolution TIFF file.
  See the :variable:`CPACK_DMG_DS_STORE_SETUP_SCRIPT` and
  :variable:`CPACK_DMG_BACKGROUND_IMAGE` variables.

* The :cpack_gen:`CPack DEB Generator` learned to set the optional config
  file ``Source`` field using a monolithic or per-component variable.
  See :variable:`CPACK_DEBIAN_PACKAGE_SOURCE`.

* The :cpack_gen:`CPack DEB Generator` learned to set Package, Section
  and Priority control fields per-component.
  See variables :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION` and
  :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY`.

* The :cpack_gen:`CPack DragNDrop Generator` learned to add
  multi-lingual SLAs to a DMG which is presented to the user when they try to
  mount the DMG.  See the :variable:`CPACK_DMG_SLA_LANGUAGES` and
  :variable:`CPACK_DMG_SLA_DIR` variables for details.

* The :cpack_gen:`CPack NSIS Generator` learned new variables to
  add bitmaps to the installer.
  See the :variable:`CPACK_NSIS_MUI_WELCOMEFINISHPAGE_BITMAP`
  and :variable:`CPACK_NSIS_MUI_UNWELCOMEFINISHPAGE_BITMAP` variables.

* The :cpack_gen:`CPack RPM Generator` learned to set Name and Group
  control fields per-component.
  See :variable:`CPACK_RPM_<component>_PACKAGE_NAME`
  and :variable:`CPACK_RPM_<component>_PACKAGE_GROUP`.

Other
-----

* Warnings about deprecated functionality are now enabled by default.
  They may be suppressed with ``-Wno-deprecated`` or by setting the
  :variable:`CMAKE_WARN_DEPRECATED` variable to false.

Deprecated and Removed Features
===============================

* The :manual:`cmake(1)` ``-E time`` command now properly passes arguments
  with spaces or special characters through to the child process.  This
  may break scripts that worked around the bug with their own extra
  quoting or escaping.

* The :generator:`Xcode` generator was fixed to escape backslashes in
  strings consistently with other generators.  Projects that previously
  worked around the inconsistecy with an extra level of backslashes
  conditioned on the Xcode generator must be updated to remove the
  workaround for CMake 3.5 and greater.

Other Changes
=============

* The :generator:`Visual Studio 14 2015` generator learned to map the
  ``/debug:fastlink`` linker flag to the ``.vcxproj`` file property.

* The :module:`FindGTK2` module now configures the ``GTK2::sigc++`` imported
  target to enable c++11 on its dependents when using sigc++ 2.5.1 or higher.

* The precompiled Windows binary provided on ``cmake.org`` is now a
  ``.msi`` package instead of an installer executable.  One may need
  to manually uninstall CMake versions lower than 3.5 before installing
  the new package.


code:
CMake 3.6 Release Notes
***********************

.. only:: html

  .. contents::

Changes made since CMake 3.5 include the following.

New Features
============

Generators
----------

* The :generator:`Ninja` generator learned to produce phony targets
  of the form ``sub/dir/all`` to drive the build of a subdirectory.
  This is equivalent to ``cd sub/dir; make all`` with
  :ref:`Makefile Generators`.

* The :generator:`Ninja` generator now includes system header files in build
  dependencies to ensure correct re-builds when system packages are updated.

* The :generator:`Visual Studio 14 2015` generator learned to support the
  Clang/C2 toolsets, e.g. with the ``-T v140_clang_3_7`` option.
  This feature is experimental.

Commands
--------

* The :command:`add_custom_command` and :command:`add_custom_target` commands
  learned how to use the :prop_tgt:`CROSSCOMPILING_EMULATOR` executable
  target property.

* The :command:`install` command learned a new ``EXCLUDE_FROM_ALL`` option
  to leave installation rules out of the default installation.

* The :command:`list` command gained a ``FILTER`` sub-command to filter
  list elements by regular expression.

* The :command:`string(TIMESTAMP)` and :command:`file(TIMESTAMP)`
  commands gained support for the ``%s`` placeholder.  This is
  the number of seconds since the UNIX Epoch.

Variables
---------

* A :variable:`CMAKE_DEPENDS_IN_PROJECT_ONLY` variable was introduced
  to tell :ref:`Makefile Generators` to limit dependency scanning only
  to files in the project source and build trees.

* A new :variable:`CMAKE_HOST_SOLARIS` variable was introduced to
  indicate when CMake is running on an Oracle Solaris host.

* A :variable:`CMAKE_<LANG>_STANDARD_INCLUDE_DIRECTORIES` variable was
  added for use by toolchain files to specify system include directories
  to be appended to all compiler command lines.

* The :variable:`CMAKE_<LANG>_STANDARD_LIBRARIES` variable is now documented.
  It is intended for use by toolchain files to specify system libraries to be
  added to all linker command lines.

* A :variable:`CMAKE_NINJA_OUTPUT_PATH_PREFIX` variable was introduced
  to tell the :generator:`Ninja` generator to configure the generated
  ``build.ninja`` file for use as a ``subninja``.

* A :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` variable was
  added for use by toolchain files to specify platform-specific
  variables that must be propagated by the :command:`try_compile`
  command into test projects.

* A :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable was added
  to optionally tell the :command:`try_compile` command to build
  a static library instead of an executable.  This is useful for
  cross-compiling toolchains that cannot link binaries without
  custom flags or scripts.

Properties
----------

* A :prop_tgt:`DEPLOYMENT_REMOTE_DIRECTORY` target property was introduced
  to tell the :generator:`Visual Studio 9 2008` and
  :generator:`Visual Studio 8 2005` generators to generate the "remote
  directory" for WinCE project deployment and debugger settings.

* A :prop_tgt:`<LANG>_CLANG_TIDY` target property and supporting
  :variable:`CMAKE_<LANG>_CLANG_TIDY` variable were introduced to tell the
  :ref:`Makefile Generators` and the :generator:`Ninja` generator to run
  ``clang-tidy`` along with the compiler for ``C`` and ``CXX`` languages.

* A :prop_test:`TIMEOUT_AFTER_MATCH` test property was introduced to
  optionally tell CTest to enforce a secondary timeout after matching
  certain output from a test.

* A :prop_tgt:`VS_CONFIGURATION_TYPE` target property was introduced
  to specify a custom project file type for :ref:`Visual Studio Generators`
  supporting VS 2010 and above.

* A :prop_dir:`VS_STARTUP_PROJECT` directory property was introduced
  to specify for :ref:`Visual Studio Generators` the default startup
  project for generated solutions (``.sln`` files).

Modules
-------

* The :module:`CMakePushCheckState` module now pushes/pops/resets the variable
  ``CMAKE_EXTRA_INCLUDE_FILES`` used in :module:`CheckTypeSize`.

* The :module:`ExternalProject` module leared the ``GIT_SHALLOW 1``
  option to perform a shallow clone of a Git repository.

* The :module:`ExternalProject` module learned to initialize Git submodules
  recursively and also to initialize new submodules on updates.  Use the
  ``GIT_SUBMODULES`` option to restrict which submodules are initialized and
  updated.

* The :module:`ExternalProject` module leared the ``DOWNLOAD_NO_EXTRACT 1``
  argument to skip extracting the file that is downloaded (e.g., for
  self-extracting shell installers or ``.msi`` files).

* The :module:`ExternalProject` module now uses ``TLS_VERIFY`` when fetching
  from git repositories.

* The :module:`FindBLAS` and :module:`FindLAPACK` modules learned to
  support `OpenBLAS <http://www.openblas.net>`__.

* The :module:`FindCUDA` module learned to find the ``cublas_device`` library.

* The :module:`FindGTest` module ``gtest_add_tests`` function now causes
  CMake to automatically re-run when test sources change so that they
  can be re-scanned.

* The :module:`FindLTTngUST` module was introduced to find the LTTng-UST
  library.

* The :module:`FindPkgConfig` module learned to optionally create imported
  targets for the libraries it has found.

* The :module:`FindProtobuf` module learned to provide a ``Protobuf_VERSION``
  variable and check the version number requested in a :command:`find_package`
  call.

* The :module:`InstallRequiredSystemLibraries` module learned a new
  ``CMAKE_INSTALL_UCRT_LIBRARIES`` option to enable app-local deployment
  of the Windows Universal CRT libraries with Visual Studio 2015.

Platforms
---------

* The Clang compiler is now supported on CYGWIN.

* Support was added for the Bruce C Compiler with compiler id ``Bruce``.

CTest
-----

* The :command:`ctest_update` command now looks at the
  :variable:`CTEST_GIT_INIT_SUBMODULES` variable to determine whether
  submodules should be updated or not before updating.

* The :command:`ctest_update` command will now synchronize submodules on an
  update. Updates which add submodules or change a submodule's URL will now be
  pulled properly.

CPack
-----

* The :cpack_gen:`CPack DEB Generator` learned how to handle ``$ORIGIN``
  in ``CMAKE_INSTALL_RPATH`` when :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS`
  is used for dependency auto detection.

* The :cpack_gen:`CPack DEB Generator` learned how to generate
  ``DEBIAN/shlibs`` control file when package contains shared libraries.

* The :cpack_gen:`CPack DEB Generator` learned how to generate
  ``DEBIAN/postinst`` and ``DEBIAN/postrm`` files if the package installs
  libraries in ldconfig-controlled locations (e.g. ``/lib/``, ``/usr/lib/``).

* The :cpack_gen:`CPack DEB Generator` learned how to generate dependencies
  between Debian packages if multi-component setup is used and
  :variable:`CPACK_COMPONENT_<compName>_DEPENDS` variables are set.
  For backward compatibility this feature is disabled by default.
  See :variable:`CPACK_DEBIAN_ENABLE_COMPONENT_DEPENDS`.

* The :cpack_gen:`CPack DEB Generator` learned how to set custom package
  file names including how to generate properly-named Debian packages::

    <PackageName>_<VersionNumber>-<DebianRevisionNumber>_<DebianArchitecture>.deb

  For backward compatibility this feature is disabled by default. See
  :variable:`CPACK_DEBIAN_FILE_NAME` and
  :variable:`CPACK_DEBIAN_<COMPONENT>_FILE_NAME`.

* The :cpack_gen:`CPack DEB Generator` learned how to set the package
  release number (``DebianRevisionNumber`` in package file name when
  used in combination with ``DEB-DEFAULT`` value set by
  :variable:`CPACK_DEBIAN_FILE_NAME`).
  See :variable:`CPACK_DEBIAN_PACKAGE_RELEASE`.

* The :cpack_gen:`CPack DEB Generator` learned how to set the package
  architecture per-component.
  See :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE`.

* The :cpack_gen:`CPack DragNDrop Generator` learned a new option to skip the
  ``/Applications`` symlink.
  See the :variable:`CPACK_DMG_DISABLE_APPLICATIONS_SYMLINK` variable.

* The :module:`CPackIFW` module gained a new
  :command:`cpack_ifw_update_repository` command to update a QtIFW-specific
  repository from a remote repository.

* The :cpack_gen:`CPack RPM Generator` learned how to set RPM ``dist`` tag
  as part of RPM ``Release:`` tag when enabled (mandatory on some Linux
  distributions for e.g. on Fedora).
  See :variable:`CPACK_RPM_PACKAGE_RELEASE_DIST`.

* The :cpack_gen:`CPack RPM Generator` learned how to set default values
  for owning user/group and file/directory permissions of package content.
  See :variable:`CPACK_RPM_DEFAULT_USER`, :variable:`CPACK_RPM_DEFAULT_GROUP`,
  :variable:`CPACK_RPM_DEFAULT_FILE_PERMISSIONS`,
  :variable:`CPACK_RPM_DEFAULT_DIR_PERMISSIONS` and their per component
  counterparts.

* The :cpack_gen:`CPack RPM Generator` learned how to set user defined
  package file names, how to specify that rpmbuild should decide on file
  name format as well as handling of multiple rpm packages generated by a
  single user defined spec file.
  See :variable:`CPACK_RPM_PACKAGE_NAME` and
  :variable:`CPACK_RPM_<component>_PACKAGE_NAME`.

* The :cpack_gen:`CPack RPM Generator` learned how to correctly handle symlinks
  that are pointing outside generated packages.

Other
-----

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
  is now aware of features supported by Intel C++ compilers versions 12.1
  through 16.0 on UNIX platforms.

Deprecated and Removed Features
===============================

* The :module:`CMakeForceCompiler` module and its macros are now deprecated.
  See module documentation for an explanation.

* The :command:`find_library`, :command:`find_path`, and :command:`find_file`
  commands no longer search in installation prefixes derived from the ``PATH``
  environment variable on non-Windows platforms.  This behavior was added in
  CMake 3.3 to support Windows hosts but has proven problematic on UNIX hosts.
  Users that keep some ``<prefix>/bin`` directories in the ``PATH`` just for
  their tools do not necessarily want any supporting ``<prefix>/lib``
  directories searched.  One may set the ``CMAKE_PREFIX_PATH`` environment
  variable with a :ref:`semicolon-separated list <CMake Language Lists>` of prefixes that are
  to be searched.

* The :generator:`Visual Studio 7 .NET 2003` generator is now
  deprecated and will be removed in a future version of CMake.

* The :generator:`Visual Studio 7` generator (for VS .NET 2002) has been
  removed.  It had been deprecated since CMake 3.3.

* The :generator:`Visual Studio 6` generator has been removed.
  It had been deprecated since CMake 3.3.

Other Changes
=============

* The precompiled OS X binary provided on ``cmake.org`` now requires
  OS X 10.7 or newer.

* On Linux and FreeBSD platforms, when building CMake itself from source and
  not using a system-provided libcurl, OpenSSL is now used by default if it is
  found on the system.  This enables SSL/TLS support for commands supporting
  network communication via ``https``, such as :command:`file(DOWNLOAD)`,
  :command:`file(UPLOAD)`, and :command:`ctest_submit`.

* The :manual:`cmake(1)` ``--build`` command-line tool now rejects multiple
  ``--target`` options with an error instead of silently ignoring all but the
  last one.

* :prop_tgt:`AUTOMOC` now diagnoses name collisions when multiple source
  files in different directories use ``#include <moc_foo.cpp>`` with the
  same name (because the generated ``moc_foo.cpp`` files would collide).

* The :module:`FindBISON` module ``BISON_TARGET`` macro now supports
  special characters by passing the ``VERBATIM`` option to internal
  :command:`add_custom_command` calls.  This may break clients that
  added escaping manually to work around the bug.

* The :module:`FindFLEX` module ``FLEX_TARGET`` macro now supports
  special characters by passing the ``VERBATIM`` option to internal
  :command:`add_custom_command` calls.  This may break clients that
  added escaping manually to work around the bug.

* The :module:`FindProtobuf` module input and output variables were all renamed
  from ``PROTOBUF_`` to ``Protobuf_`` for consistency with other find modules.
  Input variables of the old case will be honored if provided, and output
  variables of the old case are always provided.

* The :cpack_gen:`CPack RPM Generator` now supports upper cased component
  names in per component CPackRPM specific variables.
  E.g. component named ``foo`` now expects component specific
  variable to be ``CPACK_RPM_FOO_PACKAGE_NAME`` while before
  it expected ``CPACK_RPM_foo_PACKAGE_NAME``.
  Upper cased component name part in variables is compatible
  with convention used for other CPack variables.
  For back compatibility old format of variables is still valid
  and preferred if both versions of variable are set, but the
  preferred future use is upper cased component names in variables.
  New variables that will be added to CPackRPM in later versions
  will only support upper cased component variable format.

* The CPack NSIS generator's configuration file template was fixed to
  quote the path to the uninstaller tool used by the
  :variable:`CPACK_NSIS_ENABLE_UNINSTALL_BEFORE_INSTALL` option.
  This avoids depending on an insecure Windows feature to run an
  uninstaller tool with a space in the path.

repo_name: lazytadpole/codenamesilverfish

license: mit


code:
CMake 3.7 Release Notes
***********************

.. only:: html

  .. contents::

Changes made since CMake 3.6 include the following.

New Features
============

Platforms
---------

* CMake now supports :ref:`Cross Compiling for Android` with simple
  toolchain files.

* The Clang compiler is now supported on AIX.

Generators
----------

* The :generator:`Ninja` generator learned to conditionally support
  Fortran when using a ``ninja`` tool that has the necessary features.
  See generator documentation for details.

* The :generator:`Ninja` generator learned to produce phony targets
  of the form ``sub/dir/{test,install,package}`` to drive the build
  of a subdirectory installation, test or packaging target.
  This is equivalent to ``cd sub/dir; make {test,install,package}``
  with :ref:`Makefile Generators`.

* The :generator:`Visual Studio 15 2017` generator was added.  This is
  experimental and based on "Visual Studio 2017 RC" because this version
  of VS has not been released.

* :ref:`Visual Studio Generators` for VS 2010 and above learned to
  place ``.natvis`` source files into VS project files properly.

* The :generator:`Xcode` generator's rudimentary Swift language support
  learned to honor a new :variable:`CMAKE_Swift_LANGUAGE_VERSION` variable
  to tell Xcode what version of Swift is used by the source.

* The :generator:`CodeLite` generator gained a new
  :variable:`CMAKE_CODELITE_USE_TARGETS` option
  to change project creation from projects to targets.

Commands
--------

* The :command:`add_custom_command` command gained a new ``DEPFILE``
  option that works with the :generator:`Ninja` generator to provide
  implicit dependency information to the build tool.

* The :command:`cmake_parse_arguments` command gained a new ``PARSE_ARGV``
  mode to read arguments directly from ``ARGC`` and ``ARGV#``
  variables inside a :command:`function` body.

* The :command:`export` command gained an ``ANDROID_MK`` option
  to generate ``Android.mk`` files referencing CMake-built
  libraries as prebuilts for the Android NDK build system.

* The :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands gained
  ``HTTPHEADER <HTTP-header>`` and ``USERPWD <username>:<password>`` options.

* The :command:`find_library` and :command:`find_package` commands learned
  to search in ``lib32/`` directories when the build targets a 32-bit
  architecture.  See the :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` global
  property.

* The :command:`find_package` command gained the possibility of
  sorting compatible libraries by ``NAME`` or by ``NATURAL`` sorting by
  setting the two new variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER`
  and :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`.

* The :command:`if` command gained new boolean comparison operations
  ``LESS_EQUAL``, ``GREATER_EQUAL``, ``STRLESS_EQUAL``, ``STRGREATER_EQUAL``,
  ``VERSION_LESS_EQUAL``, and ``VERSION_GREATER_EQUAL``.

* The :command:`install` command gained an ``EXPORT_ANDROID_MK``
  subcommand to install ``Android.mk`` files referencing installed
  libraries as prebuilts for the Android NDK build system.

* The :command:`string(TIMESTAMP)` and :command:`file(TIMESTAMP)`
  commands gained support for the ``%a`` and ``%b`` placeholders.
  These are the abbreviated weekday and month names.

* The :command:`try_compile` command source file signature now honors
  configuration-specific flags (e.g. :variable:`CMAKE_<LANG>_FLAGS_DEBUG`)
  in the generated test project.  Previously only the default such flags
  for the current toolchain were used.  See policy :policy:`CMP0066`.

Variables
---------

* Variable :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` was added to control
  the sorting mode of the :command:`find_package` command.

* Variable :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION` was added to control
  the sorting direction the :command:`find_package` command.

* :variable:`Toolchain files <CMAKE_TOOLCHAIN_FILE>` may now set a
  :variable:`CMAKE_<LANG>_FLAGS_INIT` variable to initialize the
  :variable:`CMAKE_<LANG>_FLAGS` cache entry the first time a language is
  enabled in a build tree.

* :variable:`Toolchain files <CMAKE_TOOLCHAIN_FILE>` may now set
  :variable:`CMAKE_EXE_LINKER_FLAGS_INIT`,
  :variable:`CMAKE_SHARED_LINKER_FLAGS_INIT`, and
  :variable:`CMAKE_MODULE_LINKER_FLAGS_INIT` variables to initialize the
  :variable:`CMAKE_EXE_LINKER_FLAGS`,
  :variable:`CMAKE_SHARED_LINKER_FLAGS`, and
  :variable:`CMAKE_MODULE_LINKER_FLAGS` cache entries the first time
  a language is enabled in a build tree.

Properties
----------

* On Apple platforms the :prop_tgt:`BUNDLE_EXTENSION` target property
  now also applies to Frameworks and App Bundles.

* A :prop_dir:`BINARY_DIR` directory property was added to get the
  absolute path to the binary directory corresponding to the source
  directory on which the property is read.

* A :prop_dir:`BUILDSYSTEM_TARGETS` directory property was added to
  get the list of logical buildsystem target names added by the
  project in a directory.

* A :prop_tgt:`LINK_WHAT_YOU_USE` target property and supporting
  :variable:`CMAKE_LINK_WHAT_YOU_USE` variable were introduced
  to detect (on UNIX) shared libraries that are linked but not
  needed by running ``ldd -r -u``.

* A :prop_dir:`SOURCE_DIR` directory property was added to get the
  absolute path to the source directory associated with a directory.

* A :prop_dir:`SUBDIRECTORIES` directory property was added to
  get the list of subdirectories added by a project in a directory.

* A :prop_tgt:`VS_SDK_REFERENCES` target property was added to tell
  :ref:`Visual Studio Generators` to reference the named SDKs.

* A :prop_sf:`VS_TOOL_OVERRIDE` source file property was created to tell
  :ref:`Visual Studio Generators` what tool to use for a source file.

* The :prop_tgt:`WINDOWS_EXPORT_ALL_SYMBOLS` target property now applies
  to executable targets with the :prop_tgt:`ENABLE_EXPORTS` property set.

* A :prop_sf:`XCODE_FILE_ATTRIBUTES` source file property was
  added to tell the :generator:`Xcode` generator to generate
  custom content in the Xcode project attributes for the file.

Modules
-------

* An :module:`AndroidTestUtilities` module was added to manage transfer
  of test data to an Android device.

* The :module:`CheckFortranSourceCompiles` module macro
  ``CHECK_Fortran_SOURCE_COMPILES`` gained a ``SRC_EXT`` option
  to specify a custom test Fortran source file extension.

* The :module:`ExternalProject` module gained ``HTTP_USERNAME`` and
  ``HTTP_PASSWORD`` options to set http download credentials.

* The :module:`ExternalProject` module gained a ``HTTP_HEADER``
  option to add http download headers.

* The :module:`FindBISON` module ``BISON_TARGET`` macro learned a new
  ``REPORT_FILE`` option to specify the bison ``--report-file=`` option.

* The :module:`FindBZip2` module now provides imported targets.

* A :module:`FindICU` module was introduced to find the International
  Components for Unicode (ICU) libraries and programs.

* The :module:`FindMatlab` module learned to find the SIMULINK and MAT
  components.

* The :module:`FindMatlab` module :command:`matlab_add_mex` command learned
  to add executables and modules.

* The :module:`FindMatlab` module :command:`matlab_add_unit_test` command
  learned to support inline Matlab test code.

* The :module:`FindOpenCL` module now provides imported targets.

* The :module:`FindOpenMP` module learned to detect the OpenMP
  version (specification date) from the compiler.

* A :module:`FindVulkan` module was added.

* The :module:`GenerateExportHeader` module learned a new
  ``CUSTOM_CONTENT_FROM_VARIABLE`` option to specify a variable
  containing custom content for inclusion in the generated header.

* The :module:`GNUInstallDirs` module gained a new
  :command:`GNUInstallDirs_get_absolute_install_dir` command.

* The :module:`UseJava` module gained APIs to "export" jar targets
  for use by external CMake projects.  See the ``install_jar_exports``
  and ``export_jars`` functions.

CTest
-----

* CTest now supports test fixtures through the new :prop_test:`FIXTURES_SETUP`,
  :prop_test:`FIXTURES_CLEANUP` and :prop_test:`FIXTURES_REQUIRED` test
  properties. When using regular expressions or ``--rerun-failed`` to limit
  the tests to be run, a fixture's setup and cleanup tests will automatically
  be added to the execution set if any test requires that fixture.

* The :command:`ctest_configure`, :command:`ctest_build`,
  :command:`ctest_test`, :command:`ctest_coverage`, and :command:`ctest_upload`
  commands gained a new ``CAPTURE_CMAKE_ERROR`` option to capture any errors
  that occur as the commands run into a variable and avoid affecting the return
  code of the :manual:`ctest(1)` process.

CPack
-----

* CPack gained a :cpack_gen:`CPack productbuild Generator` on OS X.

* CPack gained a new :variable:`CPACK_PACKAGE_CHECKSUM` variable to
  enable generation of a checksum file for each package file.

* The :cpack_gen:`CPack DEB Generator` learned to support long file names
  when archive format is set to GNU tar.
  See :variable:`CPACK_DEBIAN_ARCHIVE_TYPE`

* The :module:`CPackIFW` module gained a new
  :command:`cpack_ifw_add_package_resources` command to include additional
  resources in the installer binary.

* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and
  :command:`cpack_ifw_configure_component_group` commands gained a new
  ``USER_INTERFACES`` option to add a list of additional pages to the IFW
  installer.

* The :cpack_gen:`CPack RPM Generator` learned to generate debuginfo
  packages on demand. See :variable:`CPACK_RPM_DEBUGINFO_PACKAGE`
  and its per component version.

* The :cpack_gen:`CPack RPM Generator` learned to generate source rpm
  (SRPM) packages on demand. See :variable:`CPACK_RPM_PACKAGE_SOURCES`,
  :variable:`CPACK_RPM_SOURCE_PKG_BUILD_PARAMS` and
  :variable:`CPACK_RPM_SOURCE_PKG_PACKAGING_INSTALL_PREFIX`.

* The :cpack_gen:`CPack NSIS Generator` now supports
  :variable:`CPACK_NSIS_<compName>_INSTALL_DIRECTORY`.
  This can be used to set component specific installation directories.

* The :cpack_gen:`CPack WIX Generator` now supports
  :variable:`CPACK_WIX_SKIP_PROGRAM_FOLDER` to allow specification
  of a custom absolute installation prefix outside
  of the ProgramFiles folders.

* The :cpack_gen:`CPack WIX Generator` now supports
  :variable:`CPACK_COMPONENT_<compName>_DISABLED`.
  This can be used to deselect a component from being installed by default.

* The :cpack_gen:`CPack WIX Generator` now supports
  :variable:`CPACK_WIX_PATCH_FILE` fragments for Feature elements.

* The :cpack_gen:`CPack WIX Generator` now supports
  :variable:`CPACK_WIX_ROOT_FEATURE_TITLE` and
  :variable:`CPACK_WIX_ROOT_FEATURE_DESCRIPTION` to allow the specification
  of a custom title and description for the root feature element.

Other
-----

* :manual:`cmake(1)` gained a ``-E capabilities`` option to provide a
  machine-readable (JSON) description of the capabilities of the
  cmake tool (available generators, etc.).

* A new :manual:`cmake-server(7)` mode was added to provide semantic
  information about a CMake-generated buildsystem to clients through
  a JSON protocol.  Currently all protocols are experimental and subject
  to change.

* The :manual:`cmake(1)` command learned a ``--trace-source=<file>`` option.

* :manual:`ccmake(1)` learned to support vim-like navigation bindings.

* :manual:`cmake-gui(1)` gained a button to open the generated project file
  for :ref:`Visual Studio Generators` and the :generator:`Xcode` generator.

Deprecated and Removed Features
===============================

* We no longer provide Linux i386 binaries for download from ``cmake.org``
  for new versions of CMake.

* Vim support files ``cmake-indent.vim``, ``cmake-syntax.vim``, and
  ``cmake-help.vim`` have been removed in favor of the files now provided
  from the `vim-cmake-syntax`_ project.

* Support for building CMake itself with some compilers was dropped:

  * Visual Studio 7.1 and 2005 -- superseded by VS 2008 and above
  * MinGW.org mingw32 -- superseded by MSYS2 mingw32 and mingw64

  CMake still supports generating build systems for other projects using
  these compilers.

Other Changes
=============

* The Fortran dependency scanner learned to support the syntax of
  `Fortran Submodules`_.

* Vim support files ``indent/cmake.vim`` and ``syntax/cmake.vim``
  from the `vim-cmake-syntax`_ project are now distributed with CMake.

.. _`Fortran Submodules`: https://fortranwiki.org/fortran/show/Submodules
.. _`vim-cmake-syntax`: https://github.com/pboettch/vim-cmake-syntax


code:
CMake 3.8 Release Notes
***********************

.. only:: html

  .. contents::

Changes made since CMake 3.7 include the following.

New Features
============

Languages
---------

C#
^^

* CMake learned to support ``CSharp`` (C#) as a first-class language that
  can be enabled via the :command:`project` and :command:`enable_language`
  commands.  It is currently supported by the :ref:`Visual Studio Generators`
  for VS 2010 and above.

  C# assemblies and programs can be added just like common C++ targets using
  the :command:`add_library` and :command:`add_executable` commands.
  References between C# targets in the same source tree may be specified by
  :command:`target_link_libraries` like for C++.  References to system or
  3rd-party assemblies may be specified by the target properties
  :prop_tgt:`VS_DOTNET_REFERENCE_<refname>` and
  :prop_tgt:`VS_DOTNET_REFERENCES`.

* More fine tuning of C# targets may be done using target and source
  file properties.  Specifically the target properties related to
  Visual Studio (``VS_*``) are worth a look (for setting toolset
  versions, root namespaces, assembly icons, ...).

CUDA
^^^^

* CMake learned to support ``CUDA`` as a first-class language that can be
  enabled via the :command:`project` and :command:`enable_language` commands.

* ``CUDA`` is currently supported by the :ref:`Makefile Generators`
  and the :generator:`Ninja` generator on Linux, macOS, and Windows.
  Support for the Visual Studio IDE is under development but not
  included in this release.

* The NVIDIA CUDA Toolkit compiler (``nvcc``) is supported.

C & C++
^^^^^^^

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
  now offers meta-features that request compiler modes for specific language
  standard levels (e.g. ``cxx_std_11``).  See
  :prop_gbl:`CMAKE_C_KNOWN_FEATURES` and :prop_gbl:`CMAKE_CXX_KNOWN_FEATURES`.

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
  is now aware of C++ 17.  No specific features are yet enumerated besides
  the ``cxx_std_17`` meta-feature.

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
  is now aware of the availability of C99 in gcc since version 3.4.

Platforms
---------

* A new minimal platform file for ``Fuchsia`` was added.

Generators
----------

* The :generator:`CodeBlocks` extra generator may now be used to
  generate with :generator:`NMake Makefiles JOM`.

* The :ref:`Visual Studio Generators` for VS 2013 and above learned to
  support a ``host=x64`` option in the :variable:`CMAKE_GENERATOR_TOOLSET`
  value (e.g.  via the :manual:`cmake(1)` ``-T`` option) to request use
  of a VS 64-bit toolchain on 64-bit hosts.

* The :ref:`Visual Studio Generators` learned to treat files passed to
  :command:`target_link_libraries` whose names end in ``.targets``
  as MSBuild "targets" files to be imported into generated project files.

Commands
--------

* The :command:`add_custom_command` and :command:`add_custom_target` commands
  learned the option ``COMMAND_EXPAND_LISTS`` which causes lists in the
  ``COMMAND`` argument to be expanded, including lists created by generator
  expressions.

* The :command:`execute_process` command gained an ``ENCODING`` option to
  specify on Windows which encoding is used for output from child process.

* The :command:`math(EXPR)` command gained support for unary
  ``+`` and ``-`` operators.

* The :command:`source_group` command gained ``TREE`` and ``PREFIX``
  options to add groups following source tree directory structure.

* The :command:`string(TIMESTAMP)` command learned to treat ``%%``
  as a way to encode plain ``%``.

* The :command:`string(TIMESTAMP)` command will now honor the
  ``SOURCE_DATE_EPOCH`` environment variable and use its value
  instead of the current time.

* The :command:`try_compile` command source file signature gained new options
  to specify the language standard to use in the generated test project.

* The :command:`try_compile` command source file signature now honors
  language standard variables like :variable:`CMAKE_CXX_STANDARD`.
  See policy :policy:`CMP0067`.

Variables
---------

* A :variable:`CMAKE_CODELITE_USE_TARGETS` variable was added to tell the
  :generator:`CodeLite` extra generator to change the generated project
  to have target-centric organization.
  The ``build``, ``rebuild``, and ``clean`` operations within ``CodeLite``
  then work on a selected target rather than the whole workspace.
  (Note that the :generator:`Ninja` clean operation on a target
  includes its dependencies, though.)

* The :variable:`CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS` variable was added to
  tell the :generator:`Sublime Text 2` extra generator to place specified
  environment variables in the generated ``.sublime-project``.

* The :variable:`CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE` variable was added
  to tell the :generator:`Sublime Text 2` extra generator whether to exclude
  the build tree from the ``.sublime-project`` when it is inside the source
  tree.

* A :variable:`CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD` variable was
  added to tell :ref:`Visual Studio Generators` for VS 2010 and above
  to include the ``PACKAGE`` target in the default build, similar to
  the existing :variable:`CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD`
  variable for the ``INSTALL`` target.

Properties
----------

* A :prop_tgt:`BUILD_RPATH` target property and corresponding
  :variable:`CMAKE_BUILD_RPATH` variable were added to support custom
  ``RPATH`` locations to be added to binaries in the build tree.

* The :prop_sf:`COMPILE_FLAGS` source file property learned to support
  :manual:`generator expressions <cmake-generator-expressions(7)>`.

* The :prop_tgt:`FRAMEWORK` target property may now also be applied to
  static libraries on Apple targets.  It will result in a proper
  Framework but with a static library inside.

* :ref:`Imported <Imported Targets>` :ref:`Interface Libraries` learned new
  :prop_tgt:`IMPORTED_LIBNAME` and :prop_tgt:`IMPORTED_LIBNAME_<CONFIG>`
  target properties to specify a link library name since interface libraries
  do not build their own library files.

* A :prop_tgt:`<LANG>_CPPLINT` target property and supporting
  :variable:`CMAKE_<LANG>_CPPLINT` variable were introduced to tell
  the :ref:`Makefile Generators` and the :generator:`Ninja` generator to
  run the ``cpplint`` style checker along with the compiler for ``C`` and
  ``CXX`` languages.

* A :prop_tgt:`MANUALLY_ADDED_DEPENDENCIES` target property has been added.
  It provides a read-only list of dependencies that have been added with
  the :command:`add_dependencies` command.

* The :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` target property learned
  to interpret empty list elements as referring to the configuration-less
  imported location specified by :prop_tgt:`IMPORTED_LOCATION`.

* The :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target property is now supported
  on :ref:`Imported <Imported Targets>` :ref:`Interface Libraries`.

* New source file properties :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC`,
  :prop_sf:`SKIP_AUTORCC`, and :prop_sf:`SKIP_AUTOGEN` were added to allow
  source files to be excluded from processing by :prop_tgt:`AUTOMOC`,
  :prop_tgt:`AUTOUIC`, and :prop_tgt:`AUTORCC` target properties.

* A :prop_sf:`VS_COPY_TO_OUT_DIR` source file property was added to
  tell :ref:`Visual Studio Generators` for VS 2010 and above whether
  or not a file should e copied to the output directory.

* A :prop_tgt:`VS_DEBUGGER_WORKING_DIRECTORY` target property was added
  to tell :ref:`Visual Studio Generators` for VS 2010 and above what
  debugger working directory should be set for the target.

* A :prop_tgt:`VS_DOTNET_REFERENCES_COPY_LOCAL` target property was added
  to specify whether to copy referenced assemblies to the output directory.

* A :prop_tgt:`VS_DOTNET_REFERENCE_<refname>` target property was added
  to tell :ref:`Visual Studio Generators` for VS 2010 and above to add
  a .NET reference with a given hint path.

* A :prop_sf:`VS_INCLUDE_IN_VSIX` source file property was added to
  tell :ref:`Visual Studio Generators` for VS 2010 and above whether
  to include the file in a Visual Studio extension package.

* A :prop_sf:`VS_RESOURCE_GENERATOR` source file property was added to
  give :ref:`Visual Studio Generators` for VS 2010 and above a setting
  for the resource generator (``C#`` only).

* A :prop_tgt:`VS_USER_PROPS` target property was added to tell
  :ref:`Visual Studio Generators` for VS 2010 and above to use a
  custom MSBuild user ``.props`` file.

* A :prop_gbl:`XCODE_EMIT_EFFECTIVE_PLATFORM_NAME` global property was
  added to tell the :generator:`Xcode` generator whether to emit the
  ``EFFECTIVE_PLATFORM_NAME`` variable.  This is useful when building
  with multiple SDKs like ``macosx`` and ``iphoneos`` in parallel.

* New :prop_tgt:`XCODE_PRODUCT_TYPE` and :prop_tgt:`XCODE_EXPLICIT_FILE_TYPE`
  target properties were created to tell the :generator:`Xcode` generator
  to use custom values of the corresponding attributes for a target in the
  generated Xcode project.

Modules
-------

* A :module:`CSharpUtilities` module was added to aid parameterization of
  Visual Studio C# targets.  It provides functions to allow automated
  setting of source file properties to support Windows Forms, WPF/XAML or
  other technologies as needed.

* The :module:`ExternalData` module learned to support multiple
  content links for one data file using different hashes, e.g.
  ``img.png.sha256`` and ``img.png.sha1``.  This allows objects
  to be fetched from sources indexed by different hash algorithms.

* The :module:`ExternalProject` module gained the ``GIT_PROGRESS`` option to
  force Git to show progress when cloning repositories.

* The :module:`ExternalProject` module gained a ``GIT_CONFIG`` option
  to pass ``--config`` options to Git when cloning repositories.

* The :module:`FeatureSummary` module :command:`feature_summary` command now
  accepts a new ``QUIET_ON_EMPTY`` option that suppresses the output when
  the list of packages that belong to the selected category is empty.

* The :module:`FeatureSummary` module :command:`add_feature_info` command
  now accepts lists of dependencies for deciding whether a feature is enabled
  or not.

* The package types accepted by the :module:`FeatureSummary` module can now
  be tweaked by changing the :variable:`FeatureSummary_PKG_TYPES`,
  :variable:`FeatureSummary_REQUIRED_PKG_TYPES` and
  :variable:`FeatureSummary_DEFAULT_PKG_TYPE` global properties.

* The :module:`FindOpenGL` module now provides imported targets
  ``OpenGL::GL`` and ``OpenGL::GLU`` when the libraries are found.

* The :module:`UseSWIG` module gained a ``swig_add_library`` command
  to give more flexibility over the old ``swig_add_module`` command.

* The :module:`UseSWIG` module ``swig_add_source_to_module`` command
  learned a new ``SWIG_OUTFILE_DIR`` option to control the output
  file location (``swig -o``).

* The :module:`WriteCompilerDetectionHeader` module gained the
  ``ALLOW_UNKNOWN_COMPILERS`` and ``ALLOW_UNKNOWN_COMPILER_VERSIONS`` options
  that allow creation of headers that will work also with unknown or old
  compilers by simply assuming they do not support any of the requested
  features.

CTest
-----

* The :command:`ctest_memcheck` command gained a ``DEFECT_COUNT <var>``
  option to capture the number of memory defects detected.

* The :command:`ctest_memcheck` command learned to read the location of
  suppressions files for sanitizers from the
  :variable:`CTEST_MEMORYCHECK_SUPPRESSIONS_FILE` variable.

* The :command:`ctest_memcheck` command learned to support ``LeakSanitizer``
  independently from ``AddressSanitizer``.

* The :command:`ctest_update` command ``CDASH_UPLOAD`` signature was taught
  to honor the ``RETRY_COUNT``, ``RETRY_DELAY``, and ``QUIET`` options.

CPack
-----

* The :module:`CPackIFWConfigureFile` module was added to define a new
  :command:`cpack_ifw_configure_file` command to configure file templates
  prepared in QtIFW/SDK/Creator style.

* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and
  :command:`cpack_ifw_configure_component_group` commands gained a new
  ``DEFAULT``, ``VIRTUAL``, ``FORCED_INSTALLATION``, ``REQUIRES_ADMIN_RIGHTS``,
  ``DISPLAY_NAME``, ``UPDATE_TEXT``, ``DESCRIPTION``, ``RELEASE_DATE``,
  ``AUTO_DEPEND_ON`` and ``TRANSLATIONS`` options to more specific
  configuration.

* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component`
  command gained a new ``DEPENDENCIES`` alias for ``DEPENDS`` option.

* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component_group`
  command gained a new ``DEPENDS`` option. The ``DEPENDENCIES`` alias also
  added.

* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and
  :command:`cpack_ifw_configure_component_group` commands ``PRIORITY``
  option now is deprecated and will be removed in a future version of CMake.
  Please use new ``SORTING_PRIORITY`` option instead.

* The :cpack_gen:`CPack IFW Generator` gained new
  :variable:`CPACK_IFW_PACKAGE_WATERMARK`,
  :variable:`CPACK_IFW_PACKAGE_BANNER`,
  :variable:`CPACK_IFW_PACKAGE_BACKGROUND`,
  :variable:`CPACK_IFW_PACKAGE_WIZARD_STYLE`,
  :variable:`CPACK_IFW_PACKAGE_WIZARD_DEFAULT_WIDTH`,
  :variable:`CPACK_IFW_PACKAGE_WIZARD_DEFAULT_HEIGHT`, and
  :variable:`CPACK_IFW_PACKAGE_TITLE_COLOR`
  variables to customize a QtIFW installer look.

* The :cpack_gen:`CPack productbuild Generator` gained options to sign packages.
  See the variables :variable:`CPACK_PRODUCTBUILD_IDENTITY_NAME`,
  :variable:`CPACK_PRODUCTBUILD_KEYCHAIN_PATH`,
  :variable:`CPACK_PKGBUILD_IDENTITY_NAME`, and
  :variable:`CPACK_PKGBUILD_KEYCHAIN_PATH`.

* The :cpack_gen:`CPack RPM Generator` learned to omit tags that are not
  supported by provided ``rpmbuild`` tool. If unsupported tags are set they
  are ignored and a developer warning is printed out.

* The :cpack_gen:`CPack RPM Generator` learned to generate main component
  package which forces generation of a rpm for defined component without
  component suffix in filename and package name.
  See :variable:`CPACK_RPM_MAIN_COMPONENT` variable.

* The :cpack_gen:`CPack RPM Generator` learned to generate a single
  ``debuginfo`` package on demand even if components packaging is used.
  See :variable:`CPACK_RPM_DEBUGINFO_SINGLE_PACKAGE` variable.

* The :cpack_gen:`CPack RPM Generator` learned to support
  multiple directives per file when using
  :variable:`CPACK_RPM_USER_FILELIST` variable.

Other
-----

* CMake functionality using cryptographic hashes now supports SHA-3 algorithms.

* A new generator expression ``$<IF:cond,true-value,false-value>`` was added.
  It resolves to the true-value if the condition is ``1`` and resolves to
  the false-value if the condition is ``0``.

Deprecated and Removed Features
===============================

* The :module:`FeatureSummary` module commands :command:`set_package_info`,
  :command:`set_feature_info`, :command:`print_enabled_features`, and
  :command:`print_disabled_features` are now deprecated.

* The :module:`UseSWIG` module ``swig_add_module`` command is now
  deprecated in favor of ``swig_add_library``.

Other Changes
=============

* If a command specified by the :prop_tgt:`<LANG>_CLANG_TIDY` target property
  returns non-zero at build time this is now treated as an error instead of
  silently ignored.

* The :command:`ctest_memcheck` command no longer automatically adds
  ``leak_check=1`` to the options used by ``AddressSanitizer``. The default
  behavior of ``AddressSanitizer`` is to run `LeakSanitizer` to check leaks
  unless ``leak_check=0``.

* The :command:`ctest_memcheck` command was fixed to correctly append extra
  sanitizer options read from the
  :variable:`CTEST_MEMORYCHECK_SANITIZER_OPTIONS` variable to the environment
  variables used internally by the sanitizers.

* The :module:`FeatureSummary` module :command:`set_package_properties`
  command no longer forces the package type to ``OPTIONAL`` when the type
  is not explicitly set.

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
  is now aware of features supported by Intel C++ compilers versions 12.1
  through 17.0 on UNIX and Windows platforms.

* Calls to the :module:`FindPkgConfig` module :command:`pkg_check_modules`
  command following a successful call learned to re-evaluate the cached values
  for a given prefix after changes to the parameters to the command for that
  prefix.

* When using :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC`, generated
  ``moc_*``, ``*.moc`` and ``ui_*`` are placed in the
  ``<CMAKE_CURRENT_BINARY_DIR>/<TARGETNAME>_autogen/include`` directory which
  is automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`.
  It is therefore not necessary anymore to have
  :variable:`CMAKE_CURRENT_BINARY_DIR` in the target's
  :prop_tgt:`INCLUDE_DIRECTORIES`.

* The :generator:`Sublime Text 2` generator no longer runs the native
  build command (e.g. ``ninja`` or ``make``) with verbose build output
  enabled.

* The :command:`try_compile` command source file signature now
  honors the :variable:`CMAKE_WARN_DEPRECATED` variable value
  in the generated test project.

* The :ref:`Visual Studio Generators` for VS 2010 and above now place
  per-source file flags after target-wide flags when they are classified
  as raw flags with no project file setting (``AdditionalOptions``).
  This behavior is more consistent with the ordering of flags produced
  by other generators, and allows flags on more-specific properties
  (per-source) to override those on more general ones (per-target).

* The precompiled Windows binary MSI package provided on ``cmake.org`` now
  records the installation directory in the Windows Registry under the key
  ``HKLM\Software\Kitware\CMake`` with a value named ``InstallDir``.


code:
CMake 3.9 Release Notes
***********************

.. only:: html

  .. contents::

Changes made since CMake 3.8 include the following.

New Features
============

Languages
---------

* ``CUDA`` is now supported by the :ref:`Visual Studio Generators`
  for VS 2010 and above.  This complements the existing support by the
  :ref:`Makefile Generators` and the :generator:`Ninja` generator.
  CUDA 8.0.61 or higher is recommended due to known bugs in the VS
  integration by earlier versions.

* CMake is now aware of the :prop_tgt:`C++ standards <CXX_STANDARD>` and
  :prop_tgt:`C standards <C_STANDARD>` and their associated meta-features for
  the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>`: ``Cray``,
  ``PGI``, and ``XL``.

Generators
----------

* :ref:`Visual Studio Generators` for VS 2010 and above learned to support
  the ``ASM_NASM`` language when ``nasm`` is installed.

* The :generator:`Xcode` generator learned to create Xcode schema files.
  This is an experimental feature and can be activated by setting the
  :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable to a ``TRUE`` value.

Commands
--------

* The :command:`add_library` command ``IMPORTED`` option learned to support
  :ref:`Object Libraries`.

* The :command:`find_library` command learned to search ``libx32`` paths
  when the build targets the ``x32`` ABI.  See the
  :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` global property.

* The :command:`include_external_msproject` command learned to use
  the :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` target property
  to map current configurations to the external configurations.

* The :command:`install(TARGETS)` command learned a new ``OBJECTS`` option to
  specify where to install :ref:`Object Libraries`.

* The :command:`install(EXPORT)` command learned how to export
  :ref:`Object Libraries`.

* The :command:`project` command learned an optional ``DESCRIPTION``
  parameter to set the :variable:`PROJECT_DESCRIPTION` variable.

* The :command:`separate_arguments` command gained a ``NATIVE_COMMAND`` mode
  that performs argument separation depending on the host operating system.

Variables
---------

* A :variable:`CMAKE_ANDROID_NDK_DEPRECATED_HEADERS` variable was added
  for use when :ref:`Cross Compiling for Android with the NDK` to request
  use of the deprecated headers even when unified headers are available.
  The default is now to use unified headers if available.

* A :variable:`CMAKE_AUTOMOC_DEPEND_FILTERS` variable was introduced to
  allow :variable:`CMAKE_AUTOMOC` to extract additional dependency file names
  for ``moc`` from the contents of source files.

* A :variable:`CMAKE_AUTOUIC_SEARCH_PATHS` variable was introduced to
  allow :variable:`CMAKE_AUTOUIC` to search for ``foo.ui`` in more
  places than the vicinity of the file including ``ui_foo.h``.

* A :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable was added to
  tell the :command:`find_library` command to search in a ``lib<suffix>``
  directory before each ``lib`` directory that would normally be searched.

* A :variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION` variable was added to
  initialize the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` property on all
  targets.

* A :variable:`CMAKE_<LANG>_COMPILER_AR` variable was added to hold
  the path to the GCC/Clang wrapper of ``ar``.

* A :variable:`CMAKE_<LANG>_COMPILER_RANLIB` variable was added to hold
  the path to the GCC/Clang wrapper of ``ranlib``.

* The :variable:`CMAKE_SYSROOT_COMPILE` and :variable:`CMAKE_SYSROOT_LINK`
  variables were added to use separate sysroots for compiling and linking.

Properties
----------

* A new :prop_tgt:`AUTOGEN_BUILD_DIR` target property was introduced to set
  a custom output directory for :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC`,
  and :prop_tgt:`AUTORCC`.

* A new :prop_tgt:`AUTOMOC_DEPEND_FILTERS` target property was introduced to
  allow :prop_tgt:`AUTOMOC` to extract additional dependency file names
  for ``moc`` from the contents of source files.

* A new :prop_tgt:`AUTOUIC_SEARCH_PATHS` target property was introduced to
  allow :prop_tgt:`AUTOUIC` to search for ``foo.ui`` in more
  places than the vicinity of the file including ``ui_foo.h``.

* Global properties :prop_gbl:`AUTOGEN_SOURCE_GROUP`,
  :prop_gbl:`AUTOMOC_SOURCE_GROUP` and
  :prop_gbl:`AUTORCC_SOURCE_GROUP` were
  introduced to allow files generated by :prop_tgt:`AUTOMOC` or
  :prop_tgt:`AUTORCC` to be placed in a :command:`source_group`.

* A :prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR` target property and corresponding
  :variable:`CMAKE_BUILD_WITH_INSTALL_NAME_DIR` variable were added to
  control whether to use the :prop_tgt:`INSTALL_NAME_DIR` target property
  value for binaries in the build tree.  This is for macOS ``install_name``
  as :prop_tgt:`BUILD_WITH_INSTALL_RPATH` is for ``RPATH``.

* A :prop_tgt:`CUDA_PTX_COMPILATION` target property was added to
  :ref:`Object Libraries` to support compiling to ``.ptx`` files
  instead of host object files.

* A :prop_gbl:`GENERATOR_IS_MULTI_CONFIG` global property was
  added to determine whether the current generator is a multi-configuration
  generator (such as :ref:`Visual Studio Generators` or :generator:`Xcode`).

* The :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property is now enforced
  when enabled.  CMake will add IPO flags unconditionally or produce an error
  if it does not know the flags for the current compiler.  The project is now
  responsible to use the :module:`CheckIPOSupported` module to check for IPO
  support before enabling the target property.  See policy :policy:`CMP0069`.

* The :prop_tgt:`WINDOWS_EXPORT_ALL_SYMBOLS` target property may now
  be used in combination with explicit ``.def`` files in order to
  export all symbols from the object files within a target plus
  an explicit list of symbols that the linker finds in dependencies
  (e.g. ``msvcrt.lib``).

Modules
-------

* A :module:`CheckIPOSupported` module was added to help projects
  check whether interprocedural optimization (IPO) is supported by
  the current toolchain and CMake version.

* The :module:`CMakeFindDependencyMacro` module ``find_dependency`` macro
  now forwards all arguments to the underlying :command:`find_package`
  call.  Existing uses will continue to function as before, but callers can
  now access the full suite of arguments that :command:`find_package` accepts.

* The :module:`FeatureSummary` module :command:`feature_summary` command now
  accepts the new ``DEFAULT_DESCRIPTION`` option that will print the default
  title for the selected package type.

* The :module:`FeatureSummary` module gained a new
  :variable:`FeatureSummary_<TYPE>_DESCRIPTION` variable that can be defined
  for each ``<TYPE>`` to replace the type name with the specified string
  whenever the package type is used in an output string by the module.

* The :module:`FindDoxygen` module learned to control Doxygen behavior using
  CMake variables and generate documentation via the newly added
  :command:`doxygen_add_docs` function. The Doxygen input file (``Doxyfile``)
  is automatically generated and doxygen is run as part of a custom target.
  Additional components can be specified to find optional tools: ``dot``,
  ``mscgen`` and ``dia``.

* The :module:`FindMPI` module now provides imported targets.

* The :module:`FindProtobuf` module :command:`protobuf_generate_cpp`
  command gained an ``EXPORT_MACRO`` option to specify the name of
  a DLL export markup macro.

* The :module:`FindProtobuf` module now supports usage of static libraries
  for Unix via a new ``Protobuf_USE_STATIC_LIBS`` input variable.

* The :module:`FindProtobuf` module now provides imported targets
  when the libraries are found.

* A new :module:`GoogleTest` module was added to provide the
  :command:`gtest_add_tests` function independently of the :module:`FindGTest`
  module. The function was also updated to support keyword arguments, with
  functionality expanded to allow a test name prefix and suffix to be
  specified, the dependency on the source files to be optional and the list of
  discovered test cases to be returned to the caller.

CTest
-----

* The :command:`ctest_submit` command gained a ``HTTPHEADER`` option
  to specify custom headers to send during submission.

* The :manual:`ctest(1)` executable gained new options which allow the
  developer to disable automatically adding tests to the test set to satisfy
  fixture dependencies. ``-FS`` prevents adding setup tests for fixtures
  matching the provided regular expression, ``-FC`` prevents adding cleanup
  tests for matching fixtures and ``-FA`` prevents adding any test for matching
  fixtures.

* A :prop_test:`DISABLED` test property was added to mark tests that
  are configured but explicitly disabled so they do not run.

CPack
-----

* The :cpack_gen:`CPack Archive Generator` learned to modify the filename
  per-component.  See the :variable:`CPACK_ARCHIVE_FILE_NAME` variable and
  its per-component version :variable:`CPACK_ARCHIVE_<component>_FILE_NAME`.

* The :module:`CPackComponent` module :command:`cpack_add_component` command
  gained a new ``PLIST <filename>`` option to specify the ``pkgbuild``
  ``--component-plist`` argument when using the
  :module:`productbuild <CPackProductBuild>` generator.

* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and
  :command:`cpack_ifw_configure_component_group` commands gained
  internationalization support for ``DISPLAY_NAME`` and ``DESCRIPTION``
  options.

* The :cpack_gen:`CPack IFW Generator` learned the new hint
  :variable:`CPACK_IFW_ROOT` variable for finding the QtIFW tool suite
  installed in a non-standard place.

* The :cpack_gen:`CPack productbuild Generator` gained a new
  :variable:`CPACK_PRODUCTBUILD_RESOURCES_DIR` variable to
  specify resources to be copied into the ``Resources``
  directory.

* The :cpack_gen:`CPack RPM Generator` learned to modify the ``debuginfo``
  package name.  See the :variable:`CPACK_RPM_DEBUGINFO_FILE_NAME` variable.

* The :cpack_gen:`CPack WIX Generator` patching system now has the
  ability to set additional attributes.  This can be done by specifying
  attributes with the ``CPackWiXFragment`` XML tag after the ``Id`` attribute.
  See the :variable:`CPACK_WIX_PATCH_FILE` variable.

* The :cpack_gen:`CPack WIX Generator` implemented a new
  :variable:`CPACK_WIX_ROOT_FOLDER_ID` variable which allows
  using a custom root folder ID instead of the default
  ``ProgramFilesFolder`` / ``ProgramFiles64Folder``.

Other
-----

* Interprocedural optimization (IPO) is now supported for GNU and Clang
  compilers using link time optimization (LTO) flags.  See the
  :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property and
  :module:`CheckIPOSupported` module.

* The ``TARGET_OBJECTS``
  :manual:`generator expression <cmake-generator-expressions(7)>`
  is now supported by the :command:`add_custom_command` and
  :command:`file(GENERATE)` commands.

* Two new informational generator expressions to retrieve Apple Bundle
  directories have been added. The first one :genex:`$<TARGET_BUNDLE_DIR:tgt>`
  outputs the full path to the Bundle directory, the other one
  :genex:`$<TARGET_BUNDLE_CONTENT_DIR:tgt>` outputs the full path to the
  ``Contents`` directory of macOS Bundles and App Bundles. For all other
  bundle types and SDKs it is identical with :genex:`$<TARGET_BUNDLE_DIR:tgt>`.
  The new expressions are helpful to query Bundle locations independent of
  the different Bundle types and layouts on macOS and iOS.

Deprecated and Removed Features
===============================

* An explicit deprecation diagnostic was added for policies ``CMP0036``
  and below.  The :manual:`cmake-policies(7)` manual explains that the
  OLD behaviors of all policies are deprecated and that projects should
  always port to the NEW behaviors as soon as possible.

* The :generator:`Visual Studio 8 2005` generator is now deprecated
  and will be removed in a future version of CMake.

* The :generator:`Visual Studio 7 .NET 2003` generator has been removed.

* The :generator:`Xcode` generator dropped support for Xcode versions
  older than 3.

* The :module:`FindDoxygen` module has deprecated several variables.

* The version of curl bundled with CMake no longer accepts URLs of the form
  ``file://c:/...`` on Windows due to a change in upstream curl 7.52.  Use
  the form ``file:///c:/...`` instead to work on all versions.

Other Changes
=============

* When using :prop_tgt:`AUTOMOC`, CMake now scans for the presence of the
  ``Q_PLUGIN_METADATA`` macro and reruns moc when the file from the
  macro's ``FILE`` argument changes.

* When :prop_tgt:`AUTOMOC` detects an include statement of the form
  ``#include "moc_<basename>.cpp"`` the search for the respective header file
  now looks in the :prop_tgt:`INCLUDE_DIRECTORIES` of the target as well.

* When running tests, CTest learned to treat skipped tests (using the
  :prop_test:`SKIP_RETURN_CODE` property) the same as tests with the new
  :prop_test:`DISABLED` property. Due to this change, CTest will not indicate
  failure when all tests are either skipped or pass.

* The :generator:`Ninja` generator has loosened the dependencies of object
  compilation.  Object compilation now depends only on custom targets
  and custom commands associated with libraries on which the object's target
  depends and no longer depends on the libraries themselves.  Source files
  in dependent targets may now compile without waiting for their targets'
  dependencies to link.

* On macOS, ``RPATH`` settings such as :prop_tgt:`BUILD_WITH_INSTALL_RPATH`
  no longer affect the ``install_name`` field.  See policy :policy:`CMP0068`.

* The :generator:`Visual Studio 14 2015` generator has been taught about
  a change to the ``v140`` toolset made by a VS 2015 update.  VS changed
  the set of values it understands for the ``GenerateDebugInformation``
  linker setting that produces the ``-DEBUG`` linker flag variants.

Updates
=======

Changes made since CMake 3.9.0 include the following.

3.9.1
-----

* The ``find_`` command ``PACKAGE_ROOT`` search path group added by
  CMake 3.9.0 has been removed for the 3.9 series due to regressions
  caused by new use of ``<PackageName>_ROOT`` variables.  The behavior
  may be re-introduced in the future in a more-compatible way.

3.9.2
-----

* On macOS, the default application bundle ``Info.plist`` file no longer
  enables Hi-DPI support as it did in 3.9.0 and 3.9.1.  The change had
  to be reverted because it broke iOS applications.

* The Xcode generator no longer adds "outputPaths" to custom script
  build phases as it did in 3.9.0 and 3.9.1.  This was added in an
  attempt to support Xcode 9's new build system, but broke incremental
  rebuilds for both the old and new Xcode build systems.


code:
..
  This file should be included by the adjacent "index.rst"
  in development versions but not in release versions.

Changes Since Release
=====================

The following noteworthy changes have been made in this development
version since the preceding release but have not yet been consolidated
into notes for a specific release version:

.. toctree::
   :maxdepth: 1
   :glob:

   dev/*


code:
ANDROID
-------

.. versionadded:: 3.7

Set to ``1`` when the target system (:variable:`CMAKE_SYSTEM_NAME`) is
``Android``.


code:
APPLE
-----

Set to ``True`` when the target system is an Apple platform
(macOS, iOS, tvOS, visionOS or watchOS).


code:
BORLAND
-------

``True`` if the Borland compiler is being used.

This is set to ``true`` if the Borland compiler is being used.


code:
BSD
---

.. versionadded:: 3.25

Set to a string value when the target system is BSD. This value can be one of
the following: DragonFlyBSD, FreeBSD, OpenBSD, or NetBSD.


code:
BUILD_SHARED_LIBS
-----------------

Tell :command:`add_library` to default to ``SHARED`` libraries,
instead of ``STATIC`` libraries, when called with no explicit library type.

Calls to :command:`add_library` without any explicit library type check
the current ``BUILD_SHARED_LIBS`` variable value.  If it is true, then the
default library type is ``SHARED``.  Otherwise, the default is ``STATIC``.

For example, the code:

.. code-block:: cmake

  add_library(example ${sources})

behaves as if written

.. code-block:: cmake

  if(BUILD_SHARED_LIBS)
    add_library(example SHARED ${sources})
  else()
    add_library(example STATIC ${sources})
  endif()

CMake does not define ``BUILD_SHARED_LIBS`` by default, but projects
often create a cache entry for it using the :command:`option` command:

.. code-block:: cmake

  option(BUILD_SHARED_LIBS "Build using shared libraries" ON)

This provides a switch that users can control, e.g., with :option:`cmake -D`.
If adding such an option to the project, do so in the top level
``CMakeLists.txt`` file, before any :command:`add_library` calls.
Note that if bringing external dependencies directly into the build, such as
with :module:`FetchContent` or a direct call to :command:`add_subdirectory`,
and one of those dependencies has such a call to
:command:`option(BUILD_SHARED_LIBS ...) <option>`, the top level project must
also call :command:`option(BUILD_SHARED_LIBS ...) <option>` before bringing in
its dependencies.  Failure to do so can lead to different behavior between the
first and subsequent CMake runs.


code:
CACHE
-----

.. versionadded:: 3.13

Operator to read cache variables.

Use the syntax ``$CACHE{VAR}`` to read cache entry ``VAR``.
See the :ref:`cmake-language(7) variables <CMake Language Variables>`
documentation for more complete documentation of the interaction of
normal variables and cache entries.

When evaluating :ref:`Variable References` of the form ``${VAR}``,
CMake first searches for a normal variable with that name, and if not
found CMake will search for a cache entry with that name.
The ``$CACHE{VAR}`` syntax can be used to do direct cache lookup and
ignore any existing normal variable.

See the :command:`set` and :command:`unset` commands to see how to
write or remove cache variables.


code:
CMAKE_ABSOLUTE_DESTINATION_FILES
--------------------------------

List of files which have been installed using an ``ABSOLUTE DESTINATION`` path.

This variable is defined by CMake-generated ``cmake_install.cmake``
scripts.  It can be used (read-only) by programs or scripts that
source those install scripts.  This is used by some CPack generators
(e.g.  RPM).


code:
CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY
----------------------------------------------

.. versionadded:: 3.27

Whether to enable the ``DEPENDS_EXPLICIT_ONLY`` option by default in
:command:`add_custom_command`.

This variable affects the default behavior of the :command:`add_custom_command`
command.  Setting this variable to ``ON`` is equivalent to using the
``DEPENDS_EXPLICIT_ONLY`` option in all uses of that command.

See also :variable:`CMAKE_OPTIMIZE_DEPENDENCIES`.


code:
CMAKE_ADSP_ROOT
---------------

.. versionadded:: 3.24

When :ref:`Cross Compiling for ADSP SHARC/Blackfin`,
this variable holds the absolute path to the latest CCES or VDSP++ install.
The directory is expected to contain the ``cc21k.exe`` and ``ccblkfn.exe`` compilers.
This will be set automatically if a default install of CCES or VDSP++ can be found.

See also the :envvar:`ADSP_ROOT` environment variable.


code:
CMAKE_AIX_EXPORT_ALL_SYMBOLS
----------------------------

.. versionadded:: 3.17

Default value for :prop_tgt:`AIX_EXPORT_ALL_SYMBOLS` target property.
This variable is used to initialize the property on each target as it is
created.


code:
CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS
------------------------------------

.. versionadded:: 3.4

Default value for the :prop_tgt:`ANDROID_ANT_ADDITIONAL_OPTIONS` target property.
See that target property for additional information.


code:
CMAKE_ANDROID_API
-----------------

.. versionadded:: 3.1

When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
Edition`, this variable may be set to specify the default value for the
:prop_tgt:`ANDROID_API` target property.  See that target property for
additional information.

When :ref:`Cross Compiling for Android`, the :variable:`CMAKE_SYSTEM_VERSION`
variable represents the Android API version number targeted.  For historical
reasons, if a toolchain file sets ``CMAKE_ANDROID_API``, but not
``CMAKE_SYSTEM_VERSION``, the latter will be initialized using the former.


code:
CMAKE_ANDROID_API_MIN
---------------------

.. versionadded:: 3.2

Default value for the :prop_tgt:`ANDROID_API_MIN` target property.
See that target property for additional information.


code:
CMAKE_ANDROID_ARCH
------------------

.. versionadded:: 3.4

When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
Edition`, this variable may be set to specify the default value for the
:prop_tgt:`ANDROID_ARCH` target property.  See that target property for
additional information.

Otherwise, when :ref:`Cross Compiling for Android`, this variable provides
the name of the Android architecture corresponding to the value of the
:variable:`CMAKE_ANDROID_ARCH_ABI` variable.  The architecture name
may be one of:

* ``arm``
* ``arm64``
* ``mips``
* ``mips64``
* ``x86``
* ``x86_64``


code:
CMAKE_ANDROID_ARCH_ABI
----------------------

.. versionadded:: 3.7

When :ref:`Cross Compiling for Android`, this variable specifies the
target architecture and ABI to be used.  Valid values are:

* ``arm64-v8a``
* ``armeabi-v7a``
* ``armeabi-v6``
* ``armeabi``
* ``mips``
* ``mips64``
* ``x86``
* ``x86_64``

See also the :variable:`CMAKE_ANDROID_ARM_MODE` and
:variable:`CMAKE_ANDROID_ARM_NEON` variables.


code:
CMAKE_ANDROID_ARM_MODE
----------------------

.. versionadded:: 3.7

When :ref:`Cross Compiling for Android` and :variable:`CMAKE_ANDROID_ARCH_ABI`
is set to one of the ``armeabi`` architectures, set ``CMAKE_ANDROID_ARM_MODE``
to ``ON`` to target 32-bit ARM processors (``-marm``).  Otherwise, the
default is to target the 16-bit Thumb processors (``-mthumb``).


code:
CMAKE_ANDROID_ARM_NEON
----------------------

.. versionadded:: 3.7

When :ref:`Cross Compiling for Android` and :variable:`CMAKE_ANDROID_ARCH_ABI`
is set to ``armeabi-v7a`` set ``CMAKE_ANDROID_ARM_NEON`` to ``ON`` to target
ARM NEON devices.


code:
CMAKE_ANDROID_ASSETS_DIRECTORIES
--------------------------------

.. versionadded:: 3.4

Default value for the :prop_tgt:`ANDROID_ASSETS_DIRECTORIES` target property.
See that target property for additional information.


code:
CMAKE_ANDROID_EXCEPTIONS
------------------------

.. versionadded:: 3.20

When :ref:`Cross Compiling for Android with the NDK`, this variable may be set
to specify whether exceptions are enabled.


code:
CMAKE_ANDROID_GUI
-----------------

.. versionadded:: 3.1

Default value for the :prop_tgt:`ANDROID_GUI` target property of
executables.  See that target property for additional information.


code:
CMAKE_ANDROID_JAR_DEPENDENCIES
------------------------------

.. versionadded:: 3.4

Default value for the :prop_tgt:`ANDROID_JAR_DEPENDENCIES` target property.
See that target property for additional information.


code:
CMAKE_ANDROID_JAR_DIRECTORIES
-----------------------------

.. versionadded:: 3.4

Default value for the :prop_tgt:`ANDROID_JAR_DIRECTORIES` target property.
See that target property for additional information.


code:
CMAKE_ANDROID_JAVA_SOURCE_DIR
-----------------------------

.. versionadded:: 3.4

Default value for the :prop_tgt:`ANDROID_JAVA_SOURCE_DIR` target property.
See that target property for additional information.


code:
CMAKE_ANDROID_NATIVE_LIB_DEPENDENCIES
-------------------------------------

.. versionadded:: 3.4

Default value for the :prop_tgt:`ANDROID_NATIVE_LIB_DEPENDENCIES` target
property.  See that target property for additional information.


code:
CMAKE_ANDROID_NATIVE_LIB_DIRECTORIES
------------------------------------

.. versionadded:: 3.4

Default value for the :prop_tgt:`ANDROID_NATIVE_LIB_DIRECTORIES` target
property.  See that target property for additional information.


code:
CMAKE_ANDROID_NDK
-----------------

.. versionadded:: 3.7

When :ref:`Cross Compiling for Android with the NDK`, this variable holds
the absolute path to the root directory of the NDK.  The directory must
contain a ``platforms`` subdirectory holding the ``android-<api>``
directories.


code:
CMAKE_ANDROID_NDK_DEPRECATED_HEADERS
------------------------------------

.. versionadded:: 3.9

When :ref:`Cross Compiling for Android with the NDK`, this variable
may be set to specify whether to use the deprecated per-api-level
headers instead of the unified headers.

If not specified, the default will be *false* if using a NDK version
that provides the unified headers and *true* otherwise.


code:
CMAKE_ANDROID_NDK_TOOLCHAIN_HOST_TAG
------------------------------------

.. versionadded:: 3.7.1

When :ref:`Cross Compiling for Android with the NDK`, this variable
provides the NDK's "host tag" used to construct the path to prebuilt
toolchains that run on the host.


code:
CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION
-----------------------------------

.. versionadded:: 3.7

When :ref:`Cross Compiling for Android with the NDK`, this variable
may be set to specify the version of the toolchain to be used
as the compiler.

On NDK r19 or above, this variable must be unset or set to ``clang``.

On NDK r18 or below, this variable must be set to one of these forms:

* ``<major>.<minor>``: GCC of specified version
* ``clang<major>.<minor>``: Clang of specified version
* ``clang``: Clang of most recent available version

A toolchain of the requested version will be selected automatically to
match the ABI named in the :variable:`CMAKE_ANDROID_ARCH_ABI` variable.

If not specified, the default will be a value that selects the latest
available GCC toolchain.


code:
CMAKE_ANDROID_NDK_VERSION
-------------------------

.. versionadded:: 3.20

When :ref:`Cross Compiling for Android with the NDK` and using an
Android NDK version 11 or higher, this variable is provided by
CMake to report the NDK version number.


code:
CMAKE_ANDROID_PROCESS_MAX
-------------------------

.. versionadded:: 3.4

Default value for the :prop_tgt:`ANDROID_PROCESS_MAX` target property.
See that target property for additional information.


code:
CMAKE_ANDROID_PROGUARD
----------------------

.. versionadded:: 3.4

Default value for the :prop_tgt:`ANDROID_PROGUARD` target property.
See that target property for additional information.


code:
CMAKE_ANDROID_PROGUARD_CONFIG_PATH
----------------------------------

.. versionadded:: 3.4

Default value for the :prop_tgt:`ANDROID_PROGUARD_CONFIG_PATH` target property.
See that target property for additional information.


code:
CMAKE_ANDROID_RTTI
------------------

.. versionadded:: 3.20

When :ref:`Cross Compiling for Android with the NDK`, this variable may be set
to specify whether RTTI is enabled.


code:
CMAKE_ANDROID_SECURE_PROPS_PATH
-------------------------------

.. versionadded:: 3.4

Default value for the :prop_tgt:`ANDROID_SECURE_PROPS_PATH` target property.
See that target property for additional information.


code:
CMAKE_ANDROID_SKIP_ANT_STEP
---------------------------

.. versionadded:: 3.4

Default value for the :prop_tgt:`ANDROID_SKIP_ANT_STEP` target property.
See that target property for additional information.


code:
CMAKE_ANDROID_STANDALONE_TOOLCHAIN
----------------------------------

.. versionadded:: 3.7

When :ref:`Cross Compiling for Android with a Standalone Toolchain`, this
variable holds the absolute path to the root directory of the toolchain.
The specified directory must contain a ``sysroot`` subdirectory.


code:
CMAKE_ANDROID_STL_TYPE
----------------------

.. versionadded:: 3.4

When :ref:`Cross Compiling for Android with NVIDIA Nsight Tegra Visual Studio
Edition`, this variable may be set to specify the default value for the
:prop_tgt:`ANDROID_STL_TYPE` target property.  See that target property
for additional information.

When :ref:`Cross Compiling for Android with the NDK`, this variable may be
set to specify the STL variant to be used.  The value may be one of:

``none``
  No C++ Support
``system``
  Minimal C++ without STL
``gabi++_static``
  GAbi++ Static
``gabi++_shared``
  GAbi++ Shared
``gnustl_static``
  GNU libstdc++ Static
``gnustl_shared``
  GNU libstdc++ Shared
``c++_static``
  LLVM libc++ Static
``c++_shared``
  LLVM libc++ Shared
``stlport_static``
  STLport Static
``stlport_shared``
  STLport Shared

The default value is ``gnustl_static`` on NDK versions that provide it
and otherwise ``c++_static``.  Note that this default differs from
the native NDK build system because CMake may be used to build projects for
Android that are not natively implemented for it and use the C++ standard
library.


code:
CMAKE_APPBUNDLE_PATH
--------------------

:ref:`Semicolon-separated list <CMake Language Lists>` of directories specifying a search path
for macOS application bundles used by the :command:`find_program`, and
:command:`find_package` commands.

There is also an environment variable :envvar:`CMAKE_APPBUNDLE_PATH`, which is used
as an additional list of search directories.


code:
CMAKE_APPLE_SILICON_PROCESSOR
-----------------------------

.. versionadded:: 3.19.2

On Apple Silicon hosts running macOS, set this variable to tell
CMake what architecture to use for :variable:`CMAKE_HOST_SYSTEM_PROCESSOR`.
The value must be either ``arm64`` or ``x86_64``.

The value of this variable should never be modified by project code.
It is meant to be set as a cache entry provided by the user,
e.g. via ``-DCMAKE_APPLE_SILICON_PROCESSOR=...``.

See also the :envvar:`CMAKE_APPLE_SILICON_PROCESSOR` environment variable.


code:
CMAKE_AR
--------

Name of archiving tool for static libraries.

This specifies the name of the program that creates archive or static
libraries.


code:
CMAKE_ARCHIVE_OUTPUT_DIRECTORY
------------------------------

Where to put all the :ref:`ARCHIVE <Archive Output Artifacts>`
target files when built.

This variable is used to initialize the :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`
property on all the targets.  See that target property for additional
information.


code:
CMAKE_ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>
---------------------------------------

.. versionadded:: 3.3

Where to put all the :ref:`ARCHIVE <Archive Output Artifacts>`
target files when built for a specific configuration.

This variable is used to initialize the
:prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>` property on all the targets.
See that target property for additional information.


code:
CMAKE_ARGC
----------

Number of command line arguments passed to CMake in script mode.

When run in :ref:`-P <Script Processing Mode>` script mode, CMake sets this
variable to the number of command line arguments.  See also
:variable:`CMAKE_ARGV0`, ``1``, ``2`` ...


code:
CMAKE_ARGV0
-----------

Command line argument passed to CMake in script mode.

When run in :ref:`-P <Script Processing Mode>` script mode, CMake sets this
variable to the first command line argument.  It then also sets ``CMAKE_ARGV1``,
``CMAKE_ARGV2``, ... and so on, up to the number of command line arguments
given.  See also :variable:`CMAKE_ARGC`.


code:
CMAKE_AUTOGEN_BETTER_GRAPH_MULTI_CONFIG
---------------------------------------

.. versionadded:: 3.29

This variable is used to initialize the
:prop_tgt:`AUTOGEN_BETTER_GRAPH_MULTI_CONFIG` property on all targets as they
are created.  See that target property for additional information.

By default ``CMAKE_AUTOGEN_BETTER_GRAPH_MULTI_CONFIG`` is unset.


code:
CMAKE_AUTOGEN_COMMAND_LINE_LENGTH_MAX
-------------------------------------

.. versionadded:: 3.29

Command line length limit for autogen targets, i.e. ``moc`` or ``uic``,
that triggers the use of response files on Windows instead of passing all
arguments to the command line.

By default ``CMAKE_AUTOGEN_COMMAND_LINE_LENGTH_MAX`` is unset.


code:
CMAKE_AUTOGEN_ORIGIN_DEPENDS
----------------------------

.. versionadded:: 3.14

Switch for forwarding origin target dependencies to the corresponding
:ref:`<ORIGIN>_autogen` targets.

  .. note::

    If Qt 5.15 or later is used and the generator is either :generator:`Ninja`
    or :ref:`Makefile Generators`, additional target dependencies are added to
    the :ref:`<ORIGIN>_autogen_timestamp_deps` target instead of the
    :ref:`<ORIGIN>_autogen` target.

This variable is used to initialize the :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`
property on all the targets.  See that target property for additional
information.

By default ``CMAKE_AUTOGEN_ORIGIN_DEPENDS`` is ``ON``.


code:
CMAKE_AUTOGEN_PARALLEL
----------------------

.. versionadded:: 3.11

Number of parallel ``moc`` or ``uic`` processes to start when using
:prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`.

This variable is used to initialize the :prop_tgt:`AUTOGEN_PARALLEL` property
on all the targets.  See that target property for additional information.

By default ``CMAKE_AUTOGEN_PARALLEL`` is unset.


code:
CMAKE_AUTOGEN_USE_SYSTEM_INCLUDE
--------------------------------

.. versionadded:: 3.27

This variable is used to initialize the :prop_tgt:`AUTOGEN_USE_SYSTEM_INCLUDE`
property on all targets as they are created.  See that target property for
additional information.

By default ``CMAKE_AUTOGEN_USE_SYSTEM_INCLUDE`` is unset.


code:
CMAKE_AUTOGEN_VERBOSE
---------------------

.. versionadded:: 3.13

Sets the verbosity of :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC` and
:prop_tgt:`AUTORCC`.  A positive integer value or a true boolean value
lets the ``AUTO*`` generators output additional processing information.

Setting ``CMAKE_AUTOGEN_VERBOSE`` has the same effect
as setting the ``VERBOSE`` environment variable during
generation (e.g. by calling ``make VERBOSE=1``).
The extra verbosity is limited to the ``AUTO*`` generators though.

By default ``CMAKE_AUTOGEN_VERBOSE`` is unset.


code:
CMAKE_AUTOMOC
-------------

Whether to handle ``moc`` automatically for Qt targets.

This variable is used to initialize the :prop_tgt:`AUTOMOC` property on all the
targets.  See that target property for additional information.


code:
CMAKE_AUTOMOC_COMPILER_PREDEFINES
---------------------------------

.. versionadded:: 3.10

This variable is used to initialize the :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES`
property on all the targets. See that target property for additional
information.

By default it is ON.


code:
CMAKE_AUTOMOC_DEPEND_FILTERS
----------------------------

.. versionadded:: 3.9

Filter definitions used by :variable:`CMAKE_AUTOMOC`
to extract file names from source code as additional dependencies
for the ``moc`` file.

This variable is used to initialize the :prop_tgt:`AUTOMOC_DEPEND_FILTERS`
property on all the targets. See that target property for additional
information.

By default it is empty.


code:
CMAKE_AUTOMOC_EXECUTABLE
------------------------

.. versionadded:: 3.27

This variable is used to initialize the :prop_tgt:`AUTOMOC_EXECUTABLE`
property on all the targets. See that target property for additional
information.

By default it is empty.


code:
CMAKE_AUTOMOC_MACRO_NAMES
----------------------------

.. versionadded:: 3.10

:ref:`Semicolon-separated list <CMake Language Lists>` list of macro names used by
:variable:`CMAKE_AUTOMOC` to determine if a C++ file needs to be
processed by ``moc``.

This variable is used to initialize the :prop_tgt:`AUTOMOC_MACRO_NAMES`
property on all the targets. See that target property for additional
information.

The default value is ``Q_OBJECT;Q_GADGET;Q_NAMESPACE;Q_NAMESPACE_EXPORT``.

Example
^^^^^^^
Let CMake know that source files that contain ``CUSTOM_MACRO`` must be ``moc``
processed as well::

  set(CMAKE_AUTOMOC ON)
  list(APPEND CMAKE_AUTOMOC_MACRO_NAMES "CUSTOM_MACRO")


code:
CMAKE_AUTOMOC_MOC_OPTIONS
-------------------------

Additional options for ``moc`` when using :variable:`CMAKE_AUTOMOC`.

This variable is used to initialize the :prop_tgt:`AUTOMOC_MOC_OPTIONS` property
on all the targets.  See that target property for additional information.


code:
CMAKE_AUTOMOC_PATH_PREFIX
-------------------------

.. versionadded:: 3.16

Whether to generate the ``-p`` path prefix option for ``moc`` on
:prop_tgt:`AUTOMOC` enabled Qt targets.

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 ``OFF``.


code:
CMAKE_AUTOMOC_RELAXED_MODE
--------------------------

.. deprecated:: 3.15

Switch between strict and relaxed automoc mode.

By default, :prop_tgt:`AUTOMOC` behaves exactly as described in the
documentation of the :prop_tgt:`AUTOMOC` target property.  When set to
``TRUE``, it accepts more input and tries to find the correct input file for
``moc`` even if it differs from the documented behavior.  In this mode it
e.g.  also checks whether a header file is intended to be processed by moc
when a ``"foo.moc"`` file has been included.

Relaxed mode has to be enabled for KDE4 compatibility.


code:
CMAKE_AUTORCC
-------------

Whether to handle ``rcc`` automatically for Qt targets.

This variable is used to initialize the :prop_tgt:`AUTORCC` property on all
the targets.  See that target property for additional information.


code:
CMAKE_AUTORCC_EXECUTABLE
------------------------

.. versionadded:: 3.27

This variable is used to initialize the :prop_tgt:`AUTORCC_EXECUTABLE`
property on all the targets. See that target property for additional
information.

By default it is empty.


code:
CMAKE_AUTORCC_OPTIONS
---------------------

Additional options for ``rcc`` when using :variable:`CMAKE_AUTORCC`.

This variable is used to initialize the :prop_tgt:`AUTORCC_OPTIONS` property on
all the targets.  See that target property for additional information.

EXAMPLE
^^^^^^^

.. code-block:: cmake

  # ...
  set(CMAKE_AUTORCC_OPTIONS "--compress;9")
  # ...


code:
CMAKE_AUTOUIC
-------------

Whether to handle ``uic`` automatically for Qt targets.

This variable is used to initialize the :prop_tgt:`AUTOUIC` property on all
the targets.  See that target property for additional information.


code:
CMAKE_AUTOUIC_EXECUTABLE
------------------------

.. versionadded:: 3.27

This variable is used to initialize the :prop_tgt:`AUTOUIC_EXECUTABLE`
property on all the targets. See that target property for additional
information.

By default it is empty.


code:
CMAKE_AUTOUIC_OPTIONS
---------------------

Additional options for ``uic`` when using :variable:`CMAKE_AUTOUIC`.

This variable is used to initialize the :prop_tgt:`AUTOUIC_OPTIONS` property on
all the targets.  See that target property for additional information.

EXAMPLE
^^^^^^^

.. code-block:: cmake

  # ...
  set_property(CMAKE_AUTOUIC_OPTIONS "--no-protection")
  # ...


code:
CMAKE_AUTOUIC_SEARCH_PATHS
--------------------------

.. versionadded:: 3.9

Search path list used by :variable:`CMAKE_AUTOUIC` to find included
``.ui`` files.

This variable is used to initialize the :prop_tgt:`AUTOUIC_SEARCH_PATHS`
property on all the targets. See that target property for additional
information.

By default it is empty.


code:
CMAKE_BACKWARDS_COMPATIBILITY
-----------------------------

Deprecated.  See CMake Policy :policy:`CMP0001` documentation.


code:
CMAKE_BINARY_DIR
----------------

The path to the top level of the build tree.

This is the full path to the top level of the current CMake build
tree.  For an in-source build, this would be the same as
:variable:`CMAKE_SOURCE_DIR`.

When run in :option:`cmake -P` script mode, CMake sets the variables
``CMAKE_BINARY_DIR``, :variable:`CMAKE_SOURCE_DIR`,
:variable:`CMAKE_CURRENT_BINARY_DIR` and
:variable:`CMAKE_CURRENT_SOURCE_DIR` to the current working directory.


code:
CMAKE_BUILD_RPATH
-----------------

.. versionadded:: 3.8

:ref:`Semicolon-separated list <CMake Language Lists>` specifying runtime path (``RPATH``)
entries to add to binaries linked in the build tree (for platforms that
support it).  The entries will *not* be used for binaries in the install
tree.  See also the :variable:`CMAKE_INSTALL_RPATH` variable.

This is used to initialize the :prop_tgt:`BUILD_RPATH` target property
for all targets.


code:
CMAKE_BUILD_RPATH_USE_ORIGIN
----------------------------

.. versionadded:: 3.14

Whether to use relative paths for the build ``RPATH``.

This is used to initialize the :prop_tgt:`BUILD_RPATH_USE_ORIGIN` target
property for all targets, see that property for more details.


code:
CMAKE_BUILD_TOOL
----------------

This variable exists only for backwards compatibility.
It contains the same value as :variable:`CMAKE_MAKE_PROGRAM`.
Use that variable instead.


code:
CMAKE_BUILD_TYPE
----------------

Specifies the build type on single-configuration generators (e.g.
:ref:`Makefile Generators` or :generator:`Ninja`).  Typical values include
``Debug``, ``Release``, ``RelWithDebInfo`` and ``MinSizeRel``, but custom
build types can also be defined.

This variable is initialized by the first :command:`project` or
:command:`enable_language` command called in a project when a new build
tree is first created.  If the :envvar:`CMAKE_BUILD_TYPE` environment
variable is set, its value is used.  Otherwise, a toolchain-specific
default is chosen when a language is enabled.  The default value is often
an empty string, but this is usually not desirable and one of the other
standard build types is usually more appropriate.

Depending on the situation, the value of this variable may be treated
case-sensitively or case-insensitively.  See :ref:`Build Configurations`
for discussion of this and other related topics.

For multi-config generators, see :variable:`CMAKE_CONFIGURATION_TYPES`.


code:
CMAKE_BUILD_WITH_INSTALL_NAME_DIR
---------------------------------

.. versionadded:: 3.9

Whether to use :prop_tgt:`INSTALL_NAME_DIR` on targets in the build tree.

This variable is used to initialize the :prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR`
property on all targets.


code:
CMAKE_BUILD_WITH_INSTALL_RPATH
------------------------------

Use the install path for the ``RPATH``.

Normally CMake uses the build tree for the ``RPATH`` when building
executables etc on systems that use ``RPATH``.  When the software is
installed the executables etc are relinked by CMake to have the
install ``RPATH``.  If this variable is set to true then the software is
always built with the install path for the ``RPATH`` and does not need to
be relinked when installed.

This is used to initialize the :prop_tgt:`BUILD_WITH_INSTALL_RPATH` target property
for all targets.


code:
CMAKE_CACHEFILE_DIR
-------------------

This variable is used internally by CMake, and may not be set during
the first configuration of a build tree.  When it is set, it has the
same value as :variable:`CMAKE_BINARY_DIR`.  Use that variable instead.


code:
CMAKE_CACHE_MAJOR_VERSION
-------------------------

Major version of CMake used to create the ``CMakeCache.txt`` file

This stores the major version of CMake used to write a CMake cache
file.  It is only different when a different version of CMake is run
on a previously created cache file.


code:
CMAKE_CACHE_MINOR_VERSION
-------------------------

Minor version of CMake used to create the ``CMakeCache.txt`` file

This stores the minor version of CMake used to write a CMake cache
file.  It is only different when a different version of CMake is run
on a previously created cache file.


code:
CMAKE_CACHE_PATCH_VERSION
-------------------------

Patch version of CMake used to create the ``CMakeCache.txt`` file

This stores the patch version of CMake used to write a CMake cache
file.  It is only different when a different version of CMake is run
on a previously created cache file.


code:
CMAKE_CFG_INTDIR
----------------

.. deprecated:: 3.21

  This variable has poor support on :generator:`Ninja Multi-Config`, and
  predates the existence of the :genex:`$<CONFIG>` generator expression. Use
  ``$<CONFIG>`` instead.

Build-time reference to per-configuration output subdirectory.

For native build systems supporting multiple configurations in the
build tree (such as :ref:`Visual Studio Generators` and :generator:`Xcode`),
the value is a reference to a build-time variable specifying the name
of the per-configuration output subdirectory.  On :ref:`Makefile Generators`
this evaluates to `.` because there is only one configuration in a build tree.
Example values:

::

  $(ConfigurationName) = Visual Studio 9
  $(Configuration)     = Visual Studio 12 and above
  $(CONFIGURATION)     = Xcode
  .                    = Make-based tools
  .                    = Ninja
  ${CONFIGURATION}     = Ninja Multi-Config

Since these values are evaluated by the native build system, this
variable is suitable only for use in command lines that will be
evaluated at build time.  Example of intended usage:

::

  add_executable(mytool mytool.c)
  add_custom_command(
    OUTPUT out.txt
    COMMAND ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_CFG_INTDIR}/mytool
            ${CMAKE_CURRENT_SOURCE_DIR}/in.txt out.txt
    DEPENDS mytool in.txt
    )
  add_custom_target(drive ALL DEPENDS out.txt)

Note that ``CMAKE_CFG_INTDIR`` is no longer necessary for this purpose but
has been left for compatibility with existing projects.  Instead
:command:`add_custom_command` recognizes executable target names in its
``COMMAND`` option, so
``${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_CFG_INTDIR}/mytool`` can be replaced
by just ``mytool``.

This variable is read-only.  Setting it is undefined behavior.  In
multi-configuration build systems the value of this variable is passed
as the value of preprocessor symbol ``CMAKE_INTDIR`` to the compilation
of all source files.


code:
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.


code:
CMAKE_CL_64
-----------

Discouraged.  Use :variable:`CMAKE_SIZEOF_VOID_P` instead.

Set to a true value when using a Microsoft Visual Studio ``cl`` compiler that
*targets* a 64-bit architecture.


code:
CMAKE_CODEBLOCKS_COMPILER_ID
----------------------------

.. versionadded:: 3.11

Change the compiler id in the generated CodeBlocks project files.

CodeBlocks uses its own compiler id string which differs from
:variable:`CMAKE_<LANG>_COMPILER_ID`.  If this variable is left empty,
CMake tries to recognize the CodeBlocks compiler id automatically.
Otherwise the specified string is used in the CodeBlocks project file.
See the CodeBlocks documentation for valid compiler id strings.

Other IDEs like QtCreator that also use the CodeBlocks generator may ignore
this setting.


code:
CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES
---------------------------------------

.. versionadded:: 3.10

Change the way the CodeBlocks generator creates project files.

If this variable evaluates to ``ON`` the generator excludes from
the project file any files that are located outside the project root.


code:
CMAKE_CODELITE_USE_TARGETS
--------------------------

.. versionadded:: 3.7

Change the way the CodeLite generator creates projectfiles.

If this variable evaluates to ``ON`` at the end of the top-level
``CMakeLists.txt`` file, the generator creates projectfiles based on targets
rather than projects.


code:
CMAKE_COLOR_DIAGNOSTICS
-----------------------

.. versionadded:: 3.24

Enable color diagnostics throughout.

This variable uses three states: ``ON``, ``OFF`` and not defined.

When not defined:

* :ref:`Makefile Generators` initialize the :variable:`CMAKE_COLOR_MAKEFILE`
  variable to ``ON``.  It controls color buildsystem messages.

* GNU/Clang compilers are not invoked with any color diagnostics flag.

When ``ON``:

* :ref:`Makefile Generators` produce color buildsystem messages by default.
  :variable:`CMAKE_COLOR_MAKEFILE` is not initialized, but may be
  explicitly set to ``OFF`` to disable color buildsystem messages.

* GNU/Clang compilers are invoked with a flag enabling color diagnostics
  (``-fcolor-diagnostics``).

When ``OFF``:

* :ref:`Makefile Generators` do not produce color buildsystem messages by
  default.  :variable:`CMAKE_COLOR_MAKEFILE` is not initialized, but may be
  explicitly set to ``ON`` to enable color buildsystem messages.

* GNU/Clang compilers are invoked with a flag disabling color diagnostics
  (``-fno-color-diagnostics``).

If the :envvar:`CMAKE_COLOR_DIAGNOSTICS` environment variable is set, its
value is used.  Otherwise, ``CMAKE_COLOR_DIAGNOSTICS`` is not defined by
default.


code:
CMAKE_COLOR_MAKEFILE
--------------------

Enables color output when using the :ref:`Makefile Generators`.

When enabled, the generated Makefiles will produce colored output.
Default is ``ON``.