diff options
Diffstat (limited to 'Help')
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). |