Commit acbbccf7 authored by Brad King's avatar Brad King
Browse files

Help: Organize and revise 3.11 release notes

Add section headers similar to the 3.10 release notes and move each
individual bullet into an appropriate section.  Revise a few bullets.
parent 22ac06ed
......@@ -7,140 +7,51 @@ CMake 3.11 Release Notes
Changes made since CMake 3.10 include the following.
* When using :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC`, CMake starts multiple
parallel ``moc`` or ``uic`` processes to reduce the build time.
The new :variable:`CMAKE_AUTOGEN_PARALLEL` variable and
:prop_tgt:`AUTOGEN_PARALLEL` target property allow to modify the number of
parallel ``moc`` or ``uic`` processes to start.
By default CMake starts a single ``moc`` or ``uic`` process for each physical
CPU on the host system.
New Features
============
* The :module:`FindBLAS` and :module:`FindLAPACK` modules learned to support
`FLAME <https://github.com/flame>`__ ``blis`` and ``libflame``.
* Variables containing newlines in their values now get truncated before the
newline when they are written to the cache file. In addition, a warning
comment is written to the cache file, and a warning message is displayed to
the user on the console.
* The :module:`CheckIncludeFile` module ``check_include_file`` macro
learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable.
* The :module:`CheckIncludeFileCXX` module ``check_include_file_cxx`` macro
learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable.
* The :module:`CheckIncludeFiles` module ``check_include_files`` macro
learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable.
Platforms
---------
* The :module:`CheckIncludeFiles` module :command:`CHECK_INCLUDE_FILES`
command gained a ``LANGUAGE`` option to specify whether to check using the
``C`` or ``CXX`` compiler.
* The :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable was added
to enable setting of default permissions for directories created implicitly
during installation of files by :command:`install` and
:command:`file(INSTALL)`.
* The :variable:`CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable was added
which serves the same purpose during packaging as the
:variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable serves during
installation (e.g. ``make install``).
* A :variable:`CMAKE_JOB_POOLS` variable was added specify a value to use for
the :prop_gbl:`JOB_POOLS` property. This enables control over build
parallelism with command line configuration parameters when using the Ninja
generator.
* TI C/C++ compilers are now supported by the :generator:`Ninja` generator.
* The :manual:`cmake(1)` ``--open <dir>`` command line option can now
be used to open generated IDE projects like Visual Studio solutions
or Xcode projects.
Generators
----------
* The :generator:`CodeBlocks` extra generator learned to check a
:variable:`CMAKE_CODEBLOCKS_COMPILER_ID` variable for a custom
compiler identification value to place in the project file.
* The :module:`CPackIFW` module gained new
:variable:`CPACK_IFW_PACKAGE_REMOVE_TARGET_DIR` variable to control
if the target directory should not be deleted when uninstalling.
* The :module:`CPackRPM` module learned to enable enforcing of execute
privileges on programs and shared libraries.
See :variable:`CPACK_RPM_INSTALL_WITH_EXEC` variable.
* :manual:`cpack(1)` gained ``--trace`` and ``--trace-expand`` options.
* The :command:`ctest_start` command no longer sets
:variable:`CTEST_RUN_CURRENT_SCRIPT` due to issues with scoping if it is
called from inside a function. Instead, it sets an internal variable in
CTest. However, setting :variable:`CTEST_RUN_CURRENT_SCRIPT` to 0 at the
global scope still prevents the script from being re-run at the end.
* A :variable:`CMAKE_CUDA_SEPARABLE_COMPILATION` variable was added to
initialize the :prop_tgt:`CUDA_SEPARABLE_COMPILATION` target property
on targets when they are created.
* The :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands
gained ``NETRC`` and ``NETRC_FILE`` options to specify use of a
``.netrc`` file.
* The :module:`ExternalProject` module gained ``NETRC`` and ``NETRC_FILE``
options to specify use of a ``.netrc`` file.
* The :variable:`CMAKE_NETRC` and :variable:`CMAKE_NETRC_FILE` variables
were added to specify use of a ``.netrc`` file by the
:command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands and
the :module:`ExternalProject` module.
* :command:`add_library` and :command:`add_executable` commands can now be
called without any sources and will not complain as long as sources will
be added later via :command:`target_sources`.
* An explicit deprecation diagnostic was added for policies ``CMP0037``
through ``CMP0054`` (``CMP0036`` and below were already deprecated).
The :manual:`cmake-policies(7)` manual explains that the OLD behaviors
of all policies are deprecated and that projects should port to the
NEW behaviors.
* The :command:`doxygen_add_docs` function of the :module:`FindDoxygen` module
now supports a new ``DOXYGEN_VERBATIM_VARS`` list variable. Any
``DOXYGEN_...`` variable contained in that list will bypass the automatic
quoting logic, leaving its contents untouched when transferring them to the
output Doxyfile.
* The :ref:`Makefile Generators` and the :generator:`Ninja` generator learned
to add compiler launcher tools along with the compiler for the ``Fortran``
language (``C``, ``CXX``, and ``CUDA`` were supported previously).
See the :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable and
:prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property for details.
* :ref:`Visual Studio Generators` learned to support the ``COMPILE_LANGUAGE``
:manual:`generator expression <cmake-generator-expressions(7)>` in
target-wide :prop_tgt:`COMPILE_DEFINITIONS`,
:prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_OPTIONS`, and
:command:`file(GENERATE)`.
:command:`file(GENERATE)`. See generator expression documentation
for caveats.
* The :generator:`Xcode` generator learned to support the ``COMPILE_LANGUAGE``
:manual:`generator expression <cmake-generator-expressions(7)>` in
target-wide :prop_tgt:`COMPILE_DEFINITIONS` and
:prop_tgt:`INCLUDE_DIRECTORIES`. It previously supported only
:prop_tgt:`COMPILE_OPTIONS` and :command:`file(GENERATE)`.
See generator expression documentation for caveats.
* The :module:`ExternalProject` module learnt to substitute ``<DOWNLOAD_DIR>``
in comments, commands, working directory and byproducts.
Commands
--------
* A new :module:`FetchContent` module was added which supports populating
content at configure time using any of the download/update methods
supported by :command:`ExternalProject_Add`. This allows the content
to be used immediately during the configure stage, such as with
:command:`add_subdirectory`, etc. Hierarchical project structures are
well supported, allowing parent projects to override the content details
of child projects and ensuring content is not populated multiple times
throughout the whole project tree.
* A :module:`FindIconv` module was added to locate iconv support.
* The :module:`FindOpenGL` module now prefers GLVND libraries if available.
See policy :policy:`CMP0072`.
* :command:`add_library` and :command:`add_executable` commands can now be
called without any sources and will not complain as long as sources are
added later via the :command:`target_sources` command.
* The :ref:`Makefile Generators` and the :generator:`Ninja` generator learned
to add compiler launcher tools along with the compiler for the ``Fortran``
language (``C``, ``CXX``, and ``CUDA`` were supported previously).
See the :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable and
:prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property for details.
* The :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands
gained ``NETRC`` and ``NETRC_FILE`` options to specify use of a
``.netrc`` file.
* The :command:`target_compile_definitions` command learned to set the
:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` property on
......@@ -162,14 +73,8 @@ Changes made since CMake 3.10 include the following.
* The :command:`target_link_libraries` command learned to set the
:prop_tgt:`INTERFACE_LINK_LIBRARIES` property on :ref:`Imported Targets`.
* :ref:`Alias Targets` may now alias :ref:`Imported Targets` that are
created with the ``GLOBAL`` option to :command:`add_library`.
* The :module:`GenerateExportHeader` module learned an optional
``INCLUDE_GUARD_NAME`` parameter to change the name of the include guard
symbol written to the generated export header.
Additionally, it now adds a comment after the closing ``#endif`` on the
generated export header's include guard.
Variables
---------
* A :variable:`CMAKE_GENERATOR_INSTANCE` variable was introduced
to hold the selected instance of the generator's corresponding
......@@ -177,64 +82,197 @@ Changes made since CMake 3.10 include the following.
:generator:`Visual Studio 15 2017` generator to hold the
selected instance of Visual Studio persistently.
* Added new target-property :prop_tgt:`IMPORTED_GLOBAL` which
indicates if an :ref:`IMPORTED target <Imported Targets>` is
globally visible.
It will be set automatically if such an imported target is
created with the ``GLOBAL`` flag.
* A :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable was added
to enable setting of default permissions for directories created implicitly
during installation of files by :command:`install` and
:command:`file(INSTALL)`, e.g. during ``make install``.
* Additionally, it is now also possible to promote a local imported
target to become globally visible by setting its
:prop_tgt:`IMPORTED_GLOBAL` property to `TRUE`. (However, this
promotion can only succeed if it is done from within the same
directory where the imported target was created in the first
place.) Setting it to `FALSE` is not supported!
* A :variable:`CMAKE_JOB_POOLS` variable was added specify a value to use for
the :prop_gbl:`JOB_POOLS` property. This enables control over build
parallelism with command line configuration parameters when using the Ninja
generator.
* The minimum deployment target set in the
:variable:`CMAKE_OSX_DEPLOYMENT_TARGET` variable used to be only
applied for macOS regardless of the selected SDK. It is now properly
set for the target platform selected by :variable:`CMAKE_OSX_SYSROOT`.
* The :variable:`CMAKE_NETRC` and :variable:`CMAKE_NETRC_FILE` variables
were added to specify use of a ``.netrc`` file by the
:command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands and
the :module:`ExternalProject` module.
If for example the sysroot variable specifies an iOS SDK then the
value in ``CMAKE_OSX_DEPLOYMENT_TARGET`` is interpreted as minimum
iOS version.
* A :variable:`CMAKE_CUDA_SEPARABLE_COMPILATION` variable was added to
initialize the :prop_tgt:`CUDA_SEPARABLE_COMPILATION` target property
on targets when they are created.
* The ``KDevelop3`` generator has been removed.
Properties
----------
* The :prop_sf:`COMPILE_DEFINITIONS` source file property learned to support
:manual:`generator expressions <cmake-generator-expressions(7)>`.
* Source file learns new properties:
* A :prop_sf:`COMPILE_OPTIONS` source file property was added to manage list
of options to pass to the compiler.
* A :prop_sf:`COMPILE_OPTIONS` source file property was added to manage list
of options to pass to the compiler.
* An :prop_tgt:`IMPORTED_GLOBAL` target property was added to indicate
whether an :ref:`IMPORTED target <Imported Targets>` is globally visible.
It is automatically set to a true value for targets created with the
``GLOBAL`` option to :command:`add_library` or :command:`add_executable`.
Additionally, project code may now *promote* a local imported target
to be globally visible by setting this property to ``TRUE``.
* An :prop_sf:`INCLUDE_DIRECTORIES` source file property was added to specify
list of preprocessor include file search directories.
* TI C/C++ compilers are now supported by the :generator:`Ninja` generator.
* | The command add_jar from :module:`UseJava` module learns how to generate native
headers files using option -h of javac tool.
| This capability requires, at least, version 1.8 of Javac tool.
| Command create_javah will no longer be supported due to the
`suppression of javah tool <http://openjdk.java.net/jeps/313>`_ in the version 1.10
of the JDK, so ``add_jar(GENERATE_NATIVE_HEADERS)`` must be used instead.
* An :prop_sf:`INCLUDE_DIRECTORIES` source file property was added to specify
list of preprocessor include file search directories.
* Source file properties :prop_sf:`VS_SHADER_DISABLE_OPTIMIZATIONS` and
:prop_sf:`VS_SHADER_ENABLE_DEBUG` have been added to specify more
details of ``.hlsl`` sources with :ref:`Visual Studio Generators`.
* ``INTERFACE`` libraries may now have custom properties set on them if they
start with either an underscore (``_``) or a lowercase ASCII character. The
original intention was to only allow properties which made sense for
Modules
-------
* The :module:`CheckIncludeFile` module ``check_include_file`` macro
learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable.
* The :module:`CheckIncludeFileCXX` module ``check_include_file_cxx`` macro
learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable.
* The :module:`CheckIncludeFiles` module ``check_include_files`` macro
learned to honor the ``CMAKE_REQUIRED_LIBRARIES`` variable.
* The :module:`CheckIncludeFiles` module :command:`CHECK_INCLUDE_FILES`
command gained a ``LANGUAGE`` option to specify whether to check using the
``C`` or ``CXX`` compiler.
* The :module:`CMakePackageConfigHelpers` module
:command:`write_basic_package_version_file` command learned a new
``SameMinorVersion`` mode for the ``COMPATIBILITY`` argument.
* The :module:`ExternalProject` module learned to substitute ``<DOWNLOAD_DIR>``
in comments, commands, working directory and byproducts.
* The :module:`ExternalProject` module gained ``NETRC`` and ``NETRC_FILE``
options to specify use of a ``.netrc`` file.
* A new :module:`FetchContent` module was added which supports populating
content at configure time using any of the download/update methods
supported by :command:`ExternalProject_Add`. This allows the content
to be used immediately during the configure stage, such as with
:command:`add_subdirectory`, etc. Hierarchical project structures are
well supported, allowing parent projects to override the content details
of child projects and ensuring content is not populated multiple times
throughout the whole project tree.
* The :module:`FindBLAS` and :module:`FindLAPACK` modules learned to support
`FLAME`_ ``blis`` and ``libflame``.
* The :module:`FindDoxygen` module :command:`doxygen_add_docs` function
now supports a new ``DOXYGEN_VERBATIM_VARS`` list variable. Any
``DOXYGEN_...`` variable contained in that list will bypass the automatic
quoting logic, leaving its contents untouched when transferring them to the
output ``Doxyfile``.
* A :module:`FindIconv` module was added to locate iconv support.
* The :module:`GenerateExportHeader` module ``GENERATE_EXPORT_HEADER`` command
gained an ``INCLUDE_GUARD_NAME`` option to change the name of the include
guard symbol written to the generated export header.
Additionally, it now adds a comment after the closing ``#endif`` on the
generated export header's include guard.
* The :module:`UseJava` module ``add_jar`` command gained a
``GENERATE_NATIVE_HEADERS`` option to generate native header files
using ``javac -h`` for ``javac`` 1.8 or above. This supersedes
``create_javah``, which no longer works with JDK 1.10 and above due
to removal of the ``javah`` tool by `JEP 313`_.
.. _`FLAME`: https://github.com/flame
.. _`JEP 313`: http://openjdk.java.net/jeps/313
Autogen
-------
* When using :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC`, CMake now starts
multiple parallel ``moc`` or ``uic`` processes to reduce the build time.
A new :variable:`CMAKE_AUTOGEN_PARALLEL` variable and
:prop_tgt:`AUTOGEN_PARALLEL` target property may be set to specify the
number of parallel ``moc`` or ``uic`` processes to start. The default
is derived from the number of CPUs on the host.
CTest
-----
* The :command:`ctest_start` command no longer sets
:variable:`CTEST_RUN_CURRENT_SCRIPT` due to issues with scoping if it is
called from inside a function. Instead, it sets an internal variable in
CTest. However, setting :variable:`CTEST_RUN_CURRENT_SCRIPT` to 0 at the
global scope still prevents the script from being re-run at the end.
CPack
-----
* :manual:`cpack(1)` gained ``--trace`` and ``--trace-expand`` options.
* The :module:`CPackIFW` module gained new
:variable:`CPACK_IFW_PACKAGE_REMOVE_TARGET_DIR` variable to control
if the target directory should not be deleted when uninstalling.
* The :module:`CPackRPM` module learned to enable enforcing of execute
privileges on programs and shared libraries.
See :variable:`CPACK_RPM_INSTALL_WITH_EXEC` variable.
* A :variable:`CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable was added
which serves the same purpose during packaging (e.g. ``make package``) as the
:variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable serves during
installation (e.g. ``make install``).
Other
-----
* :ref:`Alias Targets` may now alias :ref:`Imported Targets` that are
created with the ``GLOBAL`` option to :command:`add_library`.
* :ref:`Interface Libraries` may now have custom properties set on them if
they start with either an underscore (``_``) or a lowercase ASCII character.
The original intention was to only allow properties which made sense for
``INTERFACE`` libraries, but it also blocked usage of custom properties.
* The :command:`write_basic_package_version_file` understands a new
``SameMinorVersion`` option for the ``COMPATIBILITY`` argument.
* The :manual:`cmake(1)` ``--open <dir>`` command-line option was added
to open generated IDE projects like Visual Studio solutions or Xcode
projects.
Deprecated and Removed Features
===============================
* An explicit deprecation diagnostic was added for policies ``CMP0037``
through ``CMP0054`` (``CMP0036`` and below were already deprecated).
The :manual:`cmake-policies(7)` manual explains that the OLD behaviors
of all policies are deprecated and that projects should port to the
NEW behaviors.
* The ``KDevelop3`` generator has been removed.
Other Changes
=============
* Policy :policy:`CMP0037` no longer reserves target names associated
with optional features, such as ``test`` and ``package``, unless
the corresponding feature is enabled.
* The :module:`FindOpenGL` module now prefers GLVND libraries if available.
See policy :policy:`CMP0072`.
* The minimum deployment target set in the
:variable:`CMAKE_OSX_DEPLOYMENT_TARGET` variable used to be only
applied for macOS regardless of the selected SDK. It is now properly
set for the target platform selected by :variable:`CMAKE_OSX_SYSROOT`.
For example, if the sysroot variable specifies an iOS SDK then the
value in ``CMAKE_OSX_DEPLOYMENT_TARGET`` is interpreted as minimum
iOS version.
* The :generator:`Xcode` generator behavior of generating one project
file per :command:`project()` command could now be controlled with the
file per :command:`project()` command may now be controlled with the
:variable:`CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY` variable.
This could be useful to speed up the CMake generation step for
large projects and to work-around a bug in the ``ZERO_CHECK`` logic.
* Since the ``CMakeCache.txt`` format does not support newlines in values,
values containing newlines are now truncated before writing to the file.
In addition, a warning comment is written to the cache file, and a warning
message is displayed to the user on the console.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment