diff --git a/Help/release/3.4.rst b/Help/release/3.4.rst index 448ea35e0..8cc0796a3 100644 --- a/Help/release/3.4.rst +++ b/Help/release/3.4.rst @@ -7,6 +7,16 @@ CMake 3.4 Release Notes Changes made since CMake 3.4 include the following. +New Features +============ + +Generators +---------- + +* The :generator:`Visual Studio 14 2015` generator learned to select + a Windows 10 SDK based on the value of the :variable:`CMAKE_SYSTEM_VERSION` + variable and the SDKs available on the host. + * CMake learned rudimentary support for the Apple Swift language. When using the :generator:`Xcode` generator with Xcode 6.1 or higher, one may enable the ``Swift`` language with the :command:`enable_language` command or the @@ -14,6 +24,38 @@ Changes made since CMake 3.4 include the following. Xcode is too old). Then one may list ``.swift`` source files in targets for compilation. +Commands +-------- + +* The :command:`find_program` command learned a ``NAMES_PER_DIR`` + option to consider all given ``NAMES`` in each directory before + moving on to the next directory. + +* The :command:`get_filename_component` command learned a new ``BASE_DIR`` + subcommand. This is used to specify a base directory when calculating an + absolute path from a relative path. + +* The :command:`if` command learned a new ``TEST`` operator that evaluates + to true if a given test name has been defined by the :command:`add_test` + command. See policy :policy:`CMP0064`. + +* The :command:`install(DIRECTORY)` command ``DESTINATION`` option learned to + support :manual:`generator expressions `. + +* The :command:`install(FILES)` command ``DESTINATION`` option learned to + support :manual:`generator expressions `. + +* The :command:`string` command learned a new ``APPEND`` subcommand. + +Variables +--------- + +* The :ref:`Makefile Generators` and the :generator:`Ninja` generator + learned to add compiler launcher tools like distcc and ccache along + with the compiler for ``C`` and ``CXX`` languages. See the + :variable:`CMAKE__COMPILER_LAUNCHER` variable and + :prop_tgt:`_COMPILER_LAUNCHER` target property for details. + * New :variable:`CMAKE_LINK_SEARCH_START_STATIC` and :variable:`CMAKE_LINK_SEARCH_END_STATIC` variables were introduced to initialize the @@ -21,191 +63,8 @@ Changes made since CMake 3.4 include the following. :prop_tgt:`LINK_SEARCH_END_STATIC` target properties, respectively. -* On Windows with MS-compatible tools, CMake learned to optionally - generate a module definition (``.def``) file for ``SHARED`` libraries. - See the :prop_tgt:`WINDOWS_EXPORT_ALL_SYMBOLS` target property. - -* The :ref:`Makefile Generators` and the :generator:`Ninja` generator - learned to add compiler launcher tools like distcc and ccache along with the - compiler for ``C`` and ``CXX`` languages. See the - :variable:`CMAKE__COMPILER_LAUNCHER` variable and - :prop_tgt:`_COMPILER_LAUNCHER` target property for details. - -* The `Concurrent Fortran 77 `__ compiler is now supported. - Its :variable:`compiler id _COMPILER_ID>` is ``CCur``. - -* The :module:`CPackDeb` module now correctly excludes symlinks during package checksum calculation. - -* The :module:`CPackDeb` module learned to set package dependencies - per component. See :variable:`CPACK_DEBIAN__PACKAGE_PREDEPENDS`, - :variable:`CPACK_DEBIAN__PACKAGE_ENHANCES`, - :variable:`CPACK_DEBIAN__PACKAGE_BREAKS`, - :variable:`CPACK_DEBIAN__PACKAGE_CONFLICTS`, - :variable:`CPACK_DEBIAN__PACKAGE_PROVIDES`, - :variable:`CPACK_DEBIAN__PACKAGE_REPLACES`, - :variable:`CPACK_DEBIAN__PACKAGE_RECOMMENDS` and - :variable:`CPACK_DEBIAN__PACKAGE_SUGGESTS`. - -* :module:`CPackDeb` no longer uses fakeroot and system tar program for packaging. - -* The :module:`CPack` module learned to package empty directories. - -* The :module:`CPack` module no longer mangles settings with CMake-special - characters when they're used as defaults for other settings. The macro - ``cpack_set_if_not_set``, which was responsible for this, is now deprecated. - -* The :module:`CPack` module gained a new setting, ``CPACK_VERBATIM_VARIABLES``, - which can be used to ensure the cpack program receives the settings' values - exactly as they were set, even if they contain CMake-special characters. - For compatibility, it's off by default. - -* :manual:`ctest(1)` learned options - ``--test-output-size-passed`` and ``--test-output-size-failed`` - to customize the limit on test output size submitted when - running as a :ref:`Dashboard Client`. - -* CTest learned to optionally measure the CPU load during parallel - testing and avoid starting tests that may cause the load to exceed - a given threshold. See the :manual:`ctest(1)` command ``--test-load`` - option, the ``TestLoad`` setting of the :ref:`CTest Test Step`, - the :variable:`CTEST_TEST_LOAD` variable, and the ``TEST_LOAD`` - option of the :command:`ctest_test` command. - -* The :module:`CMakeExpandImportedTargets` module is now documented - as deprecated. See module documentation for an explanation. - -* The :module:`ExternalProject` module :command:`ExternalProject_Add` - function ``GIT_SUBMODULES`` option now also limits the set of - submodules that are initialized in addition to the prior behavior - of limiting the set of submodules that are updated. - -* Use "git stash save --all" only if supported. The --all option for git-stash - wasn't introduced until git version 1.7.6. - -* The :module:`ExternalProject` module learned new ``USES_TERMINAL`` - arguments for giving steps exclusive terminal access. Especially - useful with the :generator:`Ninja` generator to monitor CMake - superbuild progress and prevent CPU oversubscription. - -* The :module:`FindBISON` module ``BISON_TARGET`` macro learned a - new ``DEFINES_FILE`` option to specify a custom output header - to be generated. - -* The :module:`FindHDF5` module learend a new ``HDF5_PREFER_PARALLEL`` - option allowing users to specify that a parallel HDF5 tool is - preferred if both are available. - -* The :module:`FindIce` module now provides imported targets. - -* The :module:`FindOpenSSL` module now provides imported targets. - -* The :module:`FindOpenSSL` module learned a new ``OPENSSL_USE_STATIC_LIBS`` - option to search only for static libraries. - -* The :command:`find_program` command learned a ``NAMES_PER_DIR`` - option to consdier all given ``NAMES`` in each directory before - moving on to the next directory. - -* The :module:`FindProtobuf` module gained a new - :command:`protobuf_generate_python` function to generate python - sources from ``.proto`` files. - -* The :module:`FindTIFF` module learned to search separately for - debug and release variants. - -* The :module:`FindwxWidgets` module learned to support version requests. - -* The :module:`FindXercesC` module learned to search separately for - debug and release variants. - -* The :module:`FindZLIB` module learned to search separately for - debug and release variants. - -* A new ``$`` - :manual:`generator expression ` - has been added. - -* The :command:`get_filename_component` command learned a new ``BASE_DIR`` - subcommand. This is used to specify a base directory when calculating an - absolute path from a relative path. - -* The :module:`GNUInstallDirs` module learned special default values - for certain installation prefixes according to the `GNU Coding - Standards`_ and the `Filesystem Hierarchy Standard`_. - -.. _`GNU Coding Standards`: https://www.gnu.org/prep/standards/html_node/Directory-Variables.html -.. _`Filesystem Hierarchy Standard`: https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html - -* Add a new TEST operator to if() that evaluates to true - if a given test name has been defined. - -* The :command:`install(DIRECTORY)` command ``DESTINATION`` option learned to - support :manual:`generator expressions `. - -* The :command:`install(FILES)` command ``DESTINATION`` option learned to - support :manual:`generator expressions `. - -* The :module:`FindJava` module learned to optionally find - the ``idlj`` and ``jarsigner`` tools. - -* The :module:`UseJava` module ``add_jar`` function learned - to support response files (e.g. ``@srcs.txt``) for source - specification. - -* The :module:`UseJava` module ``install_jar`` function learned - new ``DESTINATION`` and ``COMPONENT`` options to specify - the corresponding :command:`install` command options. - -* The :module:`UseJava` module gained a new ``create_javah`` - function to create C headers from Java classes. - -* A :prop_gbl:`TARGET_MESSAGES` global property was added to tell the - :ref:`Makefile Generators` whether to generate commands to print output - after each target is completed. - -* The :manual:`Compile Features ` functionality - is now aware of features supported by GNU C compilers on Windows. - -* The ``SONAME`` field is no longer set for ``MODULE`` libraries - created with the :command:`add_library` command. ``MODULE`` - libraries are meant for explicit dynamic loading at runtime. - They cannot be linked so ``SONAME`` is not useful. - -* CMake learned to honor ``*.manifest`` source files with MSVC tools. - Manifest files named as sources of ``.exe`` and ``.dll`` targets - will be merged with linker-generated manifests and embedded in the - binary. - -* The :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`, - :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY`, and - :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` target properties learned to - support :manual:`generator expressions `. - -* The :prop_tgt:`OUTPUT_NAME` target property and its variants learned to - support :manual:`generator expressions `. - -* The :module:`FindPkgConfig` learned a new :command:`pkg_get_variable` - command which may be used to query for arbitrary variables from a package - (such as for related tools or data and plugin install paths). - -* The :variable:`CMAKE_USE_RELATIVE_PATHS` variable no longer has any - effect. Previously it was partially implemented and unreliable. - -* CMake no longer links executables with flags to export symbols - unless the :prop_tgt:`ENABLE_EXPORTS` target property is set. - See policy :policy:`CMP0065`. - -* The :command:`string` command learned a new ``APPEND`` subcommand. - -* The :prop_tgt:`SOURCE_DIR` and :prop_tgt:`BINARY_DIR` target properties - were introduced to allow project code to query where a target is defined. - -* The :module:`CheckFunctionExists`, :module:`CheckLibraryExists`, - :module:`CheckSymbolExists`, and :module:`FindThreads` modules learned to - work in environments where only CXX is enabled. - -* Add ``--trace-expand`` argument to CMake. Acts like ``--trace``, but expands - variable references in the output. +Properties +---------- * :ref:`Visual Studio Generators` learned to support additonal target properties to customize projects for NVIDIA Nsight @@ -226,6 +85,185 @@ Changes made since CMake 3.4 include the following. * :prop_tgt:`ANDROID_SKIP_ANT_STEP` * :prop_tgt:`ANDROID_STL_TYPE` -* The :generator:`Visual Studio 14 2015` generator learned to select - a Windows 10 SDK based on the value of the :variable:`CMAKE_SYSTEM_VERSION` - variable and the SDKs available on the host. +* The :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`, + :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY`, and + :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` target properties learned to + support :manual:`generator expressions `. + +* The :prop_tgt:`SOURCE_DIR` and :prop_tgt:`BINARY_DIR` target properties + were introduced to allow project code to query where a target is defined. + +* The :prop_tgt:`OUTPUT_NAME` target property and its variants learned to + support :manual:`generator expressions `. + +* A :prop_gbl:`TARGET_MESSAGES` global property was added to tell the + :ref:`Makefile Generators` whether to generate commands to print output + after each target is completed. + +* On Windows with MS-compatible tools, CMake learned to optionally + generate a module definition (``.def``) file for ``SHARED`` libraries. + See the :prop_tgt:`WINDOWS_EXPORT_ALL_SYMBOLS` target property. + +Modules +------- + +* The :module:`ExternalProject` module :command:`ExternalProject_Add` + function ``GIT_SUBMODULES`` option now also limits the set of + submodules that are initialized in addition to the prior behavior + of limiting the set of submodules that are updated. + +* The :module:`ExternalProject` module learned new ``USES_TERMINAL`` + arguments for giving steps exclusive terminal access. This is + useful with the :generator:`Ninja` generator to monitor CMake + superbuild progress and prevent CPU oversubscription. + +* The :module:`FindBISON` module ``BISON_TARGET`` macro learned a + new ``DEFINES_FILE`` option to specify a custom output header + to be generated. + +* The :module:`FindHDF5` module learend a new ``HDF5_PREFER_PARALLEL`` + option allowing users to specify that a parallel HDF5 tool is + preferred if both are available. + +* The :module:`FindIce` module now provides imported targets. + +* The :module:`FindJava` module learned to optionally find + the ``idlj`` and ``jarsigner`` tools. + +* The :module:`FindOpenSSL` module now provides imported targets. + +* The :module:`FindOpenSSL` module learned a new ``OPENSSL_USE_STATIC_LIBS`` + option to search only for static libraries. + +* The :module:`FindPkgConfig` learned a new :command:`pkg_get_variable` + command which may be used to query for arbitrary variables from a package + (such as for related tools or data and plugin install paths). + +* The :module:`FindProtobuf` module gained a new + :command:`protobuf_generate_python` function to generate python + sources from ``.proto`` files. + +* The :module:`FindTIFF` module learned to search separately for + debug and release variants. + +* The :module:`FindwxWidgets` module learned to support version requests. + +* The :module:`FindXercesC` module learned to search separately for + debug and release variants. + +* The :module:`FindZLIB` module learned to search separately for + debug and release variants. + +* The :module:`GNUInstallDirs` module learned special default values + for certain installation prefixes according to the `GNU Coding + Standards`_ and the `Filesystem Hierarchy Standard`_. + +* The :module:`UseJava` module ``add_jar`` function learned + to support response files (e.g. ``@srcs.txt``) for source + specification. + +* The :module:`UseJava` module ``install_jar`` function learned + new ``DESTINATION`` and ``COMPONENT`` options to specify + the corresponding :command:`install` command options. + +* The :module:`UseJava` module gained a new ``create_javah`` + function to create C headers from Java classes. + +.. _`GNU Coding Standards`: https://www.gnu.org/prep/standards/html_node/Directory-Variables.html +.. _`Filesystem Hierarchy Standard`: https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html + +Generator Expressions +--------------------- + +* A new ``$`` + :manual:`generator expression ` + has been added. + +CTest +----- + +* CTest learned to optionally measure the CPU load during parallel + testing and avoid starting tests that may cause the load to exceed + a given threshold. See the :manual:`ctest(1)` command ``--test-load`` + option, the ``TestLoad`` setting of the :ref:`CTest Test Step`, + the :variable:`CTEST_TEST_LOAD` variable, and the ``TEST_LOAD`` + option of the :command:`ctest_test` command. + +* :manual:`ctest(1)` learned options + ``--test-output-size-passed`` and ``--test-output-size-failed`` + to customize the limit on test output size submitted when + running as a :ref:`Dashboard Client`. + +CPack +----- + +* The :module:`CPackDeb` module learned to set package dependencies + per component. See variables: + + * :variable:`CPACK_DEBIAN__PACKAGE_BREAKS` + * :variable:`CPACK_DEBIAN__PACKAGE_CONFLICTS` + * :variable:`CPACK_DEBIAN__PACKAGE_ENHANCES` + * :variable:`CPACK_DEBIAN__PACKAGE_PREDEPENDS` + * :variable:`CPACK_DEBIAN__PACKAGE_PROVIDES` + * :variable:`CPACK_DEBIAN__PACKAGE_RECOMMENDS` + * :variable:`CPACK_DEBIAN__PACKAGE_REPLACES` + * :variable:`CPACK_DEBIAN__PACKAGE_SUGGESTS` + +* The :module:`CPack` module learned to package empty directories. + +* The :module:`CPack` module gained a new setting, ``CPACK_VERBATIM_VARIABLES``, + which can be used to ensure the cpack program receives the settings' values + exactly as they were set, even if they contain CMake-special characters. + For compatibility, it's off by default. + +Other +----- + +* The :manual:`Compile Features ` functionality + is now aware of features supported by GNU C compilers on Windows. + +* CMake learned to honor ``*.manifest`` source files with MSVC tools. + Manifest files named as sources of ``.exe`` and ``.dll`` targets + will be merged with linker-generated manifests and embedded in the + binary. + +* The `Concurrent Fortran 77 `__ compiler is now supported. + Its :variable:`compiler id _COMPILER_ID>` is ``CCur``. + +* :manual:`cmake(1)` gained a new ``--trace-expand`` command line option + that is like ``--trace`` but expands variable references in the output. + +Deprecated and Removed Features +=============================== + +* The :module:`CMakeExpandImportedTargets` module is now documented + as deprecated. See module documentation for an explanation. + +* The :variable:`CMAKE_USE_RELATIVE_PATHS` variable no longer has any + effect. Previously it was partially implemented and unreliable. + +Other Changes +============= + +* The :module:`CheckFunctionExists`, :module:`CheckLibraryExists`, + :module:`CheckSymbolExists`, and :module:`FindThreads` modules learned to + work in environments where only CXX is enabled. + +* The :module:`CPackDeb` module now correctly excludes symlinks during package + checksum calculation. + +* The :module:`CPackDeb` no longer uses fakeroot and system tar program for + packaging. + +* The :module:`CPack` module no longer mangles settings with CMake-special + characters when they're used as defaults for other settings. The macro + ``cpack_set_if_not_set``, which was responsible for this, is now deprecated. + +* CMake no longer links executables with flags to export symbols + unless the :prop_tgt:`ENABLE_EXPORTS` target property is set. + See policy :policy:`CMP0065`. + +* The ``SONAME`` field is no longer set for ``MODULE`` libraries + created with the :command:`add_library` command. ``MODULE`` + libraries are meant for explicit dynamic loading at runtime. + They cannot be linked so ``SONAME`` is not useful.