1CMake 3.4 Release Notes
2***********************
3
4.. only:: html
5
6  .. contents::
7
8Changes made since CMake 3.3 include the following.
9
10New Features
11============
12
13Generators
14----------
15
16* The :generator:`Visual Studio 14 2015` generator learned to select
17  a Windows 10 SDK based on the value of the :variable:`CMAKE_SYSTEM_VERSION`
18  variable and the SDKs available on the host.
19
20* CMake learned rudimentary support for the Apple Swift language.  When using
21  the :generator:`Xcode` generator with Xcode 6.1 or higher, one may enable
22  the ``Swift`` language with the :command:`enable_language` command or the
23  :command:`project` command (this is an error with other generators or when
24  Xcode is too old).  Then one may list ``.swift`` source files in targets
25  for compilation.
26
27Commands
28--------
29
30* The :command:`find_program` command learned a ``NAMES_PER_DIR``
31  option to consider all given ``NAMES`` in each directory before
32  moving on to the next directory.
33
34* The :command:`get_filename_component` command learned a new ``BASE_DIR``
35  subcommand.  This is used to specify a base directory when calculating an
36  absolute path from a relative path.
37
38* The :command:`if` command learned a new ``TEST`` operator that evaluates
39  to true if a given test name has been defined by the :command:`add_test`
40  command.  See policy :policy:`CMP0064`.
41
42* The :command:`install(DIRECTORY)` command ``DESTINATION`` option learned to
43  support :manual:`generator expressions <cmake-generator-expressions(7)>`.
44
45* The :command:`install(FILES)` command ``DESTINATION`` option learned to
46  support :manual:`generator expressions <cmake-generator-expressions(7)>`.
47
48* The :command:`string` command learned a new ``APPEND`` subcommand.
49
50Variables
51---------
52
53* The :ref:`Makefile Generators` and the :generator:`Ninja` generator
54  learned to add compiler launcher tools like distcc and ccache along
55  with the compiler for ``C`` and ``CXX`` languages.  See the
56  :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable and
57  :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property for details.
58
59* New :variable:`CMAKE_LINK_SEARCH_START_STATIC` and
60  :variable:`CMAKE_LINK_SEARCH_END_STATIC` variables were
61  introduced to initialize the
62  :prop_tgt:`LINK_SEARCH_START_STATIC` and
63  :prop_tgt:`LINK_SEARCH_END_STATIC` target properties,
64  respectively.
65
66Properties
67----------
68
69* :ref:`Visual Studio Generators` learned to support additional
70  target properties to customize projects for NVIDIA Nsight
71  Tegra Visual Studio Edition:
72
73  * :prop_tgt:`ANDROID_ANT_ADDITIONAL_OPTIONS`
74  * :prop_tgt:`ANDROID_ARCH`
75  * :prop_tgt:`ANDROID_ASSETS_DIRECTORIES`
76  * :prop_tgt:`ANDROID_JAR_DEPENDENCIES`
77  * :prop_tgt:`ANDROID_JAR_DIRECTORIES`
78  * :prop_tgt:`ANDROID_JAVA_SOURCE_DIR`
79  * :prop_tgt:`ANDROID_NATIVE_LIB_DEPENDENCIES`
80  * :prop_tgt:`ANDROID_NATIVE_LIB_DIRECTORIES`
81  * :prop_tgt:`ANDROID_PROCESS_MAX`
82  * :prop_tgt:`ANDROID_PROGUARD`
83  * :prop_tgt:`ANDROID_PROGUARD_CONFIG_PATH`
84  * :prop_tgt:`ANDROID_SECURE_PROPS_PATH`
85  * :prop_tgt:`ANDROID_SKIP_ANT_STEP`
86  * :prop_tgt:`ANDROID_STL_TYPE`
87
88* The :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`,
89  :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY`, and
90  :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` target properties learned to
91  support :manual:`generator expressions <cmake-generator-expressions(7)>`.
92
93* The :prop_tgt:`SOURCE_DIR` and :prop_tgt:`BINARY_DIR` target properties
94  were introduced to allow project code to query where a target is defined.
95
96* The :prop_tgt:`OUTPUT_NAME` target property and its variants learned to
97  support :manual:`generator expressions <cmake-generator-expressions(7)>`.
98
99* A :prop_gbl:`TARGET_MESSAGES` global property was added to tell the
100  :ref:`Makefile Generators` whether to generate commands to print output
101  after each target is completed.
102
103* On Windows with MS-compatible tools, CMake learned to optionally
104  generate a module definition (``.def``) file for ``SHARED`` libraries.
105  See the :prop_tgt:`WINDOWS_EXPORT_ALL_SYMBOLS` target property.
106
107Modules
108-------
109
110* The :module:`ExternalProject` module :command:`ExternalProject_Add`
111  function ``GIT_SUBMODULES`` option now also limits the set of
112  submodules that are initialized in addition to the prior behavior
113  of limiting the set of submodules that are updated.
114
115* The :module:`ExternalProject` module learned new ``USES_TERMINAL``
116  arguments for giving steps exclusive terminal access.  This is
117  useful with the :generator:`Ninja` generator to monitor CMake
118  superbuild progress and prevent CPU oversubscription.
119
120* The :module:`FindBISON` module ``BISON_TARGET`` macro learned a
121  new ``DEFINES_FILE`` option to specify a custom output header
122  to be generated.
123
124* The :module:`FindHDF5` module learend a new ``HDF5_PREFER_PARALLEL``
125  option allowing users to specify that a parallel HDF5 tool is
126  preferred if both are available.
127
128* The :module:`FindIce` module now provides imported targets.
129
130* The :module:`FindJava` module learned to optionally find
131  the ``idlj`` and ``jarsigner`` tools.
132
133* The :module:`FindOpenSSL` module now provides imported targets.
134
135* The :module:`FindOpenSSL` module learned a new ``OPENSSL_USE_STATIC_LIBS``
136  option to search only for static libraries.
137
138* The :module:`FindPkgConfig` learned a new :command:`pkg_get_variable`
139  command which may be used to query for arbitrary variables from a package
140  (such as for related tools or data and plugin install paths).
141
142* The :module:`FindProtobuf` module gained a new
143  :command:`protobuf_generate_python` function to generate python
144  sources from ``.proto`` files.
145
146* The :module:`FindTIFF` module learned to search separately for
147  debug and release variants.
148
149* The :module:`FindwxWidgets` module learned to support version requests.
150
151* The :module:`FindXercesC` module learned to search separately for
152  debug and release variants.
153
154* The :module:`FindZLIB` module learned to search separately for
155  debug and release variants.
156
157* The :module:`GNUInstallDirs` module learned special default values
158  for certain installation prefixes according to the `GNU Coding
159  Standards`_ and the `Filesystem Hierarchy Standard`_.
160
161* The :module:`UseJava` module ``add_jar`` function learned
162  to support response files (e.g. ``@srcs.txt``) for source
163  specification.
164
165* The :module:`UseJava` module ``install_jar`` function learned
166  new ``DESTINATION`` and ``COMPONENT`` options to specify
167  the corresponding :command:`install` command options.
168
169* The :module:`UseJava` module gained a new ``create_javah``
170  function to create C headers from Java classes.
171
172.. _`GNU Coding Standards`: https://www.gnu.org/prep/standards/html_node/Directory-Variables.html
173.. _`Filesystem Hierarchy Standard`: https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html
174
175Generator Expressions
176---------------------
177
178* A new ``$<SHELL_PATH:...>``
179  :manual:`generator expression <cmake-generator-expressions(7)>`
180  has been added.
181
182CTest
183-----
184
185* CTest learned to optionally measure the CPU load during parallel
186  testing and avoid starting tests that may cause the load to exceed
187  a given threshold.  See the :manual:`ctest(1)` command ``--test-load``
188  option, the ``TestLoad`` setting of the :ref:`CTest Test Step`,
189  the :variable:`CTEST_TEST_LOAD` variable, and the ``TEST_LOAD``
190  option of the :command:`ctest_test` command.
191
192* :manual:`ctest(1)` learned options
193  ``--test-output-size-passed`` and ``--test-output-size-failed``
194  to customize the limit on test output size submitted when
195  running as a :ref:`Dashboard Client`.
196
197CPack
198-----
199
200* The :cpack_gen:`CPack DEB Generator` learned to set package dependencies
201  per component.  See variables:
202
203  * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS`
204  * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONFLICTS`
205  * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES`
206  * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS`
207  * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_PROVIDES`
208  * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS`
209  * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES`
210  * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS`
211
212* The :module:`CPack` module learned to package empty directories.
213
214* The :module:`CPack` module gained a new setting, ``CPACK_VERBATIM_VARIABLES``,
215  which can be used to ensure the cpack program receives the settings' values
216  exactly as they were set, even if they contain CMake-special characters.
217  For compatibility, it's off by default.
218
219Other
220-----
221
222* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
223  is now aware of features supported by GNU C compilers on Windows.
224
225* CMake learned to honor ``*.manifest`` source files with MSVC tools.
226  Manifest files named as sources of ``.exe`` and ``.dll`` targets
227  will be merged with linker-generated manifests and embedded in the
228  binary.
229
230* The `Concurrent Fortran 77 <https://ccur.com>`__ compiler is now supported.
231  Its :variable:`compiler id <CMAKE_<LANG>_COMPILER_ID>` is ``CCur``.
232
233* :manual:`cmake(1)` gained a new ``--trace-expand`` command line option
234  that is like ``--trace`` but expands variable references in the output.
235
236Deprecated and Removed Features
237===============================
238
239* The :module:`CMakeExpandImportedTargets` module is now documented
240  as deprecated.  See module documentation for an explanation.
241
242* The :variable:`CMAKE_USE_RELATIVE_PATHS` variable no longer has any
243  effect.  Previously it was partially implemented and unreliable.
244
245Other Changes
246=============
247
248* The :module:`CheckFunctionExists`, :module:`CheckLibraryExists`,
249  :module:`CheckSymbolExists`, and :module:`FindThreads` modules learned to
250  work in environments where only CXX is enabled.
251
252* The :cpack_gen:`CPack DEB Generator` now correctly excludes symlinks
253  during package checksum calculation.
254
255* The :cpack_gen:`CPack DEB Generator` no longer uses fakeroot and
256  system tar program for packaging.
257
258* The :module:`CPack` module no longer mangles settings with CMake-special
259  characters when they're used as defaults for other settings. The macro
260  ``cpack_set_if_not_set``, which was responsible for this, is now deprecated.
261
262* CMake no longer links executables with flags to export symbols
263  unless the :prop_tgt:`ENABLE_EXPORTS` target property is set.
264  See policy :policy:`CMP0065`.
265
266* The ``SONAME`` field is no longer set for ``MODULE`` libraries
267  created with the :command:`add_library` command.  ``MODULE``
268  libraries are meant for explicit dynamic loading at runtime.
269  They cannot be linked so ``SONAME`` is not useful.
270
271* The internal :variable:`CMAKE_<LANG>_COMPILE_OBJECT` rule variable now
272  substitutes compiler include flags in a separate ``<INCLUDES>`` placeholder
273  instead of the main ``<FLAGS>`` placeholder.
274