summaryrefslogtreecommitdiffstats
path: root/Help
diff options
context:
space:
mode:
Diffstat (limited to 'Help')
-rw-r--r--Help/command/DEVICE_LINK_OPTIONS.txt10
-rw-r--r--Help/command/FIND_XXX.txt13
-rw-r--r--Help/command/add_compile_options.rst3
-rw-r--r--Help/command/add_link_options.rst2
-rw-r--r--Help/command/add_test.rst5
-rw-r--r--Help/command/cmake_command.rst90
-rw-r--r--Help/command/ctest_test.rst4
-rw-r--r--Help/command/execute_process.rst13
-rw-r--r--Help/command/file.rst136
-rw-r--r--Help/command/find_package.rst34
-rw-r--r--Help/command/function.rst4
-rw-r--r--Help/command/get_property.rst10
-rw-r--r--Help/command/get_source_file_property.rst11
-rw-r--r--Help/command/install.rst76
-rw-r--r--Help/command/list.rst7
-rw-r--r--Help/command/macro.rst4
-rw-r--r--Help/command/option.rst2
-rw-r--r--Help/command/separate_arguments.rst2
-rw-r--r--Help/command/set_property.rst16
-rw-r--r--Help/command/set_source_files_properties.rst13
-rw-r--r--Help/command/source_group.rst6
-rw-r--r--Help/command/string.rst21
-rw-r--r--Help/command/target_compile_options.rst2
-rw-r--r--Help/command/target_link_options.rst2
-rw-r--r--Help/cpack_gen/archive.rst65
-rw-r--r--Help/cpack_gen/cygwin.rst5
-rw-r--r--Help/cpack_gen/freebsd.rst5
-rw-r--r--Help/cpack_gen/ifw.rst177
-rw-r--r--Help/cpack_gen/nsis.rst4
-rw-r--r--Help/cpack_gen/rpm.rst24
-rw-r--r--Help/dev/source.rst162
-rw-r--r--Help/envvar/CCMAKE_COLORS.rst34
-rw-r--r--Help/envvar/CMAKE_PREFIX_PATH.rst17
-rw-r--r--Help/guide/tutorial/Step5/MathFunctions/MakeTable.cxx25
-rw-r--r--Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt12
-rw-r--r--Help/guide/tutorial/index.rst10
-rw-r--r--Help/guide/user-interaction/index.rst5
-rw-r--r--Help/manual/cmake-commands.7.rst1
-rw-r--r--Help/manual/cmake-env-variables.7.rst15
-rw-r--r--Help/manual/cmake-generator-expressions.7.rst194
-rw-r--r--Help/manual/cmake-policies.7.rst11
-rw-r--r--Help/manual/cmake-properties.7.rst9
-rw-r--r--Help/manual/cmake-variables.7.rst4
-rw-r--r--Help/manual/cmake.1.rst23
-rw-r--r--Help/manual/ctest.1.rst11
-rw-r--r--Help/policy/CMP0103.rst22
-rw-r--r--Help/policy/CMP0104.rst31
-rw-r--r--Help/policy/CMP0105.rst19
-rw-r--r--Help/policy/CMP0106.rst19
-rw-r--r--Help/prop_dir/LINK_OPTIONS.rst2
-rw-r--r--Help/prop_sf/COMPILE_OPTIONS.rst21
-rw-r--r--Help/prop_sf/UNITY_GROUP.rst5
-rw-r--r--Help/prop_sf/VS_SETTINGS.rst18
-rw-r--r--Help/prop_tgt/CONFIG_POSTFIX.rst3
-rw-r--r--Help/prop_tgt/CUDA_ARCHITECTURES.rst30
-rw-r--r--Help/prop_tgt/CUDA_STANDARD.rst2
-rw-r--r--Help/prop_tgt/FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG.rst25
-rw-r--r--Help/prop_tgt/INSTALL_RPATH.rst4
-rw-r--r--Help/prop_tgt/LINK_OPTIONS.rst12
-rw-r--r--Help/prop_tgt/PCH_WARN_INVALID.rst8
-rw-r--r--Help/prop_tgt/UNITY_BUILD.rst24
-rw-r--r--Help/prop_tgt/UNITY_BUILD_MODE.rst58
-rw-r--r--Help/prop_tgt/VS_PLATFORM_TOOLSET.rst10
-rw-r--r--Help/prop_tgt/VS_SOLUTION_DEPLOY.rst29
-rw-r--r--Help/prop_tgt/VS_SOURCE_SETTINGS_tool.rst19
-rw-r--r--Help/release/dev/0-sample-topic.rst7
-rw-r--r--Help/release/dev/CPackRPM-trans-scripts.rst7
-rw-r--r--Help/release/dev/CTestCoverageCollectGCOV-compress-opts.rst7
-rw-r--r--Help/release/dev/FPHSA-handle_components.rst5
-rw-r--r--Help/release/dev/FindBLAS-import-target.rst4
-rw-r--r--Help/release/dev/FindLAPACK-import-target.rst4
-rw-r--r--Help/release/dev/FindPython-IronPython-support.rst5
-rw-r--r--Help/release/dev/FindPython-artifacts-interactive.rst6
-rw-r--r--Help/release/dev/FindPython-dev-subcomponents.rst6
-rw-r--r--Help/release/dev/FindPython-find-implementations.rst5
-rw-r--r--Help/release/dev/FindPython-pypy.rst5
-rw-r--r--Help/release/dev/FindRuby-variable-case.rst7
-rw-r--r--Help/release/dev/GoogleTest-DISCOVERY_MODE.rst7
-rw-r--r--Help/release/dev/GoogleTest-XML_OUTPUT_DIR.rst6
-rw-r--r--Help/release/dev/ccmake-custom-colors.rst5
-rw-r--r--Help/release/dev/cmake-gui-env-platform-defaults.rst8
-rw-r--r--Help/release/dev/cmake_command-command.rst6
-rw-r--r--Help/release/dev/command-line-cat.rst5
-rw-r--r--Help/release/dev/ctest-log-environment.rst8
-rw-r--r--Help/release/dev/ctest_resource_spec_file-variable.rst6
-rw-r--r--Help/release/dev/ctest_stop_on_failure.rst8
-rw-r--r--Help/release/dev/cuda-architectures-empty.rst7
-rw-r--r--Help/release/dev/cuda-architectures.rst6
-rw-r--r--Help/release/dev/cuda-clang.rst4
-rw-r--r--Help/release/dev/curl-http2.rst8
-rw-r--r--Help/release/dev/deprecate-documentation-module.rst6
-rw-r--r--Help/release/dev/deprecate-policy-old.rst8
-rw-r--r--Help/release/dev/device-link-options.rst5
-rw-r--r--Help/release/dev/execute_process.rst5
-rw-r--r--Help/release/dev/export-multiple-calls.rst5
-rw-r--r--Help/release/dev/fetchcontent-SOURCE_SUBDIR.rst6
-rw-r--r--Help/release/dev/file-upload-tls.rst5
-rw-r--r--Help/release/dev/file_archive.rst7
-rw-r--r--Help/release/dev/file_configure.rst6
-rw-r--r--Help/release/dev/findswig-components.rst5
-rw-r--r--Help/release/dev/framework-multi-config-postfix.rst7
-rw-r--r--Help/release/dev/genex-DEVICE_LINK-HOST_LINK.rst6
-rw-r--r--Help/release/dev/genex-LINK_LANGUAGE.rst5
-rw-r--r--Help/release/dev/grouped-unity-build-mode.rst6
-rw-r--r--Help/release/dev/libxslt.rst4
-rw-r--r--Help/release/dev/list_natural_sort.rst5
-rw-r--r--Help/release/dev/ninja-compiler-PATH-windows.rst7
-rw-r--r--Help/release/dev/nsis-dpi-aware.rst6
-rw-r--r--Help/release/dev/parallel-lzma-compression.rst6
-rw-r--r--Help/release/dev/pch-warn-invalid.rst6
-rw-r--r--Help/release/dev/profiling.rst9
-rw-r--r--Help/release/dev/required_find_commands.rst6
-rw-r--r--Help/release/dev/sf-property-scopes.rst15
-rw-r--r--Help/release/dev/source_group_forward_slashes.rst5
-rw-r--r--Help/release/dev/string-hex.rst5
-rw-r--r--Help/release/dev/useswig-fortran.rst7
-rw-r--r--Help/release/dev/vs-non-built-file-item-metadata.rst10
-rw-r--r--Help/release/dev/vs-platform-toolset.rst6
-rw-r--r--Help/release/dev/vs-sln-deploy.rst6
-rw-r--r--Help/release/index.rst2
-rw-r--r--Help/variable/CMAKE_CUDA_ARCHITECTURES.rst17
-rw-r--r--Help/variable/CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG.rst8
-rw-r--r--Help/variable/CMAKE_PCH_WARN_INVALID.rst5
-rw-r--r--Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst31
-rw-r--r--Help/variable/CTEST_NIGHTLY_START_TIME.rst8
-rw-r--r--Help/variable/CTEST_RESOURCE_SPEC_FILE.rst5
-rw-r--r--Help/variable/PROJECT_SOURCE_DIR.rst8
127 files changed, 1818 insertions, 263 deletions
diff --git a/Help/command/DEVICE_LINK_OPTIONS.txt b/Help/command/DEVICE_LINK_OPTIONS.txt
new file mode 100644
index 0000000..012e9b1
--- /dev/null
+++ b/Help/command/DEVICE_LINK_OPTIONS.txt
@@ -0,0 +1,10 @@
+
+When a device link step is involved, which is controlled by
+:prop_tgt:`CUDA_SEPARABLE_COMPILATION` and
+:prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties, the raw options will be
+delivered to the host and device link steps (wrapped in ``-Xcompiler`` or
+equivalent for device link). Options wrapped with ``$<DEVICE_LINK:...>``
+:manual:`generator expression <cmake-generator-expressions(7)>` will be used
+only for the device link step. Options wrapped with ``$<HOST_LINK:...>``
+:manual:`generator expression <cmake-generator-expressions(7)>` will be used
+only for the host link step.
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt
index 42bf52b..4a62c5b 100644
--- a/Help/command/FIND_XXX.txt
+++ b/Help/command/FIND_XXX.txt
@@ -15,6 +15,7 @@ The general signature is:
[PATHS path1 [path2 ... ENV var]]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[DOC "cache documentation string"]
+ [REQUIRED]
[NO_DEFAULT_PATH]
[NO_PACKAGE_ROOT_PATH]
[NO_CMAKE_PATH]
@@ -31,8 +32,9 @@ A cache entry named by ``<VAR>`` is created to store the result
of this command.
If the |SEARCH_XXX| is found the result is stored in the variable
and the search will not be repeated unless the variable is cleared.
-If nothing is found, the result will be
-``<VAR>-NOTFOUND``, and the search will be attempted again the
+If nothing is found, the result will be ``<VAR>-NOTFOUND``.
+The ``REQUIRED`` option stops processing with an error message if nothing
+is found, otherwise the search will be attempted again the
next time |FIND_XXX| is invoked with the same variable.
Options include:
@@ -57,6 +59,9 @@ Options include:
``DOC``
Specify the documentation string for the ``<VAR>`` cache entry.
+``REQUIRED``
+ Stop processing with an error message if nothing is found.
+
If ``NO_DEFAULT_PATH`` is specified, then no additional paths are
added to the search.
If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
@@ -138,6 +143,10 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
* |CMAKE_SYSTEM_XXX_PATH|
* |CMAKE_SYSTEM_XXX_MAC_PATH|
+ The platform paths that these variables contain are locations that
+ typically include installed software. An example being ``/usr/local`` for
+ UNIX based platforms.
+
7. Search the paths specified by the PATHS option
or in the short-hand version of the command.
These are typically hard-coded guesses.
diff --git a/Help/command/add_compile_options.rst b/Help/command/add_compile_options.rst
index 43805c3..36f403c 100644
--- a/Help/command/add_compile_options.rst
+++ b/Help/command/add_compile_options.rst
@@ -46,3 +46,6 @@ to use the more specific commands :command:`add_compile_definitions`
and :command:`include_directories`.
The command :command:`target_compile_options` adds target-specific options.
+
+The source file property :prop_sf:`COMPILE_OPTIONS` adds options to one
+source file.
diff --git a/Help/command/add_link_options.rst b/Help/command/add_link_options.rst
index a83005b..faa4afb 100644
--- a/Help/command/add_link_options.rst
+++ b/Help/command/add_link_options.rst
@@ -26,6 +26,8 @@ the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.
+.. include:: DEVICE_LINK_OPTIONS.txt
+
.. include:: OPTIONS_SHELL.txt
.. include:: LINK_OPTIONS_LINKER.txt
diff --git a/Help/command/add_test.rst b/Help/command/add_test.rst
index a77ba37..c0677d2 100644
--- a/Help/command/add_test.rst
+++ b/Help/command/add_test.rst
@@ -10,8 +10,9 @@ Add a test to the project to be run by :manual:`ctest(1)`.
[WORKING_DIRECTORY <dir>]
[COMMAND_EXPAND_LISTS])
-Adds a test called ``<name>``. The test name may not contain spaces,
-quotes, or other characters special in CMake syntax. The options are:
+Adds a test called ``<name>``. The test name may contain arbitrary
+characters except for double-quotes. However, if it contains spaces
+or semicolons it must be enclosed in double-quotes. The options are:
``COMMAND``
Specify the test command-line. If ``<command>`` specifies an
diff --git a/Help/command/cmake_command.rst b/Help/command/cmake_command.rst
new file mode 100644
index 0000000..08b7832
--- /dev/null
+++ b/Help/command/cmake_command.rst
@@ -0,0 +1,90 @@
+cmake_command
+-------------
+
+Call meta-operations on CMake commands.
+
+Synopsis
+^^^^^^^^
+
+.. parsed-literal::
+
+ cmake_command(`INVOKE`_ <command> [<args>...])
+ cmake_command(`EVAL`_ CODE <code>...)
+
+Introduction
+^^^^^^^^^^^^
+
+This command will call meta-operations on built-in CMake commands or
+those created via the :command:`macro` or :command:`function` commands.
+
+``cmake_command`` does not introduce a new variable or policy scope.
+
+Invoking Commands
+^^^^^^^^^^^^^^^^^
+
+.. _INVOKE:
+
+.. code-block:: cmake
+
+ cmake_command(INVOKE <command> [<args>...])
+
+Invokes the named ``<command>`` with the given arguments (if any).
+For example, the code:
+
+.. code-block:: cmake
+
+ set(message_command "message")
+ cmake_command(INVOKE ${message_command} STATUS "Hello World!")
+
+is equivalent to
+
+.. code-block:: cmake
+
+ message(STATUS "Hello World!")
+
+Evaluating Code
+^^^^^^^^^^^^^^^
+
+.. _EVAL:
+
+.. code-block:: cmake
+
+ cmake_command(EVAL CODE <code>...)
+
+Evaluates the ``<code>...`` as CMake code.
+
+For example, the code:
+
+.. code-block:: cmake
+
+ set(A TRUE)
+ set(B TRUE)
+ set(C TRUE)
+ set(condition "(A AND B) OR C")
+
+ cmake_command(EVAL CODE "
+ if (${condition})
+ message(STATUS TRUE)
+ else()
+ message(STATUS FALSE)
+ endif()"
+ )
+
+is equivalent to
+
+.. code-block:: cmake
+
+ set(A TRUE)
+ set(B TRUE)
+ set(C TRUE)
+ set(condition "(A AND B) OR C")
+
+ file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake "
+ if (${condition})
+ message(STATUS TRUE)
+ else()
+ message(STATUS FALSE)
+ endif()"
+ )
+
+ include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake)
diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst
index 5c67b2c..3589296 100644
--- a/Help/command/ctest_test.rst
+++ b/Help/command/ctest_test.rst
@@ -20,6 +20,7 @@ Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`.
[RESOURCE_SPEC_FILE <file>]
[TEST_LOAD <threshold>]
[SCHEDULE_RANDOM <ON|OFF>]
+ [STOP_ON_FAILURE]
[STOP_TIME <time-of-day>]
[RETURN_VALUE <result-var>]
[CAPTURE_CMAKE_ERROR <result-var>]
@@ -119,6 +120,9 @@ The options are:
Launch tests in a random order. This may be useful for detecting
implicit test dependencies.
+``STOP_ON_FAILURE``
+ Stop the execution of the tests once one has failed.
+
``STOP_TIME <time-of-day>``
Specify a time of day at which the tests should all stop running.
diff --git a/Help/command/execute_process.rst b/Help/command/execute_process.rst
index 14f879d..b32025f 100644
--- a/Help/command/execute_process.rst
+++ b/Help/command/execute_process.rst
@@ -21,7 +21,9 @@ Execute one or more child processes.
[COMMAND_ECHO <where>]
[OUTPUT_STRIP_TRAILING_WHITESPACE]
[ERROR_STRIP_TRAILING_WHITESPACE]
- [ENCODING <name>])
+ [ENCODING <name>]
+ [ECHO_OUTPUT_VARIABLE]
+ [ECHO_ERROR_VARIABLE])
Runs the given sequence of one or more commands.
@@ -105,6 +107,15 @@ Options:
for this encoding. In CMake 3.11.0, ``UTF-8`` was added for consistency with
the `UTF-8 RFC <https://www.ietf.org/rfc/rfc3629>`_ naming convention.
+``ECHO_OUTPUT_VARIABLE``, ``ECHO_ERROR_VARIABLE``
+ The standard output or standard error will not be exclusively redirected to
+ the configured variables.
+
+ The output will be duplicated, it will be sent into the configured variables
+ and also on standard output or standard error.
+
+ This is analogous to the ``tee`` Unix command.
+
If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the
same pipe the precedence is not specified.
If no ``OUTPUT_*`` or ``ERROR_*`` options are given the output will
diff --git a/Help/command/file.rst b/Help/command/file.rst
index df7d8ba..bb560a9 100644
--- a/Help/command/file.rst
+++ b/Help/command/file.rst
@@ -19,6 +19,7 @@ Synopsis
file({`WRITE`_ | `APPEND`_} <filename> <content>...)
file({`TOUCH`_ | `TOUCH_NOCREATE`_} [<file>...])
file(`GENERATE`_ OUTPUT <output-file> [...])
+ file(`CONFIGURE`_ OUTPUT <output-file> CONTENT <content> [...])
`Filesystem`_
file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] [<globbing-expr>...])
@@ -41,6 +42,10 @@ Synopsis
`Locking`_
file(`LOCK`_ <path> [...])
+ `Archiving`_
+ file(`ARCHIVE_CREATE`_ OUTPUT <archive> FILES <files> [...])
+ file(`ARCHIVE_EXTRACT`_ INPUT <archive> DESTINATION <dir> [...])
+
Reading
^^^^^^^
@@ -54,7 +59,9 @@ Reading
Read content from a file called ``<filename>`` and store it in a
``<variable>``. Optionally start from the given ``<offset>`` and
read at most ``<max-in>`` bytes. The ``HEX`` option causes data to
-be converted to a hexadecimal representation (useful for binary data).
+be converted to a hexadecimal representation (useful for binary data). If the
+``HEX`` option is specified, letters in the output (``a`` through ``f``) are in
+lowercase.
.. _STRINGS:
@@ -395,8 +402,8 @@ dependency resolution:
Determines the path to the tool to use for dependency resolution. This is the
actual path to ``objdump``, ``dumpbin``, or ``otool``.
- If this variable is not specified, it is determined automatically by system
- introspection.
+ If this variable is not specified, it is determined by the value of
+ ``CMAKE_OBJDUMP`` if set, else by system introspection.
Writing
^^^^^^^
@@ -482,6 +489,45 @@ generation phase. The output file will not yet have been written when the
``file(GENERATE)`` command returns, it is written only after processing all
of a project's ``CMakeLists.txt`` files.
+.. _CONFIGURE:
+
+.. code-block:: cmake
+
+ file(CONFIGURE OUTPUT output-file
+ CONTENT content
+ [ESCAPE_QUOTES] [@ONLY]
+ [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
+
+Generate an output file using the input given by ``CONTENT`` and substitute
+variable values referenced as ``@VAR@`` or ``${VAR}`` contained therein. The
+substitution rules behave the same as the :command:`configure_file` command.
+In order to match :command:`configure_file`'s behavior, generator expressions
+are not supported for both ``OUTPUT`` and ``CONTENT``.
+
+The arguments are:
+
+``OUTPUT <output-file>``
+ Specify the output file name to generate. A relative path is treated with
+ respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. See policy
+ :policy:`CMP0070`.
+ ``<output-file>`` does not support generator expressions.
+
+``CONTENT <content>``
+ Use the content given explicitly as input.
+ ``<content>`` does not support generator expressions.
+
+``ESCAPE_QUOTES``
+ Escape any substituted quotes with backslashes (C-style).
+
+``@ONLY``
+ Restrict variable replacement to references of the form ``@VAR@``.
+ This is useful for configuring scripts that use ``${VAR}`` syntax.
+
+``NEWLINE_STYLE <style>``
+ Specify the newline style for the output file. Specify
+ ``UNIX`` or ``LF`` for ``\n`` newlines, or specify
+ ``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines.
+
Filesystem
^^^^^^^^^^
@@ -790,6 +836,18 @@ Options to both ``DOWNLOAD`` and ``UPLOAD`` are:
If neither ``NETRC`` option is given CMake will check variables
``CMAKE_NETRC`` and ``CMAKE_NETRC_FILE``, respectively.
+``TLS_VERIFY <ON|OFF>``
+ Specify whether to verify the server certificate for ``https://`` URLs.
+ The default is to *not* verify.
+
+``TLS_CAINFO <file>``
+ Specify a custom Certificate Authority file for ``https://`` URLs.
+
+For ``https://`` URLs CMake must be built with OpenSSL support. ``TLS/SSL``
+certificates are not checked by default. Set ``TLS_VERIFY`` to ``ON`` to
+check certificates. If neither ``TLS`` option is given CMake will check
+variables ``CMAKE_TLS_VERIFY`` and ``CMAKE_TLS_CAINFO``, respectively.
+
Additional options to ``DOWNLOAD`` are:
``EXPECTED_HASH ALGO=<value>``
@@ -801,19 +859,6 @@ Additional options to ``DOWNLOAD`` are:
``EXPECTED_MD5 <value>``
Historical short-hand for ``EXPECTED_HASH MD5=<value>``.
-``TLS_VERIFY <ON|OFF>``
- Specify whether to verify the server certificate for ``https://`` URLs.
- The default is to *not* verify.
-
-``TLS_CAINFO <file>``
- Specify a custom Certificate Authority file for ``https://`` URLs.
-
-For ``https://`` URLs CMake must be built with OpenSSL support. ``TLS/SSL``
-certificates are not checked by default. Set ``TLS_VERIFY`` to ``ON`` to
-check certificates and/or use ``EXPECTED_HASH`` to verify downloaded content.
-If neither ``TLS`` option is given CMake will check variables
-``CMAKE_TLS_VERIFY`` and ``CMAKE_TLS_CAINFO``, respectively.
-
Locking
^^^^^^^
@@ -846,3 +891,62 @@ child directory or file.
Trying to lock file twice is not allowed. Any intermediate directories and
file itself will be created if they not exist. ``GUARD`` and ``TIMEOUT``
options ignored on ``RELEASE`` operation.
+
+Archiving
+^^^^^^^^^
+
+.. _ARCHIVE_CREATE:
+
+.. code-block:: cmake
+
+ file(ARCHIVE_CREATE OUTPUT <archive>
+ [FILES <files>]
+ [DIRECTORY <dirs>]
+ [FORMAT <format>]
+ [TYPE <type>]
+ [MTIME <mtime>]
+ [VERBOSE])
+
+Creates an archive specifed by ``OUTPUT`` with the content of ``FILES`` and
+``DIRECTORY``.
+
+To specify the format of the archive set the ``FORMAT`` option.
+Supported formats are: ``7zip``, ``gnutar``, ``pax``, ``paxr``, ``raw``,
+(restricted pax, default), and ``zip``.
+
+To specify the type of compression set the ``TYPE`` option.
+Supported compression types are: ``None``, ``BZip2``, ``GZip``, ``XZ``,
+and ``Zstd``.
+
+.. note::
+ With ``FORMAT`` set to ``raw`` only one file will be compressed with the
+ compression type specified by ``TYPE``.
+
+With ``VERBOSE`` the command will produce verbose output.
+
+To specify the modification time recorded in tarball entries use
+the ``MTIME`` option.
+
+.. _ARCHIVE_EXTRACT:
+
+.. code-block:: cmake
+
+ file(ARCHIVE_EXTRACT INPUT <archive>
+ [FILES <files>]
+ [DIRECTORY <dirs>]
+ [DESTINATION <dir>]
+ [LIST_ONLY]
+ [VERBOSE])
+
+Extracts or lists the content of an archive specified by ``INPUT``.
+
+The directory where the content of the archive will be extracted can
+be specified via ``DESTINATION``. If the directory does not exit, it
+will be created.
+
+To select which files and directories will be extracted or listed
+use ``FILES`` and ``DIRECTORY`` options.
+
+``LIST_ONLY`` will only list the files in the archive.
+
+With ``VERBOSE`` the command will produce verbose output.
diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst
index 64a16f3..dcc0225 100644
--- a/Help/command/find_package.rst
+++ b/Help/command/find_package.rst
@@ -302,23 +302,23 @@ enabled.
are intended to be used on the command line with a ``-DVAR=value``.
The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`.
This can be skipped if ``NO_CMAKE_PATH`` is passed or by setting the
- :variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``::
+ :variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``:
- CMAKE_PREFIX_PATH
- CMAKE_FRAMEWORK_PATH
- CMAKE_APPBUNDLE_PATH
+ * :variable:`CMAKE_PREFIX_PATH`
+ * :variable:`CMAKE_FRAMEWORK_PATH`
+ * :variable:`CMAKE_APPBUNDLE_PATH`
3. Search paths specified in cmake-specific environment variables.
These are intended to be set in the user's shell configuration,
and therefore use the host's native path separator
(``;`` on Windows and ``:`` on UNIX).
This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed or by setting
- the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``::
+ the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``:
- <PackageName>_DIR
- CMAKE_PREFIX_PATH
- CMAKE_FRAMEWORK_PATH
- CMAKE_APPBUNDLE_PATH
+ * ``<PackageName>_DIR``
+ * :envvar:`CMAKE_PREFIX_PATH`
+ * ``CMAKE_FRAMEWORK_PATH``
+ * ``CMAKE_APPBUNDLE_PATH``
4. Search paths specified by the ``HINTS`` option. These should be paths
computed by system introspection, such as a hint provided by the
@@ -329,9 +329,9 @@ enabled.
skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed or by setting the
:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` to ``FALSE``. Path entries
ending in ``/bin`` or ``/sbin`` are automatically converted to their
- parent directories::
+ parent directories:
- PATH
+ * ``PATH``
6. Search paths stored in the CMake :ref:`User Package Registry`.
This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed or by
@@ -345,11 +345,15 @@ enabled.
7. Search cmake variables defined in the Platform files for the
current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is
passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`
- to ``FALSE``::
+ to ``FALSE``:
- CMAKE_SYSTEM_PREFIX_PATH
- CMAKE_SYSTEM_FRAMEWORK_PATH
- CMAKE_SYSTEM_APPBUNDLE_PATH
+ * :variable:`CMAKE_SYSTEM_PREFIX_PATH`
+ * :variable:`CMAKE_SYSTEM_FRAMEWORK_PATH`
+ * :variable:`CMAKE_SYSTEM_APPBUNDLE_PATH`
+
+ The platform paths that these variables contain are locations that
+ typically include installed software. An example being ``/usr/local`` for
+ UNIX based platforms.
8. Search paths stored in the CMake :ref:`System Package Registry`.
This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed
diff --git a/Help/command/function.rst b/Help/command/function.rst
index 53ba754..30938b3 100644
--- a/Help/command/function.rst
+++ b/Help/command/function.rst
@@ -44,11 +44,15 @@ can be invoked through any of
foo()
Foo()
FOO()
+ cmake_command(INVOKE foo)
and so on. However, it is strongly recommended to stay with the
case chosen in the function definition. Typically functions use
all-lowercase names.
+The :command:`cmake_command(INVOKE ...)` command can also be used to invoke the
+function.
+
Arguments
^^^^^^^^^
diff --git a/Help/command/get_property.rst b/Help/command/get_property.rst
index c0f9b46..80d97fd 100644
--- a/Help/command/get_property.rst
+++ b/Help/command/get_property.rst
@@ -10,6 +10,7 @@ Get a property.
DIRECTORY [<dir>] |
TARGET <target> |
SOURCE <source> |
+ [<TARGET_DIRECTORY ... | DIRECTORY ...>] |
INSTALL <file> |
TEST <test> |
CACHE <entry> |
@@ -49,6 +50,15 @@ It must be one of the following:
``VARIABLE``
Scope is unique and does not accept a name.
+In the ``SOURCE`` case, the queried source file scope can be changed by
+specifying one of the additional options: ``DIRECTORY`` or ``TARGET_DIRECTORY``.
+
+``DIRECTORY`` takes a path to a processed directory, and the source file property
+will be read from that directory scope.
+
+``TARGET_DIRECTORY`` takes the name of an existing target. The source file
+property will be read from this target's directory scope.
+
The required ``PROPERTY`` option is immediately followed by the name of
the property to get. If the property is not set an empty value is
returned, although some properties support inheriting from a parent scope
diff --git a/Help/command/get_source_file_property.rst b/Help/command/get_source_file_property.rst
index decec19..893a1b6 100644
--- a/Help/command/get_source_file_property.rst
+++ b/Help/command/get_source_file_property.rst
@@ -5,7 +5,7 @@ Get a property for a source file.
.. code-block:: cmake
- get_source_file_property(VAR file property)
+ get_source_file_property(VAR file [<TARGET_DIRECTORY ... | DIRECTORY ...>] property)
Gets a property from a source file. The value of the property is
stored in the variable ``VAR``. If the source property is not found, the
@@ -15,6 +15,15 @@ or not (see :command:`define_property`). Non-inherited properties will set
parent scope as described for the :command:`define_property` command and
if still unable to find the property, ``VAR`` will be set to an empty string.
+The queried source file scope can be changed by specifying one of the
+additional options: ``DIRECTORY`` or ``TARGET_DIRECTORY``.
+
+``DIRECTORY`` takes a path to a processed directory, and the source file property
+will be read from that directory scope.
+
+``TARGET_DIRECTORY`` takes the name of an existing target. The source file
+property will be read from this target's directory scope.
+
Use :command:`set_source_files_properties` to set property values. Source
file properties usually control how the file is built. One property that is
always there is :prop_sf:`LOCATION`.
diff --git a/Help/command/install.rst b/Help/command/install.rst
index 5affc5b..c8df7d9 100644
--- a/Help/command/install.rst
+++ b/Help/command/install.rst
@@ -18,10 +18,12 @@ Synopsis
Introduction
^^^^^^^^^^^^
-This command generates installation rules for a project. Rules
-specified by calls to this command within a source directory are
-executed in order during installation. The order across directories
-is not defined.
+This command generates installation rules for a project. Install rules
+specified by calls to the ``install()`` command within a source directory
+are executed in order during installation. Install rules in subdirectories
+added by calls to the :command:`add_subdirectory` command are interleaved
+with those in the parent directory to run in the order declared (see
+policy :policy:`CMP0082`).
There are multiple signatures for this command. Some of them define
installation options for files and targets. Options common to
@@ -30,13 +32,20 @@ signatures that specify them. The common options are:
``DESTINATION``
Specify the directory on disk to which a file will be installed.
- If a full path (with a leading slash or drive letter) is given
- it is used directly. If a relative path is given it is interpreted
- relative to the value of the :variable:`CMAKE_INSTALL_PREFIX` variable.
+ Arguments can be relative or absolute paths.
+
+ If a relative path is given it is interpreted relative to the value
+ of the :variable:`CMAKE_INSTALL_PREFIX` variable.
The prefix can be relocated at install time using the ``DESTDIR``
mechanism explained in the :variable:`CMAKE_INSTALL_PREFIX` variable
documentation.
+ If an absolute path (with a leading slash or drive letter) is given
+ it is used verbatim.
+
+ As absolute paths are not supported by :manual:`cpack <cpack(1)>` installer
+ generators, it is preferable to use relative paths throughout.
+
``PERMISSIONS``
Specify permissions for installed files. Valid permissions are
``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``, ``GROUP_READ``,
@@ -119,31 +128,38 @@ Installing Targets
)
The ``TARGETS`` form specifies rules for installing targets from a
-project. There are several kinds of target files that may be installed:
+project. There are several kinds of target :ref:`Output Artifacts`
+that may be installed:
``ARCHIVE``
- Static libraries are treated as ``ARCHIVE`` targets, except those
- marked with the ``FRAMEWORK`` property on macOS (see ``FRAMEWORK``
- below.) For DLL platforms (all Windows-based systems including
- Cygwin), the DLL import library is treated as an ``ARCHIVE`` target.
- On AIX, the linker import file created for executables with
- :prop_tgt:`ENABLE_EXPORTS` is treated as an ``ARCHIVE`` target.
+ Target artifacts of this kind include:
+
+ * *Static libraries*
+ (except on macOS when marked as ``FRAMEWORK``, see below);
+ * *DLL import libraries*
+ (on all Windows-based systems including Cygwin; they have extension
+ ``.lib``, in contrast to the ``.dll`` libraries that go to ``RUNTIME``);
+ * On AIX, the *linker import file* created for executables with
+ :prop_tgt:`ENABLE_EXPORTS` enabled.
``LIBRARY``
- Module libraries are always treated as ``LIBRARY`` targets. For non-
- DLL platforms shared libraries are treated as ``LIBRARY`` targets,
- except those marked with the ``FRAMEWORK`` property on macOS (see
- ``FRAMEWORK`` below.)
+ Target artifacts of this kind include:
+
+ * *Shared libraries*, except
+
+ - DLLs (these go to ``RUNTIME``, see below),
+ - on macOS when marked as ``FRAMEWORK`` (see below).
``RUNTIME``
- Executables are treated as ``RUNTIME`` objects, except those marked
- with the ``MACOSX_BUNDLE`` property on macOS (see ``BUNDLE`` below.)
- For DLL platforms (all Windows-based systems including Cygwin), the
- DLL part of a shared library is treated as a ``RUNTIME`` target.
+ Target artifacts of this kind include:
+
+ * *Executables*
+ (except on macOS when marked as ``MACOSX_BUNDLE``, see ``BUNDLE`` below);
+ * DLLs (on all Windows-based systems including Cygwin; note that the
+ accompanying import libraries are of kind ``ARCHIVE``).
``OBJECTS``
- Object libraries (a simple group of object files) are always treated
- as ``OBJECTS`` targets.
+ Object files associated with *object libraries*.
``FRAMEWORK``
Both static and shared libraries marked with the ``FRAMEWORK``
@@ -630,6 +646,13 @@ present, causes the contents of the properties matching
``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?`` to be exported, when
policy :policy:`CMP0022` is ``NEW``.
+.. note::
+ The installed ``<export-name>.cmake`` file may come with additional
+ per-configuration ``<export-name>-*.cmake`` files to be loaded by
+ globbing. Do not use an export name that is the same as the package
+ name in combination with installing a ``<package-name>-config.cmake``
+ file or the latter may be incorrectly matched by the glob and loaded.
+
When a ``COMPONENT`` option is given, the listed ``<component>`` implicitly
depends on all components mentioned in the export set. The exported
``<name>.cmake`` file will require each of the exported components to be
@@ -684,6 +707,11 @@ executable from the installation tree using the imported target name
Generated Installation Script
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. note::
+
+ Use of this feature is not recommended. Please consider using the
+ ``--install`` argument of :manual:`cmake(1)` instead.
+
The ``install()`` command generates a file, ``cmake_install.cmake``, inside
the build directory, which is used internally by the generated install target
and by CPack. You can also invoke this script manually with ``cmake -P``. This
diff --git a/Help/command/list.rst b/Help/command/list.rst
index 50bf417..4d339a0 100644
--- a/Help/command/list.rst
+++ b/Help/command/list.rst
@@ -308,6 +308,13 @@ The ``<compare>`` option should be one of:
* ``STRING``: Sorts a list of strings alphabetically. This is the
default behavior if the ``COMPARE`` option is not given.
* ``FILE_BASENAME``: Sorts a list of pathnames of files by their basenames.
+* ``NATURAL``: Sorts a list of strings using natural order
+ (see ``strverscmp(3)`` manual), i.e. such that contiguous digits
+ are compared as whole numbers.
+ For example: the following list `10.0 1.1 2.1 8.0 2.0 3.1`
+ will be sorted as `1.1 2.0 2.1 3.1 8.0 10.0` if the ``NATURAL``
+ comparison is selected where it will be sorted as
+ `1.1 10.0 2.0 2.1 3.1 8.0` with the ``STRING`` comparison.
Use the ``CASE`` keyword to select a case sensitive or case insensitive
sort mode. The ``<case>`` option should be one of:
diff --git a/Help/command/macro.rst b/Help/command/macro.rst
index 008d049..65159f4 100644
--- a/Help/command/macro.rst
+++ b/Help/command/macro.rst
@@ -42,11 +42,15 @@ can be invoked through any of
foo()
Foo()
FOO()
+ cmake_command(INVOKE foo)
and so on. However, it is strongly recommended to stay with the
case chosen in the macro definition. Typically macros use
all-lowercase names.
+The :command:`cmake_command(INVOKE ...)` command can also be used to invoke the
+macro.
+
Arguments
^^^^^^^^^
diff --git a/Help/command/option.rst b/Help/command/option.rst
index 8956307..02b8dac 100644
--- a/Help/command/option.rst
+++ b/Help/command/option.rst
@@ -9,7 +9,7 @@ Provide an option that the user can optionally select.
Provides an option for the user to select as ``ON`` or ``OFF``.
If no initial ``<value>`` is provided, ``OFF`` is used.
-If ``<variable>`` is already set as a normal variable
+If ``<variable>`` is already set as a normal or cache variable,
then the command does nothing (see policy :policy:`CMP0077`).
If you have options that depend on the values of other options, see
diff --git a/Help/command/separate_arguments.rst b/Help/command/separate_arguments.rst
index fbca859..ab3d5c1 100644
--- a/Help/command/separate_arguments.rst
+++ b/Help/command/separate_arguments.rst
@@ -19,7 +19,7 @@ They are specified by the ``<mode>`` argument which must
be one of the following keywords:
``UNIX_COMMAND``
- Arguments are separated by by unquoted whitespace.
+ Arguments are separated by unquoted whitespace.
Both single-quote and double-quote pairs are respected.
A backslash escapes the next literal character (``\"`` is ``"``);
there are no special escapes (``\n`` is just ``n``).
diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst
index ec08c8f..de28be3 100644
--- a/Help/command/set_property.rst
+++ b/Help/command/set_property.rst
@@ -8,7 +8,8 @@ Set a named property in a given scope.
set_property(<GLOBAL |
DIRECTORY [<dir>] |
TARGET [<target1> ...] |
- SOURCE [<src1> ...] |
+ SOURCE [<src1> ...]
+ [<TARGET_DIRECTORY ... | DIRECTORY ...>] |
INSTALL [<file1> ...] |
TEST [<test1> ...] |
CACHE [<entry1> ...] >
@@ -34,8 +35,16 @@ It must be one of the following:
``SOURCE``
Scope may name zero or more source files. Note that source
- file properties are visible only to targets added in the same
+ file properties are by default visible only to targets added in the same
directory (``CMakeLists.txt``).
+ The file properties can be made visible in a different directory by specifying
+ one of the additional options: ``TARGET_DIRECTORY`` or ``DIRECTORY``.
+
+ ``DIRECTORY`` takes a list of processed directories paths, and sets the file
+ properties in those directory scopes.
+
+ ``TARGET_DIRECTORY`` takes a list of existing targets. The file
+ properties will be set in these targets' directory scopes.
See also the :command:`set_source_files_properties` command.
``INSTALL``
@@ -66,7 +75,8 @@ the property to set. Remaining arguments are used to compose the
property value in the form of a semicolon-separated list.
If the ``APPEND`` option is given the list is appended to any existing
-property value. If the ``APPEND_STRING`` option is given the string is
+property value (except that empty values are ignored and not appended).
+If the ``APPEND_STRING`` option is given the string is
appended to any existing property value as string, i.e. it results in a
longer string and not a list of strings. When using ``APPEND`` or
``APPEND_STRING`` with a property defined to support ``INHERITED``
diff --git a/Help/command/set_source_files_properties.rst b/Help/command/set_source_files_properties.rst
index ab95d70..8adfb9e 100644
--- a/Help/command/set_source_files_properties.rst
+++ b/Help/command/set_source_files_properties.rst
@@ -6,12 +6,25 @@ Source files can have properties that affect how they are built.
.. code-block:: cmake
set_source_files_properties([file1 [file2 [...]]]
+ [<TARGET_DIRECTORY ... | DIRECTORY ...>]
PROPERTIES prop1 value1
[prop2 value2 [...]])
Sets properties associated with source files using a key/value paired
list.
+Note that source file properties are by default visible only to
+targets added in the same directory (``CMakeLists.txt``).
+
+The file properties can be made visible in a different directory by specifying
+one of the additional options: ``TARGET_DIRECTORY`` or ``DIRECTORY``.
+
+``DIRECTORY`` takes a list of processed directories paths, and sets the file
+properties in those directory scopes.
+
+``TARGET_DIRECTORY`` takes a list of existing targets. The file
+properties will be set in these targets' directory scopes.
+
See also the :command:`set_property(SOURCE)` command.
See :ref:`Source File Properties` for the list of properties known
diff --git a/Help/command/source_group.rst b/Help/command/source_group.rst
index 6623c98..5ae9e51 100644
--- a/Help/command/source_group.rst
+++ b/Help/command/source_group.rst
@@ -37,11 +37,13 @@ explicitly lists the file with ``FILES`` will be favored, if any.
If no group explicitly lists the file, the *last* group whose
regular expression matches the file will be favored.
-The ``<name>`` of the group and ``<prefix>`` argument may contain backslashes
-to specify subgroups:
+The ``<name>`` of the group and ``<prefix>`` argument may contain forward
+slashes or backslashes to specify subgroups. Backslashes need to be escaped
+appropriately:
.. code-block:: cmake
+ source_group(base/subdir ...)
source_group(outer\\inner ...)
source_group(TREE <root> PREFIX sources\\inc ...)
diff --git a/Help/command/string.rst b/Help/command/string.rst
index 81a2061..cfcf914 100644
--- a/Help/command/string.rst
+++ b/Help/command/string.rst
@@ -11,8 +11,6 @@ Synopsis
`Search and Replace`_
string(`FIND`_ <string> <substring> <out-var> [...])
string(`REPLACE`_ <match-string> <replace-string> <out-var> <input>...)
-
- `Regular Expressions`_
string(`REGEX MATCH`_ <match-regex> <out-var> <input>...)
string(`REGEX MATCHALL`_ <match-regex> <out-var> <input>...)
string(`REGEX REPLACE`_ <match-regex> <replace-expr> <out-var> <input>...)
@@ -38,6 +36,7 @@ Synopsis
`Generation`_
string(`ASCII`_ <number>... <out-var>)
+ string(`HEX`_ <string> <out-var>)
string(`CONFIGURE`_ <string> <out-var> [...])
string(`MAKE_C_IDENTIFIER`_ <string> <out-var>)
string(`RANDOM`_ [<option>...] <out-var>)
@@ -47,6 +46,9 @@ Synopsis
Search and Replace
^^^^^^^^^^^^^^^^^^
+Search and Replace With Plain Strings
+"""""""""""""""""""""""""""""""""""""
+
.. _FIND:
.. code-block:: cmake
@@ -74,8 +76,8 @@ so strings containing multi-byte characters may lead to unexpected results.
Replace all occurrences of ``<match_string>`` in the ``<input>``
with ``<replace_string>`` and store the result in the ``<output_variable>``.
-Regular Expressions
-^^^^^^^^^^^^^^^^^^^
+Search and Replace With Regular Expressions
+"""""""""""""""""""""""""""""""""""""""""""
.. _`REGEX MATCH`:
@@ -87,6 +89,7 @@ Regular Expressions
Match the ``<regular_expression>`` once and store the match in the
``<output_variable>``.
All ``<input>`` arguments are concatenated before matching.
+Regular expressions are specified in the subsection just below.
.. _`REGEX MATCHALL`:
@@ -353,6 +356,16 @@ Generation
Convert all numbers into corresponding ASCII characters.
+.. _HEX:
+
+.. code-block:: cmake
+
+ string(HEX <string> <output_variable>)
+
+Convert each byte in the input ``<string>`` to its hexadecimal representation
+and store the concatenated hex digits in the ``<output_variable>``. Letters in
+the output (``a`` through ``f``) are in lowercase.
+
.. _CONFIGURE:
.. code-block:: cmake
diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst
index 47e7d86..3c733c5 100644
--- a/Help/command/target_compile_options.rst
+++ b/Help/command/target_compile_options.rst
@@ -46,3 +46,5 @@ to use the more specific commands :command:`target_compile_definitions`
and :command:`target_include_directories`.
For directory-wide settings, there is the command :command:`add_compile_options`.
+
+For file-specific settings, there is the source file property :prop_sf:`COMPILE_OPTIONS`.
diff --git a/Help/command/target_link_options.rst b/Help/command/target_link_options.rst
index b5abbc4..89038e3 100644
--- a/Help/command/target_link_options.rst
+++ b/Help/command/target_link_options.rst
@@ -43,6 +43,8 @@ with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.
+.. include:: DEVICE_LINK_OPTIONS.txt
+
.. include:: OPTIONS_SHELL.txt
.. include:: LINK_OPTIONS_LINKER.txt
diff --git a/Help/cpack_gen/archive.rst b/Help/cpack_gen/archive.rst
index d455f4b..3656aa2 100644
--- a/Help/cpack_gen/archive.rst
+++ b/Help/cpack_gen/archive.rst
@@ -1,8 +1,8 @@
CPack Archive Generator
-----------------------
-Archive CPack generator that supports packaging of sources and binaries in
-different formats:
+CPack generator for packaging files into an archive, which can have
+any of the following formats:
- 7Z - 7zip - (.7z)
- TBZ2 (.tar.bz2)
@@ -12,25 +12,64 @@ different formats:
- TZST (.tar.zst)
- ZIP (.zip)
+When this generator is called from ``CPackSourceConfig.cmake`` (or through
+the ``package_source`` target), then the generated archive will contain all
+files in the project directory, except those specified in
+:variable:`CPACK_SOURCE_IGNORE_FILES`. The following is one example of
+packaging all source files of a project:
+
+.. code-block:: cmake
+
+ set(CPACK_SOURCE_GENERATOR "TGZ")
+ set(CPACK_SOURCE_IGNORE_FILES
+ \\.git/
+ build/
+ ".*~$"
+ )
+ set(CPACK_VERBATIM_VARIABLES YES)
+ include(CPack)
+
+When this generator is called from ``CPackConfig.cmake`` (or through the
+``package`` target), then the generated archive will contain all files
+that have been installed via CMake's :command:`install` command (and the
+deprecated commands :command:`install_files`, :command:`install_programs`,
+and :command:`install_targets`).
+
Variables specific to CPack Archive generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. variable:: CPACK_ARCHIVE_FILE_NAME
CPACK_ARCHIVE_<component>_FILE_NAME
- Package file name without extension which is added automatically depending
- on the archive format.
-
- * Mandatory : YES
- * Default : ``<CPACK_PACKAGE_FILE_NAME>[-<component>].<extension>`` with
- spaces replaced by '-'
+ Package file name without extension. The extension is determined from the
+ archive format (see list above) and automatically appended to the file name.
+ The default is ``<CPACK_PACKAGE_FILE_NAME>[-<component>]``, with spaces
+ replaced by '-'.
.. variable:: CPACK_ARCHIVE_COMPONENT_INSTALL
- Enable component packaging for CPackArchive
+ Enable component packaging. If enabled (ON), then the archive generator
+ creates multiple packages. The default is OFF, which means that a single
+ package containing files of all components is generated.
+
+Variables used by CPack Archive generator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These variables are used by the Archive generator, but are also available to
+CPack generators which are essentially archives at their core. These include:
+
+ - :cpack_gen:`CPack Cygwin Generator`
+ - :cpack_gen:`CPack FreeBSD Generator`
+
+.. variable:: CPACK_ARCHIVE_THREADS
+
+ The number of threads to use when performing the compression. If set to
+ ``0``, the number of available cores on the machine will be used instead.
+ The default is ``1`` which limits compression to a single thread. Note that
+ not all compression modes support threading in all environments. Currently,
+ only the XZ compression may support it.
- * Mandatory : NO
- * Default : OFF
+.. note::
- If enabled (ON) multiple packages are generated. By default a single package
- containing files of all components is generated.
+ Official CMake binaries available on ``cmake.org`` ship with a ``liblzma``
+ that does not support parallel compression.
diff --git a/Help/cpack_gen/cygwin.rst b/Help/cpack_gen/cygwin.rst
index 1c5f7af..c65653e 100644
--- a/Help/cpack_gen/cygwin.rst
+++ b/Help/cpack_gen/cygwin.rst
@@ -3,6 +3,11 @@ CPack Cygwin Generator
Cygwin CPack generator (Cygwin).
+Variables affecting the CPack Cygwin generator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ - :variable:`CPACK_ARCHIVE_THREADS`
+
Variables specific to CPack Cygwin generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/Help/cpack_gen/freebsd.rst b/Help/cpack_gen/freebsd.rst
index a8dd320..47a7784 100644
--- a/Help/cpack_gen/freebsd.rst
+++ b/Help/cpack_gen/freebsd.rst
@@ -3,6 +3,11 @@ CPack FreeBSD Generator
The built in (binary) CPack FreeBSD (pkg) generator (Unix only)
+Variables affecting the CPack FreeBSD (pkg) generator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ - :variable:`CPACK_ARCHIVE_THREADS`
+
Variables specific to CPack FreeBSD (pkg) generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/Help/cpack_gen/ifw.rst b/Help/cpack_gen/ifw.rst
index 4a9ab99..776bb46 100644
--- a/Help/cpack_gen/ifw.rst
+++ b/Help/cpack_gen/ifw.rst
@@ -1,73 +1,28 @@
CPack IFW Generator
-------------------
+Configure and run the Qt Installer Framework to generate a Qt installer.
+
+.. only:: html
+
+ .. contents::
+
Overview
^^^^^^^^
This :manual:`cpack generator <cpack-generators(7)>` generates
configuration and meta information for the `Qt Installer Framework
-<http://doc.qt.io/qtinstallerframework/index.html>`_ (QtIFW).
+<http://doc.qt.io/qtinstallerframework/index.html>`_ (QtIFW),
+and runs QtIFW tools to generate a Qt installer.
QtIFW provides tools and utilities to create installers for
the platforms supported by `Qt <https://www.qt.io>`_: Linux,
Microsoft Windows, and macOS.
-To make use of this generator, QtIFW should also be installed.
-The module :module:`CPackIFW` looks for the location of the
-QtIFW command-line utilities.
-
-Hints
-^^^^^
-
-Generally, the CPack ``IFW`` generator automatically finds QtIFW tools,
-but if you don't use a default path for installation of the QtIFW tools,
-the path may be specified in either a CMake or an environment variable:
-
-.. variable:: CPACK_IFW_ROOT
-
- An CMake variable which specifies the location of the QtIFW tool suite.
-
- The variable will be cached in the ``CPackConfig.cmake`` file and used at
- CPack runtime.
-
-.. variable:: QTIFWDIR
-
- An environment variable which specifies the location of the QtIFW tool
- suite.
-
-.. note::
- The specified path should not contain "bin" at the end
- (for example: "D:\\DevTools\\QtIFW2.0.5").
-
-The :variable:`CPACK_IFW_ROOT` variable has a higher priority and overrides
-the value of the :variable:`QTIFWDIR` variable.
-
-Internationalization
-^^^^^^^^^^^^^^^^^^^^
-
-Some variables and command arguments support internationalization via
-CMake script. This is an optional feature.
-
-Installers created by QtIFW tools have built-in support for
-internationalization and many phrases are localized to many languages,
-but this does not apply to the description of the your components and groups
-that will be distributed.
-
-Localization of the description of your components and groups is useful for
-users of your installers.
-
-A localized variable or argument can contain a single default value, and a
-set of pairs the name of the locale and the localized value.
-
-For example:
-
-.. code-block:: cmake
-
- set(LOCALIZABLE_VARIABLE "Default value"
- en "English value"
- en_US "American value"
- en_GB "Great Britain value"
- )
+To make use of this generator, QtIFW needs to be installed.
+The :module:`CPackIFW` module looks for the location of the
+QtIFW command-line utilities, and defines several commands to
+control the behavior of this generator.
Variables
^^^^^^^^^
@@ -157,6 +112,8 @@ Package
Default target directory for installation.
By default used
"@ApplicationsDir@/:variable:`CPACK_PACKAGE_INSTALL_DIRECTORY`"
+ (variables embedded in '@' are expanded by the
+ `QtIFW scripting engine <https://doc.qt.io/qtinstallerframework/scripting.html>`_).
You can use predefined variables.
@@ -263,55 +220,111 @@ Components
repack dependent components. This feature available only
since QtIFW 3.1.
-Tools
-"""""
+QtIFW Tools
+"""""""""""
.. variable:: CPACK_IFW_FRAMEWORK_VERSION
The version of used QtIFW tools.
-.. variable:: CPACK_IFW_BINARYCREATOR_EXECUTABLE
+The following variables provide the locations of the QtIFW
+command-line tools as discovered by the module :module:`CPackIFW`.
+These variables are cached, and may be configured if needed.
- The path to "binarycreator" command line client.
+.. variable:: CPACK_IFW_BINARYCREATOR_EXECUTABLE
- This variable is cached and may be configured if needed.
+ The path to ``binarycreator``.
.. variable:: CPACK_IFW_REPOGEN_EXECUTABLE
- The path to "repogen" command line client.
-
- This variable is cached and may be configured if needed.
+ The path to ``repogen``.
.. variable:: CPACK_IFW_INSTALLERBASE_EXECUTABLE
- The path to "installerbase" installer executable base.
-
- This variable is cached and may be configured if needed.
+ The path to ``installerbase``.
.. variable:: CPACK_IFW_DEVTOOL_EXECUTABLE
- The path to "devtool" command line client.
+ The path to ``devtool``.
+
+Hints for Finding QtIFW
+"""""""""""""""""""""""
+
+Generally, the CPack ``IFW`` generator automatically finds QtIFW tools,
+but if you don't use a default path for installation of the QtIFW tools,
+the path may be specified in either a CMake or an environment variable:
+
+.. variable:: CPACK_IFW_ROOT
- This variable is cached and may be configured if needed.
+ An CMake variable which specifies the location of the QtIFW tool suite.
+
+ The variable will be cached in the ``CPackConfig.cmake`` file and used at
+ CPack runtime.
+
+.. variable:: QTIFWDIR
+
+ An environment variable which specifies the location of the QtIFW tool
+ suite.
+
+.. note::
+ The specified path should not contain "bin" at the end
+ (for example: "D:\\DevTools\\QtIFW2.0.5").
+
+The :variable:`CPACK_IFW_ROOT` variable has a higher priority and overrides
+the value of the :variable:`QTIFWDIR` variable.
+Other Settings
+^^^^^^^^^^^^^^
Online installer
-^^^^^^^^^^^^^^^^
+""""""""""""""""
-By default CPack IFW generator makes offline installer. This means that all
-components will be packaged into a binary file.
+By default, this generator generates an *offline installer*. This means that
+that all packaged files are fully contained in the installer executable.
-To make a component downloaded, you must set the ``DOWNLOADED`` option in
-:command:`cpack_add_component`.
+In contrast, an *online installer* will download some or all components from
+a remote server.
-Then you would use the command :command:`cpack_configure_downloads`.
-If you set ``ALL`` option all components will be downloaded.
+The ``DOWNLOADED`` option in the :command:`cpack_add_component` command
+specifies that a component is to be downloaded. Alternatively, the ``ALL``
+option in the :command:`cpack_configure_downloads` command specifies that
+`all` components are to be be downloaded.
-You also can use command :command:`cpack_ifw_add_repository` and
-variable :variable:`CPACK_IFW_DOWNLOAD_ALL` for more specific configuration.
+The :command:`cpack_ifw_add_repository` command and the
+:variable:`CPACK_IFW_DOWNLOAD_ALL` variable allow for more specific
+configuration.
-CPack IFW generator creates "repository" dir in current binary dir. You
-would copy content of this dir to specified ``site`` (``url``).
+When there are online components, CPack will write them to archive files.
+The help page of the :module:`CPackComponent` module, especially the section
+on the :command:`cpack_configure_downloads` function, explains how to make
+these files accessible from a download URL.
+
+Internationalization
+""""""""""""""""""""
+
+Some variables and command arguments support internationalization via
+CMake script. This is an optional feature.
+
+Installers created by QtIFW tools have built-in support for
+internationalization and many phrases are localized to many languages,
+but this does not apply to the description of the your components and groups
+that will be distributed.
+
+Localization of the description of your components and groups is useful for
+users of your installers.
+
+A localized variable or argument can contain a single default value, and a
+set of pairs the name of the locale and the localized value.
+
+For example:
+
+.. code-block:: cmake
+
+ set(LOCALIZABLE_VARIABLE "Default value"
+ en "English value"
+ en_US "American value"
+ en_GB "Great Britain value"
+ )
See Also
^^^^^^^^
@@ -330,5 +343,5 @@ Qt Installer Framework Manual:
* Promoting Updates:
http://doc.qt.io/qtinstallerframework/ifw-updates.html
-Download Qt Installer Framework for you platform from Qt site:
+Download Qt Installer Framework for your platform from Qt site:
http://download.qt.io/official_releases/qt-installer-framework
diff --git a/Help/cpack_gen/nsis.rst b/Help/cpack_gen/nsis.rst
index d1e495f..0dd876e 100644
--- a/Help/cpack_gen/nsis.rst
+++ b/Help/cpack_gen/nsis.rst
@@ -155,3 +155,7 @@ on Windows Nullsoft Scriptable Install System.
.. variable:: CPACK_NSIS_MUI_HEADERIMAGE
The image to display on the header of installers pages.
+
+.. variable:: CPACK_NSIS_MANIFEST_DPI_AWARE
+
+ If set, declares that the installer is DPI-aware.
diff --git a/Help/cpack_gen/rpm.rst b/Help/cpack_gen/rpm.rst
index 2693c7b..66d5464 100644
--- a/Help/cpack_gen/rpm.rst
+++ b/Help/cpack_gen/rpm.rst
@@ -473,38 +473,42 @@ List of CPack RPM generator specific variables:
.. variable:: CPACK_RPM_PRE_INSTALL_SCRIPT_FILE
CPACK_RPM_PRE_UNINSTALL_SCRIPT_FILE
+ CPACK_RPM_PRE_TRANS_SCRIPT_FILE
- Path to file containing pre (un)install script.
+ Path to file containing pre install/uninstall/transaction script.
* Mandatory : NO
* Default : -
- May be used to embed a pre (un)installation script in the spec file.
+ May be used to embed a pre installation/uninstallation/transaction script in the spec file.
The referred script file (or both) will be read and directly
put after the ``%pre`` or ``%preun`` section
- If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the (un)install
+ If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the install/uninstall/transaction
script for each component can be overridden with
- ``CPACK_RPM_<COMPONENT>_PRE_INSTALL_SCRIPT_FILE`` and
- ``CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_SCRIPT_FILE``.
+ ``CPACK_RPM_<COMPONENT>_PRE_INSTALL_SCRIPT_FILE``,
+ ``CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_SCRIPT_FILE``, and
+ ``CPACK_RPM_<COMPONENT>_PRE_TRANS_SCRIPT_FILE``
One may verify which scriptlet has been included with::
rpm -qp --scripts package.rpm
.. variable:: CPACK_RPM_POST_INSTALL_SCRIPT_FILE
CPACK_RPM_POST_UNINSTALL_SCRIPT_FILE
+ CPACK_RPM_POST_TRANS_SCRIPT_FILE
- Path to file containing post (un)install script.
+ Path to file containing post install/uninstall/transaction script.
* Mandatory : NO
* Default : -
- May be used to embed a post (un)installation script in the spec file.
+ May be used to embed a post installation/uninstallation/transaction script in the spec file.
The referred script file (or both) will be read and directly
put after the ``%post`` or ``%postun`` section.
- If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the (un)install
+ If :variable:`CPACK_RPM_COMPONENT_INSTALL` is set to ON the install/uninstall/transaction
script for each component can be overridden with
- ``CPACK_RPM_<COMPONENT>_POST_INSTALL_SCRIPT_FILE`` and
- ``CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE``.
+ ``CPACK_RPM_<COMPONENT>_POST_INSTALL_SCRIPT_FILE``,
+ ``CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE``, and
+ ``CPACK_RPM_<COMPONENT>_POST_TRANS_SCRIPT_FILE``
One may verify which scriptlet has been included with::
rpm -qp --scripts package.rpm
diff --git a/Help/dev/source.rst b/Help/dev/source.rst
index 0f7488b..0ccb8f4 100644
--- a/Help/dev/source.rst
+++ b/Help/dev/source.rst
@@ -23,12 +23,157 @@ format only a subset of files, such as those that are locally modified.
C++ Subset Permitted
====================
-CMake requires compiling as C++11 or above. However, in order to support
-building on older toolchains some constructs need to be handled with care:
+CMake requires compiling as C++11 in order to support building on older
+toolchains. However, to facilitate development, some standard library
+features from more recent C++ standards are supported through a compatibility
+layer. These features are defined under the namespace ``cm`` and headers
+are accessible under the ``cm/`` directory. The headers under ``cm/`` can
+be used in place of the standard ones when extended features are needed.
+For example ``<cm/memory>`` can be used in place of ``<memory>``.
-* Do not use ``std::auto_ptr``.
+Available features are:
- The ``std::auto_ptr`` template is deprecated in C++11. Use ``std::unique_ptr``.
+* From ``C++14``:
+
+ * ``<cm/iterator>``:
+ ``cm::make_reverse_iterator``, ``cm::cbegin``, ``cm::cend``,
+ ``cm::rbegin``, ``cm::rend``, ``cm::crbegin``, ``cm::crend``
+
+ * ``<cm/memory>``:
+ ``cm::make_unique``
+
+ * ``<cm/shared_mutex>``:
+ ``cm::shared_lock``
+
+ * ``<cm/type_traits>``:
+ ``cm::enable_if_t``
+
+* From ``C++17``:
+
+ * ``<cm/algorithm>``:
+ ``cm::clamp``
+
+ * ``<cm/iterator>``:
+ ``cm::size``, ``cm::empty``, ``cm::data``
+
+ * ``<cm/optional>``:
+ ``cm::nullopt_t``, ``cm::nullopt``, ``cm::optional``,
+ ``cm::make_optional``, ``cm::bad_optional_access``
+
+ * ``<cm/shared_mutex>``:
+ ``cm::shared_mutex``
+
+ * ``<cm/string_view>``:
+ ``cm::string_view``
+
+ * ``<cm/type_traits>``:
+ ``cm::bool_constant``, ``cm::invoke_result_t``, ``cm::invoke_result``,
+ ``cm::void_t``
+
+ * ``<cm/utility>``:
+ ``cm::in_place_t``, ``cm::in_place``
+
+* From ``C++20``:
+
+ * ``<cm/deque>``:
+ ``cm::erase``, ``cm::erase_if``
+
+ * ``<cm/list>``:
+ ``cm::erase``, ``cm::erase_if``
+
+ * ``<cm/map>`` :
+ ``cm::erase_if``
+
+ * ``<cm/set>`` :
+ ``cm::erase_if``
+
+ * ``<cm/string>``:
+ ``cm::erase``, ``cm::erase_if``
+
+ * ``<cm/unordered_map>``:
+ ``cm::erase_if``
+
+ * ``<cm/unordered_set>``:
+ ``cm::erase_if``
+
+ * ``<cm/vector>``:
+ ``cm::erase``, ``cm::erase_if``
+
+Additionally, some useful non-standard extensions to the C++ standard library
+are available in headers under the directory ``cmext/`` in namespace ``cm``.
+These are:
+
+* ``<cmext/algorithm>``:
+
+ * ``cm::append``:
+ Append elements to a sequential container.
+
+ * ``cm::contains``:
+ Checks if element or key is contained in container.
+
+* ``<cmext/iterator>``:
+
+ * ``cm::is_terator``:
+ Checks if a type is an iterator type.
+
+ * ``cm::is_input_iterator``:
+ Checks if a type is an input iterator type.
+
+ * ``cm::is_range``:
+ Checks if a type is a range type: functions ``std::begin()`` and
+ ``std::end()`` apply.
+
+ * ``cm::is_input_range``:
+ Checks if a type is an input range type: functions ``std::begin()`` and
+ ``std::end()`` apply and return an input iterator.
+
+* ``<cmext/memory>``:
+
+ * ``cm::static_reference_cast``:
+ Apply a ``static_cast`` to a smart pointer.
+
+ * ``cm::dynamic_reference_cast``:
+ Apply a ``dynamic_cast`` to a smart pointer.
+
+* ``<cmext/type_traits>``:
+
+ * ``cm::is_container``:
+ Checks if a type is a container type.
+
+ * ``cm::is_associative_container``:
+ Checks if a type is an associative container type.
+
+ * ``cm::is_unordered_associative_container``:
+ Checks if a type is an unordered associative container type.
+
+ * ``cm::is_sequence_container``:
+ Checks if a type is a sequence container type.
+
+ * ``cm::is_unique_ptr``:
+ Checks if a type is a ``std::unique_ptr`` type.
+
+Dynamic Memory Management
+=========================
+
+To ensure efficient memory management, i.e. no memory leaks, it is required
+to use smart pointers. Any dynamic memory allocation must be handled by a
+smart pointer such as ``std::unique_ptr`` or ``std::shared_ptr``.
+
+It is allowed to pass raw pointers between objects to enable objects sharing.
+A raw pointer **must** not be deleted. Only the object(s) owning the smart
+pointer are allowed to delete dynamically allocated memory.
+
+Third Parties
+=============
+
+To build CMake, some third parties are needed. Under ``Utilities``
+directory, are versions of these third parties which can be used as an
+alternate to the ones provided by the system.
+
+To enable the selection of the third parties between the system and CMake ones,
+in CMake sources, third parties headers must be prefixed by ``cm3p/``
+(for example: ``<cm3p/json/reader.h>``). These wrappers are located under
+``Utilities/cm3p`` directory.
Source Tree Layout
==================
@@ -69,6 +214,15 @@ The CMake source tree is organized as follows.
* ``Utilities/``:
Scripts, third-party source code.
+ * ``Utilities/std/cm``:
+ Support files for various C++ standards.
+
+ * ``Utilities/std/cmext``:
+ Extensions to the C++ STL.
+
+ * ``Utilities/cm3p``:
+ Public headers for third parties needed to build CMake.
+
* ``Utilities/Sphinx/``:
Sphinx configuration to build CMake user documentation.
diff --git a/Help/envvar/CCMAKE_COLORS.rst b/Help/envvar/CCMAKE_COLORS.rst
new file mode 100644
index 0000000..d4750c3
--- /dev/null
+++ b/Help/envvar/CCMAKE_COLORS.rst
@@ -0,0 +1,34 @@
+CCMAKE_COLORS
+-------------
+
+Determines what colors are used by the CMake curses interface,
+when run on a terminal that supports colors.
+The syntax follows the same conventions as ``LS_COLORS``;
+that is, a list of key/value pairs separated by ``:``.
+
+Keys are a single letter corresponding to a CMake cache variable type:
+
+- ``s``: A ``STRING``.
+- ``p``: A ``FILEPATH``.
+- ``c``: A value which has an associated list of choices.
+- ``y``: A ``BOOL`` which has a true-like value (e.g. ``ON``, ``YES``).
+- ``n``: A ``BOOL`` which has a false-like value (e.g. ``OFF``, ``NO``).
+
+Values are an integer number that specifies what color to use.
+``0`` is black (you probably don't want to use that).
+Others are determined by your terminal's color support.
+Most (color) terminals will support at least 8 or 16 colors.
+Some will support up to 256 colors. The colors will likely match
+`this chart <https://upload.wikimedia.org/wikipedia/commons/1/15/Xterm_256color_chart.svg>`_,
+although the first 16 colors may match the original
+`CGA color palette <https://en.wikipedia.org/wiki/Color_Graphics_Adapter#Color_palette>`_.
+(Many modern terminal emulators also allow their color palette,
+at least for the first 16 colors, to be configured by the user.)
+
+Note that fairly minimal checking is done for bad colors
+(although a value higher than what curses believes your terminal supports
+will be silently ignored) or bad syntax.
+
+For example::
+
+ CCMAKE_COLORS='s=39:p=220:c=207:n=196:y=46'
diff --git a/Help/envvar/CMAKE_PREFIX_PATH.rst b/Help/envvar/CMAKE_PREFIX_PATH.rst
new file mode 100644
index 0000000..276fdd6
--- /dev/null
+++ b/Help/envvar/CMAKE_PREFIX_PATH.rst
@@ -0,0 +1,17 @@
+CMAKE_PREFIX_PATH
+-----------------
+
+.. include:: ENV_VAR.txt
+
+The ``CMAKE_PREFIX_PATH`` environment variable may be set to a list of
+directories specifying installation *prefixes* to be searched by the
+:command:`find_package`, :command:`find_program`, :command:`find_library`,
+:command:`find_file`, and :command:`find_path` commands. Each command will
+add appropriate subdirectories (like ``bin``, ``lib``, or ``include``)
+as specified in its own documentation.
+
+This variable may hold a single prefix or a list of prefixes separated
+by ``:`` on UNIX or ``;`` on Windows (the same as the ``PATH`` environment
+variable convention on those platforms).
+
+See also the :variable:`CMAKE_PREFIX_PATH` CMake variable.
diff --git a/Help/guide/tutorial/Step5/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step5/MathFunctions/MakeTable.cxx
deleted file mode 100644
index ee58556..0000000
--- a/Help/guide/tutorial/Step5/MathFunctions/MakeTable.cxx
+++ /dev/null
@@ -1,25 +0,0 @@
-// A simple program that builds a sqrt table
-#include <cmath>
-#include <fstream>
-#include <iostream>
-
-int main(int argc, char* argv[])
-{
- // make sure we have enough arguments
- if (argc < 2) {
- return 1;
- }
-
- std::ofstream fout(argv[1], std::ios_base::out);
- const bool fileOpen = fout.is_open();
- if (fileOpen) {
- fout << "double sqrtTable[] = {" << std::endl;
- for (int i = 0; i < 10; ++i) {
- fout << sqrt(static_cast<double>(i)) << "," << std::endl;
- }
- // close the table with a zero
- fout << "0};" << std::endl;
- fout.close();
- }
- return fileOpen ? 0 : 1; // return 0 if wrote the file
-}
diff --git a/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt
index 4bf6024..f64c6ac 100644
--- a/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt
+++ b/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt
@@ -8,10 +8,20 @@ target_include_directories(MathFunctions
# does this system provide the log and exp functions?
include(CheckSymbolExists)
-set(CMAKE_REQUIRED_LIBRARIES "m")
check_symbol_exists(log "math.h" HAVE_LOG)
check_symbol_exists(exp "math.h" HAVE_EXP)
+if(NOT (HAVE_LOG AND HAVE_EXP))
+ unset(HAVE_LOG CACHE)
+ unset(HAVE_EXP CACHE)
+ set(CMAKE_REQUIRED_LIBRARIES "m")
+ check_symbol_exists(log "math.h" HAVE_LOG)
+ check_symbol_exists(exp "math.h" HAVE_EXP)
+ if(HAVE_LOG AND HAVE_EXP)
+ target_link_libraries(MathFunctions PRIVATE m)
+ endif()
+endif()
+# add compile definitions
if(HAVE_LOG AND HAVE_EXP)
target_compile_definitions(MathFunctions
PRIVATE "HAVE_LOG" "HAVE_EXP")
diff --git a/Help/guide/tutorial/index.rst b/Help/guide/tutorial/index.rst
index a844cbf..6e26de9 100644
--- a/Help/guide/tutorial/index.rst
+++ b/Help/guide/tutorial/index.rst
@@ -380,13 +380,17 @@ tutorial assume that they are not common.
If the platform has ``log`` and ``exp`` then we will use them to compute the
square root in the ``mysqrt`` function. We first test for the availability of
these functions using the :module:`CheckSymbolExists` module in the top-level
-``CMakeLists.txt``. We're going to use the new defines in
-``TutorialConfig.h.in``, so be sure to set them before that file is configured.
+``CMakeLists.txt``. On some platforms, we will need to link to the m library.
+If ``log`` and ``exp`` are not initially found, require the m library and try
+again.
+
+We're going to use the new defines in ``TutorialConfig.h.in``, so be sure to
+set them before that file is configured.
.. literalinclude:: Step6/MathFunctions/CMakeLists.txt
:language: cmake
:start-after: # does this system provide the log and exp functions?
- :end-before: if(HAVE_LOG AND HAVE_EXP)
+ :end-before: # add compile definitions
Now let's add these defines to ``TutorialConfig.h.in`` so that we can use them
from ``mysqrt.cxx``:
diff --git a/Help/guide/user-interaction/index.rst b/Help/guide/user-interaction/index.rst
index 3a1038f..c724b6f 100644
--- a/Help/guide/user-interaction/index.rst
+++ b/Help/guide/user-interaction/index.rst
@@ -86,6 +86,7 @@ populated. It is always advised to use different
directories for the source and the build.
.. image:: /guide/user-interaction/GUI-Source-Binary.png
+ :alt: Choosing source and binary directories
Generating a Buildsystem
========================
@@ -246,16 +247,19 @@ The "Configure" button triggers a new dialog to
select the CMake generator to use.
.. image:: /guide/user-interaction/GUI-Configure-Dialog.png
+ :alt: Configuring a generator
All generators available on the command line are also
available in :manual:`cmake-gui(1)`.
.. image:: /guide/user-interaction/GUI-Choose-Generator.png
+ :alt: Choosing a generator
When choosing a Visual Studio generator, further options
are available to set an architecture to generate for.
.. image:: /manual/VS-Choose-Arch.png
+ :alt: Choosing an architecture for Visual Studio generators
.. _`Setting Build Variables`:
@@ -356,6 +360,7 @@ button. This triggers a new dialog to set the value of
the variable.
.. image:: /guide/user-interaction/GUI-Add-Entry.png
+ :alt: Editing a cache entry
The main view of the :manual:`cmake-gui(1)` user interface
can be used to edit existing variables.
diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst
index 59ba897..87743b4 100644
--- a/Help/manual/cmake-commands.7.rst
+++ b/Help/manual/cmake-commands.7.rst
@@ -16,6 +16,7 @@ These commands are always available.
:maxdepth: 1
/command/break
+ /command/cmake_command
/command/cmake_host_system_information
/command/cmake_minimum_required
/command/cmake_parse_arguments
diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst
index f72e414..ce1e360 100644
--- a/Help/manual/cmake-env-variables.7.rst
+++ b/Help/manual/cmake-env-variables.7.rst
@@ -14,6 +14,13 @@ For general information on environment variables, see the
:ref:`Environment Variables <CMake Language Environment Variables>`
section in the cmake-language manual.
+Environment Variables that Change Behavior
+==========================================
+
+.. toctree::
+ :maxdepth: 1
+
+ /envvar/CMAKE_PREFIX_PATH
Environment Variables that Control the Build
============================================
@@ -75,3 +82,11 @@ Environment Variables for CTest
/envvar/CTEST_PROGRESS_OUTPUT
/envvar/CTEST_USE_LAUNCHERS_DEFAULT
/envvar/DASHBOARD_TEST_FROM_CTEST
+
+Environment Variables for the CMake curses interface
+====================================================
+
+.. toctree::
+ :maxdepth: 1
+
+ /envvar/CCMAKE_COLORS
diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst
index 691481b..9e411a4 100644
--- a/Help/manual/cmake-generator-expressions.7.rst
+++ b/Help/manual/cmake-generator-expressions.7.rst
@@ -259,6 +259,121 @@ Variable Queries
add_executable(myapp main.cpp)
target_link_libraries(myapp myapp_c myapp_cxx)
+.. _`Boolean LINK_LANGUAGE Generator Expression`:
+
+``$<LINK_LANG_AND_ID:language,compiler_ids>``
+ ``1`` when the language used for link step matches ``language`` and the
+ CMake's compiler id of the language linker matches any one of the entries
+ in ``compiler_ids``, otherwise ``0``. This expression is a short form for the
+ combination of ``$<LINK_LANGUAGE:language>`` and
+ ``$<LANG_COMPILER_ID:compiler_ids>``. This expression may be used to specify
+ link libraries, link options, link directories and link dependencies of a
+ particular language and linker combination in a target. For example:
+
+ .. code-block:: cmake
+
+ add_library(libC_Clang ...)
+ add_library(libCXX_Clang ...)
+ add_library(libC_Intel ...)
+ add_library(libCXX_Intel ...)
+
+ add_executable(myapp main.c)
+ if (CXX_CONFIG)
+ target_sources(myapp PRIVATE file.cxx)
+ endif()
+ target_link_libraries(myapp
+ PRIVATE $<$<LINK_LANG_AND_ID:CXX,Clang,AppleClang>:libCXX_Clang>
+ $<$<LINK_LANG_AND_ID:C,Clang,AppleClang>:libC_Clang>
+ $<$<LINK_LANG_AND_ID:CXX,Intel>:libCXX_Intel>
+ $<$<LINK_LANG_AND_ID:C,Intel>:libC_Intel>)
+
+ This specifies the use of different link libraries based on both the
+ compiler id and link language. This example will have target ``libCXX_Clang``
+ as link dependency when ``Clang`` or ``AppleClang`` is the ``CXX``
+ linker, and ``libCXX_Intel`` when ``Intel`` is the ``CXX`` linker.
+ Likewise when the ``C`` linker is ``Clang`` or ``AppleClang``, target
+ ``libC_Clang`` will be added as link dependency and ``libC_Intel`` when
+ ``Intel`` is the ``C`` linker.
+
+ See :ref:`the note related to
+ <Constraints LINK_LANGUAGE Generator Expression>`
+ ``$<LINK_LANGUAGE:language>`` for constraints about the usage of this
+ generator expression.
+
+``$<LINK_LANGUAGE:languages>``
+ ``1`` when the language used for link step matches any of the entries
+ in ``languages``, otherwise ``0``. This expression may be used to specify
+ link libraries, link options, link directories and link dependencies of a
+ particular language in a target. For example:
+
+ .. code-block:: cmake
+
+ add_library(api_C ...)
+ add_library(api_CXX ...)
+ add_library(api INTERFACE)
+ target_link_options(api INTERFACE $<$<LINK_LANGUAGE:C>:-opt_c>
+ $<$<LINK_LANGUAGE:CXX>:-opt_cxx>)
+ target_link_libraries(api INTERFACE $<$<LINK_LANGUAGE:C>:api_C>
+ $<$<LINK_LANGUAGE:CXX>:api_CXX>)
+
+ add_executable(myapp1 main.c)
+ target_link_options(myapp1 PRIVATE api)
+
+ add_executable(myapp2 main.cpp)
+ target_link_options(myapp2 PRIVATE api)
+
+ This specifies to use the ``api`` target for linking targets ``myapp1`` and
+ ``myapp2``. In practice, ``myapp1`` will link with target ``api_C`` and
+ option ``-opt_c`` because it will use ``C`` as link language. And ``myapp2``
+ will link with ``api_CXX`` and option ``-opt_cxx`` because ``CXX`` will be
+ the link language.
+
+ .. _`Constraints LINK_LANGUAGE Generator Expression`:
+
+ .. note::
+
+ To determine the link language of a target, it is required to collect,
+ transitively, all the targets which will be linked to it. So, for link
+ libraries properties, a double evaluation will be done. During the first
+ evaluation, ``$<LINK_LANGUAGE:..>`` expressions will always return ``0``.
+ The link language computed after this first pass will be used to do the
+ second pass. To avoid inconsistency, it is required that the second pass
+ do not change the link language. Moreover, to avoid unexpected
+ side-effects, it is required to specify complete entities as part of the
+ ``$<LINK_LANGUAGE:..>`` expression. For example:
+
+ .. code-block:: cmake
+
+ add_library(lib STATIC file.cxx)
+ add_library(libother STATIC file.c)
+
+ # bad usage
+ add_executable(myapp1 main.c)
+ target_link_libraries(myapp1 PRIVATE lib$<$<LINK_LANGUAGE:C>:other>)
+
+ # correct usage
+ add_executable(myapp2 main.c)
+ target_link_libraries(myapp2 PRIVATE $<$<LINK_LANGUAGE:C>:libother>)
+
+ In this example, for ``myapp1``, the first pass will, unexpectedly,
+ determine that the link language is ``CXX`` because the evaluation of the
+ generator expression will be an empty string so ``myapp1`` will depends on
+ target ``lib`` which is ``C++``. On the contrary, for ``myapp2``, the first
+ evaluation will give ``C`` as link language, so the second pass will
+ correctly add target ``libother`` as link dependency.
+
+``$<DEVICE_LINK:list>``
+ Returns the list if it is the device link step, an empty list otherwise.
+ The device link step is controlled by :prop_tgt:`CUDA_SEPARABLE_COMPILATION`
+ and :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties. This expression can
+ only be used to specify link options.
+
+``$<HOST_LINK:list>``
+ Returns the list if it is the normal link step, an empty list otherwise.
+ This expression is mainly useful when a device link step is also involved
+ (see ``$<DEVICE_LINK:list>`` generator expression). This expression can only
+ be used to specify link options.
+
String-Valued Generator Expressions
===================================
@@ -450,22 +565,41 @@ Variable Queries
<Boolean COMPILE_LANGUAGE Generator Expression>`
``$<COMPILE_LANGUAGE:language>``
for notes about the portability of this generator expression.
+``$<LINK_LANGUAGE>``
+ The link language of target when evaluating link options.
+ See :ref:`the related boolean expression
+ <Boolean LINK_LANGUAGE Generator Expression>` ``$<LINK_LANGUAGE:language>``
+ for notes about the portability of this generator expression.
+
+ .. note::
+
+ This generator expression is not supported by the link libraries
+ properties to avoid side-effects due to the double evaluation of
+ these properties.
Target-Dependent Queries
------------------------
+These queries refer to a target ``tgt``. This can be any runtime artifact,
+namely:
+
+* an executable target created by :command:`add_executable`
+* a shared library target (``.so``, ``.dll`` but not their ``.lib`` import library)
+ created by :command:`add_library`
+* a static library target created by :command:`add_library`
+
+In the following, "the ``tgt`` filename" means the name of the ``tgt``
+binary file. This has to be distinguished from "the target name",
+which is just the string ``tgt``.
+
``$<TARGET_NAME_IF_EXISTS:tgt>``
- Expands to the ``tgt`` if the given target exists, an empty string
- otherwise.
+ The target name ``tgt`` if the target exists, an empty string otherwise.
``$<TARGET_FILE:tgt>``
- Full path to main file (.exe, .so.1.2, .a) where ``tgt`` is the name of a
- target.
+ Full path to the ``tgt`` binary file.
``$<TARGET_FILE_BASE_NAME:tgt>``
- Base name of main file where ``tgt`` is the name of a target.
-
- The base name corresponds to the target file name (see
- ``$<TARGET_FILE_NAME:tgt>``) without prefix and suffix. For example, if
- target file name is ``libbase.so``, the base name is ``base``.
+ Base name of ``tgt``, i.e. ``$<TARGET_FILE_NAME:tgt>`` without prefix and
+ suffix.
+ For example, if the ``tgt`` filename is ``libbase.so``, the base name is ``base``.
See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`,
:prop_tgt:`LIBRARY_OUTPUT_NAME` and :prop_tgt:`RUNTIME_OUTPUT_NAME`
@@ -480,32 +614,31 @@ Target-Dependent Queries
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on.
``$<TARGET_FILE_PREFIX:tgt>``
- Prefix of main file where ``tgt`` is the name of a target.
+ Prefix of the ``tgt`` filename (such as ``lib``).
See also the :prop_tgt:`PREFIX` target property.
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on.
``$<TARGET_FILE_SUFFIX:tgt>``
- Suffix of main file where ``tgt`` is the name of a target.
-
- The suffix corresponds to the file extension (such as ".so" or ".exe").
+ Suffix of the ``tgt`` filename (extension such as ``.so`` or ``.exe``).
See also the :prop_tgt:`SUFFIX` target property.
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on.
``$<TARGET_FILE_NAME:tgt>``
- Name of main file (.exe, .so.1.2, .a).
+ The ``tgt`` filename.
``$<TARGET_FILE_DIR:tgt>``
- Directory of main file (.exe, .so.1.2, .a).
+ Directory of the ``tgt`` binary file.
``$<TARGET_LINKER_FILE:tgt>``
- File used to link (.a, .lib, .so) where ``tgt`` is the name of a target.
+ File used when linking to the ``tgt`` target. This will usually
+ be the library that ``tgt`` represents (``.a``, ``.lib``, ``.so``),
+ but for a shared library on DLL platforms, it would be the ``.lib``
+ import library associated with the DLL.
``$<TARGET_LINKER_FILE_BASE_NAME:tgt>``
- Base name of file used to link where ``tgt`` is the name of a target.
-
- The base name corresponds to the target linker file name (see
- ``$<TARGET_LINKER_FILE_NAME:tgt>``) without prefix and suffix. For example,
+ Base name of file used to link the target ``tgt``, i.e.
+ ``$<TARGET_LINKER_FILE_NAME:tgt>`` without prefix and suffix. For example,
if target file name is ``libbase.a``, the base name is ``base``.
See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`,
@@ -520,7 +653,7 @@ Target-Dependent Queries
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on.
``$<TARGET_LINKER_FILE_PREFIX:tgt>``
- Prefix of file used to link where ``tgt`` is the name of a target.
+ Prefix of file used to link target ``tgt``.
See also the :prop_tgt:`PREFIX` and :prop_tgt:`IMPORT_PREFIX` target
properties.
@@ -538,15 +671,15 @@ Target-Dependent Queries
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on.
``$<TARGET_LINKER_FILE_NAME:tgt>``
- Name of file used to link (.a, .lib, .so).
+ Name of file used to link target ``tgt``.
``$<TARGET_LINKER_FILE_DIR:tgt>``
- Directory of file used to link (.a, .lib, .so).
+ Directory of file used to link target ``tgt``.
``$<TARGET_SONAME_FILE:tgt>``
- File with soname (.so.3) where ``tgt`` is the name of a target.
+ File with soname (``.so.3``) where ``tgt`` is the name of a target.
``$<TARGET_SONAME_FILE_NAME:tgt>``
- Name of file with soname (.so.3).
+ Name of file with soname (``.so.3``).
``$<TARGET_SONAME_FILE_DIR:tgt>``
- Directory of with soname (.so.3).
+ Directory of with soname (``.so.3``).
``$<TARGET_PDB_FILE:tgt>``
Full path to the linker generated program database file (.pdb)
where ``tgt`` is the name of a target.
@@ -589,11 +722,10 @@ Target-Dependent Queries
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on.
``$<TARGET_PROPERTY:prop>``
- Value of the property ``prop`` on the target on which the generator
- expression is evaluated. Note that for generator expressions in
- :ref:`Target Usage Requirements` this is the value of the property
- on the consuming target rather than the target specifying the
- requirement.
+ Value of the property ``prop`` on the target for which the expression
+ is being evaluated. Note that for generator expressions in
+ :ref:`Target Usage Requirements` this is the consuming target rather
+ than the target specifying the requirement.
``$<INSTALL_PREFIX>``
Content of the install prefix when the target is exported via
:command:`install(EXPORT)`, or when evaluated in
diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index c256250..3f3b70d 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -51,6 +51,17 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used
to determine whether to report an error on use of deprecated macros or
functions.
+Policies Introduced by CMake 3.18
+=================================
+
+.. toctree::
+ :maxdepth: 1
+
+ CMP0106: The Documentation module is removed. </policy/CMP0106>
+ CMP0105: Device link step uses the link options. </policy/CMP0105>
+ CMP0104: CMAKE_CUDA_ARCHITECTURES now detected for NVCC, empty CUDA_ARCHITECTURES not allowed. </policy/CMP0104>
+ CMP0103: Multiple export() with same FILE without APPEND is not allowed. </policy/CMP0103>
+
Policies Introduced by CMake 3.17
=================================
diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index 060a072..4103806 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -127,6 +127,7 @@ Properties on Targets
/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY
/prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG
/prop_tgt/ARCHIVE_OUTPUT_NAME
+ /prop_tgt/PCH_WARN_INVALID
/prop_tgt/AUTOGEN_BUILD_DIR
/prop_tgt/AUTOGEN_ORIGIN_DEPENDS
/prop_tgt/AUTOGEN_PARALLEL
@@ -171,6 +172,7 @@ Properties on Targets
/prop_tgt/CONFIG_OUTPUT_NAME
/prop_tgt/CONFIG_POSTFIX
/prop_tgt/CROSSCOMPILING_EMULATOR
+ /prop_tgt/CUDA_ARCHITECTURES
/prop_tgt/CUDA_PTX_COMPILATION
/prop_tgt/CUDA_SEPARABLE_COMPILATION
/prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS
@@ -200,6 +202,7 @@ Properties on Targets
/prop_tgt/Fortran_FORMAT
/prop_tgt/Fortran_MODULE_DIRECTORY
/prop_tgt/FRAMEWORK
+ /prop_tgt/FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG
/prop_tgt/FRAMEWORK_VERSION
/prop_tgt/GENERATOR_FILE_NAME
/prop_tgt/GHS_INTEGRITY_APP
@@ -343,6 +346,7 @@ Properties on Targets
/prop_tgt/UNITY_BUILD_BATCH_SIZE
/prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE
/prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE
+ /prop_tgt/UNITY_BUILD_MODE
/prop_tgt/VERSION
/prop_tgt/VISIBILITY_INLINES_HIDDEN
/prop_tgt/VS_CONFIGURATION_TYPE
@@ -369,12 +373,15 @@ Properties on Targets
/prop_tgt/VS_MOBILE_EXTENSIONS_VERSION
/prop_tgt/VS_NO_SOLUTION_DEPLOY
/prop_tgt/VS_PACKAGE_REFERENCES
+ /prop_tgt/VS_PLATFORM_TOOLSET
/prop_tgt/VS_PROJECT_IMPORT
/prop_tgt/VS_SCC_AUXPATH
/prop_tgt/VS_SCC_LOCALPATH
/prop_tgt/VS_SCC_PROJECTNAME
/prop_tgt/VS_SCC_PROVIDER
/prop_tgt/VS_SDK_REFERENCES
+ /prop_tgt/VS_SOLUTION_DEPLOY
+ /prop_tgt/VS_SOURCE_SETTINGS_tool
/prop_tgt/VS_USER_PROPS
/prop_tgt/VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION
/prop_tgt/VS_WINRT_COMPONENT
@@ -478,12 +485,14 @@ Properties on Source Files
/prop_sf/Swift_DEPENDENCIES_FILE
/prop_sf/Swift_DIAGNOSTICS_FILE
/prop_sf/SYMBOLIC
+ /prop_sf/UNITY_GROUP
/prop_sf/VS_COPY_TO_OUT_DIR
/prop_sf/VS_CSHARP_tagname
/prop_sf/VS_DEPLOYMENT_CONTENT
/prop_sf/VS_DEPLOYMENT_LOCATION
/prop_sf/VS_INCLUDE_IN_VSIX
/prop_sf/VS_RESOURCE_GENERATOR
+ /prop_sf/VS_SETTINGS
/prop_sf/VS_SHADER_DISABLE_OPTIMIZATIONS
/prop_sf/VS_SHADER_ENABLE_DEBUG
/prop_sf/VS_SHADER_ENTRYPOINT
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index fc27739..7d802e1 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -388,6 +388,7 @@ Variables that Control the Build
/variable/CMAKE_EXE_LINKER_FLAGS_INIT
/variable/CMAKE_FOLDER
/variable/CMAKE_FRAMEWORK
+ /variable/CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG
/variable/CMAKE_Fortran_FORMAT
/variable/CMAKE_Fortran_MODULE_DIRECTORY
/variable/CMAKE_GHS_NO_SOURCE_GROUP_FILE
@@ -437,6 +438,7 @@ Variables that Control the Build
/variable/CMAKE_OSX_ARCHITECTURES
/variable/CMAKE_OSX_DEPLOYMENT_TARGET
/variable/CMAKE_OSX_SYSROOT
+ /variable/CMAKE_PCH_WARN_INVALID
/variable/CMAKE_PDB_OUTPUT_DIRECTORY
/variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG
/variable/CMAKE_POSITION_INDEPENDENT_CODE
@@ -486,6 +488,7 @@ Variables for Languages
/variable/CMAKE_COMPILER_IS_GNUCC
/variable/CMAKE_COMPILER_IS_GNUCXX
/variable/CMAKE_COMPILER_IS_GNUG77
+ /variable/CMAKE_CUDA_ARCHITECTURES
/variable/CMAKE_CUDA_COMPILE_FEATURES
/variable/CMAKE_CUDA_HOST_COMPILER
/variable/CMAKE_CUDA_EXTENSIONS
@@ -621,6 +624,7 @@ Variables for CTest
/variable/CTEST_P4_COMMAND
/variable/CTEST_P4_OPTIONS
/variable/CTEST_P4_UPDATE_OPTIONS
+ /variable/CTEST_RESOURCE_SPEC_FILE
/variable/CTEST_RUN_CURRENT_SCRIPT
/variable/CTEST_SCP_COMMAND
/variable/CTEST_SITE
diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index d343874..9becfc6 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -358,6 +358,20 @@ Options
in :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR`.
This flag tells CMake to warn about other files as well.
+``--profiling-output=<path>``
+ Used in conjuction with ``--profiling-format`` to output to a given path.
+
+``--profiling-format=<file>``
+ Enable the output of profiling data of CMake script in the given format.
+
+ This can aid performance analysis of CMake scripts executed. Third party
+ applications should be used to process the output into human readable format.
+
+ Currently supported values are:
+ ``google-trace`` Outputs in Google Trace Format, which can be parsed by the
+ about:tracing tab of Google Chrome or using a plugin for a tool like Trace
+ Compass.
+
.. _`Build Tool Mode`:
Build a Project
@@ -467,13 +481,17 @@ Run a Script
.. code-block:: shell
- cmake [{-D <var>=<value>}...] -P <cmake-script-file>
+ cmake [{-D <var>=<value>}...] -P <cmake-script-file> [-- <unparsed-options>...]
Process the given cmake file as a script written in the CMake
language. No configure or generate step is performed and the cache
is not modified. If variables are defined using ``-D``, this must be
done before the ``-P`` argument.
+Any options after ``--`` are not parsed by CMake, but they are still included
+in the set of :variable:`CMAKE_ARGV<n> <CMAKE_ARGV0>` variables passed to the
+script (including the ``--`` itself).
+
Run a Command-Line Tool
=======================
@@ -540,6 +558,9 @@ Available commands are:
``serverMode``
``true`` if cmake supports server-mode and ``false`` otherwise.
+``cat <files>...``
+ Concatenate files and print on the standard output.
+
``chdir <dir> <cmd> [<arg>...]``
Change the current working directory and run a command.
diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst
index 6503f0e..5f953b3 100644
--- a/Help/manual/ctest.1.rst
+++ b/Help/manual/ctest.1.rst
@@ -72,6 +72,9 @@ Options
This option can also be enabled by setting the
:envvar:`CTEST_OUTPUT_ON_FAILURE` environment variable
+``--stop-on-failure``
+ Stop running the tests when the first failure happens.
+
``-F``
Enable failover.
@@ -994,8 +997,12 @@ Configuration settings include:
``ResourceSpecFile``
Specify a
- :ref:`resource specification file <ctest-resource-specification-file>`. See
- :ref:`ctest-resource-allocation` for more information.
+ :ref:`resource specification file <ctest-resource-specification-file>`.
+
+ * `CTest Script`_ variable: :variable:`CTEST_RESOURCE_SPEC_FILE`
+ * :module:`CTest` module variable: ``CTEST_RESOURCE_SPEC_FILE``
+
+ See :ref:`ctest-resource-allocation` for more information.
``LabelsForSubprojects``
Specify a semicolon-separated list of labels that will be treated as
diff --git a/Help/policy/CMP0103.rst b/Help/policy/CMP0103.rst
new file mode 100644
index 0000000..223e0cb
--- /dev/null
+++ b/Help/policy/CMP0103.rst
@@ -0,0 +1,22 @@
+CMP0103
+-------
+
+Multiple calls to :command:`export` command with same ``FILE`` without
+``APPEND`` is no longer allowed.
+
+In CMake 3.17 and below, multiple calls to :command:`export` command with the
+same ``FILE`` without ``APPEND`` are accepted silently but only the last
+occurrence is taken into account during the generation.
+
+The ``OLD`` behavior for this policy is to ignore the multiple occurrences of
+ :command:`export` command except the last one.
+
+The ``NEW`` behavior of this policy is to raise an error on second call to
+:command:`export` command with same ``FILE`` without ``APPEND``.
+
+This policy was introduced in CMake version 3.18. CMake version
+|release| warns when the policy is not set and uses ``OLD`` behavior.
+Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW``
+explicitly.
+
+.. include:: DEPRECATED.txt
diff --git a/Help/policy/CMP0104.rst b/Help/policy/CMP0104.rst
new file mode 100644
index 0000000..ca2c571
--- /dev/null
+++ b/Help/policy/CMP0104.rst
@@ -0,0 +1,31 @@
+CMP0104
+-------
+
+Initialize :variable:`CMAKE_CUDA_ARCHITECTURES` when
+:variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` is ``NVIDIA``.
+Raise an error if :prop_tgt:`CUDA_ARCHITECTURES` is empty.
+
+:variable:`CMAKE_CUDA_ARCHITECTURES` introduced in CMake 3.18 is used to
+initialize :prop_tgt:`CUDA_ARCHITECTURES`, which passes correct code generation
+flags to the CUDA compiler.
+
+Previous to this users had to manually specify the code generation flags. This
+policy is for backwards compatibility with manually specifying code generation
+flags.
+
+The ``OLD`` behavior for this policy is to not initialize
+:variable:`CMAKE_CUDA_ARCHITECTURES` when
+:variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` is ``NVIDIA``.
+Empty :prop_tgt:`CUDA_ARCHITECTURES` is allowed.
+
+The ``NEW`` behavior of this policy is to initialize
+:variable:`CMAKE_CUDA_ARCHITECTURES` when
+:variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` is ``NVIDIA``
+and raise an error if :prop_tgt:`CUDA_ARCHITECTURES` is empty during generation.
+
+This policy was introduced in CMake version 3.18. CMake version
+|release| warns when the policy is not set and uses ``OLD`` behavior.
+Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW``
+explicitly.
+
+.. include:: DEPRECATED.txt
diff --git a/Help/policy/CMP0105.rst b/Help/policy/CMP0105.rst
new file mode 100644
index 0000000..19a1edb
--- /dev/null
+++ b/Help/policy/CMP0105.rst
@@ -0,0 +1,19 @@
+CMP0105
+-------
+
+:prop_tgt:`LINK_OPTIONS` and :prop_tgt:`INTERFACE_LINK_OPTIONS` target
+properties are now used for the device link step.
+
+In CMake 3.17 and below, link options are not used by the device link step.
+
+The ``OLD`` behavior for this policy is to ignore the link options.
+
+The ``NEW`` behavior of this policy is to use the link options during the
+device link step.
+
+This policy was introduced in CMake version 3.17. Use the
+:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
+Unlike many policies, CMake version |release| does *not* warn
+when this policy is not set and simply uses ``OLD`` behavior.
+
+.. include:: DEPRECATED.txt
diff --git a/Help/policy/CMP0106.rst b/Help/policy/CMP0106.rst
new file mode 100644
index 0000000..e34d15a
--- /dev/null
+++ b/Help/policy/CMP0106.rst
@@ -0,0 +1,19 @@
+CMP0106
+-------
+
+The :module:`Documentation` module is removed.
+
+The :module:`Documentation` was added as a support mechanism for the VTK
+project and was tuned for that project. Instead of CMake providing this module
+with (now old) VTK patterns for cache variables and required packages, the
+module is now deprecated by CMake itself.
+
+The ``OLD`` behavior of this policy is for :module:`Documentation` to add
+cache variables and find VTK documentation dependent packages. The ``NEW``
+behavior is to act as an empty module.
+
+This policy was introduced in CMake version 3.18. CMake version |release|
+warns when the policy is not set and uses ``OLD`` behavior. Use the
+:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
+
+.. include:: DEPRECATED.txt
diff --git a/Help/prop_dir/LINK_OPTIONS.rst b/Help/prop_dir/LINK_OPTIONS.rst
index 54ac6dd..f229ba6 100644
--- a/Help/prop_dir/LINK_OPTIONS.rst
+++ b/Help/prop_dir/LINK_OPTIONS.rst
@@ -2,7 +2,7 @@ LINK_OPTIONS
------------
List of options to use for the link step of shared library, module
-and executable targets.
+and executable targets as well as the device link step.
This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of options
given so far to the :command:`add_link_options` command.
diff --git a/Help/prop_sf/COMPILE_OPTIONS.rst b/Help/prop_sf/COMPILE_OPTIONS.rst
index 7e48271..537dcec 100644
--- a/Help/prop_sf/COMPILE_OPTIONS.rst
+++ b/Help/prop_sf/COMPILE_OPTIONS.rst
@@ -5,9 +5,7 @@ List of additional options to pass to the compiler.
This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of options
and will be added to the list of compile flags when this
-source file builds. Use :prop_sf:`COMPILE_DEFINITIONS` to pass
-additional preprocessor definitions and :prop_sf:`INCLUDE_DIRECTORIES` to pass
-additional include directories.
+source file builds.
Contents of ``COMPILE_OPTIONS`` may use "generator expressions" with the
syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual
@@ -16,6 +14,19 @@ does not support per-config per-source settings, so expressions
that depend on the build configuration are not allowed with that
generator.
-.. note::
+Usage example:
- This property should be preferred over the :prop_sf:`COMPILE_FLAGS` property.
+.. code-block:: cmake
+
+ set_source_files_properties(foo.cpp PROPERTIES COMPILE_OPTIONS "-Wno-unused-parameter;-Wno-missing-field-initializer")
+
+Related properties:
+
+* Prefer this property over :prop_sf:`COMPILE_FLAGS`.
+* Use :prop_sf:`COMPILE_DEFINITIONS` to pass additional preprocessor definitions.
+* Use :prop_sf:`INCLUDE_DIRECTORIES` to pass additional include directories.
+
+Related commands:
+
+* :command:`add_compile_options` for directory-wide settings
+* :command:`target_compile_options` for target-specific settings
diff --git a/Help/prop_sf/UNITY_GROUP.rst b/Help/prop_sf/UNITY_GROUP.rst
new file mode 100644
index 0000000..ec6b0f6
--- /dev/null
+++ b/Help/prop_sf/UNITY_GROUP.rst
@@ -0,0 +1,5 @@
+UNITY_GROUP
+-----------
+
+This property controls which *bucket* the source will be part of when
+the :prop_tgt:`UNITY_BUILD_MODE` is set to ``GROUP``.
diff --git a/Help/prop_sf/VS_SETTINGS.rst b/Help/prop_sf/VS_SETTINGS.rst
new file mode 100644
index 0000000..0719406
--- /dev/null
+++ b/Help/prop_sf/VS_SETTINGS.rst
@@ -0,0 +1,18 @@
+VS_SETTINGS
+-----------
+
+Set any item metadata on a non-built file.
+
+Takes a list of ``Key=Value`` pairs. Tells the Visual Studio generator to set
+``Key`` to ``Value`` as item metadata on the file.
+
+For example:
+
+.. code-block:: cmake
+
+ set_property(SOURCE file.hlsl PROPERTY VS_SETTINGS "Key=Value" "Key2=Value2")
+
+will set ``Key`` to ``Value`` and ``Key2`` to ``Value2`` on the
+``file.hlsl`` item as metadata.
+
+Generator expressions are supported.
diff --git a/Help/prop_tgt/CONFIG_POSTFIX.rst b/Help/prop_tgt/CONFIG_POSTFIX.rst
index 11b50b9..5c2fbd7 100644
--- a/Help/prop_tgt/CONFIG_POSTFIX.rst
+++ b/Help/prop_tgt/CONFIG_POSTFIX.rst
@@ -8,3 +8,6 @@ is appended to the target file name built on disk. For non-executable
targets, this property is initialized by the value of the variable
CMAKE_<CONFIG>_POSTFIX if it is set when a target is created. This
property is ignored on the Mac for Frameworks and App Bundles.
+
+For macOS see also the :prop_tgt:`FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>`
+target property.
diff --git a/Help/prop_tgt/CUDA_ARCHITECTURES.rst b/Help/prop_tgt/CUDA_ARCHITECTURES.rst
new file mode 100644
index 0000000..328f40b
--- /dev/null
+++ b/Help/prop_tgt/CUDA_ARCHITECTURES.rst
@@ -0,0 +1,30 @@
+CUDA_ARCHITECTURES
+------------------
+
+List of architectures to generate device code for.
+
+An architecture can be suffixed by either ``-real`` or ``-virtual`` to specify
+the kind of architecture to generate code for.
+If no suffix is given then code is generated for both real and virtual
+architectures.
+
+This property is initialized by the value of the :variable:`CMAKE_CUDA_ARCHITECTURES`
+variable if it is set when a target is created.
+
+The ``CUDA_ARCHITECTURES`` target property must be set to a non-empty value on targets
+that compile CUDA sources, or it is an error. See policy :policy:`CMP0104`.
+
+Examples
+^^^^^^^^
+
+.. code-block:: cmake
+
+ set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES 35 50 72)
+
+Generates code for real and virtual architectures ``30``, ``50`` and ``72``.
+
+.. code-block:: cmake
+
+ set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES 70-real 72-virtual)
+
+Generates code for real architecture ``70`` and virtual architecture ``72``.
diff --git a/Help/prop_tgt/CUDA_STANDARD.rst b/Help/prop_tgt/CUDA_STANDARD.rst
index a3a2f56..6d6774e 100644
--- a/Help/prop_tgt/CUDA_STANDARD.rst
+++ b/Help/prop_tgt/CUDA_STANDARD.rst
@@ -7,7 +7,7 @@ This property specifies the CUDA/C++ standard whose features are requested
to build this target. For some compilers, this results in adding a
flag such as ``-std=gnu++11`` to the compile line.
-Supported values are ``98``, ``11``, ``14``.
+Supported values are ``98``, ``03``, ``11``, ``14``, ``17``, ``20``.
If the value requested does not result in a compile flag being added for
the compiler in use, a previous standard flag will be added instead. This
diff --git a/Help/prop_tgt/FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG.rst b/Help/prop_tgt/FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG.rst
new file mode 100644
index 0000000..2b20bf9
--- /dev/null
+++ b/Help/prop_tgt/FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG.rst
@@ -0,0 +1,25 @@
+FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>
+---------------------------------------
+
+Postfix to append to the framework file name for configuration <CONFIG>,
+when using a multi-config generator (like Xcode and Ninja Multi-Config).
+
+When building with configuration <CONFIG> the value of this property
+is appended to the framework file name built on disk.
+
+For example given a framework called ``my_fw``, a value of ``_debug``
+for the :prop_tgt:`FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>` property, and
+``Debug;Release`` in `CMAKE_CONFIGURATION_TYPES`, the following relevant
+files would be created for the ``Debug`` and ``Release`` configurations:
+
+- Release/my_fw.framework/my_fw
+- Release/my_fw.framework/Versions/A/my_fw
+- Debug/my_fw.framework/my_fw_debug
+- Debug/my_fw.framework/Versions/A/my_fw_debug
+
+For framework targets, this property is initialized by the value of the
+variable :variable:`CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>` if it
+is set when a target is created.
+
+This property is ignored for non-framework targets, and when using single
+config generators.
diff --git a/Help/prop_tgt/INSTALL_RPATH.rst b/Help/prop_tgt/INSTALL_RPATH.rst
index 93b4488..4549b92 100644
--- a/Help/prop_tgt/INSTALL_RPATH.rst
+++ b/Help/prop_tgt/INSTALL_RPATH.rst
@@ -8,5 +8,9 @@ targets (for platforms that support it). This property is initialized
by the value of the variable :variable:`CMAKE_INSTALL_RPATH` if it is set when
a target is created.
+Because the rpath may contain ``${ORIGIN}``, which coincides with CMake syntax,
+the contents of ``INSTALL_RPATH`` are properly escaped in the
+``cmake_install.cmake`` script (see policy :policy:`CMP0095`.)
+
This property supports
:manual:`generator expressions <cmake-generator-expressions(7)>`.
diff --git a/Help/prop_tgt/LINK_OPTIONS.rst b/Help/prop_tgt/LINK_OPTIONS.rst
index 2a05ea7..ff3ee87 100644
--- a/Help/prop_tgt/LINK_OPTIONS.rst
+++ b/Help/prop_tgt/LINK_OPTIONS.rst
@@ -2,12 +2,16 @@ LINK_OPTIONS
------------
List of options to use for the link step of shared library, module
-and executable targets. Targets that are static libraries need to use
-the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property.
+and executable targets as well as the device link step. Targets that are static
+libraries need to use the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property.
+These options are used for both normal linking and device linking
+(see policy :policy:`CMP0105`). To control link options for normal and device
+link steps, ``$<HOST_LINK>`` and ``$<DEVICE_LINK>``
+:manual:`generator expressions <cmake-generator-expressions(7)>` can be used.
-This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of options
-specified so far for its target. Use the :command:`target_link_options`
+This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of
+options specified so far for its target. Use the :command:`target_link_options`
command to append more options.
This property is initialized by the :prop_dir:`LINK_OPTIONS` directory
diff --git a/Help/prop_tgt/PCH_WARN_INVALID.rst b/Help/prop_tgt/PCH_WARN_INVALID.rst
new file mode 100644
index 0000000..36ec348
--- /dev/null
+++ b/Help/prop_tgt/PCH_WARN_INVALID.rst
@@ -0,0 +1,8 @@
+PCH_WARN_INVALID
+----------------
+
+When this property is set to true, the precompile header compiler options
+will contain a compiler flag wich should warn about invalid precompiled
+headers e.g. ``-Winvalid-pch`` for GNU compiler.
+
+The defalut value is ``ON``.
diff --git a/Help/prop_tgt/UNITY_BUILD.rst b/Help/prop_tgt/UNITY_BUILD.rst
index 479802e..e140952 100644
--- a/Help/prop_tgt/UNITY_BUILD.rst
+++ b/Help/prop_tgt/UNITY_BUILD.rst
@@ -5,8 +5,28 @@ When this property is set to true, the target source files will be combined
into batches for faster compilation. This is done by creating a (set of)
unity sources which ``#include`` the original sources, then compiling these
unity sources instead of the originals. This is known as a *Unity* or *Jumbo*
-build. The :prop_tgt:`UNITY_BUILD_BATCH_SIZE` property controls the upper
-limit on how many sources can be combined per unity source file.
+build.
+
+CMake provides different algorithms for selecting which sources are grouped
+together into a *bucket*. Algorithm selection is decided by the
+:prop_tgt:`UNITY_BUILD_MODE` target property, which has the following acceptable
+values:
+
+* ``BATCH``
+ When in this mode CMake determines which files are grouped together.
+ The :prop_tgt:`UNITY_BUILD_BATCH_SIZE` property controls the upper limit on
+ how many sources can be combined per unity source file.
+
+* ``GROUP``
+ When in this mode each target explicitly specifies how to group
+ source files. Each source file that has the same
+ :prop_sf:`UNITY_GROUP` value will be grouped together. Any sources
+ that don't have this property will be compiled individually. The
+ :prop_tgt:`UNITY_BUILD_BATCH_SIZE` property is ignored when using
+ this mode.
+
+If no explicit :prop_tgt:`UNITY_BUILD_MODE` has been specified, CMake will
+default to ``BATCH``.
Unity builds are not currently supported for all languages. CMake version
|release| supports combining ``C`` and ``CXX`` source files. For targets that
diff --git a/Help/prop_tgt/UNITY_BUILD_MODE.rst b/Help/prop_tgt/UNITY_BUILD_MODE.rst
new file mode 100644
index 0000000..1ebab23
--- /dev/null
+++ b/Help/prop_tgt/UNITY_BUILD_MODE.rst
@@ -0,0 +1,58 @@
+UNITY_BUILD_MODE
+----------------
+
+CMake provides different algorithms for selecting which sources are grouped
+together into a *bucket*. Selection is decided by this property,
+which has the following acceptable values:
+
+``BATCH``
+ When in this mode CMake determines which files are grouped together.
+ The :prop_tgt:`UNITY_BUILD_BATCH_SIZE` property controls the upper limit on
+ how many sources can be combined per unity source file.
+
+ Example usage:
+
+ .. code-block:: cmake
+
+ add_library(example_library
+ source1.cxx
+ source2.cxx
+ source3.cxx
+ source4.cxx)
+
+ set_target_properties(example_library PROPERTIES
+ UNITY_BUILD_MODE BATCH
+ UNITY_BUILD_BATCH_SIZE 2
+ )
+
+``GROUP``
+ When in this mode each target explicitly specifies how to group
+ source files. Each source file that has the same
+ :prop_sf:`UNITY_GROUP` value will be grouped together. Any sources
+ that don't have this property will be compiled individually. The
+ :prop_tgt:`UNITY_BUILD_BATCH_SIZE` property is ignored when using
+ this mode.
+
+ Example usage:
+
+ .. code-block:: cmake
+
+ add_library(example_library
+ source1.cxx
+ source2.cxx
+ source3.cxx
+ source4.cxx)
+
+ set_target_properties(example_library PROPERTIES
+ UNITY_BUILD_MODE GROUP
+ )
+
+ set_source_files_properties(source1.cxx source2.cxx source3.cxx
+ PROPERTIES UNITY_GROUP "bucket1"
+ )
+ set_source_files_properties(source4.cxx
+ PROPERTIES UNITY_GROUP "bucket2"
+ )
+
+If no explicit :prop_tgt:`UNITY_BUILD_MODE` has been specified, CMake will
+default to ``BATCH``.
diff --git a/Help/prop_tgt/VS_PLATFORM_TOOLSET.rst b/Help/prop_tgt/VS_PLATFORM_TOOLSET.rst
new file mode 100644
index 0000000..f8f2e8e
--- /dev/null
+++ b/Help/prop_tgt/VS_PLATFORM_TOOLSET.rst
@@ -0,0 +1,10 @@
+VS_PLATFORM_TOOLSET
+-------------------
+
+Overrides the platform toolset used to build a target.
+
+Only supported when the compiler used by the given toolset is the
+same as the compiler used to build the whole source tree.
+
+This is especially useful to create driver projects with the toolsets
+"WindowsUserModeDriver10.0" or "WindowsKernelModeDriver10.0".
diff --git a/Help/prop_tgt/VS_SOLUTION_DEPLOY.rst b/Help/prop_tgt/VS_SOLUTION_DEPLOY.rst
new file mode 100644
index 0000000..7906d75
--- /dev/null
+++ b/Help/prop_tgt/VS_SOLUTION_DEPLOY.rst
@@ -0,0 +1,29 @@
+VS_SOLUTION_DEPLOY
+------------------
+
+Specify that the target should be marked for deployment when not targeting
+Windows CE, Windows Phone or a Windows Store application.
+
+If the target platform doesn't support deployment, this property won't have any effect.
+
+Generator expressions are supported.
+
+Example 1
+^^^^^^^^^
+
+This shows setting the variable for the target foo.
+
+.. code-block:: cmake
+
+ add_executable(foo SHARED foo.cpp)
+ set_property(TARGET foo PROPERTY VS_SOLUTION_DEPLOY ON)
+
+Example 2
+^^^^^^^^^
+
+This shows setting the variable for the Release configuration only.
+
+.. code-block:: cmake
+
+ add_executable(foo SHARED foo.cpp)
+ set_property(TARGET foo PROPERTY VS_SOLUTION_DEPLOY "$<NOT:$<CONFIG:Release>>")
diff --git a/Help/prop_tgt/VS_SOURCE_SETTINGS_tool.rst b/Help/prop_tgt/VS_SOURCE_SETTINGS_tool.rst
new file mode 100644
index 0000000..f706888
--- /dev/null
+++ b/Help/prop_tgt/VS_SOURCE_SETTINGS_tool.rst
@@ -0,0 +1,19 @@
+VS_SOURCE_SETTINGS_<tool>
+-------------------------
+
+Set any item metadata on all non-built files that use <tool>.
+
+Takes a list of ``Key=Value`` pairs. Tells the Visual Studio generator
+to set ``Key`` to ``Value`` as item metadata on all non-built files
+that use ``<tool>``.
+
+For example:
+
+.. code-block:: cmake
+
+ set_property(TARGET main PROPERTY VS_SOURCE_SETTINGS_FXCompile "Key=Value" "Key2=Value2")
+
+will set ``Key`` to ``Value`` and ``Key2`` to ``Value2`` for all
+non-built files that use ``FXCompile``.
+
+Generator expressions are supported.
diff --git a/Help/release/dev/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst
new file mode 100644
index 0000000..e4cc01e
--- /dev/null
+++ b/Help/release/dev/0-sample-topic.rst
@@ -0,0 +1,7 @@
+0-sample-topic
+--------------
+
+* This is a sample release note for the change in a topic.
+ Developers should add similar notes for each topic branch
+ making a noteworthy change. Each document should be named
+ and titled to match the topic name to avoid merge conflicts.
diff --git a/Help/release/dev/CPackRPM-trans-scripts.rst b/Help/release/dev/CPackRPM-trans-scripts.rst
new file mode 100644
index 0000000..57fc099
--- /dev/null
+++ b/Help/release/dev/CPackRPM-trans-scripts.rst
@@ -0,0 +1,7 @@
+CPackRPM-trans-scripts
+----------------------
+
+* The :cpack_gen:`CPack RPM Generator` gained
+ :variable:`CPACK_RPM_PRE_TRANS_SCRIPT_FILE`
+ :variable:`CPACK_RPM_POST_TRANS_SCRIPT_FILE`
+ variables to specify pre- and post-trans scripts.
diff --git a/Help/release/dev/CTestCoverageCollectGCOV-compress-opts.rst b/Help/release/dev/CTestCoverageCollectGCOV-compress-opts.rst
new file mode 100644
index 0000000..eb8532d
--- /dev/null
+++ b/Help/release/dev/CTestCoverageCollectGCOV-compress-opts.rst
@@ -0,0 +1,7 @@
+CTestCoverageCollectGCOV-compress-opts
+--------------------------------------
+
+* The :module:`CTestCoverageCollectGCOV` module
+ :command:`ctest_coverage_collect_gcov` function gained a
+ ``TARBALL_COMPRESSION`` option to control compression of the
+ tarball of collected results.
diff --git a/Help/release/dev/FPHSA-handle_components.rst b/Help/release/dev/FPHSA-handle_components.rst
new file mode 100644
index 0000000..39907c4
--- /dev/null
+++ b/Help/release/dev/FPHSA-handle_components.rst
@@ -0,0 +1,5 @@
+FPHSA-handle_components
+-----------------------
+
+* The :module:`FindPackageHandleStandardArgs` module option ``REQUIRED_VARS``
+ is now optional if ``HANDLE_COMPONENTS`` is specified.
diff --git a/Help/release/dev/FindBLAS-import-target.rst b/Help/release/dev/FindBLAS-import-target.rst
new file mode 100644
index 0000000..29d6f0c
--- /dev/null
+++ b/Help/release/dev/FindBLAS-import-target.rst
@@ -0,0 +1,4 @@
+FindBLAS-import-target
+----------------------
+
+* The :module:`FindBLAS` module now provides an imported target.
diff --git a/Help/release/dev/FindLAPACK-import-target.rst b/Help/release/dev/FindLAPACK-import-target.rst
new file mode 100644
index 0000000..912d642
--- /dev/null
+++ b/Help/release/dev/FindLAPACK-import-target.rst
@@ -0,0 +1,4 @@
+FindLAPACK-import-target
+------------------------
+
+* The :module:`FindLAPACK` module now provides an imported target.
diff --git a/Help/release/dev/FindPython-IronPython-support.rst b/Help/release/dev/FindPython-IronPython-support.rst
new file mode 100644
index 0000000..0ed11e9
--- /dev/null
+++ b/Help/release/dev/FindPython-IronPython-support.rst
@@ -0,0 +1,5 @@
+FindPython-IronPython-support
+-----------------------------
+
+* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
+ modules support now the ``IronPython`` implementation on all platforms.
diff --git a/Help/release/dev/FindPython-artifacts-interactive.rst b/Help/release/dev/FindPython-artifacts-interactive.rst
new file mode 100644
index 0000000..1aa4b3e
--- /dev/null
+++ b/Help/release/dev/FindPython-artifacts-interactive.rst
@@ -0,0 +1,6 @@
+FindPython-artifacts-interactive
+--------------------------------
+
+* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
+ modules gained the possibility to create artifacts cache variables for
+ interactive edition.
diff --git a/Help/release/dev/FindPython-dev-subcomponents.rst b/Help/release/dev/FindPython-dev-subcomponents.rst
new file mode 100644
index 0000000..fe76ee8
--- /dev/null
+++ b/Help/release/dev/FindPython-dev-subcomponents.rst
@@ -0,0 +1,6 @@
+FindPython-dev-subcomponents
+----------------------------
+
+* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
+ modules gained sub-components ``Development.Module`` and
+ ``Development.Embed`` for ``Development`` component.
diff --git a/Help/release/dev/FindPython-find-implementations.rst b/Help/release/dev/FindPython-find-implementations.rst
new file mode 100644
index 0000000..d4f548b
--- /dev/null
+++ b/Help/release/dev/FindPython-find-implementations.rst
@@ -0,0 +1,5 @@
+FindPython-find-implementations
+-------------------------------
+
+* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
+ modules gained the capability to specify which implementations to search for.
diff --git a/Help/release/dev/FindPython-pypy.rst b/Help/release/dev/FindPython-pypy.rst
new file mode 100644
index 0000000..84f0db1
--- /dev/null
+++ b/Help/release/dev/FindPython-pypy.rst
@@ -0,0 +1,5 @@
+FindPython-pypy
+---------------
+
+* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
+ modules gained the capability to handle ``PyPy`` product.
diff --git a/Help/release/dev/FindRuby-variable-case.rst b/Help/release/dev/FindRuby-variable-case.rst
new file mode 100644
index 0000000..bd4a2f1
--- /dev/null
+++ b/Help/release/dev/FindRuby-variable-case.rst
@@ -0,0 +1,7 @@
+FindRuby-variable-case
+----------------------
+
+* The :module:`FindRuby` module input and output variables were all renamed
+ from ``RUBY_`` to ``Ruby_`` 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.
diff --git a/Help/release/dev/GoogleTest-DISCOVERY_MODE.rst b/Help/release/dev/GoogleTest-DISCOVERY_MODE.rst
new file mode 100644
index 0000000..7bc2f14
--- /dev/null
+++ b/Help/release/dev/GoogleTest-DISCOVERY_MODE.rst
@@ -0,0 +1,7 @@
+GoogleTest-DISCOVERY_MODE
+-------------------------
+
+* The :module:`GoogleTest` module :command:`gtest_discover_tests` command
+ gained a new ``DISCOVERY_MODE`` option to control when the test
+ discovery step is run. It offers a new ``PRE_TEST`` setting to
+ run the discovery at test time instead of build time.
diff --git a/Help/release/dev/GoogleTest-XML_OUTPUT_DIR.rst b/Help/release/dev/GoogleTest-XML_OUTPUT_DIR.rst
new file mode 100644
index 0000000..e8aba01
--- /dev/null
+++ b/Help/release/dev/GoogleTest-XML_OUTPUT_DIR.rst
@@ -0,0 +1,6 @@
+GoogleTest-XML_OUTPUT_DIR
+-------------------------
+
+* The :module:`GoogleTest` module :command:`gtest_discover_tests` command
+ gained a new optional parameter ``XML_OUTPUT_DIR``. When set the JUnit XML
+ test results are stored in that directory.
diff --git a/Help/release/dev/ccmake-custom-colors.rst b/Help/release/dev/ccmake-custom-colors.rst
new file mode 100644
index 0000000..fcabe56
--- /dev/null
+++ b/Help/release/dev/ccmake-custom-colors.rst
@@ -0,0 +1,5 @@
+ccmake-custom-colors
+--------------------
+
+* :manual:`ccmake(1)` learned to read a :envvar:`CCMAKE_COLORS`
+ environment variable to customize colors.
diff --git a/Help/release/dev/cmake-gui-env-platform-defaults.rst b/Help/release/dev/cmake-gui-env-platform-defaults.rst
new file mode 100644
index 0000000..0960ef1
--- /dev/null
+++ b/Help/release/dev/cmake-gui-env-platform-defaults.rst
@@ -0,0 +1,8 @@
+cmake-gui-env-platform-defaults
+-------------------------------
+
+* :manual:`cmake-gui(1)` now populates its generator selection
+ widget default value from the :envvar:`CMAKE_GENERATOR` environment
+ variable. Additionally, environment variables
+ :envvar:`CMAKE_GENERATOR_PLATFORM` and :envvar:`CMAKE_GENERATOR_TOOLSET`
+ are used to populate their respective widget defaults.
diff --git a/Help/release/dev/cmake_command-command.rst b/Help/release/dev/cmake_command-command.rst
new file mode 100644
index 0000000..6200ae2
--- /dev/null
+++ b/Help/release/dev/cmake_command-command.rst
@@ -0,0 +1,6 @@
+cmake_command
+-------------
+
+* The :command:`cmake_command()` command was added for meta-operations on
+ scripted or built-in commands, starting with a mode to ``INVOKE`` other
+ commands, and ``EVAL CODE`` to inplace evaluate a CMake script.
diff --git a/Help/release/dev/command-line-cat.rst b/Help/release/dev/command-line-cat.rst
new file mode 100644
index 0000000..acde835
--- /dev/null
+++ b/Help/release/dev/command-line-cat.rst
@@ -0,0 +1,5 @@
+Command-Line
+------------
+* :manual:`cmake(1)` gained a ``cat`` command line
+ option that can be used to concatenate files and print them
+ on standard output.
diff --git a/Help/release/dev/ctest-log-environment.rst b/Help/release/dev/ctest-log-environment.rst
new file mode 100644
index 0000000..0636a25
--- /dev/null
+++ b/Help/release/dev/ctest-log-environment.rst
@@ -0,0 +1,8 @@
+ctest-log-environment
+---------------------
+
+* :manual:`ctest(1)` now logs environment variables that it sets for each test,
+ either due to the :prop_test:`ENVIRONMENT` property or the
+ :ref:`resource allocation <ctest-resource-allocation>` feature, and submits
+ this log to CDash. It does not log environment variables that were set
+ outside of CTest.
diff --git a/Help/release/dev/ctest_resource_spec_file-variable.rst b/Help/release/dev/ctest_resource_spec_file-variable.rst
new file mode 100644
index 0000000..2ddf854
--- /dev/null
+++ b/Help/release/dev/ctest_resource_spec_file-variable.rst
@@ -0,0 +1,6 @@
+ctest_resource_spec_file-variable
+---------------------------------
+
+* :manual:`ctest(1)` gained a new :variable:`CTEST_RESOURCE_SPEC_FILE`
+ variable, which can be used to specify a
+ :ref:`resource specification file <ctest-resource-specification-file>`.
diff --git a/Help/release/dev/ctest_stop_on_failure.rst b/Help/release/dev/ctest_stop_on_failure.rst
new file mode 100644
index 0000000..f10c37c
--- /dev/null
+++ b/Help/release/dev/ctest_stop_on_failure.rst
@@ -0,0 +1,8 @@
+ctest_stop_on_failure
+---------------------
+
+* :manual:`ctest(1)` gained a ``--stop-on-failure`` option,
+ which can be used to stop running the tests once one has failed.
+
+* The :command:`ctest_test` command gained a ``STOP_ON_FAILURE`` option
+ which can be used to stop running the tests once one has failed.
diff --git a/Help/release/dev/cuda-architectures-empty.rst b/Help/release/dev/cuda-architectures-empty.rst
new file mode 100644
index 0000000..b0fc327
--- /dev/null
+++ b/Help/release/dev/cuda-architectures-empty.rst
@@ -0,0 +1,7 @@
+cuda-architectures-empty
+------------------------
+
+* :variable:`CMAKE_CUDA_ARCHITECTURES` is now initialized when
+ :variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` is ``NVIDIA``.
+ Empty :prop_tgt:`CUDA_ARCHITECTURES` raises an error. See policy
+ :policy:`CMP0104`.
diff --git a/Help/release/dev/cuda-architectures.rst b/Help/release/dev/cuda-architectures.rst
new file mode 100644
index 0000000..dc6c55b
--- /dev/null
+++ b/Help/release/dev/cuda-architectures.rst
@@ -0,0 +1,6 @@
+cuda-architectures
+------------------
+
+* Added :prop_tgt:`CUDA_ARCHITECTURES` target property for specifying CUDA
+ output architectures. Users are encouraged to use this instead of specifying
+ options manually, as this approach is compiler-agnostic.
diff --git a/Help/release/dev/cuda-clang.rst b/Help/release/dev/cuda-clang.rst
new file mode 100644
index 0000000..fa5cd5a
--- /dev/null
+++ b/Help/release/dev/cuda-clang.rst
@@ -0,0 +1,4 @@
+cuda-clang
+----------
+
+* The ``CUDA`` language now supports Clang as a compiler.
diff --git a/Help/release/dev/curl-http2.rst b/Help/release/dev/curl-http2.rst
new file mode 100644
index 0000000..8390a42
--- /dev/null
+++ b/Help/release/dev/curl-http2.rst
@@ -0,0 +1,8 @@
+curl-http2
+----------
+
+* When building CMake itself from source and not using a system-provided
+ libcurl, HTTP/2 support is now enabled for commands supporting
+ network communication via ``http(s)``, such as :command:`file(DOWNLOAD)`,
+ :command:`file(UPLOAD)`, and :command:`ctest_submit`.
+ The precompiled binaries provided on ``cmake.org`` now support HTTP/2.
diff --git a/Help/release/dev/deprecate-documentation-module.rst b/Help/release/dev/deprecate-documentation-module.rst
new file mode 100644
index 0000000..5c3157b
--- /dev/null
+++ b/Help/release/dev/deprecate-documentation-module.rst
@@ -0,0 +1,6 @@
+deprecate-documentation-module
+------------------------------
+
+* The :module:`Documentation` module has been deprecated via
+ :policy:`CMP0106`. This module was essentially VTK code that CMake should
+ not be shipping anymore.
diff --git a/Help/release/dev/deprecate-policy-old.rst b/Help/release/dev/deprecate-policy-old.rst
new file mode 100644
index 0000000..cffd206
--- /dev/null
+++ b/Help/release/dev/deprecate-policy-old.rst
@@ -0,0 +1,8 @@
+deprecate-policy-old
+--------------------
+
+* An explicit deprecation diagnostic was added for policy ``CMP0070``
+ and policy ``CMP0071`` (``CMP0069`` 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.
diff --git a/Help/release/dev/device-link-options.rst b/Help/release/dev/device-link-options.rst
new file mode 100644
index 0000000..f58026b
--- /dev/null
+++ b/Help/release/dev/device-link-options.rst
@@ -0,0 +1,5 @@
+device-link-options
+-------------------
+
+* the :prop_tgt:`LINK_OPTIONS` and :prop_tgt:`INTERFACE_LINK_OPTIONS` target
+ properties are now used for the device link step. See policy :policy:`CMP0105`.
diff --git a/Help/release/dev/execute_process.rst b/Help/release/dev/execute_process.rst
new file mode 100644
index 0000000..02e813b
--- /dev/null
+++ b/Help/release/dev/execute_process.rst
@@ -0,0 +1,5 @@
+execute_process
+---------------
+
+* The :command:`execute_process` command gained the ``ECHO_OUTPUT_VARIABLE``
+ and ``ECHO_ERROR_VARIABLE`` options.
diff --git a/Help/release/dev/export-multiple-calls.rst b/Help/release/dev/export-multiple-calls.rst
new file mode 100644
index 0000000..00372ce
--- /dev/null
+++ b/Help/release/dev/export-multiple-calls.rst
@@ -0,0 +1,5 @@
+export-multiple-calls
+---------------------
+
+* The :command:`export` command now raise an error if used multiple times with
+ same ``FILE`` without ``APPEND``. See policy :policy:`CMP0103`.
diff --git a/Help/release/dev/fetchcontent-SOURCE_SUBDIR.rst b/Help/release/dev/fetchcontent-SOURCE_SUBDIR.rst
new file mode 100644
index 0000000..e9e185c
--- /dev/null
+++ b/Help/release/dev/fetchcontent-SOURCE_SUBDIR.rst
@@ -0,0 +1,6 @@
+fetchcontent-SOURCE_SUBDIR
+--------------------------
+
+* The :command:`FetchContent_Declare` command now supports a ``SOURCE_SUBDIR``
+ option. It can be used to direct :command:`FetchContent_MakeAvailable`
+ to look in a different location for the ``CMakeLists.txt`` file.
diff --git a/Help/release/dev/file-upload-tls.rst b/Help/release/dev/file-upload-tls.rst
new file mode 100644
index 0000000..e19be24
--- /dev/null
+++ b/Help/release/dev/file-upload-tls.rst
@@ -0,0 +1,5 @@
+file-upload-tls
+---------------
+
+* The :command:`file(UPLOAD)` command gained ``TLS_VERIFY`` and ``TLS_CAINFO``
+ options to control server certificate verification.
diff --git a/Help/release/dev/file_archive.rst b/Help/release/dev/file_archive.rst
new file mode 100644
index 0000000..e79529c
--- /dev/null
+++ b/Help/release/dev/file_archive.rst
@@ -0,0 +1,7 @@
+file_archive
+------------
+
+* The :command:`file` command gained the ``ARCHIVE_{CREATE|EXTRACT}`` subcommands.
+
+ These subcommands will replicate the :manual:`cmake(1)` ``-E tar`` functionality in
+ CMake scripting code.
diff --git a/Help/release/dev/file_configure.rst b/Help/release/dev/file_configure.rst
new file mode 100644
index 0000000..35e99c4
--- /dev/null
+++ b/Help/release/dev/file_configure.rst
@@ -0,0 +1,6 @@
+file_configure
+--------------
+
+* The :command:`file(CONFIGURE)` subcommand was created in order replicate the
+ :command:`configure_file` functionality without resorting to a pre-existing
+ file on disk as input. The content is instead passed as a string.
diff --git a/Help/release/dev/findswig-components.rst b/Help/release/dev/findswig-components.rst
new file mode 100644
index 0000000..ce569be
--- /dev/null
+++ b/Help/release/dev/findswig-components.rst
@@ -0,0 +1,5 @@
+findswig-components
+-------------------
+
+* The :module:`FindSWIG` module now accepts target languages as ``COMPONENTS``
+ and ``OPTIONAL_COMPONENTS`` arguments to ``find_package``.
diff --git a/Help/release/dev/framework-multi-config-postfix.rst b/Help/release/dev/framework-multi-config-postfix.rst
new file mode 100644
index 0000000..50cf9ce
--- /dev/null
+++ b/Help/release/dev/framework-multi-config-postfix.rst
@@ -0,0 +1,7 @@
+framework-multi-config-postfix
+------------------------------
+
+* The :prop_tgt:`FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>` target property
+ and associated :variable:`CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>`
+ variable were created to allow adding a postfix to the name of a
+ framework file name when using a multi-config generator.
diff --git a/Help/release/dev/genex-DEVICE_LINK-HOST_LINK.rst b/Help/release/dev/genex-DEVICE_LINK-HOST_LINK.rst
new file mode 100644
index 0000000..ef275e7
--- /dev/null
+++ b/Help/release/dev/genex-DEVICE_LINK-HOST_LINK.rst
@@ -0,0 +1,6 @@
+genex-DEVICE_LINK-HOST_LINK
+---------------------------
+
+* To manage device and host link steps, the ``$<DEVICE_LINK:...>`` and
+ ``$<HOST_LINK:...>``
+ :manual:`generator expressions <cmake-generator-expressions(7)>` were added.
diff --git a/Help/release/dev/genex-LINK_LANGUAGE.rst b/Help/release/dev/genex-LINK_LANGUAGE.rst
new file mode 100644
index 0000000..05894d6
--- /dev/null
+++ b/Help/release/dev/genex-LINK_LANGUAGE.rst
@@ -0,0 +1,5 @@
+genex-LINK_LANGUAGE
+===================
+
+* The ``$<LINK_LANGUAGE:...>`` and ``$<LINK_LANG_AND_ID:...>``
+ :manual:`generator expressions <cmake-generator-expressions(7)>` were added.
diff --git a/Help/release/dev/grouped-unity-build-mode.rst b/Help/release/dev/grouped-unity-build-mode.rst
new file mode 100644
index 0000000..802de4a
--- /dev/null
+++ b/Help/release/dev/grouped-unity-build-mode.rst
@@ -0,0 +1,6 @@
+grouped-unity-build-mode
+------------------------
+
+* The :prop_tgt:`UNITY_BUILD_MODE` target property was added to tell
+ generators which algorithm to use for grouping included source
+ files.
diff --git a/Help/release/dev/libxslt.rst b/Help/release/dev/libxslt.rst
new file mode 100644
index 0000000..ce3527e
--- /dev/null
+++ b/Help/release/dev/libxslt.rst
@@ -0,0 +1,4 @@
+libxslt-target
+--------------
+
+* The :module:`FindLibXslt` module now provides imported targets.
diff --git a/Help/release/dev/list_natural_sort.rst b/Help/release/dev/list_natural_sort.rst
new file mode 100644
index 0000000..ff74e5a
--- /dev/null
+++ b/Help/release/dev/list_natural_sort.rst
@@ -0,0 +1,5 @@
+list_natural_sort
+-----------------
+
+* The :command:`list` operation ``SORT`` gained the ``NATURAL`` sort
+ option to sort using natural order (see ``strverscmp(3)`` manual).
diff --git a/Help/release/dev/ninja-compiler-PATH-windows.rst b/Help/release/dev/ninja-compiler-PATH-windows.rst
new file mode 100644
index 0000000..cb33493
--- /dev/null
+++ b/Help/release/dev/ninja-compiler-PATH-windows.rst
@@ -0,0 +1,7 @@
+ninja-compiler-PATH-windows
+---------------------------
+
+* On Windows, the :generator:`Ninja` and :generator:`Ninja Multi-Config`
+ generators, when a compiler is not explicitly specified, now select
+ the first compiler (of any name) found in directories listed by the
+ ``PATH`` environment variable.
diff --git a/Help/release/dev/nsis-dpi-aware.rst b/Help/release/dev/nsis-dpi-aware.rst
new file mode 100644
index 0000000..8b5032e
--- /dev/null
+++ b/Help/release/dev/nsis-dpi-aware.rst
@@ -0,0 +1,6 @@
+nsis-dpi-aware
+--------------
+
+* The :cpack_gen:`CPack NSIS Generator` gained a new variable
+ :variable:`CPACK_NSIS_MANIFEST_DPI_AWARE` to declare that the
+ installer is DPI-aware.
diff --git a/Help/release/dev/parallel-lzma-compression.rst b/Help/release/dev/parallel-lzma-compression.rst
new file mode 100644
index 0000000..12b7102
--- /dev/null
+++ b/Help/release/dev/parallel-lzma-compression.rst
@@ -0,0 +1,6 @@
+parallel-lzma-compression
+-------------------------
+
+* The :cpack_gen:`CPack Archive Generator`'s ``TXZ`` format learned the
+ :variable:`CPACK_ARCHIVE_THREADS` variable to enable parallel compression.
+ Requires support in the ``liblzma`` used by CMake.
diff --git a/Help/release/dev/pch-warn-invalid.rst b/Help/release/dev/pch-warn-invalid.rst
new file mode 100644
index 0000000..5fa3de7
--- /dev/null
+++ b/Help/release/dev/pch-warn-invalid.rst
@@ -0,0 +1,6 @@
+pch-warn-invalid
+----------------
+
+* The :variable:`CMAKE_PCH_WARN_INVALID` variable was added to initialize the
+ :prop_tgt:`PCH_WARN_INVALID` target property to allow the removal of the
+ precompiled header invalid warning.
diff --git a/Help/release/dev/profiling.rst b/Help/release/dev/profiling.rst
new file mode 100644
index 0000000..ab180f0
--- /dev/null
+++ b/Help/release/dev/profiling.rst
@@ -0,0 +1,9 @@
+cmake-profiling
+---------------
+
+* Add support for profiling of CMake scripts through the parameters
+ ``--profiling-output`` and ``--profiling-format``. These options can
+ be used by users to gain insight into the performance of their scripts.
+
+ The first supported output format is ``google-trace`` which is a format
+ supported by Google Chrome's ``about:tracing`` tab.
diff --git a/Help/release/dev/required_find_commands.rst b/Help/release/dev/required_find_commands.rst
new file mode 100644
index 0000000..cc2bf02
--- /dev/null
+++ b/Help/release/dev/required_find_commands.rst
@@ -0,0 +1,6 @@
+required_find_commands
+----------------------
+
+* The :command:`find_program`, :command:`find_library`, :command:`find_path`
+ and :command:`find_file` commands gained a new ``REQUIRED`` option that will
+ stop processing with an error message if nothing is found.
diff --git a/Help/release/dev/sf-property-scopes.rst b/Help/release/dev/sf-property-scopes.rst
new file mode 100644
index 0000000..0b61625
--- /dev/null
+++ b/Help/release/dev/sf-property-scopes.rst
@@ -0,0 +1,15 @@
+sf-property-scopes
+------------------
+
+* The :command:`set_property` with the ``SOURCE`` scope gained the
+ ``DIRECTORY`` and ``TARGET_DIRECTORY`` options to set properties
+ in the provided directory scopes.
+* The :command:`set_source_files_properties` gained the ``DIRECTORY``
+ and ``TARGET_DIRECTORY`` options to set properties in the provided
+ directory scopes.
+* The :command:`get_property` with ``SOURCE`` scope gained the
+ ``DIRECTORY`` and ``TARGET_DIRECTORY`` options to get a property
+ from the provided directory scope.
+* The :command:`get_source_file_property` gained the ``DIRECTORY``
+ and ``TARGET_DIRECTORY`` options to get a property from the
+ provided directory scope.
diff --git a/Help/release/dev/source_group_forward_slashes.rst b/Help/release/dev/source_group_forward_slashes.rst
new file mode 100644
index 0000000..fa0dfa9
--- /dev/null
+++ b/Help/release/dev/source_group_forward_slashes.rst
@@ -0,0 +1,5 @@
+source_group_forward_slashes
+----------------------------
+
+* The :command:`source_group` command now also recognizes forward slashes
+ as subgroup delimiters, not just backslashes.
diff --git a/Help/release/dev/string-hex.rst b/Help/release/dev/string-hex.rst
new file mode 100644
index 0000000..f220aca
--- /dev/null
+++ b/Help/release/dev/string-hex.rst
@@ -0,0 +1,5 @@
+string-hex
+----------
+
+* The :command:`string` command learned a new ``HEX`` sub-command, which
+ converts strings into their hexadecimal representation.
diff --git a/Help/release/dev/useswig-fortran.rst b/Help/release/dev/useswig-fortran.rst
new file mode 100644
index 0000000..17baf96
--- /dev/null
+++ b/Help/release/dev/useswig-fortran.rst
@@ -0,0 +1,7 @@
+useswig-fortran
+---------------
+
+* The :module:`UseSWIG` module now supports Fortran as a target language if
+ the ``SWIG_EXECUTABLE`` is SWIG-Fortran_.
+
+.. _`SWIG-Fortran`: https://github.com/swig-fortran/swig
diff --git a/Help/release/dev/vs-non-built-file-item-metadata.rst b/Help/release/dev/vs-non-built-file-item-metadata.rst
new file mode 100644
index 0000000..26cbad0
--- /dev/null
+++ b/Help/release/dev/vs-non-built-file-item-metadata.rst
@@ -0,0 +1,10 @@
+vs-non-built-file-item-metadata
+-------------------------------
+
+* The :prop_tgt:`VS_SOURCE_SETTINGS_<tool>` target property was added
+ to tell :ref:`Visual Studio Generators` for VS 2010 and above to add
+ metadata to non-built source files using ``<tool>``.
+
+* The :prop_sf:`VS_SETTINGS` source file property was added to tell
+ :ref:`Visual Studio Generators` for VS 2010 and above to add
+ metadata to a non-built source file.
diff --git a/Help/release/dev/vs-platform-toolset.rst b/Help/release/dev/vs-platform-toolset.rst
new file mode 100644
index 0000000..c5062c7
--- /dev/null
+++ b/Help/release/dev/vs-platform-toolset.rst
@@ -0,0 +1,6 @@
+vs-platform-toolset
+-------------------
+
+* The :prop_tgt:`VS_PLATFORM_TOOLSET` target property was added to tell
+ :ref:`Visual Studio Generators` for VS 2010 and above to override
+ the platform toolset.
diff --git a/Help/release/dev/vs-sln-deploy.rst b/Help/release/dev/vs-sln-deploy.rst
new file mode 100644
index 0000000..2e83e52
--- /dev/null
+++ b/Help/release/dev/vs-sln-deploy.rst
@@ -0,0 +1,6 @@
+vs-sln-deploy
+-------------
+
+* The :prop_tgt:`VS_SOLUTION_DEPLOY` target property was added to tell
+ :ref:`Visual Studio Generators` for VS 2010 and above to mark a
+ target for deployment even when not building for Windows Phone/Store/CE.
diff --git a/Help/release/index.rst b/Help/release/index.rst
index 5d1f8a2..22b1a09 100644
--- a/Help/release/index.rst
+++ b/Help/release/index.rst
@@ -7,6 +7,8 @@ CMake Release Notes
This file should include the adjacent "dev.txt" file
in development versions but not in release versions.
+.. include:: dev.txt
+
Releases
========
diff --git a/Help/variable/CMAKE_CUDA_ARCHITECTURES.rst b/Help/variable/CMAKE_CUDA_ARCHITECTURES.rst
new file mode 100644
index 0000000..149bffa
--- /dev/null
+++ b/Help/variable/CMAKE_CUDA_ARCHITECTURES.rst
@@ -0,0 +1,17 @@
+CMAKE_CUDA_ARCHITECTURES
+------------------------
+
+Default value for :prop_tgt:`CUDA_ARCHITECTURES` property of targets.
+
+This is initialized as follows depending on :variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>`:
+
+- For ``Clang``: the oldest architecture that works.
+
+- For ``NVIDIA``: the default architecture chosen by the compiler.
+ See policy :policy:`CMP0104`.
+
+Users are encouraged to override this, as the default varies across compilers
+and compiler versions.
+
+This variable is used to initialize the :prop_tgt:`CUDA_ARCHITECTURES` property
+on all targets. See the target property for additional information.
diff --git a/Help/variable/CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG.rst b/Help/variable/CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG.rst
new file mode 100644
index 0000000..5c7cd23
--- /dev/null
+++ b/Help/variable/CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG.rst
@@ -0,0 +1,8 @@
+CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>
+---------------------------------------------
+
+Default framework filename postfix under configuration ``<CONFIG>`` when
+using a multi-config generator.
+
+When a framework target is created its :prop_tgt:`FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>`
+target property is initialized with the value of this variable if it is set.
diff --git a/Help/variable/CMAKE_PCH_WARN_INVALID.rst b/Help/variable/CMAKE_PCH_WARN_INVALID.rst
new file mode 100644
index 0000000..e152abd
--- /dev/null
+++ b/Help/variable/CMAKE_PCH_WARN_INVALID.rst
@@ -0,0 +1,5 @@
+CMAKE_PCH_WARN_INVALID
+----------------------
+
+This variable is used to initialize the :prop_tgt:`PCH_WARN_INVALID`
+property of targets when they are created.
diff --git a/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst
index 87a9d06..e0ee979 100644
--- a/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst
+++ b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst
@@ -8,11 +8,40 @@ CMAKE_SYSTEM_PREFIX_PATH
subdirectories (like ``bin``, ``lib``, or ``include``) as specified in its own
documentation.
-By default this contains the standard directories for the current system, the
+By default this contains the system directories for the current system, the
:variable:`CMAKE_INSTALL_PREFIX`, and the :variable:`CMAKE_STAGING_PREFIX`.
The installation and staging prefixes may be excluded by setting
the :variable:`CMAKE_FIND_NO_INSTALL_PREFIX` variable.
+The system directories that are contained in ``CMAKE_SYSTEM_PREFIX_PATH`` are
+locations that typically include installed software. An example being
+``/usr/local`` for UNIX based platforms. In addition to standard platform
+locations, CMake will also add values to ``CMAKE_SYSTEM_PREFIX_PATH`` based on
+environment variables. The environment variables and search locations that
+CMake uses may evolve over time, as platforms and their conventions also
+evolve. The following provides an indicative list of environment variables
+and locations that CMake searches, but they are subject to change:
+
+
+CrayLinuxEnvironment:
+ * ``ENV{SYSROOT_DIR}/``
+ * ``ENV{SYSROOT_DIR}/usr``
+ * ``ENV{SYSROOT_DIR}/usr/local``
+
+Darwin:
+ * ``ENV{SDKROOT}/usr`` When ``CMAKE_OSX_SYSROOT`` is not explicitly specified.
+
+OpenBSD:
+ * ``ENV{LOCALBASE}``
+
+Windows:
+ * ``ENV{ProgramW6432}``
+ * ``ENV{ProgramFiles}``
+ * ``ENV{ProgramFiles(x86)}``
+ * ``ENV{SystemDrive}/Program Files``
+ * ``ENV{SystemDrive}/Program Files (x86)``
+
+
``CMAKE_SYSTEM_PREFIX_PATH`` is *not* intended to be modified by the project;
use :variable:`CMAKE_PREFIX_PATH` for this.
diff --git a/Help/variable/CTEST_NIGHTLY_START_TIME.rst b/Help/variable/CTEST_NIGHTLY_START_TIME.rst
index bc80276..90841f9 100644
--- a/Help/variable/CTEST_NIGHTLY_START_TIME.rst
+++ b/Help/variable/CTEST_NIGHTLY_START_TIME.rst
@@ -1,5 +1,9 @@
CTEST_NIGHTLY_START_TIME
------------------------
-Specify the CTest ``NightlyStartTime`` setting
-in a :manual:`ctest(1)` dashboard client script.
+Specify the CTest ``NightlyStartTime`` setting in a :manual:`ctest(1)`
+dashboard client script.
+
+Note that this variable must always be set for a nightly build in a
+dashboard script. It is needed so that nightly builds can be properly grouped
+together in CDash.
diff --git a/Help/variable/CTEST_RESOURCE_SPEC_FILE.rst b/Help/variable/CTEST_RESOURCE_SPEC_FILE.rst
new file mode 100644
index 0000000..59f365f
--- /dev/null
+++ b/Help/variable/CTEST_RESOURCE_SPEC_FILE.rst
@@ -0,0 +1,5 @@
+CTEST_RESOURCE_SPEC_FILE
+------------------------
+
+Specify the CTest ``ResourceSpecFile`` setting in a :manual:`ctest(1)`
+dashboard client script.
diff --git a/Help/variable/PROJECT_SOURCE_DIR.rst b/Help/variable/PROJECT_SOURCE_DIR.rst
index 27f2838..b4601c2 100644
--- a/Help/variable/PROJECT_SOURCE_DIR.rst
+++ b/Help/variable/PROJECT_SOURCE_DIR.rst
@@ -1,6 +1,8 @@
PROJECT_SOURCE_DIR
------------------
-Top level source directory for the current project.
-
-This is the source directory of the most recent :command:`project` command.
+This is the source directory of the last call to the
+:command:`project` command made in the current directory scope or one
+of its parents. Note, it is not affected by calls to
+:command:`project` made within a child directory scope (i.e. from
+within a call to :command:`add_subdirectory` from the current scope).