diff options
Diffstat (limited to 'Help')
325 files changed, 8802 insertions, 2191 deletions
diff --git a/Help/command/DEVICE_LINK_OPTIONS.txt b/Help/command/DEVICE_LINK_OPTIONS.txt index 1297cd0..3d50208 100644 --- a/Help/command/DEVICE_LINK_OPTIONS.txt +++ b/Help/command/DEVICE_LINK_OPTIONS.txt @@ -1,3 +1,5 @@ +Host And Device Specific Link Options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. versionadded:: 3.18 When a device link step is involved, which is controlled by diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 97eecfc..ee6c1cc 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -11,10 +11,11 @@ The general signature is: |FIND_XXX| ( <VAR> name | |NAMES| - [HINTS path1 [path2 ... ENV var]] - [PATHS path1 [path2 ... ENV var]] + [HINTS [path | ENV var]... ] + [PATHS [path | ENV var]... ] [PATH_SUFFIXES suffix1 [suffix2 ...]] [DOC "cache documentation string"] + [NO_CACHE] [REQUIRED] [NO_DEFAULT_PATH] [NO_PACKAGE_ROOT_PATH] @@ -28,8 +29,8 @@ The general signature is: ) This command is used to find a |SEARCH_XXX_DESC|. -A cache entry named by ``<VAR>`` is created to store the result -of this command. +A cache entry, or a normal variable if ``NO_CACHE`` is specified, +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``. @@ -56,6 +57,22 @@ Options include: ``DOC`` Specify the documentation string for the ``<VAR>`` cache entry. +``NO_CACHE`` + .. versionadded:: 3.21 + + The result of the search will be stored in a normal variable rather than + a cache entry. + + .. note:: + + If the variable is already set before the call (as a normal or cache + variable) then the search will not occur. + + .. warning:: + + This option should be used with caution because it can greatly increase + the cost of repeated configure steps. + ``REQUIRED`` .. versionadded:: 3.18 @@ -153,6 +170,11 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: or in the short-hand version of the command. These are typically hard-coded guesses. +The :variable:`CMAKE_IGNORE_PATH`, :variable:`CMAKE_IGNORE_PREFIX_PATH`, +:variable:`CMAKE_SYSTEM_IGNORE_PATH` and +:variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` variables can also cause some +of the above locations to be ignored. + .. versionadded:: 3.16 Added ``CMAKE_FIND_USE_<CATEGORY>_PATH`` variables to globally disable various search locations. diff --git a/Help/command/LINK_OPTIONS_LINKER.txt b/Help/command/LINK_OPTIONS_LINKER.txt index 3f66181..e71e5ea 100644 --- a/Help/command/LINK_OPTIONS_LINKER.txt +++ b/Help/command/LINK_OPTIONS_LINKER.txt @@ -1,3 +1,6 @@ +Handling Compiler Driver Differences +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + To pass options to the linker tool, each compiler driver has its own syntax. The ``LINKER:`` prefix and ``,`` separator can be used to specify, in a portable way, options to pass to the linker tool. ``LINKER:`` is replaced by the diff --git a/Help/command/OPTIONS_SHELL.txt b/Help/command/OPTIONS_SHELL.txt index 4051ffe..4171f01 100644 --- a/Help/command/OPTIONS_SHELL.txt +++ b/Help/command/OPTIONS_SHELL.txt @@ -1,11 +1,15 @@ -The final set of compile or link options used for a target is constructed by +Option De-duplication +^^^^^^^^^^^^^^^^^^^^^ + +The final set of options used for a target is constructed by accumulating options from the current target and the usage requirements of its dependencies. The set of options is de-duplicated to avoid repetition. .. versionadded:: 3.12 While beneficial for individual options, the de-duplication step can break - up option groups. For example, ``-D A -D B`` becomes ``-D A B``. One may - specify a group of options using shell-like quoting along with a ``SHELL:`` - prefix. The ``SHELL:`` prefix is dropped, and the rest of the option string - is parsed using the :command:`separate_arguments` ``UNIX_COMMAND`` mode. - For example, ``"SHELL:-D A" "SHELL:-D B"`` becomes ``-D A -D B``. + up option groups. For example, ``-option A -option B`` becomes + ``-option A B``. One may specify a group of options using shell-like + quoting along with a ``SHELL:`` prefix. The ``SHELL:`` prefix is dropped, + and the rest of the option string is parsed using the + :command:`separate_arguments` ``UNIX_COMMAND`` mode. For example, + ``"SHELL:-option A" "SHELL:-option B"`` becomes ``-option A -option B``. diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index c0b9593..ec73f9f 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -271,26 +271,78 @@ The options are: ``DEPFILE`` .. versionadded:: 3.7 - Specify a ``.d`` depfile for the :generator:`Ninja` generator and - :ref:`Makefile Generators`. - A ``.d`` file holds dependencies usually emitted by the custom - command itself. - Using ``DEPFILE`` with other generators than :generator:`Ninja` or - :ref:`Makefile Generators` is an error. + Specify a depfile which holds dependencies for the custom command. It is + usually emitted by the custom command itself. This keyword may only be used + if the generator supports it, as detailed below. + + The expected format, compatible with what is generated by ``gcc`` with the + option ``-M``, is independent of the generator or platform. + + The formal syntax, as specified using + `BNF <https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form>`_ notation with + the regular extensions, is the following: + + .. raw:: latex + + \begin{small} + + .. productionlist:: depfile + depfile: `rule`* + rule: `targets` (`:` (`separator` `dependencies`?)?)? `eol` + targets: `target` (`separator` `target`)* `separator`* + target: `pathname` + dependencies: `dependency` (`separator` `dependency`)* `separator`* + dependency: `pathname` + separator: (space | line_continue)+ + line_continue: '\' `eol` + space: ' ' | '\t' + pathname: `character`+ + character: `std_character` | `dollar` | `hash` | `whitespace` + std_character: <any character except '$', '#' or ' '> + dollar: '$$' + hash: '\#' + whitespace: '\ ' + eol: '\r'? '\n' + + .. raw:: latex + + \end{small} + + .. note:: + + As part of ``pathname``, any slash and backslash is interpreted as + a directory separator. + + .. versionadded:: 3.7 + The :generator:`Ninja` generator supports ``DEPFILE`` since the keyword + was first added. + + .. versionadded:: 3.17 + Added the :generator:`Ninja Multi-Config` generator, which included + support for the ``DEPFILE`` keyword. .. versionadded:: 3.20 - Added the support of :ref:`Makefile Generators`. + Added support for :ref:`Makefile Generators`. - If the ``DEPFILE`` argument is relative, it should be relative to - :variable:`CMAKE_CURRENT_BINARY_DIR`, and any relative paths inside the - ``DEPFILE`` should also be relative to :variable:`CMAKE_CURRENT_BINARY_DIR` - (see policy :policy:`CMP0116`. This policy is always ``NEW`` for - :ref:`Makefile Generators`). + .. note:: - .. note:: + ``DEPFILE`` cannot be specified at the same time as the + ``IMPLICIT_DEPENDS`` option for :ref:`Makefile Generators`. + + .. versionadded:: 3.21 + Added support for :ref:`Visual Studio Generators` with VS 2012 and above, + and for the :generator:`Xcode` generator. Support for + :manual:`generator expressions <cmake-generator-expressions(7)>` was also + added. - For :ref:`Makefile Generators`, this option cannot be specified at the - same time as ``IMPLICIT_DEPENDS`` option. + Using ``DEPFILE`` with generators other than those listed above is an error. + + If the ``DEPFILE`` argument is relative, it should be relative to + :variable:`CMAKE_CURRENT_BINARY_DIR`, and any relative paths inside the + ``DEPFILE`` should also be relative to :variable:`CMAKE_CURRENT_BINARY_DIR`. + See policy :policy:`CMP0116`, which is always ``NEW`` for + :ref:`Makefile Generators`, :ref:`Visual Studio Generators`, + and the :generator:`Xcode` generator. Examples: Generating Files ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -331,6 +383,8 @@ will re-run whenever ``in.txt`` changes. where ``<config>`` is the build configuration, and then compile the generated source as part of a library. +.. _`add_custom_command(TARGET)`: + Build Events ^^^^^^^^^^^^ @@ -381,6 +435,9 @@ of the following is specified: This allows to add individual build events for every configuration. +.. versionadded:: 3.21 + Support for target-dependent generator expressions. + Examples: Build Events ^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index dfc6500..7dc4365 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -151,6 +151,7 @@ itself and is not included as a target in the generated buildsystem. ``PUBLIC`` keywords. If an interface library has source files (i.e. the :prop_tgt:`SOURCES` + target property is set), or header sets (i.e. the :prop_tgt:`HEADER_SETS` target property is set), it will appear in the generated buildsystem as a build target much like a target defined by the :command:`add_custom_target` command. It does not compile any sources, @@ -166,6 +167,8 @@ itself and is not included as a target in the generated buildsystem. call are ``PRIVATE`` to the interface library and do not appear in its :prop_tgt:`INTERFACE_SOURCES` target property. +.. _`add_library imported libraries`: + Imported Libraries ^^^^^^^^^^^^^^^^^^ @@ -205,7 +208,8 @@ The ``<type>`` must be one of: :prop_tgt:`IMPORTED_IMPLIB_<CONFIG>`) specifies the location of the DLL import library file (``.lib`` or ``.dll.a``) on disk, and the ``IMPORTED_LOCATION`` is the location of the ``.dll`` runtime - library (and is optional). + library (and is optional, but needed by the :genex:`TARGET_RUNTIME_DLLS` + generator expression). Additional usage requirements may be specified in ``INTERFACE_*`` properties. diff --git a/Help/command/add_test.rst b/Help/command/add_test.rst index 95cd037..53555a4 100644 --- a/Help/command/add_test.rst +++ b/Help/command/add_test.rst @@ -20,6 +20,9 @@ if necessary. See policy :policy:`CMP0110`. The options are: automatically be replaced by the location of the executable created at build time. + The command may be specified using + :manual:`generator expressions <cmake-generator-expressions(7)>`. + ``CONFIGURATIONS`` Restrict execution of the test only to the named configurations. @@ -30,6 +33,9 @@ if necessary. See policy :policy:`CMP0110`. The options are: directory set to the build directory corresponding to the current source directory. + The working directory may be specified using + :manual:`generator expressions <cmake-generator-expressions(7)>`. + ``COMMAND_EXPAND_LISTS`` .. versionadded:: 3.16 @@ -48,9 +54,10 @@ unless the :prop_test:`PASS_REGULAR_EXPRESSION`, .. versionadded:: 3.16 Added :prop_test:`SKIP_REGULAR_EXPRESSION` property. -The ``COMMAND`` and ``WORKING_DIRECTORY`` options may use "generator -expressions" with the syntax ``$<...>``. See the -:manual:`cmake-generator-expressions(7)` manual for available expressions. +Tests added with the ``add_test(NAME)`` signature support using +:manual:`generator expressions <cmake-generator-expressions(7)>` +in test properties set by :command:`set_property(TEST)` or +:command:`set_tests_properties`. Example usage: @@ -73,10 +80,15 @@ file produced by target ``myexe``. --------------------------------------------------------------------- +This command also supports a simpler, but less flexible, signature: + .. code-block:: cmake add_test(<name> <command> [<arg>...]) -Add a test called ``<name>`` with the given command-line. Unlike -the above ``NAME`` signature no transformation is performed on the -command-line to support target names or generator expressions. +Add a test called ``<name>`` with the given command-line. + +Unlike the above ``NAME`` signature, target names are not supported +in the command-line. Furthermore, tests added with this signature do not +support :manual:`generator expressions <cmake-generator-expressions(7)>` +in the command-line or test properties. diff --git a/Help/command/build_command.rst b/Help/command/build_command.rst index 6659005..a03979d 100644 --- a/Help/command/build_command.rst +++ b/Help/command/build_command.rst @@ -8,23 +8,29 @@ This is mainly intended for internal use by the :module:`CTest` module. build_command(<variable> [CONFIGURATION <config>] + [PARALLEL_LEVEL <parallel>] [TARGET <target>] [PROJECT_NAME <projname>] # legacy, causes warning ) Sets the given ``<variable>`` to a command-line string of the form:: - <cmake> --build . [--config <config>] [--target <target>...] [-- -i] + <cmake> --build . [--config <config>] [--parallel <parallel>] [--target <target>...] [-- -i] where ``<cmake>`` is the location of the :manual:`cmake(1)` command-line -tool, and ``<config>`` and ``<target>`` are the values provided to the -``CONFIGURATION`` and ``TARGET`` options, if any. The trailing ``-- -i`` -option is added for :ref:`Makefile Generators` if policy :policy:`CMP0061` -is not set to ``NEW``. +tool, and ``<config>``, ``<parallel>`` and ``<target>`` are the values +provided to the ``CONFIGURATION``, ``PARALLEL_LEVEL`` and ``TARGET`` +options, if any. The trailing ``-- -i`` option is added for +:ref:`Makefile Generators` if policy :policy:`CMP0061` is not set to +``NEW``. When invoked, this ``cmake --build`` command line will launch the underlying build system tool. +.. versionadded:: 3.21 + The ``PARALLEL_LEVEL`` argument can be used to set the ``--parallel`` + flag. + .. code-block:: cmake build_command(<cachevariable> <makecommand>) diff --git a/Help/command/cmake_host_system_information.rst b/Help/command/cmake_host_system_information.rst index 2b902a9..998e146 100644 --- a/Help/command/cmake_host_system_information.rst +++ b/Help/command/cmake_host_system_information.rst @@ -13,46 +13,236 @@ queried. The list of queried values is stored in ``<variable>``. ``<key>`` can be one of the following values: -============================= ================================================ -Key Description -============================= ================================================ -``NUMBER_OF_LOGICAL_CORES`` Number of logical cores -``NUMBER_OF_PHYSICAL_CORES`` Number of physical cores -``HOSTNAME`` Hostname -``FQDN`` Fully qualified domain name -``TOTAL_VIRTUAL_MEMORY`` Total virtual memory in MiB [#mebibytes]_ -``AVAILABLE_VIRTUAL_MEMORY`` Available virtual memory in MiB [#mebibytes]_ -``TOTAL_PHYSICAL_MEMORY`` Total physical memory in MiB [#mebibytes]_ -``AVAILABLE_PHYSICAL_MEMORY`` Available physical memory in MiB [#mebibytes]_ -============================= ================================================ - -.. versionadded:: 3.10 - Additional ``<key>`` values are available: - -============================= ================================================ -Key Description -============================= ================================================ -``IS_64BIT`` One if processor is 64Bit -``HAS_FPU`` One if processor has floating point unit -``HAS_MMX`` One if processor supports MMX instructions -``HAS_MMX_PLUS`` One if processor supports Ext. MMX instructions -``HAS_SSE`` One if processor supports SSE instructions -``HAS_SSE2`` One if processor supports SSE2 instructions -``HAS_SSE_FP`` One if processor supports SSE FP instructions -``HAS_SSE_MMX`` One if processor supports SSE MMX instructions -``HAS_AMD_3DNOW`` One if processor supports 3DNow instructions -``HAS_AMD_3DNOW_PLUS`` One if processor supports 3DNow+ instructions -``HAS_IA64`` One if IA64 processor emulating x86 -``HAS_SERIAL_NUMBER`` One if processor has serial number -``PROCESSOR_SERIAL_NUMBER`` Processor serial number -``PROCESSOR_NAME`` Human readable processor name -``PROCESSOR_DESCRIPTION`` Human readable full processor description -``OS_NAME`` See :variable:`CMAKE_HOST_SYSTEM_NAME` -``OS_RELEASE`` The OS sub-type e.g. on Windows ``Professional`` -``OS_VERSION`` The OS build ID -``OS_PLATFORM`` See :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` -============================= ================================================ +``NUMBER_OF_LOGICAL_CORES`` + Number of logical cores + +``NUMBER_OF_PHYSICAL_CORES`` + Number of physical cores + +``HOSTNAME`` + Hostname + +``FQDN`` + Fully qualified domain name + +``TOTAL_VIRTUAL_MEMORY`` + Total virtual memory in MiB [#mebibytes]_ + +``AVAILABLE_VIRTUAL_MEMORY`` + Available virtual memory in MiB [#mebibytes]_ + +``TOTAL_PHYSICAL_MEMORY`` + Total physical memory in MiB [#mebibytes]_ + +``AVAILABLE_PHYSICAL_MEMORY`` + Available physical memory in MiB [#mebibytes]_ + +``IS_64BIT`` + .. versionadded:: 3.10 + + One if processor is 64Bit + +``HAS_FPU`` + .. versionadded:: 3.10 + + One if processor has floating point unit + +``HAS_MMX`` + .. versionadded:: 3.10 + + One if processor supports MMX instructions + +``HAS_MMX_PLUS`` + .. versionadded:: 3.10 + + One if processor supports Ext. MMX instructions + +``HAS_SSE`` + .. versionadded:: 3.10 + + One if processor supports SSE instructions + +``HAS_SSE2`` + .. versionadded:: 3.10 + + One if processor supports SSE2 instructions + +``HAS_SSE_FP`` + .. versionadded:: 3.10 + + One if processor supports SSE FP instructions + +``HAS_SSE_MMX`` + .. versionadded:: 3.10 + + One if processor supports SSE MMX instructions + +``HAS_AMD_3DNOW`` + .. versionadded:: 3.10 + + One if processor supports 3DNow instructions + +``HAS_AMD_3DNOW_PLUS`` + .. versionadded:: 3.10 + + One if processor supports 3DNow+ instructions + +``HAS_IA64`` + .. versionadded:: 3.10 + + One if IA64 processor emulating x86 + +``HAS_SERIAL_NUMBER`` + .. versionadded:: 3.10 + + One if processor has serial number + +``PROCESSOR_SERIAL_NUMBER`` + .. versionadded:: 3.10 + + Processor serial number + +``PROCESSOR_NAME`` + .. versionadded:: 3.10 + + Human readable processor name + +``PROCESSOR_DESCRIPTION`` + .. versionadded:: 3.10 + + Human readable full processor description + +``OS_NAME`` + .. versionadded:: 3.10 + + See :variable:`CMAKE_HOST_SYSTEM_NAME` + +``OS_RELEASE`` + .. versionadded:: 3.10 + + The OS sub-type e.g. on Windows ``Professional`` + +``OS_VERSION`` + .. versionadded:: 3.10 + + The OS build ID + +``OS_PLATFORM`` + .. versionadded:: 3.10 + + See :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` + +``DISTRIB_INFO`` + .. versionadded:: 3.22 + + Read :file:`/etc/os-release` file and define the given ``<variable>`` + into a list of read variables + +``DISTRIB_<name>`` + .. versionadded:: 3.22 + + Get the ``<name>`` variable (see `man 5 os-release`_) if it exists in the + :file:`/etc/os-release` file + + Example: + + .. code-block:: cmake + + cmake_host_system_information(RESULT PRETTY_NAME QUERY DISTRIB_PRETTY_NAME) + message(STATUS "${PRETTY_NAME}") + + cmake_host_system_information(RESULT DISTRO QUERY DISTRIB_INFO) + + foreach(VAR IN LISTS DISTRO) + message(STATUS "${VAR}=`${${VAR}}`") + endforeach() + + + Output:: + + -- Ubuntu 20.04.2 LTS + -- DISTRO_BUG_REPORT_URL=`https://bugs.launchpad.net/ubuntu/` + -- DISTRO_HOME_URL=`https://www.ubuntu.com/` + -- DISTRO_ID=`ubuntu` + -- DISTRO_ID_LIKE=`debian` + -- DISTRO_NAME=`Ubuntu` + -- DISTRO_PRETTY_NAME=`Ubuntu 20.04.2 LTS` + -- DISTRO_PRIVACY_POLICY_URL=`https://www.ubuntu.com/legal/terms-and-policies/privacy-policy` + -- DISTRO_SUPPORT_URL=`https://help.ubuntu.com/` + -- DISTRO_UBUNTU_CODENAME=`focal` + -- DISTRO_VERSION=`20.04.2 LTS (Focal Fossa)` + -- DISTRO_VERSION_CODENAME=`focal` + -- DISTRO_VERSION_ID=`20.04` + +If :file:`/etc/os-release` file is not found, the command tries to gather OS +identification via fallback scripts. The fallback script can use `various +distribution-specific files`_ to collect OS identification data and map it +into `man 5 os-release`_ variables. + +Fallback Interface Variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. variable:: CMAKE_GET_OS_RELEASE_FALLBACK_SCRIPTS + + In addition to the scripts shipped with CMake, a user may append full + paths to his script(s) to the this list. The script filename has the + following format: ``NNN-<name>.cmake``, where ``NNN`` is three digits + used to apply collected scripts in a specific order. + +.. variable:: CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_<varname> + + Variables collected by the user provided fallback script + ought to be assigned to CMake variables using this naming + convention. Example, the ``ID`` variable from the manual becomes + ``CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID``. + +.. variable:: CMAKE_GET_OS_RELEASE_FALLBACK_RESULT + + The fallback script ought to store names of all assigned + ``CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_<varname>`` variables in this list. + +Example: + +.. code-block:: cmake + + # Try to detect some old distribution + # See also + # - http://linuxmafia.com/faq/Admin/release-files.html + # + if(NOT EXISTS "${CMAKE_SYSROOT}/etc/foobar-release") + return() + endif() + # Get the first string only + file( + STRINGS "${CMAKE_SYSROOT}/etc/foobar-release" CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT + LIMIT_COUNT 1 + ) + # + # Example: + # + # Foobar distribution release 1.2.3 (server) + # + if(CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT MATCHES "Foobar distribution release ([0-9\.]+) .*") + set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_NAME Foobar) + set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_PRETTY_NAME "${CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT}") + set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID foobar) + set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION ${CMAKE_MATCH_1}) + set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION_ID ${CMAKE_MATCH_1}) + list( + APPEND CMAKE_GET_OS_RELEASE_FALLBACK_RESULT + CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_NAME + CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_PRETTY_NAME + CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID + CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION + CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION_ID + ) + endif() + unset(CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT) + .. rubric:: Footnotes .. [#mebibytes] One MiB (mebibyte) is equal to 1024x1024 bytes. + +.. _man 5 os-release: https://www.freedesktop.org/software/systemd/man/os-release.html +.. _various distribution-specific files: http://linuxmafia.com/faq/Admin/release-files.html diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst index 99f874b..2859f6b 100644 --- a/Help/command/cmake_language.rst +++ b/Help/command/cmake_language.rst @@ -190,7 +190,7 @@ For example, the code: .. code-block:: cmake cmake_language(DEFER CALL message "${deferred_message}") - cmake_language(DEFER ID_VAR id CALL message "Cancelled Message") + cmake_language(DEFER ID_VAR id CALL message "Canceled Message") cmake_language(DEFER CANCEL_CALL ${id}) message("Immediate Message") set(deferred_message "Deferred Message") @@ -201,7 +201,7 @@ prints:: Deferred Message The ``Cancelled Message`` is never printed because its command is -cancelled. The ``deferred_message`` variable reference is not evaluated +canceled. The ``deferred_message`` variable reference is not evaluated until the call site, so it can be set after the deferred call is scheduled. In order to evaluate variable references immediately when scheduling a diff --git a/Help/command/cmake_minimum_required.rst b/Help/command/cmake_minimum_required.rst index c3b3e73..d159770 100644 --- a/Help/command/cmake_minimum_required.rst +++ b/Help/command/cmake_minimum_required.rst @@ -5,21 +5,21 @@ Require a minimum version of cmake. .. code-block:: cmake - cmake_minimum_required(VERSION <min>[...<max>] [FATAL_ERROR]) + cmake_minimum_required(VERSION <min>[...<policy_max>] [FATAL_ERROR]) .. versionadded:: 3.12 - The optional ``<max>`` version. + The optional ``<policy_max>`` version. Sets the minimum required version of cmake for a project. Also updates the policy settings as explained below. -``<min>`` and the optional ``<max>`` are each CMake versions of the form -``major.minor[.patch[.tweak]]``, and the ``...`` is literal. +``<min>`` and the optional ``<policy_max>`` are each CMake versions of the +form ``major.minor[.patch[.tweak]]``, and the ``...`` is literal. If the running version of CMake is lower than the ``<min>`` required version it will stop processing the project and report an error. -The optional ``<max>`` version, if specified, must be at least the -``<min>`` version and affects policy settings as described below. +The optional ``<policy_max>`` version, if specified, must be at least the +``<min>`` version and affects policy settings as described in `Policy Settings`_. If the running version of CMake is older than 3.12, the extra ``...`` dots will be seen as version component separators, resulting in the ``...<max>`` part being ignored and preserving the pre-3.12 behavior @@ -40,8 +40,15 @@ with an error instead of just a warning. they may affect. See also policy :policy:`CMP0000`. Calling ``cmake_minimum_required()`` inside a :command:`function` - limits some effects to the function scope when invoked. Such calls - should not be made with the intention of having global effects. + limits some effects to the function scope when invoked. For example, + the :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable won't be set + in the calling scope. Functions do not introduce their own policy + scope though, so policy settings of the caller *will* be affected + (see below). Due to this mix of things that do and do not affect the + calling scope, calling ``cmake_minimum_required()`` inside a function + is generally discouraged. + +.. _`Policy Settings`: Policy Settings ^^^^^^^^^^^^^^^ diff --git a/Help/command/cmake_path.rst b/Help/command/cmake_path.rst index e7a01ab..454c860 100644 --- a/Help/command/cmake_path.rst +++ b/Help/command/cmake_path.rst @@ -69,8 +69,8 @@ Synopsis `Native Conversion`_ cmake_path(`NATIVE_PATH`_ <path-var> [NORMALIZE] <out-var>) - cmake_path(`CONVERT`_ <input> `TO_CMAKE_PATH_LIST`_ <out-var>) - cmake_path(`CONVERT`_ <input> `TO_NATIVE_PATH_LIST`_ <out-var>) + cmake_path(`CONVERT`_ <input> `TO_CMAKE_PATH_LIST`_ <out-var> [NORMALIZE]) + cmake_path(`CONVERT`_ <input> `TO_NATIVE_PATH_LIST`_ <out-var> [NORMALIZE]) `Hashing`_ cmake_path(`HASH`_ <path-var> <out-var>) @@ -688,7 +688,8 @@ When the ``NORMALIZE`` option is specified, the path is :ref:`normalized <Normalization>` after the path computation. Because ``cmake_path()`` does not access the filesystem, symbolic links are -not resolved. To compute a real path with symbolic links resolved, use the +not resolved and any leading tilde is not expanded. To compute a real path +with symbolic links resolved and leading tildes expanded, use the :command:`file(REAL_PATH)` command instead. Native Conversion diff --git a/Help/command/configure_file.rst b/Help/command/configure_file.rst index d00f08b..1d81423 100644 --- a/Help/command/configure_file.rst +++ b/Help/command/configure_file.rst @@ -36,8 +36,30 @@ or depending on whether ``VAR`` is set in CMake to any value not considered a false constant by the :command:`if` command. The "..." content on the line after the variable name, if any, is processed as above. -Input file lines of the form ``#cmakedefine01 VAR`` will be replaced with -either ``#define VAR 1`` or ``#define VAR 0`` similarly. + +Unlike lines of the form ``#cmakedefine VAR ...``, in lines of the form +``#cmakedefine01 VAR``, ``VAR`` itself will expand to ``VAR 0`` or ``VAR 1`` +rather than being assigned the value ``...``. Therefore, input lines of the form + +.. code-block:: c + + #cmakedefine01 VAR + +will be replaced with either + +.. code-block:: c + + #define VAR 0 + +or + +.. code-block:: c + + #define VAR 1 + +Input lines of the form ``#cmakedefine01 VAR ...`` will expand +as ``#cmakedefine01 VAR ... 0`` or ``#cmakedefine01 VAR ... 0``, +which may lead to undefined behavior. .. versionadded:: 3.10 The result lines (with the exception of the ``#undef`` comments) can be @@ -74,6 +96,7 @@ The arguments are: with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. If the path names an existing directory the output file is placed in that directory with the same file name as the input file. + If the path contains non-existent directories, they are created. ``NO_SOURCE_PERMISSIONS`` .. versionadded:: 3.19 diff --git a/Help/command/ctest_build.rst b/Help/command/ctest_build.rst index 4d6dc5a..e05df1a 100644 --- a/Help/command/ctest_build.rst +++ b/Help/command/ctest_build.rst @@ -7,6 +7,7 @@ Perform the :ref:`CTest Build Step` as a :ref:`Dashboard Client`. ctest_build([BUILD <build-dir>] [APPEND] [CONFIGURATION <config>] + [PARALLEL_LEVEL <parallel>] [FLAGS <flags>] [PROJECT_NAME <project-name>] [TARGET <target-name>] @@ -42,6 +43,13 @@ The options are: Otherwise the ``-C <cfg>`` option given to the :manual:`ctest(1)` command will be used, if any. +``PARALLEL_LEVEL <parallel>`` + .. versionadded:: 3.21 + + Specify the parallel level of the underlying build system. If not + specified, the :envvar:`CMAKE_BUILD_PARALLEL_LEVEL` environment + variable will be checked. + ``FLAGS <flags>`` Pass additional arguments to the underlying build command. If not specified the ``CTEST_BUILD_FLAGS`` variable will be checked. diff --git a/Help/command/ctest_memcheck.rst b/Help/command/ctest_memcheck.rst index f655c2e..8b79077 100644 --- a/Help/command/ctest_memcheck.rst +++ b/Help/command/ctest_memcheck.rst @@ -17,10 +17,15 @@ Perform the :ref:`CTest MemCheck Step` as a :ref:`Dashboard Client`. [EXCLUDE_FIXTURE_SETUP <regex>] [EXCLUDE_FIXTURE_CLEANUP <regex>] [PARALLEL_LEVEL <level>] + [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>] + [REPEAT <mode>:<n>] + [OUTPUT_JUNIT <file>] [DEFECT_COUNT <defect-count-var>] [QUIET] ) diff --git a/Help/command/ctest_submit.rst b/Help/command/ctest_submit.rst index e6d277f..d661825 100644 --- a/Help/command/ctest_submit.rst +++ b/Help/command/ctest_submit.rst @@ -30,7 +30,8 @@ The options are: Build = ctest_build results, in Build.xml Test = ctest_test results, in Test.xml Coverage = ctest_coverage results, in Coverage.xml - MemCheck = ctest_memcheck results, in DynamicAnalysis.xml + MemCheck = ctest_memcheck results, in DynamicAnalysis.xml and + DynamicAnalysis-Test.xml Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES Upload = Files prepared for upload by ctest_upload(), in Upload.xml diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index b4493a0..6a9a6a0 100644 --- a/Help/command/ctest_test.rst +++ b/Help/command/ctest_test.rst @@ -25,9 +25,14 @@ Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`. [RETURN_VALUE <result-var>] [CAPTURE_CMAKE_ERROR <result-var>] [REPEAT <mode>:<n>] + [OUTPUT_JUNIT <file>] [QUIET] ) +.. + _note: If updating the argument list here, please also update the argument + list documentation for :command:`ctest_memcheck` as well. + Run tests in the project build tree and store results in ``Test.xml`` for submission with the :command:`ctest_submit` command. @@ -150,6 +155,15 @@ The options are: Store in the ``<result-var>`` variable -1 if there are any errors running the command and prevent ctest from returning non-zero if an error occurs. +``OUTPUT_JUNIT <file>`` + .. versionadded:: 3.21 + + Write test results to ``<file>`` in JUnit XML format. If ``<file>`` is a + relative path, it will be placed in the build directory. If ``<file>`` + already exists, it will be overwritten. Note that the resulting JUnit XML + file is **not** uploaded to CDash because it would be redundant with + CTest's ``Test.xml`` file. + ``QUIET`` .. versionadded:: 3.3 @@ -160,3 +174,133 @@ The options are: See also the :variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE` and :variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE` variables. + +.. _`Additional Test Measurements`: + +Additional Test Measurements +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +CTest can parse the output of your tests for extra measurements to report +to CDash. + +When run as a :ref:`Dashboard Client`, CTest will include these custom +measurements in the ``Test.xml`` file that gets uploaded to CDash. + +Check the `CDash test measurement documentation +<https://github.com/Kitware/CDash/blob/master/docs/test_measurements.md>`_ +for more information on the types of test measurements that CDash recognizes. + +.. versionadded: 3.22 + CTest can parse custom measurements from tags named + ``<CTestMeasurement>`` or ``<CTestMeasurementFile>``. The older names + ``<DartMeasurement>`` and ``<DartMeasurementFile>`` are still supported. + +The following example demonstrates how to output a variety of custom test +measurements. + +.. code-block:: c++ + + std::cout << + "<CTestMeasurement type=\"numeric/double\" name=\"score\">28.3</CTestMeasurement>" + << std::endl; + + std::cout << + "<CTestMeasurement type=\"text/string\" name=\"color\">red</CTestMeasurement>" + << std::endl; + + std::cout << + "<CTestMeasurement type=\"text/link\" name=\"CMake URL\">https://cmake.org</CTestMeasurement>" + << std::endl; + + std::cout << + "<CTestMeasurement type=\"text/preformatted\" name=\"Console Output\">" << + "line 1.\n" << + " \033[31;1m line 2. Bold red, and indented!\033[0;0ml\n" << + "line 3. Not bold or indented...\n" << + "</CTestMeasurement>" << std::endl; + +Image Measurements +"""""""""""""""""" + +The following example demonstrates how to upload test images to CDash. + +.. code-block:: c++ + + std::cout << + "<CTestMeasurementFile type=\"image/jpg\" name=\"TestImage\">" << + "/dir/to/test_img.jpg</CTestMeasurementFile>" << std::endl; + + std::cout << + "<CTestMeasurementFile type=\"image/gif\" name=\"ValidImage\">" << + "/dir/to/valid_img.gif</CTestMeasurementFile>" << std::endl; + + std::cout << + "<CTestMeasurementFile type=\"image/png\" name=\"AlgoResult\"> << + "/dir/to/img.png</CTestMeasurementFile>" + << std::endl; + +Images will be displayed together in an interactive comparison mode on CDash +if they are provided with two or more of the following names. + +* ``TestImage`` +* ``ValidImage`` +* ``BaselineImage`` +* ``DifferenceImage2`` + +By convention, ``TestImage`` is the image generated by your test, and +``ValidImage`` (or ``BaselineImage``) is basis of comparison used to determine +if the test passed or failed. + +If another image name is used it will be displayed by CDash as a static image +separate from the interactive comparison UI. + +Attached Files +"""""""""""""" + +.. versionadded:: 3.21 + +The following example demonstrates how to upload non-image files to CDash. + +.. code-block:: c++ + + std::cout << + "<CTestMeasurementFile type=\"file\" name=\"TestInputData1\">" << + "/dir/to/data1.csv</CTestMeasurementFile>\n" << + "<CTestMeasurementFile type=\"file\" name=\"TestInputData2\">" << + "/dir/to/data2.csv</CTestMeasurementFile>" << std::endl; + +If the name of the file to upload is known at configure time, you can use the +:prop_test:`ATTACHED_FILES` or :prop_test:`ATTACHED_FILES_ON_FAIL` test +properties instead. + +Custom Details +"""""""""""""" + +.. versionadded:: 3.21 + +The following example demonstrates how to specify a custom value for the +``Test Details`` field displayed on CDash. + +.. code-block:: c++ + + std::cout << + "<CTestDetails>My Custom Details Value</CTestDetails>" << std::endl; + +.. _`Additional Labels`: + +Additional Labels +""""""""""""""""" + +.. versionadded:: 3.22 + +The following example demonstrates how to add additional labels to a test +at runtime. + +.. code-block:: c++ + + std::cout << + "<CTestLabel>Custom Label 1</CTestLabel>\n" << + "<CTestLabel>Custom Label 2</CTestLabel>" << std::endl; + +Use the :prop_test:`LABELS` test property instead for labels that can be +determined at configure time. diff --git a/Help/command/define_property.rst b/Help/command/define_property.rst index 8f7439b..76b060b 100644 --- a/Help/command/define_property.rst +++ b/Help/command/define_property.rst @@ -8,15 +8,18 @@ Define and document custom properties. define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE | TEST | VARIABLE | CACHED_VARIABLE> PROPERTY <name> [INHERITED] - BRIEF_DOCS <brief-doc> [docs...] - FULL_DOCS <full-doc> [docs...]) + [BRIEF_DOCS <brief-doc> [docs...]] + [FULL_DOCS <full-doc> [docs...]] + [INITIALIZE_FROM_VARIABLE <variable>]) Defines one property in a scope for use with the :command:`set_property` and -:command:`get_property` commands. This is primarily useful to associate -documentation with property names that may be retrieved with the -:command:`get_property` command. The first argument determines the kind of -scope in which the property should be used. It must be one of the -following: +:command:`get_property` commands. It is mainly useful for defining the way +a property is initialized or inherited. Historically, the command also +associated documentation with a property, but that is no longer considered a +primary use case. + +The first argument determines the kind of scope in which the property should +be used. It must be one of the following: :: @@ -55,5 +58,18 @@ out the contents to append to. The ``BRIEF_DOCS`` and ``FULL_DOCS`` options are followed by strings to be associated with the property as its brief and full documentation. -Corresponding options to the :command:`get_property` command will retrieve -the documentation. +CMake does not use this documentation other than making it available to the +project via corresponding options to the :command:`get_property` command. + +.. versionchanged:: 3.23 + + The ``BRIEF_DOCS`` and ``FULL_DOCS`` options are optional. + +.. versionadded:: 3.23 + + The ``INITIALIZE_FROM_VARIABLE`` option specifies a variable from which the + property should be initialized. It can only be used with target properties. + The ``<variable>`` name must end with the property name and must not begin + with ``CMAKE_`` or ``_CMAKE_``. The property name must contain at least one + underscore. It is recommended that the property name have a prefix specific + to the project. diff --git a/Help/command/enable_language.rst b/Help/command/enable_language.rst index ce765de..d2acbc8 100644 --- a/Help/command/enable_language.rst +++ b/Help/command/enable_language.rst @@ -10,7 +10,7 @@ Enables support for the named language in CMake. This is the same as the :command:`project` command but does not create any of the extra variables that are created by the project command. Example languages are ``CXX``, ``C``, ``CUDA``, ``OBJC``, ``OBJCXX``, ``Fortran``, -``ISPC``, and ``ASM``. +``HIP``, ``ISPC``, and ``ASM``. .. versionadded:: 3.8 Added ``CUDA`` support. @@ -21,6 +21,9 @@ are ``CXX``, ``C``, ``CUDA``, ``OBJC``, ``OBJCXX``, ``Fortran``, .. versionadded:: 3.18 Added ``ISPC`` support. +.. versionadded:: 3.21 + Added ``HIP`` support. + If enabling ``ASM``, enable it last so that CMake can check whether compilers for other languages like ``C`` work for assembly too. diff --git a/Help/command/export.rst b/Help/command/export.rst index e8a1fa7..dc69645 100644 --- a/Help/command/export.rst +++ b/Help/command/export.rst @@ -1,44 +1,62 @@ export ------ -Export targets from the build tree for use by outside projects. +Export targets or packages for outside projects to use them directly +from the current project's build tree, without installation. + +See the :command:`install(EXPORT)` command to export targets from an +install tree. + +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + export(`TARGETS`_ <target>... [...]) + export(`EXPORT`_ <export-name> [...]) + export(`PACKAGE`_ <PackageName>) + +Exporting Targets +^^^^^^^^^^^^^^^^^ + +.. _`export(TARGETS)`: +.. _TARGETS: .. code-block:: cmake - export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>]) + export(TARGETS <target>... [NAMESPACE <namespace>] + [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES]) Creates a file ``<filename>`` that may be included by outside projects to -import targets from the current project's build tree. This is useful -during cross-compiling to build utility executables that can run on -the host platform in one project and then import them into another -project being compiled for the target platform. If the ``NAMESPACE`` -option is given the ``<namespace>`` string will be prepended to all target -names written to the file. - -Target installations are associated with the export ``<export-name>`` -using the ``EXPORT`` option of the :command:`install(TARGETS)` command. +import targets named by ``<target>...`` from the current project's build tree. +This is useful during cross-compiling to build utility executables that can +run on the host platform in one project and then import them into another +project being compiled for the target platform. The file created by this command is specific to the build tree and should never be installed. See the :command:`install(EXPORT)` command to -export targets from an installation tree. +export targets from an install tree. -The properties set on the generated IMPORTED targets will have the -same values as the final values of the input TARGETS. +The options are: -.. code-block:: cmake +``NAMESPACE <namespace>`` + Prepend the ``<namespace>`` string to all target names written to the file. - export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>] - [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES]) +``APPEND`` + Append to the file instead of overwriting it. This can be used to + incrementally export multiple targets to the same file. + +``EXPORT_LINK_INTERFACE_LIBRARIES`` + Include the contents of the properties named with the pattern + ``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?`` + in the export, even when policy :policy:`CMP0022` is NEW. This is useful + to support consumers using CMake versions older than 2.8.12. -This signature is similar to the ``EXPORT`` signature, but targets are listed -explicitly rather than specified as an export-name. If the APPEND option is -given the generated code will be appended to the file instead of overwriting it. -The EXPORT_LINK_INTERFACE_LIBRARIES keyword, if present, causes the -contents of the properties matching -``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?`` to be exported, when -policy CMP0022 is NEW. If a library target is included in the export -but a target to which it links is not included the behavior is -unspecified. +This signature requires all targets to be listed explicitly. If a library +target is included in the export, but a target to which it links is not +included, the behavior is unspecified. See the `export(EXPORT)`_ signature +to automatically export the same targets from the build tree as +:command:`install(EXPORT)` would from an install tree. .. note:: @@ -49,6 +67,50 @@ unspecified. transitive usage requirements of other targets that link to the object libraries in their implementation. +Exporting Targets to Android.mk +""""""""""""""""""""""""""""""" + +.. code-block:: cmake + + export(TARGETS <target>... ANDROID_MK <filename>) + +.. versionadded:: 3.7 + +This signature exports cmake built targets to the android ndk build system +by creating an ``Android.mk`` file that references the prebuilt targets. The +Android NDK supports the use of prebuilt libraries, both static and shared. +This allows cmake to build the libraries of a project and make them available +to an ndk build system complete with transitive dependencies, include flags +and defines required to use the libraries. The signature takes a list of +targets and puts them in the ``Android.mk`` file specified by the +``<filename>`` given. This signature can only be used if policy +:policy:`CMP0022` is NEW for all targets given. A error will be issued if +that policy is set to OLD for one of the targets. + +Exporting Targets matching install(EXPORT) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. _`export(EXPORT)`: +.. _EXPORT: + +.. code-block:: cmake + + export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>]) + +Creates a file ``<filename>`` that may be included by outside projects to +import targets from the current project's build tree. This is the same +as the `export(TARGETS)`_ signature, except that the targets are not +explicitly listed. Instead, it exports the targets associated with +the installation export ``<export-name>``. Target installations may be +associated with the export ``<export-name>`` using the ``EXPORT`` option +of the :command:`install(TARGETS)` command. + +Exporting Packages +^^^^^^^^^^^^^^^^^^ + +.. _`export(PACKAGE)`: +.. _PACKAGE: + .. code-block:: cmake export(PACKAGE <PackageName>) @@ -74,20 +136,3 @@ registry. outside the source and build trees. Set the :variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable to add build directories to the CMake user package registry. - -.. code-block:: cmake - - export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>]) - -.. versionadded:: 3.7 - -This signature exports cmake built targets to the android ndk build system -by creating an Android.mk file that references the prebuilt targets. The -Android NDK supports the use of prebuilt libraries, both static and shared. -This allows cmake to build the libraries of a project and make them available -to an ndk build system complete with transitive dependencies, include flags -and defines required to use the libraries. The signature takes a list of -targets and puts them in the Android.mk file specified by the ``<filename>`` -given. This signature can only be used if policy CMP0022 is NEW for all -targets given. A error will be issued if that policy is set to OLD for one -of the targets. diff --git a/Help/command/file.rst b/Help/command/file.rst index 31de610..799b6ff 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -38,9 +38,10 @@ Synopsis `Filesystem`_ file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] [<globbing-expr>...]) - file(`RENAME`_ <oldname> <newname>) - file({`REMOVE`_ | `REMOVE_RECURSE`_ } [<files>...]) file(`MAKE_DIRECTORY`_ [<dir>...]) + file({`REMOVE`_ | `REMOVE_RECURSE`_ } [<files>...]) + file(`RENAME`_ <oldname> <newname> [...]) + file(`COPY_FILE`_ <oldname> <newname> [...]) file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...]) file(`SIZE`_ <filename> <out-var>) file(`READ_SYMLINK`_ <linkname> <out-var>) @@ -49,7 +50,7 @@ Synopsis file(`CHMOD_RECURSE`_ <files>... <directories>... PERMISSIONS <permissions>... [...]) `Path Conversion`_ - file(`REAL_PATH`_ <path> <out-var> [BASE_DIRECTORY <dir>]) + file(`REAL_PATH`_ <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE]) file(`RELATIVE_PATH`_ <out-var> <directory> <file>) file({`TO_CMAKE_PATH`_ | `TO_NATIVE_PATH`_} <path> <out-var>) @@ -115,7 +116,8 @@ Parse a list of ASCII strings from ``<filename>`` and store it in binary while reading unless this option is given. ``REGEX <regex>`` - Consider only strings that match the given regular expression. + Consider only strings that match the given regular expression, + as described under :ref:`string(REGEX) <Regex Specification>`. ``ENCODING <encoding-type>`` .. versionadded:: 3.1 @@ -178,6 +180,8 @@ the ``<format>`` and ``UTC`` options. [PRE_EXCLUDE_REGEXES [<regexes>...]] [POST_INCLUDE_REGEXES [<regexes>...]] [POST_EXCLUDE_REGEXES [<regexes>...]] + [POST_INCLUDE_FILES [<files>...]] + [POST_EXCLUDE_FILES [<files>...]] ) .. versionadded:: 3.16 @@ -185,8 +189,10 @@ the ``<format>`` and ``UTC`` options. Recursively get the list of libraries depended on by the given files. Please note that this sub-command is not intended to be used in project mode. -Instead, use it in an :command:`install(CODE)` or :command:`install(SCRIPT)` -block. For example: +It is intended for use at install time, either from code generated by the +:command:`install(RUNTIME_DEPENDENCY_SET)` command, or from code provided by +the project via :command:`install(CODE)` or :command:`install(SCRIPT)`. +For example: .. code-block:: cmake @@ -275,6 +281,18 @@ be resolved. See below for a full description of how they work. List of post-exclude regexes through which to filter the names of resolved dependencies. +``POST_INCLUDE_FILES <files>`` + .. versionadded:: 3.21 + + List of post-include filenames through which to filter the names of resolved + dependencies. Symlinks are resolved when attempting to match these filenames. + +``POST_EXCLUDE_FILES <files>`` + .. versionadded:: 3.21 + + List of post-exclude filenames through which to filter the names of resolved + dependencies. Symlinks are resolved when attempting to match these filenames. + These arguments can be used to exclude unwanted system libraries when resolving the dependencies, or to include libraries from a specific directory. The filtering works as follows: @@ -288,16 +306,18 @@ directory. The filtering works as follows: 4. ``file(GET_RUNTIME_DEPENDENCIES)`` searches for the dependency according to the linking rules of the platform (see below). 5. If the dependency is found, and its full path matches one of the - ``POST_INCLUDE_REGEXES``, the full path is added to the resolved - dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` recursively resolves - that library's own dependencies. Otherwise, resolution proceeds to step 6. + ``POST_INCLUDE_REGEXES`` or ``POST_INCLUDE_FILES``, the full path is added + to the resolved dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` + recursively resolves that library's own dependencies. Otherwise, resolution + proceeds to step 6. 6. If the dependency is found, but its full path matches one of the - ``POST_EXCLUDE_REGEXES``, it is not added to the resolved dependencies, and - dependency resolution stops for that dependency. + ``POST_EXCLUDE_REGEXES`` or ``POST_EXCLUDE_FILES``, it is not added to the + resolved dependencies, and dependency resolution stops for that dependency. 7. If the dependency is found, and its full path does not match either - ``POST_INCLUDE_REGEXES`` or ``POST_EXCLUDE_REGEXES``, the full path is added - to the resolved dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` - recursively resolves that library's own dependencies. + ``POST_INCLUDE_REGEXES``, ``POST_INCLUDE_FILES``, ``POST_EXCLUDE_REGEXES``, + or ``POST_EXCLUDE_FILES``, the full path is added to the resolved + dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` recursively resolves + that library's own dependencies. Different platforms have different rules for how dependencies are resolved. These specifics are described here. @@ -671,14 +691,13 @@ Examples of recursive globbing include:: /dir/*.py - match all python files in /dir and subdirectories -.. _RENAME: +.. _MAKE_DIRECTORY: .. code-block:: cmake - file(RENAME <oldname> <newname>) + file(MAKE_DIRECTORY [<directories>...]) -Move a file or directory within a filesystem from ``<oldname>`` to -``<newname>``, replacing the destination atomically. +Create the given directories and their parents as needed. .. _REMOVE: .. _REMOVE_RECURSE: @@ -695,16 +714,67 @@ to the current source directory. .. versionchanged:: 3.15 Empty input paths are ignored with a warning. Previous versions of CMake - interpreted empty string as a relative path with respect to the current + interpreted empty strings as a relative path with respect to the current directory and removed its contents. -.. _MAKE_DIRECTORY: +.. _RENAME: .. code-block:: cmake - file(MAKE_DIRECTORY [<directories>...]) + file(RENAME <oldname> <newname> + [RESULT <result>] + [NO_REPLACE]) -Create the given directories and their parents as needed. +Move a file or directory within a filesystem from ``<oldname>`` to +``<newname>``, replacing the destination atomically. + +The options are: + +``RESULT <result>`` + .. versionadded:: 3.21 + + Set ``<result>`` variable to ``0`` on success or an error message otherwise. + If ``RESULT`` is not specified and the operation fails, an error is emitted. + +``NO_REPLACE`` + .. versionadded:: 3.21 + + If the ``<newname>`` path already exists, do not replace it. + If ``RESULT <result>`` is used, the result variable will be + set to ``NO_REPLACE``. Otherwise, an error is emitted. + +.. _COPY_FILE: + +.. code-block:: cmake + + file(COPY_FILE <oldname> <newname> + [RESULT <result>] + [ONLY_IF_DIFFERENT]) + +.. versionadded:: 3.21 + +Copy a file from ``<oldname>`` to ``<newname>``. Directories are not +supported. Symlinks are ignored and ``<oldfile>``'s content is read and +written to ``<newname>`` as a new file. + +The options are: + +``RESULT <result>`` + Set ``<result>`` variable to ``0`` on success or an error message otherwise. + If ``RESULT`` is not specified and the operation fails, an error is emitted. + +``ONLY_IF_DIFFERENT`` + If the ``<newname>`` path already exists, do not replace it if the file's + contents are already the same as ``<oldname>`` (this avoids updating + ``<newname>``'s timestamp). + +This sub-command has some similarities to :command:`configure_file` with the +``COPYONLY`` option. An important difference is that :command:`configure_file` +creates a dependency on the source file, so CMake will be re-run if it changes. +The ``file(COPY_FILE)`` sub-command does not create such a dependency. + +See also the ``file(COPY)`` sub-command just below which provides +further file-copying capabilities. .. _COPY: .. _INSTALL: @@ -720,6 +790,11 @@ Create the given directories and their parents as needed. [[PATTERN <pattern> | REGEX <regex>] [EXCLUDE] [PERMISSIONS <permissions>...]] [...]) +.. note:: + + For a simple file copying operation, the ``file(COPY_FILE)`` sub-command + just above may be easier to use. + The ``COPY`` signature copies files, directories, and symlinks to a destination folder. Relative input paths are evaluated with respect to the current source directory, and a relative destination is @@ -763,11 +838,16 @@ of their content even if options are used to select a subset of files. The ``INSTALL`` signature differs slightly from ``COPY``: it prints -status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable), -and ``NO_SOURCE_PERMISSIONS`` is default. +status messages, and ``NO_SOURCE_PERMISSIONS`` is default. + Installation scripts generated by the :command:`install` command use this signature (with some undocumented options for internal use). +.. versionchanged:: 3.22 + + The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the + default copying behavior of :command:`file(INSTALL)`. + .. _SIZE: .. code-block:: cmake @@ -888,16 +968,26 @@ Path Conversion .. code-block:: cmake - file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>]) + file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE]) .. versionadded:: 3.19 Compute the absolute path to an existing file or directory with symlinks resolved. -If the provided ``<path>`` is a relative path, it is evaluated relative to the -given base directory ``<dir>``. If no base directory is provided, the default -base directory will be :variable:`CMAKE_CURRENT_SOURCE_DIR`. +``BASE_DIRECTORY <dir>`` + If the provided ``<path>`` is a relative path, it is evaluated relative to the + given base directory ``<dir>``. If no base directory is provided, the default + base directory will be :variable:`CMAKE_CURRENT_SOURCE_DIR`. + +``EXPAND_TILDE`` + .. versionadded:: 3.21 + + If the ``<path>`` is ``~`` or starts with ``~/``, the ``~`` is replaced by + the user's home directory. The path to the home directory is obtained from + environment variables. On Windows, the ``USERPROFILE`` environment variable + is used, falling back to the ``HOME`` environment variable if ``USERPROFILE`` + is not defined. On all other platforms, only ``HOME`` is used. .. _RELATIVE_PATH: @@ -983,7 +1073,7 @@ Options to both ``DOWNLOAD`` and ``UPLOAD`` are: .. versionadded:: 3.11 Specify whether the .netrc file is to be used for operation. If this - option is not specified, the value of the ``CMAKE_NETRC`` variable + option is not specified, the value of the :variable:`CMAKE_NETRC` variable will be used instead. Valid levels are: @@ -1002,29 +1092,28 @@ Options to both ``DOWNLOAD`` and ``UPLOAD`` are: Specify an alternative .netrc file to the one in your home directory, if the ``NETRC`` level is ``OPTIONAL`` or ``REQUIRED``. If this option - is not specified, the value of the ``CMAKE_NETRC_FILE`` variable will + is not specified, the value of the :variable:`CMAKE_NETRC_FILE` variable will be used instead. -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. + The default is to *not* verify. If this option is not specified, the value + of the :variable:`CMAKE_TLS_VERIFY` variable will be used instead. .. versionadded:: 3.18 Added support to ``file(UPLOAD)``. ``TLS_CAINFO <file>`` - Specify a custom Certificate Authority file for ``https://`` URLs. + Specify a custom Certificate Authority file for ``https://`` URLs. If this + option is not specified, the value of the :variable:`CMAKE_TLS_CAINFO` + variable will be used instead. .. versionadded:: 3.18 Added support to ``file(UPLOAD)``. 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. +check certificates. Additional options to ``DOWNLOAD`` are: diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 3dfd62f..5acefad 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -5,12 +5,74 @@ find_package .. contents:: -Find an external project, and load its settings. +Find a package (usually provided by something external to the project), +and load its package-specific details. + +Search Modes +^^^^^^^^^^^^ + +The command has two very distinct ways of conducting the search: + +**Module mode** + In this mode, CMake searches for a file called ``Find<PackageName>.cmake``, + looking first in the locations listed in the :variable:`CMAKE_MODULE_PATH`, + then among the :ref:`Find Modules` provided by the CMake installation. + If the file is found, it is read and processed by CMake. It is responsible + for finding the package, checking the version, and producing any needed + messages. Some Find modules provide limited or no support for versioning; + check the Find module's documentation. + + The ``Find<PackageName>.cmake`` file is not typically provided by the + package itself. Rather, it is normally provided by something external to + the package, such as the operating system, CMake itself, or even the project + from which the ``find_package()`` command was called. Being externally + provided, :ref:`Find Modules` tend to be heuristic in nature and are + susceptible to becoming out-of-date. They typically search for certain + libraries, files and other package artifacts. + + Module mode is only supported by the + :ref:`basic command signature <Basic Signature>`. + +**Config mode** + In this mode, CMake searches for a file called + ``<lowercasePackageName>-config.cmake`` or ``<PackageName>Config.cmake``. + It will also look for ``<lowercasePackageName>-config-version.cmake`` or + ``<PackageName>ConfigVersion.cmake`` if version details were specified + (see :ref:`version selection` for an explanation of how these separate + version files are used). + + In config mode, the command can be given a list of names to search for + as package names. The locations where CMake searches for the config and + version files is considerably more complicated than for Module mode + (see :ref:`search procedure`). + + The config and version files are typically installed as part of the + package, so they tend to be more reliable than Find modules. They usually + contain direct knowledge of the package contents, so no searching or + heuristics are needed within the config or version files themselves. + + Config mode is supported by both the :ref:`basic <Basic Signature>` and + :ref:`full <Full Signature>` command signatures. + +The command arguments determine which of the above modes is used. When the +`basic signature`_ is used, the command searches in Module mode first. +If the package is not found, the search falls back to Config mode. +A user may set the :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` variable +to true to reverse the priority and direct CMake to search using Config mode +first before falling back to Module mode. The basic signature can also be +forced to use only Module mode with a ``MODULE`` keyword. If the +`full signature`_ is used, the command only searches in Config mode. + +Where possible, user code should generally look for packages using the +`basic signature`_, since that allows the package to be found with either mode. +Project maintainers wishing to provide a config package should understand +the bigger picture, as explained in :ref:`Full Signature` and all subsequent +sections on this page. .. _`basic signature`: -Basic Signature and Module Mode -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Basic Signature +^^^^^^^^^^^^^^^ .. code-block:: cmake @@ -19,20 +81,39 @@ Basic Signature and Module Mode [OPTIONAL_COMPONENTS components...] [NO_POLICY_SCOPE]) -Finds and loads settings from an external project. ``<PackageName>_FOUND`` -will be set to indicate whether the package was found. When the -package is found package-specific information is provided through -variables and :ref:`Imported Targets` documented by the package itself. The +The basic signature is supported by both Module and Config modes. +The ``MODULE`` keyword implies that only Module mode can be used to find +the package, with no fallback to Config mode. + +Regardless of the mode used, a ``<PackageName>_FOUND`` variable will be +set to indicate whether the package was found. When the package is found, +package-specific information may be provided through other variables and +:ref:`Imported Targets` documented by the package itself. The ``QUIET`` option disables informational messages, including those indicating that the package cannot be found if it is not ``REQUIRED``. The ``REQUIRED`` option stops processing with an error message if the package cannot be found. A package-specific list of required components may be listed after the -``COMPONENTS`` option (or after the ``REQUIRED`` option if present). +``COMPONENTS`` keyword. If any of these components are not able to be +satisfied, the package overall is considered to be not found. If the +``REQUIRED`` option is also present, this is treated as a fatal error, +otherwise execution still continues. As a form of shorthand, if the +``REQUIRED`` option is present, the ``COMPONENTS`` keyword can be omitted +and the required components can be listed directly after ``REQUIRED``. + Additional optional components may be listed after -``OPTIONAL_COMPONENTS``. Available components and their influence on -whether a package is considered to be found are defined by the target -package. +``OPTIONAL_COMPONENTS``. If these cannot be satisfied, the package overall +can still be considered found, as long as all required components are +satisfied. + +The set of available components and their meaning are defined by the +target package. Formally, it is up to the target package how to +interpret the component information given to it, but it should follow +the expectations stated above. For calls where no components are specified, +there is no single expected behavior and target packages should clearly +define what occurs in such cases. Common arrangements include assuming it +should find all components, no components or some well-defined subset of the +available components. .. _FIND_PACKAGE_VERSION_FORMAT: @@ -40,12 +121,13 @@ The ``[version]`` argument requests a version with which the package found should be compatible. There are two possible forms in which it may be specified: - * A single version with the format ``major[.minor[.patch[.tweak]]]``. + * A single version with the format ``major[.minor[.patch[.tweak]]]``, where + each component is a numeric value. * A version range with the format ``versionMin...[<]versionMax`` where - ``versionMin`` and ``versionMax`` have the same format as the single - version. By default, both end points are included. By specifying ``<``, - the upper end point will be excluded. Version ranges are only supported - with CMake 3.19 or later. + ``versionMin`` and ``versionMax`` have the same format and constraints + on components being integers as the single version. By default, both end + points are included. By specifying ``<``, the upper end point will be + excluded. Version ranges are only supported with CMake 3.19 or later. The ``EXACT`` option requests that the version be matched exactly. This option is incompatible with the specification of a version range. @@ -62,36 +144,10 @@ only take the single version at the lower end of the range into account. See the :command:`cmake_policy` command documentation for discussion of the ``NO_POLICY_SCOPE`` option. -The command has two modes by which it searches for packages: "Module" -mode and "Config" mode. The above signature selects Module mode. -If no module is found the command falls back to Config mode, described -below. This fall back is disabled if the ``MODULE`` option is given. - -In Module mode, CMake searches for a file called ``Find<PackageName>.cmake``. -The file is first searched in the :variable:`CMAKE_MODULE_PATH`, -then among the :ref:`Find Modules` provided by the CMake installation. -If the file is found, it is read and processed by CMake. It is responsible -for finding the package, checking the version, and producing any needed -messages. Some find-modules provide limited or no support for versioning; -check the module documentation. - -If the ``MODULE`` option is not specified in the above signature, -CMake first searches for the package using Module mode. Then, if the -package is not found, it searches again using Config mode. A user -may set the variable :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` to -``TRUE`` to direct CMake first search using Config mode before falling -back to Module mode. - -Full Signature and Config Mode -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -User code should generally look for packages using the above `basic -signature`_. The remainder of this command documentation specifies the -full command signature and details of the search process. Project -maintainers wishing to provide a package to be found by this command -are encouraged to read on. - -The complete Config mode command signature is +.. _`full signature`: + +Full Signature +^^^^^^^^^^^^^^ .. code-block:: cmake @@ -129,18 +185,19 @@ hold the directory containing the file. By default the command searches for a package with the name ``<PackageName>``. If the ``NAMES`` option is given the names following it are used instead of ``<PackageName>``. The command searches for a file called ``<PackageName>Config.cmake`` or -``<lower-case-package-name>-config.cmake`` for each name specified. +``<lowercasePackageName>-config.cmake`` for each name specified. A replacement set of possible configuration file names may be given -using the ``CONFIGS`` option. The search procedure is specified below. -Once found, the configuration file is read and processed by CMake. +using the ``CONFIGS`` option. The :ref:`search procedure` is specified below. +Once found, any :ref:`version constraint <version selection>` is checked, +and if satisfied, the configuration file is read and processed by CMake. Since the file is provided by the package it already knows the location of package contents. The full path to the configuration file is stored in the cmake variable ``<PackageName>_CONFIG``. All configuration files which have been considered by CMake while -searching for an installation of the package with an appropriate -version are stored in the cmake variable ``<PackageName>_CONSIDERED_CONFIGS``, -the associated versions in ``<PackageName>_CONSIDERED_VERSIONS``. +searching for the package with an appropriate version are stored in the +``<PackageName>_CONSIDERED_CONFIGS`` variable, and the associated versions +in the ``<PackageName>_CONSIDERED_VERSIONS`` variable. If the package configuration file cannot be found CMake will generate an error describing the problem unless the ``QUIET`` argument is @@ -150,143 +207,18 @@ fatal error is generated and the configure step stops executing. If configuration file CMake will ignore it and search from scratch. Package maintainers providing CMake package configuration files are -encouraged to name and install them such that the `Search Procedure`_ +encouraged to name and install them such that the :ref:`search procedure` outlined below will find them without requiring use of additional options. -Version Selection -^^^^^^^^^^^^^^^^^ - -When the ``[version]`` argument is given, Config mode will only find a -version of the package that claims compatibility with the requested -version (see :ref:`format specification <FIND_PACKAGE_VERSION_FORMAT>`). If the -``EXACT`` option is given, only a version of the package claiming an exact match -of the requested version may be found. CMake does not establish any -convention for the meaning of version numbers. Package version -numbers are checked by "version" files provided by the packages -themselves. For a candidate package configuration file -``<config-file>.cmake`` the corresponding version file is located next -to it and named either ``<config-file>-version.cmake`` or -``<config-file>Version.cmake``. If no such version file is available -then the configuration file is assumed to not be compatible with any -requested version. A basic version file containing generic version -matching code can be created using the -:module:`CMakePackageConfigHelpers` module. When a version file -is found it is loaded to check the requested version number. The -version file is loaded in a nested scope in which the following -variables have been defined: - -``PACKAGE_FIND_NAME`` - The ``<PackageName>`` -``PACKAGE_FIND_VERSION`` - Full requested version string -``PACKAGE_FIND_VERSION_MAJOR`` - Major version if requested, else 0 -``PACKAGE_FIND_VERSION_MINOR`` - Minor version if requested, else 0 -``PACKAGE_FIND_VERSION_PATCH`` - Patch version if requested, else 0 -``PACKAGE_FIND_VERSION_TWEAK`` - Tweak version if requested, else 0 -``PACKAGE_FIND_VERSION_COUNT`` - Number of version components, 0 to 4 - -When a version range is specified, the above version variables will hold -values based on the lower end of the version range. This is to preserve -compatibility with packages that have not been implemented to expect version -ranges. In addition, the version range will be described by the following -variables: - -``PACKAGE_FIND_VERSION_RANGE`` - Full requested version range string -``PACKAGE_FIND_VERSION_RANGE_MIN`` - This specifies whether the lower end point of the version range should be - included or excluded. Currently, the only supported value for this variable - is ``INCLUDE``. -``PACKAGE_FIND_VERSION_RANGE_MAX`` - This specifies whether the upper end point of the version range should be - included or excluded. The supported values for this variable are - ``INCLUDE`` and ``EXCLUDE``. - -``PACKAGE_FIND_VERSION_MIN`` - Full requested version string of the lower end point of the range -``PACKAGE_FIND_VERSION_MIN_MAJOR`` - Major version of the lower end point if requested, else 0 -``PACKAGE_FIND_VERSION_MIN_MINOR`` - Minor version of the lower end point if requested, else 0 -``PACKAGE_FIND_VERSION_MIN_PATCH`` - Patch version of the lower end point if requested, else 0 -``PACKAGE_FIND_VERSION_MIN_TWEAK`` - Tweak version of the lower end point if requested, else 0 -``PACKAGE_FIND_VERSION_MIN_COUNT`` - Number of version components of the lower end point, 0 to 4 - -``PACKAGE_FIND_VERSION_MAX`` - Full requested version string of the upper end point of the range -``PACKAGE_FIND_VERSION_MAX_MAJOR`` - Major version of the upper end point if requested, else 0 -``PACKAGE_FIND_VERSION_MAX_MINOR`` - Minor version of the upper end point if requested, else 0 -``PACKAGE_FIND_VERSION_MAX_PATCH`` - Patch version of the upper end point if requested, else 0 -``PACKAGE_FIND_VERSION_MAX_TWEAK`` - Tweak version of the upper end point if requested, else 0 -``PACKAGE_FIND_VERSION_MAX_COUNT`` - Number of version components of the upper end point, 0 to 4 - -Regardless of whether a single version or a version range is specified, the -variable ``PACKAGE_FIND_VERSION_COMPLETE`` will be defined and will hold -the full requested version string as specified. - -The version file checks whether it satisfies the requested version and -sets these variables: +.. _`search procedure`: -``PACKAGE_VERSION`` - Full provided version string -``PACKAGE_VERSION_EXACT`` - True if version is exact match -``PACKAGE_VERSION_COMPATIBLE`` - True if version is compatible -``PACKAGE_VERSION_UNSUITABLE`` - True if unsuitable as any version +Config Mode Search Procedure +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -These variables are checked by the ``find_package`` command to determine -whether the configuration file provides an acceptable version. They -are not available after the ``find_package`` call returns. If the version -is acceptable the following variables are set: - -``<PackageName>_VERSION`` - Full provided version string -``<PackageName>_VERSION_MAJOR`` - Major version if provided, else 0 -``<PackageName>_VERSION_MINOR`` - Minor version if provided, else 0 -``<PackageName>_VERSION_PATCH`` - Patch version if provided, else 0 -``<PackageName>_VERSION_TWEAK`` - Tweak version if provided, else 0 -``<PackageName>_VERSION_COUNT`` - Number of version components, 0 to 4 - -and the corresponding package configuration file is loaded. -When multiple package configuration files are available whose version files -claim compatibility with the version requested it is unspecified which -one is chosen: unless the variable :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` -is set no attempt is made to choose a highest or closest version number. - -To control the order in which ``find_package`` checks for compatibility use -the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and -:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`. -For instance in order to select the highest version one can set - -.. code-block:: cmake - - SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL) - SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC) - -before calling ``find_package``. - -Search Procedure -^^^^^^^^^^^^^^^^ +.. note:: + When Config mode is used, this search procedure is applied regardless of + whether the :ref:`full <full signature>` or :ref:`basic <basic signature>` + signature was given. CMake constructs a set of possible installation prefixes for the package. Under each prefix several directories are searched for a @@ -431,8 +363,13 @@ enabled. 9. Search paths specified by the ``PATHS`` option. These are typically hard-coded guesses. +The :variable:`CMAKE_IGNORE_PATH`, :variable:`CMAKE_IGNORE_PREFIX_PATH`, +:variable:`CMAKE_SYSTEM_IGNORE_PATH` and +:variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` variables can also cause some +of the above locations to be ignored. + .. versionadded:: 3.16 - Added the ``CMAKE_FIND_USE_<CATEGORY>_PATH`` variables to globally disable + Added the ``CMAKE_FIND_USE_<CATEGORY>`` variables to globally disable various search locations. .. |FIND_XXX| replace:: find_package @@ -448,8 +385,154 @@ which the file is found. The :variable:`CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS` variable may be set to ``TRUE`` before calling ``find_package`` in order to resolve symbolic links and store the real path to the file. -Every non-REQUIRED ``find_package`` call can be disabled by setting the -:variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``. +Every non-REQUIRED ``find_package`` call can be disabled or made REQUIRED: + +* Setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable + to ``TRUE`` disables the package. + +* Setting the :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable + to ``TRUE`` makes the package REQUIRED. + +Setting both variables to ``TRUE`` simultaneously is an error. + +.. _`version selection`: + +Config Mode Version Selection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: + When Config mode is used, this version selection process is applied + regardless of whether the :ref:`full <full signature>` or + :ref:`basic <basic signature>` signature was given. + +When the ``[version]`` argument is given, Config mode will only find a +version of the package that claims compatibility with the requested +version (see :ref:`format specification <FIND_PACKAGE_VERSION_FORMAT>`). If the +``EXACT`` option is given, only a version of the package claiming an exact match +of the requested version may be found. CMake does not establish any +convention for the meaning of version numbers. Package version +numbers are checked by "version" files provided by the packages +themselves. For a candidate package configuration file +``<config-file>.cmake`` the corresponding version file is located next +to it and named either ``<config-file>-version.cmake`` or +``<config-file>Version.cmake``. If no such version file is available +then the configuration file is assumed to not be compatible with any +requested version. A basic version file containing generic version +matching code can be created using the +:module:`CMakePackageConfigHelpers` module. When a version file +is found it is loaded to check the requested version number. The +version file is loaded in a nested scope in which the following +variables have been defined: + +``PACKAGE_FIND_NAME`` + The ``<PackageName>`` +``PACKAGE_FIND_VERSION`` + Full requested version string +``PACKAGE_FIND_VERSION_MAJOR`` + Major version if requested, else 0 +``PACKAGE_FIND_VERSION_MINOR`` + Minor version if requested, else 0 +``PACKAGE_FIND_VERSION_PATCH`` + Patch version if requested, else 0 +``PACKAGE_FIND_VERSION_TWEAK`` + Tweak version if requested, else 0 +``PACKAGE_FIND_VERSION_COUNT`` + Number of version components, 0 to 4 + +When a version range is specified, the above version variables will hold +values based on the lower end of the version range. This is to preserve +compatibility with packages that have not been implemented to expect version +ranges. In addition, the version range will be described by the following +variables: + +``PACKAGE_FIND_VERSION_RANGE`` + Full requested version range string +``PACKAGE_FIND_VERSION_RANGE_MIN`` + This specifies whether the lower end point of the version range should be + included or excluded. Currently, the only supported value for this variable + is ``INCLUDE``. +``PACKAGE_FIND_VERSION_RANGE_MAX`` + This specifies whether the upper end point of the version range should be + included or excluded. The supported values for this variable are + ``INCLUDE`` and ``EXCLUDE``. + +``PACKAGE_FIND_VERSION_MIN`` + Full requested version string of the lower end point of the range +``PACKAGE_FIND_VERSION_MIN_MAJOR`` + Major version of the lower end point if requested, else 0 +``PACKAGE_FIND_VERSION_MIN_MINOR`` + Minor version of the lower end point if requested, else 0 +``PACKAGE_FIND_VERSION_MIN_PATCH`` + Patch version of the lower end point if requested, else 0 +``PACKAGE_FIND_VERSION_MIN_TWEAK`` + Tweak version of the lower end point if requested, else 0 +``PACKAGE_FIND_VERSION_MIN_COUNT`` + Number of version components of the lower end point, 0 to 4 + +``PACKAGE_FIND_VERSION_MAX`` + Full requested version string of the upper end point of the range +``PACKAGE_FIND_VERSION_MAX_MAJOR`` + Major version of the upper end point if requested, else 0 +``PACKAGE_FIND_VERSION_MAX_MINOR`` + Minor version of the upper end point if requested, else 0 +``PACKAGE_FIND_VERSION_MAX_PATCH`` + Patch version of the upper end point if requested, else 0 +``PACKAGE_FIND_VERSION_MAX_TWEAK`` + Tweak version of the upper end point if requested, else 0 +``PACKAGE_FIND_VERSION_MAX_COUNT`` + Number of version components of the upper end point, 0 to 4 + +Regardless of whether a single version or a version range is specified, the +variable ``PACKAGE_FIND_VERSION_COMPLETE`` will be defined and will hold +the full requested version string as specified. + +The version file checks whether it satisfies the requested version and +sets these variables: + +``PACKAGE_VERSION`` + Full provided version string +``PACKAGE_VERSION_EXACT`` + True if version is exact match +``PACKAGE_VERSION_COMPATIBLE`` + True if version is compatible +``PACKAGE_VERSION_UNSUITABLE`` + True if unsuitable as any version + +These variables are checked by the ``find_package`` command to determine +whether the configuration file provides an acceptable version. They +are not available after the ``find_package`` call returns. If the version +is acceptable the following variables are set: + +``<PackageName>_VERSION`` + Full provided version string +``<PackageName>_VERSION_MAJOR`` + Major version if provided, else 0 +``<PackageName>_VERSION_MINOR`` + Minor version if provided, else 0 +``<PackageName>_VERSION_PATCH`` + Patch version if provided, else 0 +``<PackageName>_VERSION_TWEAK`` + Tweak version if provided, else 0 +``<PackageName>_VERSION_COUNT`` + Number of version components, 0 to 4 + +and the corresponding package configuration file is loaded. +When multiple package configuration files are available whose version files +claim compatibility with the version requested it is unspecified which +one is chosen: unless the variable :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` +is set no attempt is made to choose a highest or closest version number. + +To control the order in which ``find_package`` checks for compatibility use +the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and +:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`. +For instance in order to select the highest version one can set + +.. code-block:: cmake + + SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL) + SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC) + +before calling ``find_package``. Package File Interface Variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -479,7 +562,7 @@ restores their original state before returning): ``<PackageName>_FIND_VERSION_EXACT`` True if ``EXACT`` option was given ``<PackageName>_FIND_COMPONENTS`` - List of requested components + List of specified components (required and optional) ``<PackageName>_FIND_REQUIRED_<c>`` True if component ``<c>`` is required, false if component ``<c>`` is optional diff --git a/Help/command/foreach.rst b/Help/command/foreach.rst index 8de6deb..d9f54ca 100644 --- a/Help/command/foreach.rst +++ b/Help/command/foreach.rst @@ -14,9 +14,12 @@ semicolon or whitespace. All commands between ``foreach`` and the matching ``endforeach`` are recorded without being invoked. Once the ``endforeach`` is evaluated, the recorded list of commands is invoked once for each item in ``<items>``. -At the beginning of each iteration the variable ``loop_var`` will be set +At the beginning of each iteration the variable ``<loop_var>`` will be set to the value of the current item. +The scope of ``<loop_var>`` is restricted to the loop scope. See policy +:policy:`CMP0124` for details. + The commands :command:`break` and :command:`continue` provide means to escape from the normal control flow. diff --git a/Help/command/get_filename_component.rst b/Help/command/get_filename_component.rst index be9d00a..4bdd388 100644 --- a/Help/command/get_filename_component.rst +++ b/Help/command/get_filename_component.rst @@ -3,7 +3,7 @@ get_filename_component Get a specific component of a full filename. -.. versionchanged:: 3.19 +.. versionchanged:: 3.20 This command been superseded by :command:`cmake_path` command, except ``REALPATH`` now offered by :ref:`file(REAL_PATH) <REAL_PATH>` command and ``PROGRAM`` now available in :command:`separate_arguments(PROGRAM)` command. diff --git a/Help/command/get_property.rst b/Help/command/get_property.rst index f77d8af..46da285 100644 --- a/Help/command/get_property.rst +++ b/Help/command/get_property.rst @@ -9,7 +9,7 @@ Get a property. <GLOBAL | DIRECTORY [<dir>] | TARGET <target> | - SOURCE <source> | + SOURCE <source> [DIRECTORY <dir> | TARGET_DIRECTORY <target>] | INSTALL <file> | TEST <test> | diff --git a/Help/command/if.rst b/Help/command/if.rst index fbf3e36..4f955db 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -38,30 +38,49 @@ The following syntax applies to the ``condition`` argument of the ``if``, ``elseif`` and :command:`while` clauses. Compound conditions are evaluated in the following order of precedence: -Innermost parentheses are evaluated first. Next come unary tests such -as `EXISTS`_, `COMMAND`_, and `DEFINED`_. Then binary tests such as -`EQUAL`_, `LESS`_, `LESS_EQUAL`_, `GREATER`_, `GREATER_EQUAL`_, -`STREQUAL`_, `STRLESS`_, `STRLESS_EQUAL`_, `STRGREATER`_, -`STRGREATER_EQUAL`_, `VERSION_EQUAL`_, `VERSION_LESS`_, -`VERSION_LESS_EQUAL`_, `VERSION_GREATER`_, `VERSION_GREATER_EQUAL`_, -and `MATCHES`_. Then the boolean operators in the order `NOT`_, `AND`_, -and finally `OR`_. + +1. Parentheses. + +2. Unary tests such as `EXISTS`_, `COMMAND`_, and `DEFINED`_. + +3. Binary tests such as `EQUAL`_, `LESS`_, `LESS_EQUAL`_, `GREATER`_, + `GREATER_EQUAL`_, `STREQUAL`_, `STRLESS`_, `STRLESS_EQUAL`_, + `STRGREATER`_, `STRGREATER_EQUAL`_, `VERSION_EQUAL`_, `VERSION_LESS`_, + `VERSION_LESS_EQUAL`_, `VERSION_GREATER`_, `VERSION_GREATER_EQUAL`_, + and `MATCHES`_. + +4. Unary logical operator `NOT`_. + +5. Binary logical operators `AND`_ and `OR`_, from left to right, + without any short-circuit. Basic Expressions """"""""""""""""" ``if(<constant>)`` True if the constant is ``1``, ``ON``, ``YES``, ``TRUE``, ``Y``, - or a non-zero number. False if the constant is ``0``, ``OFF``, + or a non-zero number (including floating point numbers). + False if the constant is ``0``, ``OFF``, ``NO``, ``FALSE``, ``N``, ``IGNORE``, ``NOTFOUND``, the empty string, or ends in the suffix ``-NOTFOUND``. Named boolean constants are case-insensitive. If the argument is not one of these specific - constants, it is treated as a variable or string and the following - signature is used. + constants, it is treated as a variable or string (see `Variable Expansion`_ + further below) and one of the following two forms applies. -``if(<variable|string>)`` +``if(<variable>)`` True if given a variable that is defined to a value that is not a false - constant. False otherwise. (Note macro arguments are not variables.) + constant. False otherwise, including if the variable is undefined. + Note that macro arguments are not variables. + Environment variables also cannot be tested this way, e.g. + ``if(ENV{some_var})`` will always evaluate to false. + +``if(<string>)`` + A quoted string always evaluates to false unless: + + * The string's value is one of the true constants, or + * Policy :policy:`CMP0054` is not set to ``NEW`` and the string's value + happens to be a variable name that is affected by :policy:`CMP0054`'s + behavior. Logic Operators """"""""""""""" @@ -115,7 +134,16 @@ Existence Checks ``if(DEFINED <name>|CACHE{<name>}|ENV{<name>})`` True if a variable, cache variable or environment variable with given ``<name>`` is defined. The value of the variable - does not matter. Note that macro arguments are not variables. + does not matter. Note the following caveats: + + * Macro arguments are not variables. + * It is not possible to test directly whether a `<name>` is a non-cache + variable. The expression ``if(DEFINED someName)`` will evaluate to true + if either a cache or non-cache variable ``someName`` exists. In + comparison, the expression ``if(DEFINED CACHE{someName})`` will only + evaluate to true if a cache variable ``someName`` exists. Both expressions + need to be tested if you need to know whether a non-cache variable exists: + ``if(DEFINED someName AND NOT DEFINED CACHE{someName})``. .. versionadded:: 3.14 Added support for ``CACHE{<name>}`` variables. @@ -171,7 +199,7 @@ Comparisons ``if(<variable|string> MATCHES regex)`` True if the given string or variable's value matches the given regular - condition. See :ref:`Regex Specification` for regex format. + expression. See :ref:`Regex Specification` for regex format. .. versionadded:: 3.9 ``()`` groups are captured in :variable:`CMAKE_MATCH_<n>` variables. diff --git a/Help/command/install.rst b/Help/command/install.rst index 35207f4..1a9dfd7 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -9,11 +9,13 @@ Synopsis .. parsed-literal:: install(`TARGETS`_ <target>... [...]) + install(`IMPORTED_RUNTIME_ARTIFACTS`_ <target>... [...]) install({`FILES`_ | `PROGRAMS`_} <file>... [...]) install(`DIRECTORY`_ <dir>... [...]) install(`SCRIPT`_ <file> [...]) install(`CODE`_ <code> [...]) install(`EXPORT`_ <export-name> [...]) + install(`RUNTIME_DEPENDENCY_SET`_ <set-name> [...]) Introduction ^^^^^^^^^^^^ @@ -28,6 +30,10 @@ are executed in order during installation. with those in the parent directory to run in the order declared (see policy :policy:`CMP0082`). +.. versionchanged:: 3.22 + The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the + default copying behavior of :command:`install()`. + There are multiple signatures for this command. Some of them define installation options for files and targets. Options common to multiple signatures are covered here but they are valid only for @@ -124,8 +130,9 @@ Installing Targets .. code-block:: cmake install(TARGETS targets... [EXPORT <export-name>] + [RUNTIME_DEPENDENCIES args...|RUNTIME_DEPENDENCY_SET <set-name>] [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE| - PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE] + PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE|FILE_SET <set-name>] [DESTINATION <dir>] [PERMISSIONS permissions...] [CONFIGURATIONS [Debug|Release|...]] @@ -197,6 +204,17 @@ that may be installed: Similar to ``PUBLIC_HEADER`` and ``PRIVATE_HEADER``, but for ``RESOURCE`` files. See :prop_tgt:`RESOURCE` for details. +``FILE_SET <set>`` + .. versionadded:: 3.23 + + File sets are defined by the :command:`target_sources(FILE_SET)` command. + If the file set ``<set>`` exists and is ``PUBLIC`` or ``INTERFACE``, any + files in the set are installed under the destination (see below). + The directory structure relative to the file set's base directories is + preserved. For example, a file added to the file set as + ``/blah/include/myproj/here.h`` with a base directory ``/blah/include`` + would be installed to ``myproj/here.h`` below the destination. + For each of these arguments given, the arguments following them only apply to the target or file type specified in the argument. If none is given, the installation properties apply to all target types. If only one is given then @@ -207,30 +225,32 @@ For regular executables, static libraries and shared libraries, the ``DESTINATION`` argument is not required. For these target types, when ``DESTINATION`` is omitted, a default destination will be taken from the appropriate variable from :module:`GNUInstallDirs`, or set to a built-in -default value if that variable is not defined. The same is true for the -public and private headers associated with the installed targets through the -:prop_tgt:`PUBLIC_HEADER` and :prop_tgt:`PRIVATE_HEADER` target properties. -A destination must always be provided for module libraries, Apple bundles and -frameworks. A destination can be omitted for interface and object libraries, -but they are handled differently (see the discussion of this topic toward the -end of this section). +default value if that variable is not defined. The same is true for file +sets, and the public and private headers associated with the installed +targets through the :prop_tgt:`PUBLIC_HEADER` and :prop_tgt:`PRIVATE_HEADER` +target properties. A destination must always be provided for module libraries, +Apple bundles and frameworks. A destination can be omitted for interface and +object libraries, but they are handled differently (see the discussion of this +topic toward the end of this section). The following table shows the target types with their associated variables and built-in defaults that apply when no destination is given: -================== =============================== ====================== - Target Type GNUInstallDirs Variable Built-In Default -================== =============================== ====================== -``RUNTIME`` ``${CMAKE_INSTALL_BINDIR}`` ``bin`` -``LIBRARY`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib`` -``ARCHIVE`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib`` -``PRIVATE_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` -``PUBLIC_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` -================== =============================== ====================== +=============================== =============================== ====================== + Target Type GNUInstallDirs Variable Built-In Default +=============================== =============================== ====================== +``RUNTIME`` ``${CMAKE_INSTALL_BINDIR}`` ``bin`` +``LIBRARY`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib`` +``ARCHIVE`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib`` +``PRIVATE_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` +``PUBLIC_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` +``FILE_SET`` (type ``HEADERS``) ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` +=============================== =============================== ====================== Projects wishing to follow the common practice of installing headers into a -project-specific subdirectory will need to provide a destination rather than -rely on the above. +project-specific subdirectory may prefer using file sets with appropriate +paths and base directories. Otherwise, they must provide a ``DESTINATION`` +instead of being able to rely on the above (see next example below). To make packages compliant with distribution filesystem layout policies, if projects must specify a ``DESTINATION``, it is recommended that they use a @@ -239,7 +259,7 @@ This allows package maintainers to control the install destination by setting the appropriate cache variables. The following example shows a static library being installed to the default destination provided by :module:`GNUInstallDirs`, but with its headers installed to a project-specific -subdirectory that follows the above recommendation: +subdirectory without using file sets: .. code-block:: cmake @@ -331,6 +351,11 @@ top level: See documentation of the :prop_tgt:`EXPORT_NAME` target property to change the name of the exported target. + If ``EXPORT`` is used and the targets include ``PUBLIC`` or ``INTERFACE`` + file sets, all of them must be specified with ``FILE_SET`` arguments. All + ``PUBLIC`` or ``INTERFACE`` file sets associated with a target are included + in the export. + ``INCLUDES DESTINATION`` This option specifies a list of directories which will be added to the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property of the @@ -338,6 +363,49 @@ top level: relative path is specified, it is treated as relative to the ``$<INSTALL_PREFIX>``. +``RUNTIME_DEPENDENCY_SET`` + .. versionadded:: 3.21 + + This option causes all runtime dependencies of installed executable, shared + library, and module targets to be added to the specified runtime dependency + set. This set can then be installed with an + `install(RUNTIME_DEPENDENCY_SET)`_ command. + + This keyword and the ``RUNTIME_DEPENDENCIES`` keyword are mutually + exclusive. + +``RUNTIME_DEPENDENCIES`` + .. versionadded:: 3.21 + + This option causes all runtime dependencies of installed executable, shared + library, and module targets to be installed along with the targets + themselves. The ``RUNTIME``, ``LIBRARY``, ``FRAMEWORK``, and generic + arguments are used to determine the properties (``DESTINATION``, + ``COMPONENT``, etc.) of the installation of these dependencies. + + ``RUNTIME_DEPENDENCIES`` is semantically equivalent to the following pair + of calls: + + .. code-block:: cmake + + install(TARGETS ... RUNTIME_DEPENDENCY_SET <set-name>) + install(RUNTIME_DEPENDENCY_SET <set-name> args...) + + where ``<set-name>`` will be a randomly generated set name. + The ``args...`` may include any of the following keywords supported by + the `install(RUNTIME_DEPENDENCY_SET)`_ command: + + * ``DIRECTORIES`` + * ``PRE_INCLUDE_REGEXES`` + * ``PRE_EXCLUDE_REGEXES`` + * ``POST_INCLUDE_REGEXES`` + * ``POST_EXCLUDE_REGEXES`` + * ``POST_INCLUDE_FILES`` + * ``POST_EXCLUDE_FILES`` + + The ``RUNTIME_DEPENDENCIES`` and ``RUNTIME_DEPENDENCY_SET`` keywords are + mutually exclusive. + One or more groups of properties may be specified in a single call to the ``TARGETS`` form of this command. A target may be installed more than once to different locations. Consider hypothetical targets ``myExe``, @@ -382,6 +450,44 @@ set to ``TRUE`` has undefined behavior. to ensure that such out-of-directory targets are built before the subdirectory-specific install rules are run. +Installing Imported Runtime Artifacts +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. _`install(IMPORTED_RUNTIME_ARTIFACTS)`: +.. _IMPORTED_RUNTIME_ARTIFACTS: + +.. versionadded:: 3.21 + +.. code-block:: cmake + + install(IMPORTED_RUNTIME_ARTIFACTS targets... + [RUNTIME_DEPENDENCY_SET <set-name>] + [[LIBRARY|RUNTIME|FRAMEWORK|BUNDLE] + [DESTINATION <dir>] + [PERMISSIONS permissions...] + [CONFIGURATIONS [Debug|Release|...]] + [COMPONENT <component>] + [OPTIONAL] [EXCLUDE_FROM_ALL] + ] [...] + ) + +The ``IMPORTED_RUNTIME_ARTIFACTS`` form specifies rules for installing the +runtime artifacts of imported targets. Projects may do this if they want to +bundle outside executables or modules inside their installation. The +``LIBRARY``, ``RUNTIME``, ``FRAMEWORK``, and ``BUNDLE`` arguments have the +same semantics that they do in the `TARGETS`_ mode. Only the runtime artifacts +of imported targets are installed (except in the case of :prop_tgt:`FRAMEWORK` +libraries, :prop_tgt:`MACOSX_BUNDLE` executables, and :prop_tgt:`BUNDLE` +CFBundles.) For example, headers and import libraries associated with DLLs are +not installed. In the case of :prop_tgt:`FRAMEWORK` libraries, +:prop_tgt:`MACOSX_BUNDLE` executables, and :prop_tgt:`BUNDLE` CFBundles, the +entire directory is installed. + +The ``RUNTIME_DEPENDENCY_SET`` option causes the runtime artifacts of the +imported executable, shared library, and module library ``targets`` to be +added to the ``<set-name>`` runtime dependency set. This set can then be +installed with an `install(RUNTIME_DEPENDENCY_SET)`_ command. + Installing Files ^^^^^^^^^^^^^^^^ @@ -390,6 +496,12 @@ Installing Files .. _FILES: .. _PROGRAMS: +.. note:: + + If installing header files, consider using file sets defined by + :command:`target_sources(FILE_SET)` instead. File sets associate + headers with a target and they install as part of the target. + .. code-block:: cmake install(<FILES|PROGRAMS> files... @@ -446,7 +558,8 @@ file type if they wish to explicitly define the install destination. Projects wishing to follow the common practice of installing headers into a project-specific subdirectory will need to provide a destination rather than -rely on the above. +rely on the above. Using file sets for headers instead of ``install(FILES)`` +would be even better (see :command:`target_sources(FILE_SET)`). Note that some of the types' built-in defaults use the ``DATAROOT`` directory as a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with @@ -459,13 +572,14 @@ projects must specify a ``DESTINATION``, it is recommended that they use a path that begins with the appropriate :module:`GNUInstallDirs` variable. This allows package maintainers to control the install destination by setting the appropriate cache variables. The following example shows how to follow -this advice while installing headers to a project-specific subdirectory: +this advice while installing an image to a project-specific documentation +subdirectory: .. code-block:: cmake include(GNUInstallDirs) - install(FILES mylib.h - DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj + install(FILES logo.png + DESTINATION ${CMAKE_INSTALL_DOCDIR}/myproj ) .. versionadded:: 3.4 @@ -484,6 +598,13 @@ Installing Directories .. _`install(DIRECTORY)`: .. _DIRECTORY: +.. note:: + + To install a directory sub-tree of headers, consider using file sets + defined by :command:`target_sources(FILE_SET)` instead. File sets not only + preserve directory structure, they also associate headers with a target + and install as part of the target. + .. code-block:: cmake install(DIRECTORY dirs... @@ -535,12 +656,13 @@ any expression. For example, the code .. code-block:: cmake - install(DIRECTORY src/ DESTINATION include/myproj - FILES_MATCHING PATTERN "*.h") + install(DIRECTORY src/ DESTINATION doc/myproj + FILES_MATCHING PATTERN "*.png") -will extract and install header files from a source tree. +will extract and install images from a source tree. -Some options may follow a ``PATTERN`` or ``REGEX`` expression and are applied +Some options may follow a ``PATTERN`` or ``REGEX`` expression as described +under :ref:`string(REGEX) <Regex Specification>` and are applied only to files or directories matching them. The ``EXCLUDE`` option will skip the matched file or directory. The ``PERMISSIONS`` option overrides the permissions setting for the matched file or directory. For @@ -619,7 +741,8 @@ Custom Installation Logic .. code-block:: cmake install([[SCRIPT <file>] [CODE <code>]] - [COMPONENT <component>] [EXCLUDE_FROM_ALL] [...]) + [ALL_COMPONENTS | COMPONENT <component>] + [EXCLUDE_FROM_ALL] [...]) The ``SCRIPT`` form will invoke the given CMake script files during installation. If the script file name is a relative path it will be @@ -634,6 +757,12 @@ example, the code will print a message during installation. +.. versionadded:: 3.21 + When the ``ALL_COMPONENTS`` option is given, the custom installation + script code will be executed for every component of a component-specific + installation. This option is mutually exclusive with the ``COMPONENT`` + option. + .. versionadded:: 3.14 ``<file>`` or ``<code>`` may use "generator expressions" with the syntax ``$<...>`` (in the case of ``<file>``, this refers to their use in the file @@ -699,7 +828,7 @@ of the ``Development`` component in the package metadata, ensuring that the library is always installed if the headers and CMake export file are present. .. versionadded:: 3.7 - In addition to cmake language files, the ``EXPORT_ANDROID_MK`` mode maybe + In addition to cmake language files, the ``EXPORT_ANDROID_MK`` mode may be used to specify an export to the android ndk build system. This mode accepts the same options as the normal export mode. The Android NDK supports the use of prebuilt libraries, both static and shared. This @@ -724,7 +853,7 @@ executable from the installation tree using the imported target name ``mp_myexe`` as if the target were built in its own tree. .. note:: - This command supercedes the :command:`install_targets` command and + This command supersedes the :command:`install_targets` command and the :prop_tgt:`PRE_INSTALL_SCRIPT` and :prop_tgt:`POST_INSTALL_SCRIPT` target properties. It also replaces the ``FILES`` forms of the :command:`install_files` and :command:`install_programs` commands. @@ -733,6 +862,70 @@ executable from the installation tree using the imported target name :command:`install_files`, and :command:`install_programs` commands is not defined. +Installing Runtime Dependencies +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. _`install(RUNTIME_DEPENDENCY_SET)`: +.. _RUNTIME_DEPENDENCY_SET: + +.. versionadded:: 3.21 + +.. code-block:: cmake + + install(RUNTIME_DEPENDENCY_SET <set-name> + [[LIBRARY|RUNTIME|FRAMEWORK] + [DESTINATION <dir>] + [PERMISSIONS permissions...] + [CONFIGURATIONS [Debug|Release|...]] + [COMPONENT <component>] + [NAMELINK_COMPONENT <component>] + [OPTIONAL] [EXCLUDE_FROM_ALL] + ] [...] + [PRE_INCLUDE_REGEXES regexes...] + [PRE_EXCLUDE_REGEXES regexes...] + [POST_INCLUDE_REGEXES regexes...] + [POST_EXCLUDE_REGEXES regexes...] + [POST_INCLUDE_FILES files...] + [POST_EXCLUDE_FILES files...] + [DIRECTORIES directories...] + ) + +Installs a runtime dependency set previously created by one or more +`install(TARGETS)`_ or `install(IMPORTED_RUNTIME_ARTIFACTS)`_ commands. The +dependencies of targets belonging to a runtime dependency set are installed in +the ``RUNTIME`` destination and component on DLL platforms, and in the +``LIBRARY`` destination and component on non-DLL platforms. macOS frameworks +are installed in the ``FRAMEWORK`` destination and component. +Targets built within the build tree will never be installed as runtime +dependencies, nor will their own dependencies, unless the targets themselves +are installed with `install(TARGETS)`_. + +The generated install script calls :command:`file(GET_RUNTIME_DEPENDENCIES)` +on the build-tree files to calculate the runtime dependencies. The build-tree +executable files are passed as the ``EXECUTABLES`` argument, the build-tree +shared libraries as the ``LIBRARIES`` argument, and the build-tree modules as +the ``MODULES`` argument. On macOS, if one of the executables is a +:prop_tgt:`MACOSX_BUNDLE`, that executable is passed as the +``BUNDLE_EXECUTABLE`` argument. At most one such bundle executable may be in +the runtime dependency set on macOS. The :prop_tgt:`MACOSX_BUNDLE` property +has no effect on other platforms. Note that +:command:`file(GET_RUNTIME_DEPENDENCIES)` only supports collecting the runtime +dependencies for Windows, Linux and macOS platforms, so +``install(RUNTIME_DEPENDENCY_SET)`` has the same limitation. + +The following sub-arguments are forwarded through as the corresponding +arguments to :command:`file(GET_RUNTIME_DEPENDENCIES)` (for those that provide +a non-empty list of directories, regular expressions or files). They all +support :manual:`generator expressions <cmake-generator-expressions(7)>`. + +* ``DIRECTORIES <directories>`` +* ``PRE_INCLUDE_REGEXES <regexes>`` +* ``PRE_EXCLUDE_REGEXES <regexes>`` +* ``POST_INCLUDE_REGEXES <regexes>`` +* ``POST_EXCLUDE_REGEXES <regexes>`` +* ``POST_INCLUDE_FILES <files>`` +* ``POST_EXCLUDE_FILES <files>`` + Generated Installation Script ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/command/install_files.rst b/Help/command/install_files.rst index ff074a8..494f3d0 100644 --- a/Help/command/install_files.rst +++ b/Help/command/install_files.rst @@ -5,7 +5,7 @@ install_files Use the :command:`install(FILES)` command instead. -This command has been superceded by the :command:`install` command. It is +This command has been superseded by the :command:`install` command. It is provided for compatibility with older CMake code. The ``FILES`` form is directly replaced by the ``FILES`` form of the :command:`install` command. The regexp form can be expressed more clearly using the ``GLOB`` diff --git a/Help/command/install_programs.rst b/Help/command/install_programs.rst index fab6482..eafae89 100644 --- a/Help/command/install_programs.rst +++ b/Help/command/install_programs.rst @@ -5,7 +5,7 @@ install_programs Use the :command:`install(PROGRAMS)` command instead. -This command has been superceded by the :command:`install` command. It is +This command has been superseded by the :command:`install` command. It is provided for compatibility with older CMake code. The ``FILES`` form is directly replaced by the ``PROGRAMS`` form of the :command:`install` command. The regexp form can be expressed more clearly using the ``GLOB`` diff --git a/Help/command/install_targets.rst b/Help/command/install_targets.rst index c9efdce..9355f8d 100644 --- a/Help/command/install_targets.rst +++ b/Help/command/install_targets.rst @@ -5,7 +5,7 @@ install_targets Use the :command:`install(TARGETS)` command instead. -This command has been superceded by the :command:`install` command. It is +This command has been superseded by the :command:`install` command. It is provided for compatibility with older CMake code. :: diff --git a/Help/command/list.rst b/Help/command/list.rst index 7accc5a..33c4f80 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -128,7 +128,9 @@ Modification list(APPEND <list> [<element> ...]) -Appends elements to the list. +Appends elements to the list. If no variable named ``<list>`` exists in the +current scope its value is treated as empty and the elements are appended to +that empty list. .. _FILTER: @@ -141,8 +143,8 @@ Appends elements to the list. Includes or removes items from the list that match the mode's pattern. In ``REGEX`` mode, items will be matched against the given regular expression. -For more information on regular expressions see also the -:command:`string` command. +For more information on regular expressions look under +:ref:`string(REGEX) <Regex Specification>`. .. _INSERT: @@ -150,7 +152,12 @@ For more information on regular expressions see also the list(INSERT <list> <element_index> <element> [<element> ...]) -Inserts elements to the list to the specified location. +Inserts elements to the list to the specified index. It is an +error to specify an out-of-range index. Valid indexes are 0 to `N` +where `N` is the length of the list, inclusive. An empty list +has length 0. If no variable named ``<list>`` exists in the +current scope its value is treated as empty and the elements are +inserted in that empty list. .. _POP_BACK: @@ -161,8 +168,9 @@ Inserts elements to the list to the specified location. .. versionadded:: 3.15 If no variable name is given, removes exactly one element. Otherwise, -assign the last element's value to the given variable and removes it, -up to the last variable name given. +with `N` variable names provided, assign the last `N` elements' values +to the given variables and then remove the last `N` values from +``<list>``. .. _POP_FRONT: @@ -173,8 +181,9 @@ up to the last variable name given. .. versionadded:: 3.15 If no variable name is given, removes exactly one element. Otherwise, -assign the first element's value to the given variable and removes it, -up to the last variable name given. +with `N` variable names provided, assign the first `N` elements' values +to the given variables and then remove the first `N` values from +``<list>``. .. _PREPEND: @@ -184,7 +193,9 @@ up to the last variable name given. .. versionadded:: 3.15 -Insert elements to the 0th position in the list. +Insert elements to the 0th position in the list. If no variable named +``<list>`` exists in the current scope its value is treated as empty and +the elements are prepended to that empty list. .. _REMOVE_ITEM: diff --git a/Help/command/project.rst b/Help/command/project.rst index 6c931b6..2a9dcfe 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -20,12 +20,18 @@ Sets the name of the project, and stores it in the variable ``CMakeLists.txt`` also stores the project name in the variable :variable:`CMAKE_PROJECT_NAME`. -Also sets the variables +Also sets the variables: -* :variable:`PROJECT_SOURCE_DIR`, - :variable:`<PROJECT-NAME>_SOURCE_DIR` -* :variable:`PROJECT_BINARY_DIR`, - :variable:`<PROJECT-NAME>_BINARY_DIR` +:variable:`PROJECT_SOURCE_DIR`, :variable:`<PROJECT-NAME>_SOURCE_DIR` + Absolute path to the source directory for the project. + +:variable:`PROJECT_BINARY_DIR`, :variable:`<PROJECT-NAME>_BINARY_DIR` + Absolute path to the binary directory for the project. + +:variable:`PROJECT_IS_TOP_LEVEL`, :variable:`<PROJECT-NAME>_IS_TOP_LEVEL` + .. versionadded:: 3.21 + + Boolean value indicating whether the project is top-level. Further variables are set by the optional arguments described in the following. If any of these arguments is not used, then the corresponding variables are @@ -97,7 +103,7 @@ The options are: Selects which programming languages are needed to build the project. Supported languages include ``C``, ``CXX`` (i.e. C++), ``CUDA``, - ``OBJC`` (i.e. Objective-C), ``OBJCXX``, ``Fortran``, ``ISPC``, and ``ASM``. + ``OBJC`` (i.e. Objective-C), ``OBJCXX``, ``Fortran``, ``HIP``, ``ISPC``, and ``ASM``. By default ``C`` and ``CXX`` are enabled if no language options are given. Specify language ``NONE``, or use the ``LANGUAGES`` keyword and list no languages, to skip enabling any languages. diff --git a/Help/command/set.rst b/Help/command/set.rst index c0e02e2..af862e4 100644 --- a/Help/command/set.rst +++ b/Help/command/set.rst @@ -68,9 +68,13 @@ users. If the cache entry does not exist prior to the call or the ``FORCE`` option is given then the cache entry will be set to the given value. -Furthermore, any normal variable binding in the current scope will -be removed to expose the newly cached value to any immediately -following evaluation. + +.. note:: + + The content of the cache variable will not be directly accessible if a normal + variable of the same name already exists (see :ref:`rules of variable + evaluation <CMake Language Variables>`). If policy :policy:`CMP0126` is set + to ``OLD``, any normal variable binding in the current scope will be removed. It is possible for the cache entry to exist prior to the call but have no type set if it was created on the :manual:`cmake(1)` command diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst index bf437b4..b9b12c4 100644 --- a/Help/command/set_property.rst +++ b/Help/command/set_property.rst @@ -9,8 +9,8 @@ Set a named property in a given scope. DIRECTORY [<dir>] | TARGET [<target1> ...] | SOURCE [<src1> ...] - [DIRECTORY <dirs> ...] | - [TARGET_DIRECTORY <targets> ...] + [DIRECTORY <dirs> ...] + [TARGET_DIRECTORY <targets> ...] | INSTALL [<file1> ...] | TEST [<test1> ...] | CACHE [<entry1> ...] > @@ -85,6 +85,10 @@ It must be one of the following: Scope may name zero or more existing tests. See also the :command:`set_tests_properties` command. + Test property values may be specified using + :manual:`generator expressions <cmake-generator-expressions(7)>` + for tests created by the :command:`add_test(NAME)` signature. + ``CACHE`` Scope must name zero or more cache existing entries. diff --git a/Help/command/set_tests_properties.rst b/Help/command/set_tests_properties.rst index 9bc94ae..eadde33 100644 --- a/Help/command/set_tests_properties.rst +++ b/Help/command/set_tests_properties.rst @@ -9,8 +9,10 @@ Set a property of the tests. Sets a property for the tests. If the test is not found, CMake will report an error. -:manual:`Generator expressions <cmake-generator-expressions(7)>` will be -expanded the same as supported by the test's :command:`add_test` call. + +Test property values may be specified using +:manual:`generator expressions <cmake-generator-expressions(7)>` +for tests created by the :command:`add_test(NAME)` signature. See also the :command:`set_property(TEST)` command. diff --git a/Help/command/source_group.rst b/Help/command/source_group.rst index 5db1ec8..83ae286 100644 --- a/Help/command/source_group.rst +++ b/Help/command/source_group.rst @@ -11,6 +11,9 @@ There are two different signatures to create source groups. Defines a group into which sources will be placed in project files. This is intended to set up file tabs in Visual Studio. +The group is scoped in the directory where the command is called, +and applies to sources in targets created in that directory. + The options are: ``TREE`` @@ -19,7 +22,8 @@ The options are: CMake will automatically detect, from ``<src>`` files paths, source groups it needs to create, to keep structure of source groups analogically to the actual files and directories structure in the project. Paths of ``<src>`` - files will be cut to be relative to ``<root>``. + files will be cut to be relative to ``<root>``. The command fails if the + paths within ``src`` do not start with ``root``. ``PREFIX`` .. versionadded:: 3.8 diff --git a/Help/command/string.rst b/Help/command/string.rst index 8ad0089..b1ca2cb 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -449,38 +449,76 @@ be in Coordinated Universal Time (UTC) rather than local time. The optional ``<format_string>`` may contain the following format specifiers: -:: +``%%`` + .. versionadded:: 3.8 - %% A literal percent sign (%). - %d The day of the current month (01-31). - %H The hour on a 24-hour clock (00-23). - %I The hour on a 12-hour clock (01-12). - %j The day of the current year (001-366). - %m The month of the current year (01-12). - %b Abbreviated month name (e.g. Oct). - %B Full month name (e.g. October). - %M The minute of the current hour (00-59). - %s Seconds since midnight (UTC) 1-Jan-1970 (UNIX time). - %S The second of the current minute. - 60 represents a leap second. (00-60) - %U The week number of the current year (00-53). - %w The day of the current week. 0 is Sunday. (0-6) - %a Abbreviated weekday name (e.g. Fri). - %A Full weekday name (e.g. Friday). - %y The last two digits of the current year (00-99) - %Y The current year. - -.. versionadded:: 3.6 - ``%s`` format specifier (UNIX time). + A literal percent sign (%). -.. versionadded:: 3.7 - ``%a`` and ``%b`` format specifiers (abbreviated month and weekday names). +``%d`` + The day of the current month (01-31). -.. versionadded:: 3.8 - ``%%`` specifier (literal ``%``). +``%H`` + The hour on a 24-hour clock (00-23). -.. versionadded:: 3.7 - ``%A`` and ``%B`` format specifiers (full month and weekday names). +``%I`` + The hour on a 12-hour clock (01-12). + +``%j`` + The day of the current year (001-366). + +``%m`` + The month of the current year (01-12). + +``%b`` + .. versionadded:: 3.7 + + Abbreviated month name (e.g. Oct). + +``%B`` + .. versionadded:: 3.10 + + Full month name (e.g. October). + +``%M`` + The minute of the current hour (00-59). + +``%s`` + .. versionadded:: 3.6 + + Seconds since midnight (UTC) 1-Jan-1970 (UNIX time). + +``%S`` + The second of the current minute. 60 represents a leap second. (00-60) + +``%f`` + The microsecond of the current second (000000-999999). + +``%U`` + The week number of the current year (00-53). + +``%V`` + .. versionadded:: 3.22 + + The ISO 8601 week number of the current year (01-53). + +``%w`` + The day of the current week. 0 is Sunday. (0-6) + +``%a`` + .. versionadded:: 3.7 + + Abbreviated weekday name (e.g. Fri). + +``%A`` + .. versionadded:: 3.10 + + Full weekday name (e.g. Friday). + +``%y`` + The last two digits of the current year (00-99). + +``%Y`` + The current year. Unknown format specifiers will be ignored and copied to the output as-is. @@ -574,7 +612,7 @@ Requires an element of object type. .. code-block:: cmake string(JSON <out-var> [ERROR_VARIABLE <error-variable>] - LENGTH <json-string> <member|index> [<member|index> ...]) + LENGTH <json-string> [<member|index> ...]) Get the length of an element in ``<json-string>`` at the location given by the list of ``<member|index>`` arguments. diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst index 3e53b2e..9a99a7d 100644 --- a/Help/command/target_include_directories.rst +++ b/Help/command/target_include_directories.rst @@ -27,14 +27,16 @@ The following arguments specify include directories. .. versionadded:: 3.11 Allow setting ``INTERFACE`` items on :ref:`IMPORTED targets <Imported Targets>`. -Specified include directories may be absolute paths or relative paths. -Repeated calls for the same <target> append items in the order called. If -``SYSTEM`` is specified, the compiler will be told the -directories are meant as system include directories on some platforms -(signalling this setting might achieve effects such as the compiler -skipping warnings, or these fixed-install system files not being -considered in dependency calculations - see compiler docs). If ``SYSTEM`` -is used together with ``PUBLIC`` or ``INTERFACE``, the +Repeated calls for the same ``<target>`` append items in the order called. + +If ``SYSTEM`` is specified, the compiler will be told the directories +are meant as system include directories on some platforms. This may +have effects such as suppressing warnings or skipping the contained +headers in dependency calculations (see compiler documentation). +Additionally, system include directories are searched after normal +include directories regardless of the order specified. + +If ``SYSTEM`` is used together with ``PUBLIC`` or ``INTERFACE``, the :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` target property will be populated with the specified directories. @@ -43,12 +45,22 @@ 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. +Specified include directories may be absolute paths or relative paths. +A relative path will be interpreted as relative to the current source +directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`) and converted to an +absolute path before storing it in the associated target property. +If the path starts with a generator expression, it will always be assumed +to be an absolute path (with one exception noted below) and will be used +unmodified. + Include directories usage requirements commonly differ between the build-tree -and the install-tree. The ``BUILD_INTERFACE`` and ``INSTALL_INTERFACE`` -generator expressions can be used to describe separate usage requirements -based on the usage location. Relative paths are allowed within the -``INSTALL_INTERFACE`` expression and are interpreted relative to the -installation prefix. For example: +and the install-tree. The :genex:`BUILD_INTERFACE` and +:genex:`INSTALL_INTERFACE` generator expressions can be used to describe +separate usage requirements based on the usage location. Relative paths +are allowed within the :genex:`INSTALL_INTERFACE` expression and are +interpreted as relative to the installation prefix. Relative paths should not +be used in :genex:`BUILD_INTERFACE` expressions because they will not be +converted to absolute. For example: .. code-block:: cmake diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index 872e264..c85094a 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -289,6 +289,91 @@ treated as :ref:`Interface Libraries`, but when they appear in a target's :prop_tgt:`LINK_LIBRARIES` property their object files will be included in the link too. +.. _`Linking Object Libraries via $<TARGET_OBJECTS>`: + +Linking Object Libraries via $<TARGET_OBJECTS> +"""""""""""""""""""""""""""""""""""""""""""""" + +.. versionadded:: 3.21 + +The object files associated with an object library may be referenced +by the :genex:`$<TARGET_OBJECTS>` generator expression. Such object +files are placed on the link line *before* all libraries, regardless +of their relative order. Additionally, an ordering dependency will be +added to the build system to make sure the object library is up-to-date +before the dependent target links. For example, the code + +.. code-block:: cmake + + add_library(obj3 OBJECT obj3.c) + target_compile_definitions(obj3 PUBLIC OBJ3) + + add_executable(main3 main3.c) + target_link_libraries(main3 PRIVATE a3 $<TARGET_OBJECTS:obj3> b3) + +links executable ``main3`` with object files from ``main3.c`` +and ``obj3.c`` followed by the ``a3`` and ``b3`` libraries. +``main3.c`` is *not* compiled with usage requirements from ``obj3``, +such as ``-DOBJ3``. + +This approach can be used to achieve transitive inclusion of object +files in link lines as usage requirements. Continuing the above +example, the code + +.. code-block:: cmake + + add_library(iface_obj3 INTERFACE) + target_link_libraries(iface_obj3 INTERFACE obj3 $<TARGET_OBJECTS:obj3>) + +creates an interface library ``iface_obj3`` that forwards the ``obj3`` +usage requirements and adds the ``obj3`` object files to dependents' +link lines. The code + +.. code-block:: cmake + + add_executable(use_obj3 use_obj3.c) + target_link_libraries(use_obj3 PRIVATE iface_obj3) + +compiles ``use_obj3.c`` with ``-DOBJ3`` and links executable ``use_obj3`` +with object files from ``use_obj3.c`` and ``obj3.c``. + +This also works transitively through a static library. Since a static +library does not link, it does not consume the object files from +object libraries referenced this way. Instead, the object files +become transitive link dependencies of the static library. +Continuing the above example, the code + +.. code-block:: cmake + + add_library(static3 STATIC static3.c) + target_link_libraries(static3 PRIVATE iface_obj3) + + add_executable(use_static3 use_static3.c) + target_link_libraries(use_static3 PRIVATE static3) + +compiles ``static3.c`` with ``-DOBJ3`` and creates ``libstatic3.a`` +using only its own object file. ``use_static3.c`` is compiled *without* +``-DOBJ3`` because the usage requirement is not transitive through +the private dependency of ``static3``. However, the link dependencies +of ``static3`` are propagated, including the ``iface_obj3`` reference +to ``$<TARGET_OBJECTS:obj3>``. The ``use_static3`` executable is +created with object files from ``use_static3.c`` and ``obj3.c``, and +linked to library ``libstatic3.a``. + +When using this approach, it is the project's responsibility to avoid +linking multiple dependent binaries to ``iface_obj3``, because they will +all get the ``obj3`` object files on their link lines. + +.. note:: + + Referencing :genex:`$<TARGET_OBJECTS>` in ``target_link_libraries`` + calls worked in versions of CMake prior to 3.21 for some cases, + but was not fully supported: + + * It did not place the object files before libraries on link lines. + * It did not add an ordering dependency on the object library. + * It did not work in Xcode with multiple architectures. + Cyclic Dependencies of Static Libraries ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst index 520614a..1ad6c37 100644 --- a/Help/command/target_sources.rst +++ b/Help/command/target_sources.rst @@ -15,34 +15,143 @@ Specifies sources to use when building a target and/or its dependents. The named ``<target>`` must have been created by a command such as :command:`add_executable` or :command:`add_library` or :command:`add_custom_target` and must not be an -:ref:`ALIAS target <Alias Targets>`. - -.. versionchanged:: 3.13 - Relative source file paths are interpreted as being relative to the current - source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`). - See policy :policy:`CMP0076`. +:ref:`ALIAS target <Alias Targets>`. The ``<items>`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. .. versionadded:: 3.20 ``<target>`` can be a custom target. The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to -specify the scope of the items following them. ``PRIVATE`` and ``PUBLIC`` -items will populate the :prop_tgt:`SOURCES` property of -``<target>``, which are used when building the target itself. +specify the scope of the source file paths (``<items>``) that follow +them. ``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`SOURCES` +property of ``<target>``, which are used when building the target itself. ``PUBLIC`` and ``INTERFACE`` items will populate the :prop_tgt:`INTERFACE_SOURCES` property of ``<target>``, which are used -when building dependents. -The following arguments specify sources. Repeated calls for the same -``<target>`` append items in the order called. The targets created by -:command:`add_custom_target` can only have ``PRIVATE`` scope. +when building dependents. A target created by :command:`add_custom_target` +can only have ``PRIVATE`` scope. + +Repeated calls for the same ``<target>`` append items in the order called. .. versionadded:: 3.3 Allow exporting targets with :prop_tgt:`INTERFACE_SOURCES`. .. versionadded:: 3.11 - Allow setting ``INTERFACE`` items on :ref:`IMPORTED targets <Imported Targets>`. + Allow setting ``INTERFACE`` items on + :ref:`IMPORTED targets <Imported Targets>`. + +.. versionchanged:: 3.13 + Relative source file paths are interpreted as being relative to the current + source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`). + See policy :policy:`CMP0076`. + +A path that begins with a generator expression is left unmodified. +When a target's :prop_tgt:`SOURCE_DIR` property differs from +:variable:`CMAKE_CURRENT_SOURCE_DIR`, use absolute paths in generator +expressions to ensure the sources are correctly assigned to the target. + +.. code-block:: cmake + + # WRONG: starts with generator expression, but relative path used + target_sources(MyTarget "$<$<CONFIG:Debug>:dbgsrc.cpp>") + + # CORRECT: absolute path used inside the generator expression + target_sources(MyTarget "$<$<CONFIG:Debug>:${CMAKE_CURRENT_SOURCE_DIR}/dbgsrc.cpp>") + +See the :manual:`cmake-buildsystem(7)` manual for more on defining +buildsystem properties. + +File Sets +^^^^^^^^^ + +.. versionadded:: 3.23 + +.. code-block:: cmake + + target_sources(<target> + [<INTERFACE|PUBLIC|PRIVATE> + [FILE_SET <set> [TYPE <type>] [BASE_DIRS <dirs>...] [FILES <files>...]]... + ]...) + +Adds a file set to a target, or adds files to an existing file set. Targets +have zero or more named file sets. Each file set has a name, a type, a scope of +``INTERFACE``, ``PUBLIC``, or ``PRIVATE``, one or more base directories, and +files within those directories. The only acceptable type is ``HEADERS``. The +optional default file sets are named after their type. The target may not be a +custom target or :prop_tgt:`FRAMEWORK` target. + +Files in a ``PRIVATE`` or ``PUBLIC`` file set are marked as source files for +the purposes of IDE integration. Additionally, files in ``HEADERS`` file sets +have their :prop_sf:`HEADER_FILE_ONLY` property set to ``TRUE``. Files in an +``INTERFACE`` or ``PUBLIC`` file set can be installed with the +:command:`install(TARGETS)` command, and exported with the +:command:`install(EXPORT)` and :command:`export` commands. + +Each ``target_sources(FILE_SET)`` entry starts with ``INTERFACE``, ``PUBLIC``, or +``PRIVATE`` and accepts the following arguments: + +``FILE_SET <set>`` + + The name of the file set to create or add to. It must contain only letters, + numbers and underscores. Names starting with a capital letter are reserved + for built-in file sets predefined by CMake. The only predefined set name is + ``HEADERS``. All other set names must not start with a capital letter or + underscore. + +``TYPE <type>`` + + Every file set is associated with a particular type of file. ``HEADERS`` + is currently the only defined type and it is an error to specify anything + else. As a special case, if the name of the file set is ``HEADERS``, the + type does not need to be specified and the ``TYPE <type>`` arguments can be + omitted. For all other file set names, ``TYPE`` is required. + +``BASE_DIRS <dirs>...`` + + An optional list of base directories of the file set. Any relative path + is treated as relative to the current source directory + (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`). If no ``BASE_DIRS`` are + specified when the file set is first created, the value of + :variable:`CMAKE_CURRENT_SOURCE_DIR` is added. This argument supports + :manual:`generator expressions <cmake-generator-expressions(7)>`. + + No two base directories for a file set may be sub-directories of each other. + This requirement must be met across all base directories added to a file set, + not just those within a single call to ``target_sources()``. + +``FILES <files>...`` + + An optional list of files to add to the file set. Each file must be in + one of the base directories, or a subdirectory of one of the base + directories. This argument supports + :manual:`generator expressions <cmake-generator-expressions(7)>`. + + If relative paths are specified, they are considered relative to + :variable:`CMAKE_CURRENT_SOURCE_DIR` at the time ``target_sources()`` is + called. An exception to this is a path starting with ``$<``. Such paths + are treated as relative to the target's source directory after evaluation + of generator expressions. + +The following target properties are set by ``target_sources(FILE_SET)``, +but they should not generally be manipulated directly: + +* :prop_tgt:`HEADER_SETS` +* :prop_tgt:`INTERFACE_HEADER_SETS` +* :prop_tgt:`HEADER_SET` +* :prop_tgt:`HEADER_SET_<NAME>` +* :prop_tgt:`HEADER_DIRS` +* :prop_tgt:`HEADER_DIRS_<NAME>` + +Target properties related to include directories are also modified by +``target_sources(FILE_SET)`` as follows: + +:prop_tgt:`INCLUDE_DIRECTORIES` + + If the ``TYPE`` is ``HEADERS``, and the scope of the file set is ``PRIVATE`` + or ``PUBLIC``, all of the ``BASE_DIRS`` of the file set are wrapped in + :genex:`$<BUILD_INTERFACE>` and appended to this property. + +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` -Arguments to ``target_sources`` may use "generator expressions" -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. + If the ``TYPE`` is ``HEADERS``, and the scope of the file set is + ``INTERFACE`` or ``PUBLIC``, all of the ``BASE_DIRS`` of the file set are + wrapped in :genex:`$<BUILD_INTERFACE>` and appended to this property. diff --git a/Help/cpack_gen/archive.rst b/Help/cpack_gen/archive.rst index b941812..47e8e13 100644 --- a/Help/cpack_gen/archive.rst +++ b/Help/cpack_gen/archive.rst @@ -82,7 +82,8 @@ CPack generators which are essentially archives at their core. These include: See also the :variable:`CPACK_THREADS` variable. -.. note:: + .. versionadded:: 3.21 - Official CMake binaries available on ``cmake.org`` ship with a ``liblzma`` - that does not support parallel compression. + Official CMake binaries available on ``cmake.org`` now ship + with a ``liblzma`` that supports parallel compression. + Older versions did not. diff --git a/Help/cpack_gen/deb.rst b/Help/cpack_gen/deb.rst index 03c4ea8..f96ca32 100644 --- a/Help/cpack_gen/deb.rst +++ b/Help/cpack_gen/deb.rst @@ -274,10 +274,23 @@ List of CPack DEB generator specific variables: Possible values are: - - lzma - - xz - - bzip2 - - gzip + ``lzma`` + Lempel–Ziv–Markov chain algorithm + + ``xz`` + XZ Utils compression + + ``bzip2`` + bzip2 Burrows–Wheeler algorithm + + ``gzip`` + GNU Gzip compression + + ``zstd`` + .. versionadded:: 3.22 + + Zstandard compression + .. variable:: CPACK_DEBIAN_PACKAGE_PRIORITY CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY @@ -289,7 +302,7 @@ List of CPack DEB generator specific variables: * Default : "optional" .. versionadded:: 3.5 - Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY`` varables. + Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY`` variables. See https://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities @@ -652,9 +665,18 @@ Dbgsym packaging has its own set of variables: .. note:: + Setting this also strips the ELF files in the generated non-dbgsym package, + which results in debuginfo only being available in the dbgsym package. + +.. note:: + Binaries must contain debug symbols before packaging so use either ``Debug`` or ``RelWithDebInfo`` for :variable:`CMAKE_BUILD_TYPE` variable value. + Additionally, if :variable:`CPACK_STRIP_FILES` is set, the files will be stripped before + they get to the DEB generator, so will not contain debug symbols and + a dbgsym package will not get built. Do not use with :variable:`CPACK_STRIP_FILES`. + Building Debian packages on Windows ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/cpack_gen/dmg.rst b/Help/cpack_gen/dmg.rst index 4c662a6..b4ef5a2 100644 --- a/Help/cpack_gen/dmg.rst +++ b/Help/cpack_gen/dmg.rst @@ -51,9 +51,30 @@ on macOS: .. versionadded:: 3.6 - Default behaviour is to include a symlink to ``/Applications`` in the DMG. + Default behavior is to include a symlink to ``/Applications`` in the DMG. Set this option to ``ON`` to avoid adding the symlink. +.. variable:: CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE + + .. versionadded:: 3.23 + + Control whether :variable:`CPACK_RESOURCE_FILE_LICENSE`, if set to a + non-default value, is used as the license agreement provided when + mounting the DMG. If ``CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE`` is + not set, :manual:`cpack(1)` defaults to off. + + In a CMake project that uses the :module:`CPack` module to generate + ``CPackConfig.cmake``, ``CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE`` + is automatically enabled by default if it is not set and + :variable:`CPACK_RESOURCE_FILE_LICENSE` is set to a non-default value. + + .. note:: + + This option was added in response to macOS 12.0's deprecation of + the ``hdiutil udifrez`` command to make its use optional. + CPack 3.22 and below always use :variable:`CPACK_RESOURCE_FILE_LICENSE`, + if set to a non-default value, as the DMG license. + .. variable:: CPACK_DMG_SLA_DIR .. versionadded:: 3.5 @@ -103,6 +124,14 @@ on macOS: - Default: ``CPACK_PACKAGE_FILE_NAME-<component>`` +.. variable:: CPACK_DMG_FILESYSTEM + + .. versionadded:: 3.21 + + The filesystem format. Common values are ``APFS`` and ``HFS+``. + See ``man hdiutil`` for a full list of supported formats. + Defaults to ``HFS+``. + .. variable:: CPACK_COMMAND_HDIUTIL Path to the ``hdiutil(1)`` command used to operate on disk image files on diff --git a/Help/cpack_gen/freebsd.rst b/Help/cpack_gen/freebsd.rst index 2c93569..f429bc5 100644 --- a/Help/cpack_gen/freebsd.rst +++ b/Help/cpack_gen/freebsd.rst @@ -74,7 +74,7 @@ the RPM information (e.g. package license). * Default: - :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION` (this may be set already - for Debian packaging, so we may as well re-use it). + for Debian packaging, so it is used as a fallback). .. variable:: CPACK_FREEBSD_PACKAGE_WWW @@ -87,7 +87,7 @@ the RPM information (e.g. package license). - :variable:`CMAKE_PROJECT_HOMEPAGE_URL`, or if that is not set, :variable:`CPACK_DEBIAN_PACKAGE_HOMEPAGE` (this may be set already - for Debian packaging, so we may as well re-use it). + for Debian packaging, so it is used as a fallback). .. versionadded:: 3.12 The ``CMAKE_PROJECT_HOMEPAGE_URL`` variable. diff --git a/Help/cpack_gen/ifw.rst b/Help/cpack_gen/ifw.rst index 6817eac..c23bab4 100644 --- a/Help/cpack_gen/ifw.rst +++ b/Help/cpack_gen/ifw.rst @@ -24,12 +24,12 @@ Microsoft Windows, and macOS. 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. +control the behavior of this generator. See `Hints for Finding QtIFW`_. Variables ^^^^^^^^^ -You can use the following variables to change behavior of CPack ``IFW`` +You can use the following variables to change the behavior of the CPack ``IFW`` generator. Debug @@ -48,12 +48,12 @@ Package .. variable:: CPACK_IFW_PACKAGE_TITLE Name of the installer as displayed on the title bar. - By default used :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`. + If not specified, it defaults to :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`. .. variable:: CPACK_IFW_PACKAGE_PUBLISHER Publisher of the software (as shown in the Windows Control Panel). - By default used :variable:`CPACK_PACKAGE_VENDOR`. + If not specified, it defaults to :variable:`CPACK_PACKAGE_VENDOR`. .. variable:: CPACK_IFW_PRODUCT_URL @@ -61,83 +61,93 @@ Package .. variable:: CPACK_IFW_PACKAGE_ICON - Filename for a custom installer icon. The actual file is '.icns' (macOS), - '.ico' (Windows). No functionality on Unix. + Filename for a custom installer icon. It must be an absolute path. + This should be a ``.icns`` file on macOS and a ``.ico`` file on Windows. + It is ignored on other platforms. .. variable:: CPACK_IFW_PACKAGE_WINDOW_ICON Filename for a custom window icon in PNG format for the Installer - application. + application. It must be an absolute path. .. variable:: CPACK_IFW_PACKAGE_LOGO - Filename for a logo is used as QWizard::LogoPixmap. + Filename for a logo image in PNG format, used as ``QWizard::LogoPixmap``. + It must be an absolute path. .. variable:: CPACK_IFW_PACKAGE_WATERMARK .. versionadded:: 3.8 - Filename for a watermark is used as QWizard::WatermarkPixmap. + Filename for a watermark image in PNG format, used as + ``QWizard::WatermarkPixmap``. It must be an absolute path. .. variable:: CPACK_IFW_PACKAGE_BANNER .. versionadded:: 3.8 - Filename for a banner is used as QWizard::BannerPixmap. + Filename for a banner image in PNG format, used as ``QWizard::BannerPixmap``. + It must be an absolute path. .. variable:: CPACK_IFW_PACKAGE_BACKGROUND .. versionadded:: 3.8 - Filename for an image used as QWizard::BackgroundPixmap (only used by MacStyle). + Filename for a background image in PNG format, used as + ``QWizard::BackgroundPixmap`` (only used by ``MacStyle``). It must be an + absolute path. .. variable:: CPACK_IFW_PACKAGE_WIZARD_STYLE .. versionadded:: 3.8 - Wizard style to be used ("Modern", "Mac", "Aero" or "Classic"). + Wizard style to be used (``Modern``, ``Mac``, ``Aero`` or ``Classic``). .. variable:: CPACK_IFW_PACKAGE_WIZARD_DEFAULT_WIDTH .. versionadded:: 3.8 - Default width of the wizard in pixels. Setting a banner image will override this. + Default width of the wizard in pixels. Setting a banner image will override + this. .. variable:: CPACK_IFW_PACKAGE_WIZARD_DEFAULT_HEIGHT .. versionadded:: 3.8 - Default height of the wizard in pixels. Setting a watermark image will override this. + Default height of the wizard in pixels. Setting a watermark image will + override this. .. variable:: CPACK_IFW_PACKAGE_WIZARD_SHOW_PAGE_LIST .. versionadded:: 3.20 - Set to ``OFF`` if the widget listing installer pages on the left side of the wizard should not be shown. + Set to ``OFF`` if the widget listing installer pages on the left side of the + wizard should not be shown. - It is ``ON`` by default, but will only have an effect if using QtIFW 4.0 or later. + It is ``ON`` by default, but will only have an effect if using QtIFW 4.0 or + later. .. variable:: CPACK_IFW_PACKAGE_TITLE_COLOR .. versionadded:: 3.8 - Color of the titles and subtitles (takes an HTML color code, such as "#88FF33"). + Color of the titles and subtitles (takes an HTML color code, such as + ``#88FF33``). .. variable:: CPACK_IFW_PACKAGE_STYLE_SHEET .. versionadded:: 3.15 - Filename for a stylesheet. + Filename for a stylesheet. It must be an absolute path. .. variable:: CPACK_IFW_TARGET_DIRECTORY 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. + If :variable:`CPACK_PACKAGE_INSTALL_DIRECTORY` is set, this defaults to + ``@ApplicationsDir@/${CPACK_PACKAGE_INSTALL_DIRECTORY}``. If that variable + isn't set either, the default used is ``@RootDir@/usr/local``. + Predefined variables of the form ``@...@`` are expanded by the + `QtIFW scripting engine <https://doc.qt.io/qtinstallerframework/scripting.html>`_. .. variable:: CPACK_IFW_ADMIN_TARGET_DIRECTORY @@ -155,29 +165,28 @@ Package .. variable:: CPACK_IFW_PACKAGE_GROUP - The group, which will be used to configure the root package + The group, which will be used to configure the root package. .. variable:: CPACK_IFW_PACKAGE_NAME - The root package name, which will be used if configuration group is not - specified + The root package name, which will be used if the configuration group is not + specified. .. variable:: CPACK_IFW_PACKAGE_START_MENU_DIRECTORY .. versionadded:: 3.3 Name of the default program group for the product in the Windows Start menu. - - By default used :variable:`CPACK_IFW_PACKAGE_NAME`. + If not specified, it defaults to :variable:`CPACK_IFW_PACKAGE_NAME`. .. variable:: CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_NAME .. versionadded:: 3.3 Filename of the generated maintenance tool. - The platform-specific executable file extension is appended. + The platform-specific executable file extension will be appended. - By default used QtIFW defaults (``maintenancetool``). + If not specified, QtIFW provides a default name (``maintenancetool``). .. variable:: CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_INI_FILE @@ -185,15 +194,15 @@ Package Filename for the configuration of the generated maintenance tool. - By default used QtIFW defaults (``maintenancetool.ini``). + If not specified, QtIFW uses a default file name (``maintenancetool.ini``). .. variable:: CPACK_IFW_PACKAGE_ALLOW_NON_ASCII_CHARACTERS .. versionadded:: 3.3 Set to ``ON`` if the installation path can contain non-ASCII characters. - - Is ``ON`` for QtIFW less 2.0 tools. + Only supported for QtIFW 2.0 and later. Older QtIFW versions will always + allow non-ASCII characters. .. variable:: CPACK_IFW_PACKAGE_ALLOW_SPACE_IN_PATH @@ -203,6 +212,14 @@ Package Is ``ON`` for QtIFW less 2.0 tools. +.. variable:: CPACK_IFW_PACKAGE_DISABLE_COMMAND_LINE_INTERFACE + + .. versionadded:: 3.23 + + Set to ``ON`` if command line interface features should be disabled. + It is ``OFF`` by default and will only have an effect if using QtIFW 4.0 or + later. + .. variable:: CPACK_IFW_PACKAGE_CONTROL_SCRIPT .. versionadded:: 3.3 @@ -213,10 +230,11 @@ Package .. versionadded:: 3.7 - List of additional resources ('.qrc' files) to include in the installer - binary. + List of additional resources (``.qrc`` files) to include in the installer + binary. They should be specified as absolute paths and no two resource files + can have the same file name. - You can use :command:`cpack_ifw_add_package_resources` command to resolve + You can use the :command:`cpack_ifw_add_package_resources` command to resolve relative paths. .. variable:: CPACK_IFW_PACKAGE_FILE_EXTENSION @@ -226,27 +244,117 @@ Package The target binary extension. On Linux, the name of the target binary is automatically extended with - '.run', if you do not specify the extension. + ``.run``, if you do not specify the extension. On Windows, the target is created as an application with the extension - '.exe', which is automatically added, if not supplied. + ``.exe``, which is automatically added, if not supplied. On Mac, the target is created as an DMG disk image with the extension - '.dmg', which is automatically added, if not supplied. + ``.dmg``, which is automatically added, if not supplied. .. variable:: CPACK_IFW_REPOSITORIES_ALL The list of remote repositories. The default value of this variable is computed by CPack and contains - all repositories added with command :command:`cpack_ifw_add_repository` - or updated with command :command:`cpack_ifw_update_repository`. + all repositories added with :command:`cpack_ifw_add_repository` + or updated with :command:`cpack_ifw_update_repository`. .. variable:: CPACK_IFW_DOWNLOAD_ALL - If this is ``ON`` all components will be downloaded. - By default is ``OFF`` or used value - from ``CPACK_DOWNLOAD_ALL`` if set + If this is ``ON``, all components will be downloaded. If not set, the + behavior is determined by whether :command:`cpack_configure_downloads` has + been called with the ``ALL`` option or not. + +.. variable:: CPACK_IFW_PACKAGE_PRODUCT_IMAGES + + .. versionadded:: 3.23 + + A list of images to be shown on the ``PerformInstallationPage``. These + must be absolute paths and the images must be in PNG format. + + This feature is available for QtIFW 4.0.0 and later. + +.. variable:: CPACK_IFW_PACKAGE_RUN_PROGRAM + + .. versionadded:: 3.23 + + Command executed after the installer is finished, if the user accepts the + action. Provide the full path to the application, as found when installed. + This typically means the path should begin with the QtIFW predefined variable + ``@TargetDir@``. + + This feature is available for QtIFW 4.0.0 and later. + +.. variable:: CPACK_IFW_PACKAGE_RUN_PROGRAM_ARGUMENTS + + .. versionadded:: 3.23 + + List of arguments passed to the program specified in + :variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM`. + + This feature is available for QtIFW 4.0.0 and later. + +.. variable:: CPACK_IFW_PACKAGE_RUN_PROGRAM_DESCRIPTION + + .. versionadded:: 3.23 + + Text shown next to the check box for running the program after the + installation. If :variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM` is set but no + description is provided, QtIFW will use a default message like + ``Run <Name> now``. + + This feature is available for QtIFW 4.0.0 and later. + +.. variable:: CPACK_IFW_PACKAGE_SIGNING_IDENTITY + + .. versionadded:: 3.23 + + Allows specifying a code signing identity to be used for signing the generated + app bundle. Only available on macOS, ignored on other platforms. + +.. variable:: CPACK_IFW_ARCHIVE_FORMAT + + .. versionadded:: 3.23 + + Set the format used when packaging new component data archives. If you omit + this option, the ``7z`` format will be used as a default. Supported formats: + + * 7z + * zip + * tar.gz + * tar.bz2 + * tar.xz + + .. note:: + + If the Qt Installer Framework tools were built without libarchive support, + only ``7z`` format is supported. + + This feature is available for QtIFW 4.2.0 and later. + +.. variable:: CPACK_IFW_ARCHIVE_COMPRESSION + + .. versionadded:: 3.23 + + Archive compression level. The allowable values are: + + * 0 (*No compression*) + * 1 (*Fastest compression*) + * 3 (*Fast compression*) + * 5 (*Normal compression*) + * 7 (*Maximum compression*) + * 9 (*Ultra compression*) + + If this variable is not set, QtIFW will use a default compression level, + which will typically be 5 (*Normal compression*). + + .. note:: + + Some formats do not support all the possible values. For example ``zip`` + compression only supports values from 1 to 7. + + This feature is available for QtIFW 4.2.0 and later. Components """""""""" @@ -257,16 +365,17 @@ Components .. variable:: CPACK_IFW_PACKAGES_DIRECTORIES - Additional prepared packages dirs that will be used to resolve + Additional prepared packages directories that will be used to resolve dependent components. .. variable:: CPACK_IFW_REPOSITORIES_DIRECTORIES .. versionadded:: 3.10 - Additional prepared repository dirs that will be used to resolve and - repack dependent components. This feature available only - since QtIFW 3.1. + Additional prepared repository directories that will be used to resolve and + repack dependent components. + + This feature is available for QtIFW 3.1 and later. QtIFW Tools """"""""""" @@ -275,10 +384,11 @@ QtIFW Tools .. versionadded:: 3.3 - The version of used QtIFW tools. + The version of the QtIFW tools that will be used. This variable is set + by the :module:`CPackIFW` module. The following variables provide the locations of the QtIFW -command-line tools as discovered by the module :module:`CPackIFW`. +command-line tools as discovered by the :module:`CPackIFW` module. These variables are cached, and may be configured if needed. .. variable:: CPACK_IFW_ARCHIVEGEN_EXECUTABLE @@ -306,30 +416,33 @@ These variables are cached, and may be configured if needed. 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: +Generally, the CPack ``IFW`` generator automatically finds QtIFW tools. +The following (in order of precedence) can also be set to augment the +locations normally searched by :command:`find_program`: .. variable:: CPACK_IFW_ROOT - .. versionadded:: 3.9 + .. versionadded:: 3.9 + + CMake variable + +.. envvar:: CPACK_IFW_ROOT - An CMake variable which specifies the location of the QtIFW tool suite. + .. versionadded:: 3.9 - The variable will be cached in the ``CPackConfig.cmake`` file and used at - CPack runtime. + Environment variable .. variable:: QTIFWDIR - An environment variable which specifies the location of the QtIFW tool - suite. + CMake variable -.. note:: - The specified path should not contain "bin" at the end - (for example: "D:\\DevTools\\QtIFW2.0.5"). +.. envvar:: QTIFWDIR + + Environment variable -The :variable:`CPACK_IFW_ROOT` variable has a higher priority and overrides -the value of the :variable:`QTIFWDIR` variable. +.. note:: + The specified path should not contain ``bin`` at the end + (for example: ``D:\\DevTools\\QtIFW2.0.5``). Other Settings ^^^^^^^^^^^^^^ @@ -337,7 +450,7 @@ Other Settings Online installer """""""""""""""" -By default, this generator generates an *offline installer*. This means that +By default, this generator generates an *offline installer*. This means that all packaged files are fully contained in the installer executable. In contrast, an *online installer* will download some or all components from @@ -367,14 +480,13 @@ 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. +but this does not apply to the description of your components and groups. 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. +A localized variable or argument can contain a single default value, and +after that a set of pairs with the name of the locale and the localized value. For example: @@ -392,16 +504,16 @@ See Also Qt Installer Framework Manual: * Index page: - http://doc.qt.io/qtinstallerframework/index.html + https://doc.qt.io/qtinstallerframework/index.html * Component Scripting: - http://doc.qt.io/qtinstallerframework/scripting.html + https://doc.qt.io/qtinstallerframework/scripting.html * Predefined Variables: - http://doc.qt.io/qtinstallerframework/scripting.html#predefined-variables + https://doc.qt.io/qtinstallerframework/scripting.html#predefined-variables * Promoting Updates: - http://doc.qt.io/qtinstallerframework/ifw-updates.html + https://doc.qt.io/qtinstallerframework/ifw-updates.html Download Qt Installer Framework for your platform from Qt site: - http://download.qt.io/official_releases/qt-installer-framework + https://download.qt.io/official_releases/qt-installer-framework diff --git a/Help/cpack_gen/nsis.rst b/Help/cpack_gen/nsis.rst index de1f3b5..299cfec 100644 --- a/Help/cpack_gen/nsis.rst +++ b/Help/cpack_gen/nsis.rst @@ -3,8 +3,8 @@ CPack NSIS Generator CPack Nullsoft Scriptable Install System (NSIS) generator specific options. -.. versionchanged:: 3.17 - The NSIS generator requires NSIS 3.0 or newer. +.. versionchanged:: 3.22 + The NSIS generator requires NSIS 3.03 or newer. Variables specific to CPack NSIS generator ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -195,3 +195,15 @@ on Windows Nullsoft Scriptable Install System. If set, trim down the size of the control to the size of the branding text string. Allowed values for this variable are ``LEFT``, ``CENTER`` or ``RIGHT``. If not specified, the default behavior is ``LEFT``. + +.. variable:: CPACK_NSIS_EXECUTABLE + + .. versionadded:: 3.21 + + If set, specify the name of the NSIS executable. Default is ``makensis``. + +.. variable:: CPACK_NSIS_IGNORE_LICENSE_PAGE + + .. versionadded:: 3.22 + + If set, do not display the page containing the license during installation. diff --git a/Help/cpack_gen/productbuild.rst b/Help/cpack_gen/productbuild.rst index cf3041f..48a9b44 100644 --- a/Help/cpack_gen/productbuild.rst +++ b/Help/cpack_gen/productbuild.rst @@ -18,6 +18,14 @@ macOS using ProductBuild: the automatically detected command (or specify its location if the auto-detection fails to find it). +.. variable:: CPACK_PRODUCTBUILD_IDENTIFIER + + .. versionadded:: 3.23 + + Set the unique (non-localized) product identifier to be associated with the + product (i.e., ``com.kitware.cmake``). Any component product names will be + appended to this value. + .. variable:: CPACK_PRODUCTBUILD_IDENTITY_NAME .. versionadded:: 3.8 @@ -78,6 +86,65 @@ macOS using ProductBuild: :variable:`CPACK_RESOURCE_FILE_README`, and :variable:`CPACK_RESOURCE_FILE_LICENSE` files are copied. +.. variable:: CPACK_PRODUCTBUILD_DOMAINS + + .. versionadded:: 3.23 + + This option enables more granular control over where the product may be + installed. When it is set to true, a ``domains`` element of the following + form will be added to the productbuild Distribution XML: + + .. code-block:: xml + + <domains enable_anywhere="true" enable_currentUserHome="false" enable_localSystem="true"/> + + The default values are as shown above, but can be overridden with + :variable:`CPACK_PRODUCTBUILD_DOMAINS_ANYWHERE`, + :variable:`CPACK_PRODUCTBUILD_DOMAINS_USER`, and + :variable:`CPACK_PRODUCTBUILD_DOMAINS_ROOT`. + +.. variable:: CPACK_PRODUCTBUILD_DOMAINS_ANYWHERE + + .. versionadded:: 3.23 + + May be used to override the ``enable_anywhere`` attribute in the ``domains`` + element of the Distribution XML. When set to true, the product can be + installed at the root of any volume, including non-system volumes. + + :variable:`CPACK_PRODUCTBUILD_DOMAINS` must be set to true for this variable + to have any effect. + +.. variable:: CPACK_PRODUCTBUILD_DOMAINS_USER + + .. versionadded:: 3.23 + + May be used to override the ``enable_currentUserHome`` attribute in the + ``domains`` element of the Distribution XML. When set to true, the product + can be installed into the current user's home directory. Note that when + installing into the user's home directory, the following additional + requirements will apply: + + * The installer may not write outside the user's home directory. + * The install will be performed as the current user rather than as ``root``. + This may have ramifications for :variable:`CPACK_PREFLIGHT_<COMP>_SCRIPT` + and :variable:`CPACK_POSTFLIGHT_<COMP>_SCRIPT`. + * Administrative privileges will not be needed to perform the install. + + :variable:`CPACK_PRODUCTBUILD_DOMAINS` must be set to true for this variable + to have any effect. + +.. variable:: CPACK_PRODUCTBUILD_DOMAINS_ROOT + + .. versionadded:: 3.23 + + May be used to override the ``enable_localSystem`` attribute in the + ``domains`` element of the Distribution XML. When set to true, the product + can be installed in the root directory. This should normally be set to true + unless the product should only be installed to the user's home directory. + + :variable:`CPACK_PRODUCTBUILD_DOMAINS` must be set to true for this variable + to have any effect. + Background Image """""""""""""""" @@ -136,3 +203,47 @@ installer. Does the same as :variable:`CPACK_PRODUCTBUILD_BACKGROUND_UTI` option, but for the dark theme. + +Distribution XML Template +^^^^^^^^^^^^^^^^^^^^^^^^^ + +CPack uses a template file to generate the ``distribution.dist`` file used +internally by this package generator. Ordinarily, CMake provides the template +file, but projects may supply their own by placing a file called +``CPack.distribution.dist.in`` in one of the directories listed in the +:variable:`CMAKE_MODULE_PATH` variable. CPack will then pick up the project's +template file instead of using its own. + +The ``distribution.dist`` file is generated by performing substitutions +similar to the :command:`configure_file` command. Any variable set when +CPack runs will be available for substitution using the usual ``@...@`` +form. The following variables are also set internally and made available for +substitution: + +``CPACK_RESOURCE_FILE_LICENSE_NOPATH`` + Same as :variable:`CPACK_RESOURCE_FILE_LICENSE` except without the path. + The named file will be available in the same directory as the generated + ``distribution.dist`` file. + +``CPACK_RESOURCE_FILE_README_NOPATH`` + Same as :variable:`CPACK_RESOURCE_FILE_README` except without the path. + The named file will be available in the same directory as the generated + ``distribution.dist`` file. + +``CPACK_RESOURCE_FILE_WELCOME_NOPATH`` + Same as :variable:`CPACK_RESOURCE_FILE_WELCOME` except without the path. + The named file will be available in the same directory as the generated + ``distribution.dist`` file. + +``CPACK_APPLE_PKG_INSTALLER_CONTENT`` + .. versionadded:: 3.23 + + This contains all the XML elements that specify installer-wide options + (including domain details), default backgrounds and the choices outline. + +``CPACK_PACKAGEMAKER_CHOICES`` + .. deprecated:: 3.23 + + This contains only the XML elements that specify the default backgrounds + and the choices outline. It does not include the installer-wide options or + any domain details. Use ``CPACK_APPLE_PKG_INSTALLER_CONTENT`` instead. diff --git a/Help/cpack_gen/rpm.rst b/Help/cpack_gen/rpm.rst index 5260a1d..0d287fc 100644 --- a/Help/cpack_gen/rpm.rst +++ b/Help/cpack_gen/rpm.rst @@ -394,8 +394,10 @@ List of CPack RPM generator specific variables: * Mandatory : NO * Default : - - May be used to set weak RPM dependencies (suggests). Note that you must - enclose the complete requires string between quotes. + May be used to set weak RPM dependencies (suggests). If ``rpmbuild`` doesn't + support the ``Suggests`` tag, CPack will emit a warning and ignore this + variable. Note that you must enclose the complete requires string between + quotes. .. variable:: CPACK_RPM_PACKAGE_PROVIDES CPACK_RPM_<component>_PACKAGE_PROVIDES @@ -838,6 +840,10 @@ Debuginfo RPM packaging has its own set of variables: Binaries must contain debug symbols before packaging so use either ``Debug`` or ``RelWithDebInfo`` for :variable:`CMAKE_BUILD_TYPE` variable value. + Additionally, if :variable:`CPACK_STRIP_FILES` is set, the files will be stripped before + they get to the RPM generator, so will not contain debug symbols and + a debuginfo package will not get built. Do not use with :variable:`CPACK_STRIP_FILES`. + .. note:: Packages generated from packages without binary files, with binary files but @@ -1021,7 +1027,7 @@ Source RPM packaging has its own set of variables: * Mandatory : YES * Default : "/" -.. VARIABLE:: CPACK_RPM_BUILDREQUIRES +.. variable:: CPACK_RPM_BUILDREQUIRES List of source rpm build dependencies. @@ -1033,3 +1039,16 @@ Source RPM packaging has its own set of variables: example:: set(CPACK_RPM_BUILDREQUIRES "python >= 2.5.0, cmake >= 2.8") + +.. variable:: CPACK_RPM_REQUIRES_EXCLUDE_FROM + + .. versionadded:: 3.22 + + * Mandatory : NO + * Default : - + + May be used to keep the dependency generator from scanning specific files + or directories for dependencies. Note that you can use a regular + expression that matches all of the directories or files, for example:: + + set(CPACK_RPM_REQUIRES_EXCLUDE_FROM "bin/libqsqloci.*\\.so.*") diff --git a/Help/cpack_gen/wix.rst b/Help/cpack_gen/wix.rst index 79f835e..e9d5af6 100644 --- a/Help/cpack_gen/wix.rst +++ b/Help/cpack_gen/wix.rst @@ -320,3 +320,11 @@ Windows using WiX. name is the plain namespace without the usual xmlns: prefix and url is an unquoted namespace url. A list of commonly known WiX schemata can be found here: https://wixtoolset.org/documentation/manual/v3/xsd/ + +.. variable:: CPACK_WIX_SKIP_WIX_UI_EXTENSION + + .. versionadded:: 3.23 + + If this variable is set then the inclusion of WixUIExtensions is skipped, + i.e. the ``-ext "WixUIExtension"`` command line is not included during + the execution of the WiX light tool. diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst index 29fc880..db92022 100644 --- a/Help/dev/documentation.rst +++ b/Help/dev/documentation.rst @@ -92,6 +92,11 @@ literal block after ``::`` the referenced documents inline as part of the referencing document. +``versionadded``, ``versionchanged`` directives + Specify that something was added or changed by a named CMake version. + The command-line help processor prints the block content as if the lines + were normal paragraph text with interpretation. + Inline markup constructs not listed above are printed literally in the command-line help output. We prefer to use inline markup constructs that look correct in source form, so avoid use of \\-escapes in favor of inline @@ -508,7 +513,7 @@ bracket is excluded if and only if the line starts in ``#``. Additional such ``.rst:`` comments may appear anywhere in the module file. All such comments must start with ``#`` in the first column. -For example, a ``Findxxx.cmake`` module may contain: +For example, a ``FindXxx.cmake`` module may contain: :: @@ -535,13 +540,13 @@ For example, a ``Findxxx.cmake`` module may contain: <code> #[=======================================================================[.rst: - .. command:: xxx_do_something + .. command:: Xxx_do_something This command does something for Xxx:: - xxx_do_something(some arguments) + Xxx_do_something(some arguments) #]=======================================================================] - macro(xxx_do_something) + macro(Xxx_do_something) <code> endmacro() @@ -554,3 +559,56 @@ documentation, simply leave out the ``Help/module/<module-name>.rst`` file and the ``Help/manual/cmake-modules.7.rst`` toctree entry. .. _`Bracket Comment`: https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#bracket-comment + +Module Functions and Macros +--------------------------- + +Modules may provide CMake functions and macros defined by the `function()`_ +and `macro()`_ commands. To avoid conflicts across modules, name the +functions and macros using the prefix ``<ModuleName>_`` followed by the +rest of the name, where ``<ModuleName>`` is the exact-case spelling of +the module name. We have no convention for the portion of names after +the ``<ModuleName>_`` prefix. + +For historical reasons, some modules that come with CMake do not follow +this prefix convention. When adding new functions to these modules, +discussion during review can decide whether to follow their existing +convention or to use the module name prefix. + +Documentation of public functions and macros should be provided in +the module, typically in the main `module documentation`_ at the top. +For example, a ``MyModule`` module may document a function like this:: + + #[=======================================================================[.rst: + MyModule + -------- + + This is my module. It provides some functions. + + .. command:: MyModule_Some_Function + + This is some function: + + .. code-block:: cmake + + MyModule_Some_Function(...) + #]=======================================================================] + +Documentation may alternatively be placed just before each definition. +For example, a ``MyModule`` module may document another function like this:: + + #[=======================================================================[.rst: + .. command:: MyModule_Other_Function + + This is another function: + + .. code-block:: cmake + + MyModule_Other_Function(...) + #]=======================================================================] + function(MyModule_Other_Function ...) + # ... + endfunction() + +.. _`function()`: https://cmake.org/cmake/help/latest/command/function.html +.. _`macro()`: https://cmake.org/cmake/help/latest/command/macro.html diff --git a/Help/dev/experimental.rst b/Help/dev/experimental.rst index d019161..2380de4 100644 --- a/Help/dev/experimental.rst +++ b/Help/dev/experimental.rst @@ -39,7 +39,7 @@ to the file specified by the ``<DEP_FILE>`` placeholder, and write module dependencies to the file specified by the ``<DYNDEP_FILE>`` placeholder. The module dependencies should be written in the format described -by the `P1689r3`_ paper. +by the `P1689r4`_ paper. Compiler writers may try out their scanning functionality using the `cxx-modules-sandbox`_ test project, modified to set variables @@ -66,5 +66,5 @@ the GCC documentation, but the relevant section for the purposes of CMake is: -- GCC module mapper documentation .. _`D1483r1`: https://mathstuf.fedorapeople.org/fortran-modules/fortran-modules.html -.. _`P1689r3`: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2020/p1689r3.html +.. _`P1689r4`: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p1689r4.html .. _`cxx-modules-sandbox`: https://github.com/mathstuf/cxx-modules-sandbox diff --git a/Help/dev/maint.rst b/Help/dev/maint.rst index 664b7a4..53be91f 100644 --- a/Help/dev/maint.rst +++ b/Help/dev/maint.rst @@ -245,20 +245,6 @@ Commit with a message such as:: Release versions do not have the development topic section of the CMake Release Notes index page. -Update ``.gitlab-ci.yml`` to drop the ``upload:`` jobs from the -packaging pipeline by renaming them to start in ``.``: - -.. code-block:: shell - - sed -i 's/^upload:/.upload:/' .gitlab-ci.yml - -Commit with a message such as:: - - gitlab-ci: Drop package pipeline upload jobs for release branch - - The package pipeline for release versions should not upload packages - automatically to our archive of nightly development versions. - Update ``Source/CMakeVersion.cmake`` to set the version to ``$major.$minor.0-rc0``: @@ -270,8 +256,8 @@ Update ``Source/CMakeVersion.cmake`` to set the version to set(CMake_VERSION_PATCH 0) set(CMake_VERSION_RC 0) -Update uses of ``DEVEL_CMAKE_VERSION`` in the source tree to mention the -actual version number: +Replace uses of ``DEVEL_CMAKE_VERSION`` in the source tree with +the literal release version number string ``"$major.$minor.0"``: .. code-block:: shell @@ -290,15 +276,13 @@ Merge the ``release-$ver`` branch to ``master``: git merge --no-ff release-$ver Begin post-release development by restoring the development branch release -note infrastructure, the nightly package pipeline upload jobs, and -the version date from ``origin/master``: +note infrastructure, and the version date from ``origin/master``: .. code-block:: shell git checkout origin/master -- \ Source/CMakeVersion.cmake Help/release/dev/0-sample-topic.rst sed -i $'/^Releases/ i\\\n.. include:: dev.txt\\\n' Help/release/index.rst - sed -i 's/^\.upload:/upload:/' .gitlab-ci.yml Update ``Source/CMakeVersion.cmake`` to set the version to ``$major.$minor.$date``: diff --git a/Help/dev/review.rst b/Help/dev/review.rst index 8326e70..34796a1 100644 --- a/Help/dev/review.rst +++ b/Help/dev/review.rst @@ -20,8 +20,10 @@ creating a *merge request* ("MR"). The new MR will appear on the process is managed by the merge request page for the change. During the review process, the MR submitter should address review comments -or test failures by updating the MR with a (force-)push of the topic -branch. The update initiates a new round of review. +or test failures by updating their local topic branch to fix their commits +(e.g. via ``git commit --amend`` or ``git rebase -i``), and then issuing a +(force-)push of the topic branch to their remote (e.g. ``git push --force``). +This will automatically initiate a new round of review on the existing MR. We recommend that users enable the "Remove source branch when merge request is accepted" option when creating the MR or by editing it. @@ -254,7 +256,8 @@ The preferred form for references to other commits is The author date of the commit, in its original time zone, formatted as ``CCYY-MM-DD``. ``git-log(1)`` shows the original time zone by default. -This may be generated with +This may be generated with ``git show -s --pretty=reference <commit>`` with +Git 2.25 and newer. Older versions of Git can generate the same format via ``git show -s --date=short --pretty="format:%h (%s, %ad)" <commit>``. If the commit is a fix for the mentioned commit, consider using a ``Fixes:`` @@ -321,6 +324,19 @@ Heavier jobs require a manual trigger to run: * ``failed``: Restart jobs which have completed, but without success. * ``completed``: Restart all completed jobs. + +In order to keep job names shorter and keep as much information visible on the +GitLab web interface as possible, jobs have a short prefix which indicates +what its main purpose is: + + * ``b:`` jobs build CMake for the purposes of running the + test suite. + * ``l:`` jobs perform "linting" on the CMake source tree such as static + analysis. + * ``p:`` jobs perform preparatory tasks for use in other jobs. + * ``t:`` jobs perform testing of CMake. + * ``u:`` jobs upload other job results to permanent locations. + If the merge request topic branch is updated by a push, a new manual trigger using one of the above methods is needed to start CI again. diff --git a/Help/envvar/CMAKE_BUILD_TYPE.rst b/Help/envvar/CMAKE_BUILD_TYPE.rst new file mode 100644 index 0000000..f798aff --- /dev/null +++ b/Help/envvar/CMAKE_BUILD_TYPE.rst @@ -0,0 +1,10 @@ +CMAKE_BUILD_TYPE +---------------- + +.. versionadded:: 3.22 + +.. include:: ENV_VAR.txt + +The ``CMAKE_BUILD_TYPE`` environment variable specifies a default value +for the :variable:`CMAKE_BUILD_TYPE` variable when there is no explicit +configuration given on the first run while creating a new build tree. diff --git a/Help/envvar/CMAKE_CONFIGURATION_TYPES.rst b/Help/envvar/CMAKE_CONFIGURATION_TYPES.rst new file mode 100644 index 0000000..833aa4a --- /dev/null +++ b/Help/envvar/CMAKE_CONFIGURATION_TYPES.rst @@ -0,0 +1,11 @@ +CMAKE_CONFIGURATION_TYPES +------------------------- + +.. versionadded:: 3.22 + +.. include:: ENV_VAR.txt + +The ``CMAKE_CONFIGURATION_TYPES`` environment variable specifies a +default value for the :variable:`CMAKE_CONFIGURATION_TYPES` variable +when there is no explicit configuration given on the first run while +creating a new build tree. diff --git a/Help/envvar/CMAKE_INSTALL_MODE.rst b/Help/envvar/CMAKE_INSTALL_MODE.rst new file mode 100644 index 0000000..4549ea1 --- /dev/null +++ b/Help/envvar/CMAKE_INSTALL_MODE.rst @@ -0,0 +1,116 @@ +CMAKE_INSTALL_MODE +------------------ + +.. versionadded:: 3.22 + +.. include:: ENV_VAR.txt + +The ``CMAKE_INSTALL_MODE`` environment variable allows users to operate +CMake in an alternate mode of :command:`file(INSTALL)` and :command:`install()`. + +The default behavior for an installation is to copy a source file from a +source directory into a destination directory. This environment variable +however allows the user to override this behavior, causing CMake to create +symbolic links instead. + +Usage Scenarios +^^^^^^^^^^^^^^^ + +Installing symbolic links rather than copying files can help in the following +ways: + +* Conserving storage space because files do not have to be duplicated on disk. +* Changes to the source of the symbolic link are seen at the install + destination without having to re-run the install step. +* Editing through the link at the install destination will modify the source + of the link. This may be useful when dealing with CMake project hierarchies, + i.e. using :module:`ExternalProject` and consistent source navigation and + refactoring is desired across projects. + +Allowed Values +^^^^^^^^^^^^^^ + +The following values are allowed for ``CMAKE_INSTALL_MODE``: + +``COPY``, empty or unset + Duplicate the file at its destination. This is the default behavior. + +``ABS_SYMLINK`` + Create an *absolute* symbolic link to the source file at the destination. + Halt with an error if the link cannot be created. + +``ABS_SYMLINK_OR_COPY`` + Like ``ABS_SYMLINK`` but fall back to silently copying if the symlink + couldn't be created. + +``REL_SYMLINK`` + Create a *relative* symbolic link to the source file at the destination. + Halt with an error if the link cannot be created. + +``REL_SYMLINK_OR_COPY`` + Like ``REL_SYMLINK`` but fall back to silently copying if the symlink + couldn't be created. + +``SYMLINK`` + Try as if through ``REL_SYMLINK`` and fall back to ``ABS_SYMLINK`` if the + referenced file cannot be expressed using a relative path. + Halt with an error if the link cannot be created. + +``SYMLINK_OR_COPY`` + Like ``SYMLINK`` but fall back to silently copying if the symlink couldn't + be created. + +.. note:: + A symbolic link consists of a reference file path rather than contents of its + own, hence there are two ways to express the relation, either by a *relative* + or an *absolute* path. + +When To Set The Environment Variable +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For the environment variable to take effect, it must be set during the correct +build phase(s). + +* If the project calls :command:`file(INSTALL)` directly, the environment + variable must be set during the configuration phase. +* In order to apply to :command:`install()`, the environment variable must be + set during installation. This could be during a build if using the + ``install`` or ``package`` build targets, or separate from the build when + invoking an install or running :manual:`cpack <cpack(1)>` from the command + line. +* When using :module:`ExternalProject`, it might be required during the build + phase, since the external project's own configure, build and install steps + will execute during the main project's build phase. + +Given the above, it is recommended to set the environment variable consistently +across all phases (configure, build and install). + +Caveats +^^^^^^^ + +Use this environment variable with caution. The following highlights some +points to be considered: + +* ``CMAKE_INSTALL_MODE`` only affects files, not directories. + +* Symbolic links are not available on all platforms. + +* The way this environment variable interacts with the install step of + :module:`ExternalProject` is more complex. For further details, see that + module's documentation. + +* A symbolic link ties the destination to the source in a persistent way. + Writing to either of the two affects both file system objects. + This is in contrast to normal install behavior which only copies files as + they were at the time the install was performed, with no enduring + relationship between the source and destination of the install. + +* Combining ``CMAKE_INSTALL_MODE`` with :prop_tgt:`IOS_INSTALL_COMBINED` is + not supported. + +* Changing ``CMAKE_INSTALL_MODE`` from what it was on a previous run can lead + to unexpected results. Moving from a non-symlinking mode to a symlinking + mode will discard any previous file at the destination, but the reverse is + not true. Once a symlink exists at the destination, even if you switch to a + non-symlink mode, the symlink will continue to exist at the destination and + will not be replaced by an actual file. diff --git a/Help/envvar/CMAKE_LANG_LINKER_LAUNCHER.rst b/Help/envvar/CMAKE_LANG_LINKER_LAUNCHER.rst new file mode 100644 index 0000000..6251d9c --- /dev/null +++ b/Help/envvar/CMAKE_LANG_LINKER_LAUNCHER.rst @@ -0,0 +1,13 @@ +CMAKE_<LANG>_LINKER_LAUNCHER +---------------------------- + +.. versionadded:: 3.21 + +.. include:: ENV_VAR.txt + +Default launcher to use when linking a target of the specified language. Will +only be used by CMake to initialize the variable on the first configuration. +Afterwards, it is available through the cache setting of the variable of the +same name. For any configuration run (including the first), the environment +variable will be ignored if the :variable:`CMAKE_<LANG>_LINKER_LAUNCHER` +variable is defined. diff --git a/Help/envvar/CMAKE_TOOLCHAIN_FILE.rst b/Help/envvar/CMAKE_TOOLCHAIN_FILE.rst new file mode 100644 index 0000000..7ea9cea --- /dev/null +++ b/Help/envvar/CMAKE_TOOLCHAIN_FILE.rst @@ -0,0 +1,12 @@ +CMAKE_TOOLCHAIN_FILE +-------------------- + +.. versionadded:: 3.21 + +.. include:: ENV_VAR.txt + +The ``CMAKE_TOOLCHAIN_FILE`` environment variable specifies a default value +for the :variable:`CMAKE_TOOLCHAIN_FILE` variable when there is no explicit +configuration given on the first run while creating a new build tree. +On later runs in an existing build tree the value persists in the cache +as :variable:`CMAKE_TOOLCHAIN_FILE`. diff --git a/Help/envvar/CUDAARCHS.rst b/Help/envvar/CUDAARCHS.rst index 82369cd..e9e6a42 100644 --- a/Help/envvar/CUDAARCHS.rst +++ b/Help/envvar/CUDAARCHS.rst @@ -6,8 +6,7 @@ CUDAARCHS .. include:: ENV_VAR.txt Value used to initialize :variable:`CMAKE_CUDA_ARCHITECTURES` on the first -configuration if it's not already defined. Subsequent runs will use the value -stored in the cache. +configuration. Subsequent runs will use the value stored in the cache. This is a semicolon-separated list of architectures as described in :prop_tgt:`CUDA_ARCHITECTURES`. diff --git a/Help/envvar/CUDAHOSTCXX.rst b/Help/envvar/CUDAHOSTCXX.rst index 963f9d1..74f5d48 100644 --- a/Help/envvar/CUDAHOSTCXX.rst +++ b/Help/envvar/CUDAHOSTCXX.rst @@ -8,13 +8,16 @@ CUDAHOSTCXX Preferred executable for compiling host code when compiling ``CUDA`` language files. Will only be used by CMake on the first configuration to determine ``CUDA`` host compiler, after which the value for ``CUDAHOSTCXX`` is -stored in the cache as :variable:`CMAKE_CUDA_HOST_COMPILER`. For any -configuration run (including the first), the environment variable will be -ignored if the :variable:`CMAKE_CUDA_HOST_COMPILER` variable is defined. +stored in the cache as :variable:`CMAKE_CUDA_HOST_COMPILER`. This environment +variable is preferred over :variable:`CMAKE_CUDA_HOST_COMPILER`. This environment variable is primarily meant for use with projects that enable ``CUDA`` as a first-class language. +.. note:: + + Ignored when using :ref:`Visual Studio Generators`. + .. versionadded:: 3.13 The :module:`FindCUDA` module will use this variable to initialize its ``CUDA_HOST_COMPILER`` setting. diff --git a/Help/envvar/DESTDIR.rst b/Help/envvar/DESTDIR.rst index d2144ae..94cae4a 100644 --- a/Help/envvar/DESTDIR.rst +++ b/Help/envvar/DESTDIR.rst @@ -5,17 +5,26 @@ DESTDIR On UNIX one can use the ``DESTDIR`` mechanism in order to relocate the whole installation. ``DESTDIR`` means DESTination DIRectory. It is -commonly used by makefile users in order to install software at -non-default location. It is usually invoked like this: +commonly used by packagers to install software in a staging directory. -:: +For example, running - make DESTDIR=/home/john install +.. code-block:: shell -which will install the concerned software using the installation -prefix, e.g. ``/usr/local`` prepended with the ``DESTDIR`` value which -finally gives ``/home/john/usr/local``. + make DESTDIR=/package/stage install -WARNING: ``DESTDIR`` may not be used on Windows because installation -prefix usually contains a drive letter like in ``C:/Program Files`` -which cannot be prepended with some other prefix. +will install the software using the installation prefix, e.g. ``/usr/local``, +prepended with the ``DESTDIR`` value which gives ``/package/stage/usr/local``. +The packaging tool may then construct the package from the content of the +``/package/stage`` directory. + +See the :variable:`CMAKE_INSTALL_PREFIX` variable to control the +installation prefix when configuring a build tree. Or, when using +the :manual:`cmake(1)` command-line tool's ``--install`` mode, +one may specify a different prefix using the ``--prefix`` option. + +.. note:: + + ``DESTDIR`` may not be used on Windows because installation + prefix usually contains a drive letter like in ``C:/Program Files`` + which cannot be prepended with some other prefix. diff --git a/Help/envvar/HIPCXX.rst b/Help/envvar/HIPCXX.rst new file mode 100644 index 0000000..23329e9 --- /dev/null +++ b/Help/envvar/HIPCXX.rst @@ -0,0 +1,13 @@ +HIPCXX +------ + +.. versionadded:: 3.21 + +.. include:: ENV_VAR.txt + +Preferred executable for compiling ``HIP`` language files. Will only be used by +CMake on the first configuration to determine ``HIP`` compiler, after which the +value for ``HIP`` is stored in the cache as +:variable:`CMAKE_HIP_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration +run (including the first), the environment variable will be ignored if the +:variable:`CMAKE_HIP_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined. diff --git a/Help/envvar/HIPFLAGS.rst b/Help/envvar/HIPFLAGS.rst new file mode 100644 index 0000000..0df3416 --- /dev/null +++ b/Help/envvar/HIPFLAGS.rst @@ -0,0 +1,15 @@ +HIPFLAGS +-------- + +.. versionadded:: 3.21 + +.. include:: ENV_VAR.txt + +Default compilation flags to be used when compiling ``HIP`` files. Will only be +used by CMake on the first configuration to determine ``HIP`` default +compilation flags, after which the value for ``HIPFLAGS`` is stored in the +cache as :variable:`CMAKE_HIP_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration +run (including the first), the environment variable will be ignored if +the :variable:`CMAKE_HIP_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined. + +See also :variable:`CMAKE_HIP_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`. diff --git a/Help/generator/Green Hills MULTI.rst b/Help/generator/Green Hills MULTI.rst index 5d2b1cd..1b4739b 100644 --- a/Help/generator/Green Hills MULTI.rst +++ b/Help/generator/Green Hills MULTI.rst @@ -8,70 +8,125 @@ Green Hills MULTI Generates Green Hills MULTI project files (experimental, work-in-progress). -Customizations are available through the following cache variables: - -* ``GHS_CUSTOMIZATION`` -* ``GHS_GPJ_MACROS`` - -.. versionadded:: 3.14 The buildsystem has predetermined build-configuration settings that can be controlled via the :variable:`CMAKE_BUILD_TYPE` variable. -Toolset and Platform Selection -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Platform Selection +^^^^^^^^^^^^^^^^^^ .. versionadded:: 3.13 -Customizations that are used to pick toolset and target system: +The variable ``GHS_PRIMARY_TARGET`` can be used to select the target platform. + + | Sets ``primaryTarget`` entry in project file. + +For example: -* The ``-A <arch>`` can be supplied for setting the target architecture. - ``<arch>`` usually is one of ``arm``, ``ppc``, ``86``, etcetera. - If the target architecture is not specified then - the default architecture of ``arm`` will be used. +* ``cmake -G "Green Hills MULTI" -D GHS_PRIMARY_TARGET=ppc_integrity.tgt`` -* The ``-T <toolset>`` option can be used to set the directory location of the toolset. - Both absolute and relative paths are valid. Relative paths use ``GHS_TOOLSET_ROOT`` - as the root. If the toolset is not specified then the latest toolset found in - ``GHS_TOOLSET_ROOT`` will be used. +Otherwise the ``primaryTarget`` will be composed from the values of :variable:`CMAKE_GENERATOR_PLATFORM` +and ``GHS_TARGET_PLATFORM``. Defaulting to the value of ``arm_integrity.tgt`` -Cache variables that are used for toolset and target system customization: +* The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps + via the :manual:`cmake(1)` ``-A`` option. -* ``GHS_TARGET_PLATFORM`` + | Typical values of ``arm``, ``ppc``, ``86``, etcetera, are used. + +* The variable ``GHS_TARGET_PLATFORM`` may be set, perhaps via the :manual:`cmake(1)` + ``-D`` option. | Defaults to ``integrity``. | Usual values are ``integrity``, ``threadx``, ``uvelosity``, ``velosity``, ``vxworks``, ``standalone``. -* ``GHS_PRIMARY_TARGET`` +For example: - | Sets ``primaryTarget`` entry in project file. - | Defaults to ``<arch>_<GHS_TARGET_PLATFORM>.tgt``. +* ``cmake -G "Green Hills MULTI"`` for ``arm_integrity.tgt``. +* ``cmake -G "Green Hills MULTI" -A 86`` for ``86_integrity.tgt``. +* ``cmake -G "Green Hills MULTI" -D GHS_TARGET_PLATFORM=standalone`` for ``arm_standalone.tgt``. +* ``cmake -G "Green Hills MULTI" -A ppc -D GHS_TARGET_PLATFORM=standalone`` for ``ppc_standalone.tgt``. -* ``GHS_TOOLSET_ROOT`` +Toolset Selection +^^^^^^^^^^^^^^^^^ - | Root path for ``toolset`` searches. - | Defaults to ``C:/ghs`` in Windows or ``/usr/ghs`` in Linux. +.. versionadded:: 3.13 -* ``GHS_OS_ROOT`` +The generator searches for the latest compiler or can be given a location to use. +``GHS_TOOLSET_ROOT`` is the directory that is checked for the latest compiler. - | Root path for RTOS searches. +* The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps + via the :manual:`cmake(1)` ``-T`` option, to specify the location of the toolset. + Both absolute and relative paths are valid. Paths are relative to ``GHS_TOOLSET_ROOT``. + +* The variable ``GHS_TOOLSET_ROOT`` may be set, perhaps via the :manual:`cmake(1)` + ``-D`` option. + + | Root path for toolset searches and relative paths. | Defaults to ``C:/ghs`` in Windows or ``/usr/ghs`` in Linux. +For example, setting a specific compiler: + +* ``cmake -G "Green Hills MULTI" -T comp_201754`` for ``/usr/ghs/comp_201754``. +* ``cmake -G "Green Hills MULTI" -T comp_201754 -D GHS_TOOLSET_ROOT=/opt/ghs`` for ``/opt/ghs/comp_201754``. +* ``cmake -G "Green Hills MULTI" -T /usr/ghs/comp_201554`` +* ``cmake -G "Green Hills MULTI" -T C:/ghs/comp_201754`` + +For example, searching for latest compiler: + +* ``cmake -G "Green Hills MULTI"`` for searching ``/usr/ghs``. +* ``cmake -G "Green Hills MULTI -D GHS_TOOLSET_ROOT=/opt/ghs"`` for searching ``/opt/ghs``. + +.. note:: + The :variable:`CMAKE_GENERATOR_TOOLSET` should use CMake style paths. + +OS and BSP Selection +^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.3 + +Certain target platforms, like Integrity, require an OS. The RTOS directory path +can be explicitly set using ``GHS_OS_DIR``. Otherwise ``GHS_OS_ROOT`` will be +searched for the latest Integrity RTOS. + +If the target platform, like Integrity, requires a BSP name then it can be set via +the ``GHS_BSP_NAME`` variable. + * ``GHS_OS_DIR`` and ``GHS_OS_DIR_OPTION`` | Sets ``-os_dir`` entry in project file. - | Defaults to latest platform OS installation at ``GHS_OS_ROOT``. Set this value if - a specific RTOS is to be used. + | ``GHS_OS_DIR_OPTION`` default value is ``-os_dir``. .. versionadded:: 3.15 The ``GHS_OS_DIR_OPTION`` variable. + For example: + + * ``cmake -G "Green Hills MULTI" -D GHS_OS_DIR=/usr/ghs/int1144`` + +* ``GHS_OS_ROOT`` + + | Root path for RTOS searches. + | Defaults to ``C:/ghs`` in Windows or ``/usr/ghs`` in Linux. + + For example: + + * ``cmake -G "Green Hills MULTI" -D GHS_OS_ROOT=/opt/ghs`` + * ``GHS_BSP_NAME`` | Sets ``-bsp`` entry in project file. | Defaults to ``sim<arch>`` for ``integrity`` platforms. + For example: + + * ``cmake -G "Green Hills MULTI"`` for ``simarm`` on ``arm_integrity.tgt``. + * ``cmake -G "Green Hills MULTI" -A 86`` for ``sim86`` on ``86_integrity.tgt``. + * ``cmake -G "Green Hills MULTI" -A ppc -D GHS_BSP_NAME=sim800`` for ``sim800`` + on ``ppc_integrity.tgt``. + * ``cmake -G "Green Hills MULTI" -D GHS_PRIMARY_TARGET=ppc_integrity.tgt -D GHS_BSP_NAME=fsl-t1040`` + for ``fsl-t1040`` on ``ppc_integrity.tgt``. + Target Properties ^^^^^^^^^^^^^^^^^ @@ -82,6 +137,17 @@ The following properties are available: * :prop_tgt:`GHS_INTEGRITY_APP` * :prop_tgt:`GHS_NO_SOURCE_GROUP_FILE` +MULTI Project Variables +^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.3 + +Adding a Customization file and macros are available through the use of the following +variables: + +* ``GHS_CUSTOMIZATION`` - CMake path name to Customization File. +* ``GHS_GPJ_MACROS`` - CMake list of Macros. + .. note:: This generator is deemed experimental as of CMake |release| and is still a work in progress. Future versions of CMake diff --git a/Help/generator/Ninja Multi-Config.rst b/Help/generator/Ninja Multi-Config.rst index 8901192..e5ce4f5 100644 --- a/Help/generator/Ninja Multi-Config.rst +++ b/Help/generator/Ninja Multi-Config.rst @@ -34,7 +34,9 @@ below for how to enable cross-config mode. The ``Ninja Multi-Config`` generator recognizes the following variables: :variable:`CMAKE_CONFIGURATION_TYPES` - Specifies the total set of configurations to build. + Specifies the total set of configurations to build. Unlike with other + multi-config generators, this variable has a value of + ``Debug;Release;RelWithDebInfo`` by default. :variable:`CMAKE_CROSS_CONFIGS` Specifies a :ref:`semicolon-separated list <CMake Language Lists>` of diff --git a/Help/generator/VS_TOOLSET_HOST_ARCH.txt b/Help/generator/VS_TOOLSET_HOST_ARCH.txt index e361719..0293631 100644 --- a/Help/generator/VS_TOOLSET_HOST_ARCH.txt +++ b/Help/generator/VS_TOOLSET_HOST_ARCH.txt @@ -1,11 +1,7 @@ -.. versionadded:: 3.8 - For each toolset that comes with this version of Visual Studio, there are - variants that are themselves compiled for 32-bit (``x86``) and - 64-bit (``x64``) hosts (independent of the architecture they target). - |VS_TOOLSET_HOST_ARCH_DEFAULT| - One may explicitly request use of either the 32-bit or 64-bit host tools - by adding either ``host=x86`` or ``host=x64`` to the toolset specification. - See the :variable:`CMAKE_GENERATOR_TOOLSET` variable for details. - -.. versionadded:: 3.14 - Added suport for ``host=x86`` option. +For each toolset that comes with this version of Visual Studio, there are +variants that are themselves compiled for 32-bit (``x86``) and +64-bit (``x64``) hosts (independent of the architecture they target). +|VS_TOOLSET_HOST_ARCH_DEFAULT| +One may explicitly request use of either the 32-bit or 64-bit host tools +by adding either ``host=x86`` or ``host=x64`` to the toolset specification. +See the :variable:`CMAKE_GENERATOR_TOOLSET` variable for details. diff --git a/Help/generator/VS_TOOLSET_HOST_ARCH_LEGACY.txt b/Help/generator/VS_TOOLSET_HOST_ARCH_LEGACY.txt new file mode 100644 index 0000000..069638b --- /dev/null +++ b/Help/generator/VS_TOOLSET_HOST_ARCH_LEGACY.txt @@ -0,0 +1,11 @@ +.. versionadded:: 3.8 + For each toolset that comes with this version of Visual Studio, there are + variants that are themselves compiled for 32-bit (``x86``) and + 64-bit (``x64``) hosts (independent of the architecture they target). + |VS_TOOLSET_HOST_ARCH_DEFAULT| + One may explicitly request use of either the 32-bit or 64-bit host tools + by adding either ``host=x86`` or ``host=x64`` to the toolset specification. + See the :variable:`CMAKE_GENERATOR_TOOLSET` variable for details. + +.. versionadded:: 3.14 + Added support for ``host=x86`` option. diff --git a/Help/generator/Visual Studio 10 2010.rst b/Help/generator/Visual Studio 10 2010.rst index b4376d8..9ec33c3 100644 --- a/Help/generator/Visual Studio 10 2010.rst +++ b/Help/generator/Visual Studio 10 2010.rst @@ -1,7 +1,14 @@ Visual Studio 10 2010 --------------------- -Generates Visual Studio 10 (VS 2010) project files. +Deprecated. Generates Visual Studio 10 (VS 2010) project files. + +.. note:: + This generator is deprecated and will be removed in a future version + of CMake. It will still be possible to build with VS 10 2010 tools + using the :generator:`Visual Studio 11 2012` (or above) generator + with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v100``, or by + using the :generator:`NMake Makefiles` generator. For compatibility with CMake versions prior to 3.0, one may specify this generator using the name ``Visual Studio 10`` without the year component. @@ -9,8 +16,9 @@ generator using the name ``Visual Studio 10`` without the year component. Project Types ^^^^^^^^^^^^^ -Only Visual C++ and C# projects may be generated. Other types of -projects (Database, Website, etc.) are not supported. +Only Visual C++ and C# projects may be generated (and Fortran with +Intel compiler integration). Other types of projects (Database, +Website, etc.) are not supported. Platform Selection ^^^^^^^^^^^^^^^^^^ diff --git a/Help/generator/Visual Studio 11 2012.rst b/Help/generator/Visual Studio 11 2012.rst index 932548b..3952228 100644 --- a/Help/generator/Visual Studio 11 2012.rst +++ b/Help/generator/Visual Studio 11 2012.rst @@ -9,8 +9,9 @@ generator using the name "Visual Studio 11" without the year component. Project Types ^^^^^^^^^^^^^ -Only Visual C++ and C# projects may be generated. Other types of -projects (JavaScript, Database, Website, etc.) are not supported. +Only Visual C++ and C# projects may be generated (and Fortran with +Intel compiler integration). Other types of projects (JavaScript, +Database, Website, etc.) are not supported. Platform Selection ^^^^^^^^^^^^^^^^^^ diff --git a/Help/generator/Visual Studio 12 2013.rst b/Help/generator/Visual Studio 12 2013.rst index b5fa1bf..54a4d7e 100644 --- a/Help/generator/Visual Studio 12 2013.rst +++ b/Help/generator/Visual Studio 12 2013.rst @@ -9,8 +9,9 @@ generator using the name "Visual Studio 12" without the year component. Project Types ^^^^^^^^^^^^^ -Only Visual C++ and C# projects may be generated. Other types of -projects (JavaScript, Powershell, Python, etc.) are not supported. +Only Visual C++ and C# projects may be generated (and Fortran with +Intel compiler integration). Other types of projects (JavaScript, +Powershell, Python, etc.) are not supported. Platform Selection ^^^^^^^^^^^^^^^^^^ @@ -46,4 +47,4 @@ via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. .. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace:: By default this generator uses the 32-bit variant even on a 64-bit host. -.. include:: VS_TOOLSET_HOST_ARCH.txt +.. include:: VS_TOOLSET_HOST_ARCH_LEGACY.txt diff --git a/Help/generator/Visual Studio 14 2015.rst b/Help/generator/Visual Studio 14 2015.rst index 9c61641..d704ab2 100644 --- a/Help/generator/Visual Studio 14 2015.rst +++ b/Help/generator/Visual Studio 14 2015.rst @@ -8,8 +8,9 @@ Generates Visual Studio 14 (VS 2015) project files. Project Types ^^^^^^^^^^^^^ -Only Visual C++ and C# projects may be generated. Other types of -projects (JavaScript, Powershell, Python, etc.) are not supported. +Only Visual C++ and C# projects may be generated (and Fortran with +Intel compiler integration). Other types of projects (JavaScript, +Powershell, Python, etc.) are not supported. Platform Selection ^^^^^^^^^^^^^^^^^^ @@ -44,7 +45,7 @@ via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. .. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace:: By default this generator uses the 32-bit variant even on a 64-bit host. -.. include:: VS_TOOLSET_HOST_ARCH.txt +.. include:: VS_TOOLSET_HOST_ARCH_LEGACY.txt .. _`Windows 10 SDK Maximum Version for VS 2015`: diff --git a/Help/generator/Visual Studio 15 2017.rst b/Help/generator/Visual Studio 15 2017.rst index a002f2f..912afad 100644 --- a/Help/generator/Visual Studio 15 2017.rst +++ b/Help/generator/Visual Studio 15 2017.rst @@ -8,26 +8,17 @@ Generates Visual Studio 15 (VS 2017) project files. Project Types ^^^^^^^^^^^^^ -Only Visual C++ and C# projects may be generated. Other types of -projects (JavaScript, Powershell, Python, etc.) are not supported. +Only Visual C++ and C# projects may be generated (and Fortran with +Intel compiler integration). Other types of projects (JavaScript, +Powershell, Python, etc.) are not supported. Instance Selection ^^^^^^^^^^^^^^^^^^ -.. versionadded:: 3.9 - VS 2017 supports multiple installations on the same machine. - The :variable:`CMAKE_GENERATOR_INSTANCE` variable may be set as a - cache entry containing the absolute path to a Visual Studio instance. - If the value is not specified explicitly by the user or a toolchain file, - CMake queries the Visual Studio Installer to locate VS instances, chooses - one, and sets the variable as a cache entry to hold the value persistently. - .. versionadded:: 3.11 - When CMake first chooses an instance, if the ``VS150COMNTOOLS`` environment - variable is set and points to the ``Common7/Tools`` directory within - one of the instances, that instance will be used. Otherwise, if more - than one instance is installed we do not define which one is chosen - by default. + +VS 2017 supports multiple installations on the same machine. The +:variable:`CMAKE_GENERATOR_INSTANCE` variable may be used to select one. Platform Selection ^^^^^^^^^^^^^^^^^^ @@ -63,4 +54,4 @@ via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. .. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace:: By default this generator uses the 32-bit variant even on a 64-bit host. -.. include:: VS_TOOLSET_HOST_ARCH.txt +.. include:: VS_TOOLSET_HOST_ARCH_LEGACY.txt diff --git a/Help/generator/Visual Studio 16 2019.rst b/Help/generator/Visual Studio 16 2019.rst index 3da8091..6cefe6d 100644 --- a/Help/generator/Visual Studio 16 2019.rst +++ b/Help/generator/Visual Studio 16 2019.rst @@ -8,24 +8,15 @@ Generates Visual Studio 16 (VS 2019) project files. Project Types ^^^^^^^^^^^^^ -Only Visual C++ and C# projects may be generated. Other types of -projects (JavaScript, Powershell, Python, etc.) are not supported. +Only Visual C++ and C# projects may be generated (and Fortran with +Intel compiler integration). Other types of projects (JavaScript, +Powershell, Python, etc.) are not supported. Instance Selection ^^^^^^^^^^^^^^^^^^ -VS 2019 supports multiple installations on the same machine. -The :variable:`CMAKE_GENERATOR_INSTANCE` variable may be set as a -cache entry containing the absolute path to a Visual Studio instance. -If the value is not specified explicitly by the user or a toolchain file, -CMake queries the Visual Studio Installer to locate VS instances, chooses -one, and sets the variable as a cache entry to hold the value persistently. - -When CMake first chooses an instance, if the ``VS160COMNTOOLS`` environment -variable is set and points to the ``Common7/Tools`` directory within -one of the instances, that instance will be used. Otherwise, if more -than one instance is installed we do not define which one is chosen -by default. +VS 2019 supports multiple installations on the same machine. The +:variable:`CMAKE_GENERATOR_INSTANCE` variable may be used to select one. Platform Selection ^^^^^^^^^^^^^^^^^^ diff --git a/Help/generator/Visual Studio 17 2022.rst b/Help/generator/Visual Studio 17 2022.rst new file mode 100644 index 0000000..edf9d60 --- /dev/null +++ b/Help/generator/Visual Studio 17 2022.rst @@ -0,0 +1,47 @@ +Visual Studio 17 2022 +--------------------- + +.. versionadded:: 3.21 + +Generates Visual Studio 17 (VS 2022) project files. + +Project Types +^^^^^^^^^^^^^ + +Only Visual C++ and C# projects may be generated (and Fortran with +Intel compiler integration). Other types of projects (JavaScript, +Powershell, Python, etc.) are not supported. + +Instance Selection +^^^^^^^^^^^^^^^^^^ + +VS 2022 supports multiple installations on the same machine. The +:variable:`CMAKE_GENERATOR_INSTANCE` variable may be used to select one. + +Platform Selection +^^^^^^^^^^^^^^^^^^ + +The default target platform name (architecture) is that of the host +and is provided in the :variable:`CMAKE_VS_PLATFORM_NAME_DEFAULT` variable. + +The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps +via the :manual:`cmake(1)` ``-A`` option, to specify a target platform +name (architecture). For example: + +* ``cmake -G "Visual Studio 17 2022" -A Win32`` +* ``cmake -G "Visual Studio 17 2022" -A x64`` +* ``cmake -G "Visual Studio 17 2022" -A ARM`` +* ``cmake -G "Visual Studio 17 2022" -A ARM64`` + +Toolset Selection +^^^^^^^^^^^^^^^^^ + +The ``v143`` toolset that comes with VS 17 2022 is selected by default. +The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps +via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. + +.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace:: + By default this generator uses the 64-bit variant on x64 hosts and + the 32-bit variant otherwise. + +.. include:: VS_TOOLSET_HOST_ARCH.txt diff --git a/Help/guide/ide-integration/index.rst b/Help/guide/ide-integration/index.rst index 779883b..8473481 100644 --- a/Help/guide/ide-integration/index.rst +++ b/Help/guide/ide-integration/index.rst @@ -65,6 +65,12 @@ run: cmake -S /path/to/source -B /path/to/source/build -G Ninja +In cases where a preset contains lots of cache variables, and passing all of +them as ``-D`` flags would cause the command line length limit of the platform +to be exceeded, the IDE should instead construct a temporary cache script and +pass it with the ``-C`` flag. See :ref:`CMake Options` for details on how the +``-C`` flag is used. + While reading, parsing, and evaluating the contents of ``CMakePresets.json`` is straightforward, it is not trivial. In addition to the documentation, IDE vendors may also wish to refer to the CMake source code and test cases for a @@ -124,3 +130,31 @@ obtain this information and use it to present the user with a list of tests. IDEs should not invoke the ``test`` target of the generated buildsystem. Instead, they should invoke :manual:`ctest(1)` directly. + +IDEs with CMake integration +=========================== + +The following IDEs support CMake natively: + +* `CLion`_ +* `KDevelop`_ +* `QtCreator`_ +* `Vim`_ (via a plugin) +* `Visual Studio`_ +* `VSCode`_ (via a plugin) + +.. _CLion: https://www.jetbrains.com/clion/ +.. _KDevelop: https://www.kdevelop.org/ +.. _QtCreator: https://www.qt.io/product/development-tools +.. _Vim: https://www.vim.org/ +.. _Visual Studio: https://visualstudio.microsoft.com/ +.. _VSCode: https://code.visualstudio.com/ + +Additionally, CMake has builtin support for some IDEs: + +* :ref:`IDE Build Tool Generators`: + Generate IDE native build systems such as Visual Studio or Xcode. +* :ref:`Extra Generators`: + Extend :ref:`Command-Line Build Tool Generators` to generate IDE + project files that hook into the command-line build system. + Superseded by the :manual:`File API <cmake-file-api(7)>`. diff --git a/Help/guide/importing-exporting/MathFunctions/CMakeLists.txt b/Help/guide/importing-exporting/MathFunctions/CMakeLists.txt index 9a9e40e..d277b54 100644 --- a/Help/guide/importing-exporting/MathFunctions/CMakeLists.txt +++ b/Help/guide/importing-exporting/MathFunctions/CMakeLists.txt @@ -1,6 +1,9 @@ cmake_minimum_required(VERSION 3.15) project(MathFunctions) +# make cache variables for install destinations +include(GNUInstallDirs) + # specify the C++ standard set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED True) @@ -12,26 +15,26 @@ add_library(MathFunctions STATIC MathFunctions.cxx) target_include_directories(MathFunctions PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>" - "$<INSTALL_INTERFACE:include>" + "$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>" ) # install the target and create export-set install(TARGETS MathFunctions EXPORT MathFunctionsTargets - LIBRARY DESTINATION lib - ARCHIVE DESTINATION lib - RUNTIME DESTINATION bin - INCLUDES DESTINATION include + LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} + ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} + RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} + INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR} ) # install header file -install(FILES MathFunctions.h DESTINATION include) +install(FILES MathFunctions.h DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}) # generate and install export file install(EXPORT MathFunctionsTargets FILE MathFunctionsTargets.cmake NAMESPACE MathFunctions:: - DESTINATION lib/cmake/MathFunctions + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions ) # include CMakePackageConfigHelpers macro @@ -58,14 +61,14 @@ write_basic_package_version_file( # create config file configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake" - INSTALL_DESTINATION lib/cmake/MathFunctions + INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions ) # install config files install(FILES "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake" "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake" - DESTINATION lib/cmake/MathFunctions + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions ) # generate the export targets for the build tree diff --git a/Help/guide/importing-exporting/MathFunctionsComponents/Addition/CMakeLists.txt b/Help/guide/importing-exporting/MathFunctionsComponents/Addition/CMakeLists.txt index 17ad952..9de935e 100644 --- a/Help/guide/importing-exporting/MathFunctionsComponents/Addition/CMakeLists.txt +++ b/Help/guide/importing-exporting/MathFunctionsComponents/Addition/CMakeLists.txt @@ -7,24 +7,24 @@ add_library(MathFunctions::Addition ALIAS Addition) target_include_directories(Addition PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>" - $<INSTALL_INTERFACE:include> + $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}> ) # install the target and create export-set install(TARGETS Addition EXPORT AdditionTargets - LIBRARY DESTINATION lib - ARCHIVE DESTINATION lib - RUNTIME DESTINATION bin - INCLUDES DESTINATION include + LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} + ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} + RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} + INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR} ) # install header file -install(FILES Addition.h DESTINATION include) +install(FILES Addition.h DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}) # generate and install export file install(EXPORT AdditionTargets FILE MathFunctionsAdditionTargets.cmake NAMESPACE MathFunctions:: - DESTINATION lib/cmake/MathFunctions + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions ) diff --git a/Help/guide/importing-exporting/MathFunctionsComponents/CMakeLists.txt b/Help/guide/importing-exporting/MathFunctionsComponents/CMakeLists.txt index fd95e28..90ee89f 100644 --- a/Help/guide/importing-exporting/MathFunctionsComponents/CMakeLists.txt +++ b/Help/guide/importing-exporting/MathFunctionsComponents/CMakeLists.txt @@ -1,6 +1,9 @@ cmake_minimum_required(VERSION 3.15) project(MathFunctionsComponents) +# make cache variables for install destinations +include(GNUInstallDirs) + # specify the C++ standard set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED True) @@ -24,7 +27,7 @@ write_basic_package_version_file( # create config file configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake" - INSTALL_DESTINATION lib/cmake/MathFunctions + INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions NO_CHECK_REQUIRED_COMPONENTS_MACRO ) @@ -32,5 +35,5 @@ configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in install(FILES "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake" "${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake" - DESTINATION lib/cmake/MathFunctions + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions ) diff --git a/Help/guide/importing-exporting/MathFunctionsComponents/Config.cmake.in b/Help/guide/importing-exporting/MathFunctionsComponents/Config.cmake.in index 09f6c35..a535969 100644 --- a/Help/guide/importing-exporting/MathFunctionsComponents/Config.cmake.in +++ b/Help/guide/importing-exporting/MathFunctionsComponents/Config.cmake.in @@ -1,9 +1,9 @@ @PACKAGE_INIT@ -set(_supported_components Addition SquareRoot) +set(_MathFunctions_supported_components Addition SquareRoot) foreach(_comp ${MathFunctions_FIND_COMPONENTS}) - if (NOT _comp IN_LIST _supported_components) + if (NOT _comp IN_LIST _MathFunctions_supported_components) set(MathFunctions_FOUND False) set(MathFunctions_NOT_FOUND_MESSAGE "Unsupported component: ${_comp}") endif() diff --git a/Help/guide/importing-exporting/MathFunctionsComponents/SquareRoot/CMakeLists.txt b/Help/guide/importing-exporting/MathFunctionsComponents/SquareRoot/CMakeLists.txt index be5ae65..517c5e2 100644 --- a/Help/guide/importing-exporting/MathFunctionsComponents/SquareRoot/CMakeLists.txt +++ b/Help/guide/importing-exporting/MathFunctionsComponents/SquareRoot/CMakeLists.txt @@ -7,24 +7,24 @@ add_library(MathFunctions::SquareRoot ALIAS SquareRoot) target_include_directories(SquareRoot PUBLIC "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>" - "$<INSTALL_INTERFACE:include>" + "$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>" ) # install the target and create export-set install(TARGETS SquareRoot EXPORT SquareRootTargets - LIBRARY DESTINATION lib - ARCHIVE DESTINATION lib - RUNTIME DESTINATION bin - INCLUDES DESTINATION include + LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} + ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} + RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} + INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR} ) # install header file -install(FILES SquareRoot.h DESTINATION include) +install(FILES SquareRoot.h DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}) # generate and install export file install(EXPORT SquareRootTargets FILE MathFunctionsSquareRootTargets.cmake NAMESPACE MathFunctions:: - DESTINATION lib/cmake/MathFunctions + DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MathFunctions ) diff --git a/Help/guide/importing-exporting/index.rst b/Help/guide/importing-exporting/index.rst index 2e6e06d..dd3efb8 100644 --- a/Help/guide/importing-exporting/index.rst +++ b/Help/guide/importing-exporting/index.rst @@ -202,6 +202,10 @@ project. Start by specifying the :command:`cmake_minimum_required` version and :language: cmake :end-before: # create library +The :module:`GNUInstallDirs` module is included in order to provide the +project with the flexibility to install into different platform layouts by +making the directories available as cache variables. + Create a library called ``MathFunctions`` with the :command:`add_library` command: @@ -636,7 +640,7 @@ We can use the :command:`find_package` command: :start-after: # find MathFunctions :end-before: # create executable -Create an exectuable: +Create an executable: .. literalinclude:: Downstream/CMakeLists.txt :language: cmake diff --git a/Help/guide/tutorial/A Basic Starting Point.rst b/Help/guide/tutorial/A Basic Starting Point.rst new file mode 100644 index 0000000..cf1ec01 --- /dev/null +++ b/Help/guide/tutorial/A Basic Starting Point.rst @@ -0,0 +1,175 @@ +Step 1: A Basic Starting Point +============================== + +The most basic project is an executable built from source code files. +For simple projects, a three line ``CMakeLists.txt`` file is all that is +required. This will be the starting point for our tutorial. Create a +``CMakeLists.txt`` file in the ``Step1`` directory that looks like: + +.. code-block:: cmake + :caption: CMakeLists.txt + :name: CMakeLists.txt-start + + cmake_minimum_required(VERSION 3.10) + + # set the project name + project(Tutorial) + + # add the executable + add_executable(Tutorial tutorial.cxx) + + +Note that this example uses lower case commands in the ``CMakeLists.txt`` file. +Upper, lower, and mixed case commands are supported by CMake. The source +code for ``tutorial.cxx`` is provided in the ``Step1`` directory and can be +used to compute the square root of a number. + +Build and Run +------------- + +That's all that is needed - we can build and run our project now! First, run +the :manual:`cmake <cmake(1)>` executable or the +:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it +with your chosen build tool. + +For example, from the command line we could navigate to the +``Help/guide/tutorial`` directory of the CMake source code tree and create a +build directory: + +.. code-block:: console + + mkdir Step1_build + +Next, navigate to the build directory and run CMake to configure the project +and generate a native build system: + +.. code-block:: console + + cd Step1_build + cmake ../Step1 + +Then call that build system to actually compile/link the project: + +.. code-block:: console + + cmake --build . + +Finally, try to use the newly built ``Tutorial`` with these commands: + +.. code-block:: console + + Tutorial 4294967296 + Tutorial 10 + Tutorial + + +Adding a Version Number and Configured Header File +-------------------------------------------------- + +The first feature we will add is to provide our executable and project with a +version number. While we could do this exclusively in the source code, using +``CMakeLists.txt`` provides more flexibility. + +First, modify the ``CMakeLists.txt`` file to use the :command:`project` command +to set the project name and version number. + +.. literalinclude:: Step2/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-project-VERSION + :language: cmake + :end-before: # specify the C++ standard + +Then, configure a header file to pass the version number to the source +code: + +.. literalinclude:: Step2/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-configure_file + :language: cmake + :start-after: # to the source code + :end-before: # add the executable + +Since the configured file will be written into the binary tree, we +must add that directory to the list of paths to search for include +files. Add the following lines to the end of the ``CMakeLists.txt`` file: + +.. literalinclude:: Step2/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-target_include_directories + :language: cmake + :start-after: # so that we will find TutorialConfig.h + +Using your favorite editor, create ``TutorialConfig.h.in`` in the source +directory with the following contents: + +.. literalinclude:: Step2/TutorialConfig.h.in + :caption: TutorialConfig.h.in + :name: TutorialConfig.h.in + :language: c++ + +When CMake configures this header file the values for +``@Tutorial_VERSION_MAJOR@`` and ``@Tutorial_VERSION_MINOR@`` will be +replaced. + +Next modify ``tutorial.cxx`` to include the configured header file, +``TutorialConfig.h``. + +Finally, let's print out the executable name and version number by updating +``tutorial.cxx`` as follows: + +.. literalinclude:: Step2/tutorial.cxx + :caption: tutorial.cxx + :name: tutorial.cxx-print-version + :language: c++ + :start-after: { + :end-before: // convert input to double + +Specify the C++ Standard +------------------------- + +Next let's add some C++11 features to our project by replacing ``atof`` with +``std::stod`` in ``tutorial.cxx``. At the same time, remove +``#include <cstdlib>``. + +.. literalinclude:: Step2/tutorial.cxx + :caption: tutorial.cxx + :name: tutorial.cxx-cxx11 + :language: c++ + :start-after: // convert input to double + :end-before: // calculate square root + +We will need to explicitly state in the CMake code that it should use the +correct flags. The easiest way to enable support for a specific C++ standard +in CMake is by using the :variable:`CMAKE_CXX_STANDARD` variable. For this +tutorial, set the :variable:`CMAKE_CXX_STANDARD` variable in the +``CMakeLists.txt`` file to ``11`` and :variable:`CMAKE_CXX_STANDARD_REQUIRED` +to ``True``. Make sure to add the ``CMAKE_CXX_STANDARD`` declarations above the +call to ``add_executable``. + +.. literalinclude:: Step2/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-CXX_STANDARD + :language: cmake + :end-before: # configure a header file to pass some of the CMake settings + +Rebuild +------- + +Let's build our project again. We already created a build directory and ran +CMake, so we can skip to the build step: + +.. code-block:: console + + cd Step1_build + cmake --build . + +Now we can try to use the newly built ``Tutorial`` with same commands as before: + +.. code-block:: console + + Tutorial 4294967296 + Tutorial 10 + Tutorial + +Check that the version number is now reported when running the executable without +any arguments. diff --git a/Help/guide/tutorial/Adding Export Configuration.rst b/Help/guide/tutorial/Adding Export Configuration.rst new file mode 100644 index 0000000..3bd6d64 --- /dev/null +++ b/Help/guide/tutorial/Adding Export Configuration.rst @@ -0,0 +1,140 @@ +Step 11: Adding Export Configuration +==================================== + +During :guide:`tutorial/Installing and Testing` of the tutorial we added the +ability for CMake to install the library and headers of the project. During +:guide:`tutorial/Packaging an Installer` we added the ability to package up +this information so it could be distributed to other people. + +The next step is to add the necessary information so that other CMake projects +can use our project, be it from a build directory, a local install or when +packaged. + +The first step is to update our :command:`install(TARGETS)` commands to not +only specify a ``DESTINATION`` but also an ``EXPORT``. The ``EXPORT`` keyword +generates a CMake file containing code to import all targets listed in the +install command from the installation tree. So let's go ahead and explicitly +``EXPORT`` the ``MathFunctions`` library by updating the ``install`` command +in ``MathFunctions/CMakeLists.txt`` to look like: + +.. literalinclude:: Complete/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-install-TARGETS-EXPORT + :language: cmake + :start-after: # install rules + +Now that we have ``MathFunctions`` being exported, we also need to explicitly +install the generated ``MathFunctionsTargets.cmake`` file. This is done by +adding the following to the bottom of the top-level ``CMakeLists.txt``: + +.. literalinclude:: Complete/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-install-EXPORT + :language: cmake + :start-after: # install the configuration targets + :end-before: include(CMakePackageConfigHelpers) + +At this point you should try and run CMake. If everything is setup properly +you will see that CMake will generate an error that looks like: + +.. code-block:: console + + Target "MathFunctions" INTERFACE_INCLUDE_DIRECTORIES property contains + path: + + "/Users/robert/Documents/CMakeClass/Tutorial/Step11/MathFunctions" + + which is prefixed in the source directory. + +What CMake is trying to say is that during generating the export information +it will export a path that is intrinsically tied to the current machine and +will not be valid on other machines. The solution to this is to update the +``MathFunctions`` :command:`target_include_directories` to understand that it +needs different ``INTERFACE`` locations when being used from within the build +directory and from an install / package. This means converting the +:command:`target_include_directories` call for ``MathFunctions`` to look like: + +.. literalinclude:: Step12/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-target_include_directories + :language: cmake + :start-after: # to find MathFunctions.h, while we don't. + :end-before: # should we use our own math functions + +Once this has been updated, we can re-run CMake and verify that it doesn't +warn anymore. + +At this point, we have CMake properly packaging the target information that is +required but we will still need to generate a ``MathFunctionsConfig.cmake`` so +that the CMake :command:`find_package` command can find our project. So let's go +ahead and add a new file to the top-level of the project called +``Config.cmake.in`` with the following contents: + +.. literalinclude:: Step12/Config.cmake.in + :caption: Config.cmake.in + :name: Config.cmake.in + +Then, to properly configure and install that file, add the following to the +bottom of the top-level ``CMakeLists.txt``: + +.. literalinclude:: Step12/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-install-Config.cmake + :language: cmake + :start-after: # install the configuration targets + :end-before: # generate the config file + + +Next, we execute the :command:`configure_package_config_file`. This command +will configure a provided file but with a few specific differences from the +standard :command:`configure_file` way. +To properly utilize this function, the input file should have a single line +with the text ``@PACKAGE_INIT@`` in addition to the content that is desired. +That variable will be replaced with a block of code which turns set values into +relative paths. These values which are new can be referenced by the same name +but prepended with a ``PACKAGE_`` prefix. + +.. literalinclude:: Step12/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-configure-package-config.cmake + :language: cmake + :start-after: # install the configuration targets + :end-before: # generate the version file + +The :command:`write_basic_package_version_file` is next. This command writes +a file which is used by the "find_package" document the version and +compatibility of the desired package. Here, we use the ``Tutorial_VERSION_*`` +variables and say that it is compatible with ``AnyNewerVersion``, which +denotes that this version or any higher one are compatible with the requested +version. + +.. literalinclude:: Step12/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-basic-version-file.cmake + :language: cmake + :start-after: # generate the version file + :end-before: # install the generated configuration files + +Finally, set both generated files to be installed: + +.. literalinclude:: Step12/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-install-configured-files.cmake + :language: cmake + :start-after: # install the generated configuration files + :end-before: # generate the export + +At this point, we have generated a relocatable CMake Configuration for our +project that can be used after the project has been installed or packaged. If +we want our project to also be used from a build directory we only have to add +the following to the bottom of the top level ``CMakeLists.txt``: + +.. literalinclude:: Step12/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-export + :language: cmake + :start-after: # needs to be after the install(TARGETS ) command + +With this export call we now generate a ``Targets.cmake``, allowing the +configured ``MathFunctionsConfig.cmake`` in the build directory to be used by +other projects, without needing it to be installed. diff --git a/Help/guide/tutorial/Adding Generator Expressions.rst b/Help/guide/tutorial/Adding Generator Expressions.rst new file mode 100644 index 0000000..7fcc97f --- /dev/null +++ b/Help/guide/tutorial/Adding Generator Expressions.rst @@ -0,0 +1,84 @@ +Step 10: Adding Generator Expressions +===================================== + +:manual:`Generator expressions <cmake-generator-expressions(7)>` are evaluated +during build system generation to produce information specific to each build +configuration. + +:manual:`Generator expressions <cmake-generator-expressions(7)>` are allowed in +the context of many target properties, such as :prop_tgt:`LINK_LIBRARIES`, +:prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_DEFINITIONS` and others. +They may also be used when using commands to populate those properties, such as +:command:`target_link_libraries`, :command:`target_include_directories`, +:command:`target_compile_definitions` and others. + +:manual:`Generator expressions <cmake-generator-expressions(7)>` may be used +to enable conditional linking, conditional definitions used when compiling, +conditional include directories and more. The conditions may be based on the +build configuration, target properties, platform information or any other +queryable information. + +There are different types of +:manual:`generator expressions <cmake-generator-expressions(7)>` including +Logical, Informational, and Output expressions. + +Logical expressions are used to create conditional output. The basic +expressions are the ``0`` and ``1`` expressions. A ``$<0:...>`` results in the +empty string, and ``<1:...>`` results in the content of ``...``. They can also +be nested. + +A common usage of +:manual:`generator expressions <cmake-generator-expressions(7)>` is to +conditionally add compiler flags, such as those for language levels or +warnings. A nice pattern is to associate this information to an ``INTERFACE`` +target allowing this information to propagate. Let's start by constructing an +``INTERFACE`` target and specifying the required C++ standard level of ``11`` +instead of using :variable:`CMAKE_CXX_STANDARD`. + +So the following code: + +.. literalinclude:: Step10/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-CXX_STANDARD-variable-remove + :language: cmake + :start-after: project(Tutorial VERSION 1.0) + :end-before: # control where the static and shared libraries are built so that on windows + +Would be replaced with: + +.. literalinclude:: Step11/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-cxx_std-feature + :language: cmake + :start-after: project(Tutorial VERSION 1.0) + :end-before: # add compiler warning flags just when building this project via + +**Note**: This upcoming section will require a change to the +:command:`cmake_minimum_required` usage in the code. The Generator Expression +that is about to be used was introduced in `3.15`. Update the call to require +that more recent version: + +.. code-block:: cmake + :caption: CMakeLists.txt + :name: CMakeLists.txt-version-update + + cmake_minimum_required(VERSION 3.15) + +Next we add the desired compiler warning flags that we want for our project. As +warning flags vary based on the compiler we use the ``COMPILE_LANG_AND_ID`` +generator expression to control which flags to apply given a language and a set +of compiler ids as seen below: + +.. literalinclude:: Step11/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-target_compile_options-genex + :language: cmake + :start-after: # the BUILD_INTERFACE genex + :end-before: # control where the static and shared libraries are built so that on windows + +Looking at this we see that the warning flags are encapsulated inside a +``BUILD_INTERFACE`` condition. This is done so that consumers of our installed +project will not inherit our warning flags. + +**Exercise**: Modify ``MathFunctions/CMakeLists.txt`` so that all targets have +a :command:`target_link_libraries` call to ``tutorial_compiler_flags``. diff --git a/Help/guide/tutorial/Adding Support for a Testing Dashboard.rst b/Help/guide/tutorial/Adding Support for a Testing Dashboard.rst new file mode 100644 index 0000000..c6e0fd0 --- /dev/null +++ b/Help/guide/tutorial/Adding Support for a Testing Dashboard.rst @@ -0,0 +1,75 @@ +Step 8: Adding Support for a Testing Dashboard +============================================== + +Adding support for submitting our test results to a dashboard is simple. We +already defined a number of tests for our project in +:ref:`Testing Support <Tutorial Testing Support>`. Now we just have to run +those tests and submit them to a dashboard. To include support for dashboards +we include the :module:`CTest` module in our top-level ``CMakeLists.txt``. + +Replace: + +.. code-block:: cmake + :caption: CMakeLists.txt + :name: CMakeLists.txt-enable_testing-remove + + # enable testing + enable_testing() + +With: + +.. code-block:: cmake + :caption: CMakeLists.txt + :name: CMakeLists.txt-include-CTest + + # enable dashboard scripting + include(CTest) + +The :module:`CTest` module will automatically call ``enable_testing()``, so we +can remove it from our CMake files. + +We will also need to acquire a ``CTestConfig.cmake`` file to be placed in the +top-level directory where we can specify information to CTest about the +project. It contains: + +* The project name + +* The project "Nightly" start time + + * The time when a 24 hour "day" starts for this project. + +* The URL of the CDash instance where the submission's generated documents + will be sent + +One has been provided for you in this directory. It would normally be +downloaded from the ``Settings`` page of the project on the CDash +instance that will host and display the test results. Once downloaded from +CDash, the file should not be modified locally. + +.. literalinclude:: Step9/CTestConfig.cmake + :caption: CTestConfig.cmake + :name: CTestConfig.cmake + :language: cmake + +The :manual:`ctest <ctest(1)>` executable will read in this file when it runs. +To create a simple dashboard you can run the :manual:`cmake <cmake(1)>` +executable or the :manual:`cmake-gui <cmake-gui(1)>` to configure the project, +but do not build it yet. Instead, change directory to the binary tree, and then +run: + +.. code-block:: console + + ctest [-VV] -D Experimental + +Remember, for multi-config generators (e.g. Visual Studio), the configuration +type must be specified: + +.. code-block:: console + + ctest [-VV] -C Debug -D Experimental + +Or, from an IDE, build the ``Experimental`` target. + +The :manual:`ctest <ctest(1)>` executable will build and test the project and +submit the results to Kitware's public dashboard: +https://my.cdash.org/index.php?project=CMakeTutorial. diff --git a/Help/guide/tutorial/Adding System Introspection.rst b/Help/guide/tutorial/Adding System Introspection.rst new file mode 100644 index 0000000..e149110 --- /dev/null +++ b/Help/guide/tutorial/Adding System Introspection.rst @@ -0,0 +1,61 @@ +Step 5: Adding System Introspection +=================================== + +Let us consider adding some code to our project that depends on features the +target platform may not have. For this example, we will add some code that +depends on whether or not the target platform has the ``log`` and ``exp`` +functions. Of course almost every platform has these functions but for this +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 +``MathFunctions/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. + +Add the checks for ``log`` and ``exp`` to ``MathFunctions/CMakeLists.txt``, +after the call to :command:`target_include_directories`: + +.. literalinclude:: Step6/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-check_symbol_exists + :language: cmake + :start-after: # to find MathFunctions.h, while we don't. + :end-before: # add compile definitions + +If available, use :command:`target_compile_definitions` to specify +``HAVE_LOG`` and ``HAVE_EXP`` as ``PRIVATE`` compile definitions. + +.. literalinclude:: Step6/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-target_compile_definitions + :language: cmake + :start-after: # add compile definitions + :end-before: # install rules + +If ``log`` and ``exp`` are available on the system, then we will use them to +compute the square root in the ``mysqrt`` function. Add the following code to +the ``mysqrt`` function in ``MathFunctions/mysqrt.cxx`` (don't forget the +``#endif`` before returning the result!): + +.. literalinclude:: Step6/MathFunctions/mysqrt.cxx + :caption: MathFunctions/mysqrt.cxx + :name: MathFunctions/mysqrt.cxx-ifdef + :language: c++ + :start-after: // if we have both log and exp then use them + :end-before: // do ten iterations + +We will also need to modify ``mysqrt.cxx`` to include ``cmath``. + +.. literalinclude:: Step6/MathFunctions/mysqrt.cxx + :caption: MathFunctions/mysqrt.cxx + :name: MathFunctions/mysqrt.cxx-include-cmath + :language: c++ + :end-before: #include <iostream> + +Run the :manual:`cmake <cmake(1)>` executable or the +:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it +with your chosen build tool and run the Tutorial executable. + +Which function gives better results now, ``sqrt`` or ``mysqrt``? diff --git a/Help/guide/tutorial/Adding Usage Requirements for a Library.rst b/Help/guide/tutorial/Adding Usage Requirements for a Library.rst new file mode 100644 index 0000000..a8e914e --- /dev/null +++ b/Help/guide/tutorial/Adding Usage Requirements for a Library.rst @@ -0,0 +1,52 @@ +Step 3: Adding Usage Requirements for a Library +=============================================== + +Usage requirements allow for far better control over a library or executable's +link and include line while also giving more control over the transitive +property of targets inside CMake. The primary commands that leverage usage +requirements are: + + - :command:`target_compile_definitions` + - :command:`target_compile_options` + - :command:`target_include_directories` + - :command:`target_link_libraries` + +Let's refactor our code from :guide:`tutorial/Adding a Library` to use the +modern CMake approach of usage requirements. We first state that anybody +linking to ``MathFunctions`` needs to include the current source directory, +while ``MathFunctions`` itself doesn't. So this can become an ``INTERFACE`` +usage requirement. + +Remember ``INTERFACE`` means things that consumers require but the producer +doesn't. Add the following lines to the end of +``MathFunctions/CMakeLists.txt``: + +.. literalinclude:: Step4/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-target_include_directories-INTERFACE + :language: cmake + :start-after: # to find MathFunctions.h + +Now that we've specified usage requirements for ``MathFunctions`` we can safely +remove our uses of the ``EXTRA_INCLUDES`` variable from the top-level +``CMakeLists.txt``, here: + +.. literalinclude:: Step4/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-remove-EXTRA_INCLUDES + :language: cmake + :start-after: # add the MathFunctions library + :end-before: # add the executable + +And here: + +.. literalinclude:: Step4/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-target_include_directories-remove-EXTRA_INCLUDES + :language: cmake + :start-after: # so that we will find TutorialConfig.h + +Once this is done, run the :manual:`cmake <cmake(1)>` executable or the +:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it +with your chosen build tool or by using ``cmake --build .`` from the build +directory. diff --git a/Help/guide/tutorial/Adding a Custom Command and Generated File.rst b/Help/guide/tutorial/Adding a Custom Command and Generated File.rst new file mode 100644 index 0000000..70c6695 --- /dev/null +++ b/Help/guide/tutorial/Adding a Custom Command and Generated File.rst @@ -0,0 +1,85 @@ +Step 6: Adding a Custom Command and Generated File +================================================== + +Suppose, for the purpose of this tutorial, we decide that we never want to use +the platform ``log`` and ``exp`` functions and instead would like to +generate a table of precomputed values to use in the ``mysqrt`` function. +In this section, we will create the table as part of the build process, +and then compile that table into our application. + +First, let's remove the check for the ``log`` and ``exp`` functions in +``MathFunctions/CMakeLists.txt``. Then remove the check for ``HAVE_LOG`` and +``HAVE_EXP`` from ``mysqrt.cxx``. At the same time, we can remove +:code:`#include <cmath>`. + +In the ``MathFunctions`` subdirectory, a new source file named +``MakeTable.cxx`` has been provided to generate the table. + +After reviewing the file, we can see that the table is produced as valid C++ +code and that the output filename is passed in as an argument. + +The next step is to add the appropriate commands to the +``MathFunctions/CMakeLists.txt`` file to build the MakeTable executable and +then run it as part of the build process. A few commands are needed to +accomplish this. + +First, at the top of ``MathFunctions/CMakeLists.txt``, the executable for +``MakeTable`` is added as any other executable would be added. + +.. literalinclude:: Step7/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-add_executable-MakeTable + :language: cmake + :start-after: # first we add the executable that generates the table + :end-before: # add the command to generate the source code + +Then we add a custom command that specifies how to produce ``Table.h`` +by running MakeTable. + +.. literalinclude:: Step7/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-add_custom_command-Table.h + :language: cmake + :start-after: # add the command to generate the source code + :end-before: # add the main library + +Next we have to let CMake know that ``mysqrt.cxx`` depends on the generated +file ``Table.h``. This is done by adding the generated ``Table.h`` to the list +of sources for the library MathFunctions. + +.. literalinclude:: Step7/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-add_library-Table.h + :language: cmake + :start-after: # add the main library + :end-before: # state that anybody linking + +We also have to add the current binary directory to the list of include +directories so that ``Table.h`` can be found and included by ``mysqrt.cxx``. + +.. literalinclude:: Step7/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-target_include_directories-Table.h + :language: cmake + :start-after: # state that we depend on our bin + :end-before: # install rules + +Now let's use the generated table. First, modify ``mysqrt.cxx`` to include +``Table.h``. Next, we can rewrite the ``mysqrt`` function to use the table: + +.. literalinclude:: Step7/MathFunctions/mysqrt.cxx + :caption: MathFunctions/mysqrt.cxx + :name: MathFunctions/mysqrt.cxx + :language: c++ + :start-after: // a hack square root calculation using simple operations + +Run the :manual:`cmake <cmake(1)>` executable or the +:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it +with your chosen build tool. + +When this project is built it will first build the ``MakeTable`` executable. +It will then run ``MakeTable`` to produce ``Table.h``. Finally, it will +compile ``mysqrt.cxx`` which includes ``Table.h`` to produce the +``MathFunctions`` library. + +Run the Tutorial executable and verify that it is using the table. diff --git a/Help/guide/tutorial/Adding a Library.rst b/Help/guide/tutorial/Adding a Library.rst new file mode 100644 index 0000000..71755be --- /dev/null +++ b/Help/guide/tutorial/Adding a Library.rst @@ -0,0 +1,136 @@ +Step 2: Adding a Library +======================== + +Now we will add a library to our project. This library will contain our own +implementation for computing the square root of a number. The executable can +then use this library instead of the standard square root function provided by +the compiler. + +For this tutorial we will put the library into a subdirectory +called ``MathFunctions``. This directory already contains a header file, +``MathFunctions.h``, and a source file ``mysqrt.cxx``. The source file has one +function called ``mysqrt`` that provides similar functionality to the +compiler's ``sqrt`` function. + +Add the following one line ``CMakeLists.txt`` file to the ``MathFunctions`` +directory: + +.. literalinclude:: Step3/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt + :language: cmake + +To make use of the new library we will add an :command:`add_subdirectory` +call in the top-level ``CMakeLists.txt`` file so that the library will get +built. We add the new library to the executable, and add ``MathFunctions`` as +an include directory so that the ``MathFunctions.h`` header file can be found. +The last few lines of the top-level ``CMakeLists.txt`` file should now look +like: + +.. code-block:: cmake + :caption: CMakeLists.txt + :name: CMakeLists.txt-add_subdirectory + + # add the MathFunctions library + add_subdirectory(MathFunctions) + + # add the executable + add_executable(Tutorial tutorial.cxx) + + target_link_libraries(Tutorial PUBLIC MathFunctions) + + # add the binary tree to the search path for include files + # so that we will find TutorialConfig.h + target_include_directories(Tutorial PUBLIC + "${PROJECT_BINARY_DIR}" + "${PROJECT_SOURCE_DIR}/MathFunctions" + ) + +Now let us make the ``MathFunctions`` library optional. While for the tutorial +there really isn't any need to do so, for larger projects this is a common +occurrence. The first step is to add an option to the top-level +``CMakeLists.txt`` file. + +.. literalinclude:: Step3/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-option + :language: cmake + :start-after: # should we use our own math functions + :end-before: # add the MathFunctions library + +This option will be displayed in the :manual:`cmake-gui <cmake-gui(1)>` and +:manual:`ccmake <ccmake(1)>` +with a default value of ``ON`` that can be changed by the user. This setting +will be stored in the cache so that the user does not need to set the value +each time they run CMake on a build directory. + +The next change is to make building and linking the ``MathFunctions`` library +conditional. To do this, we will create an ``if`` statement which checks the +value of the option. Inside the ``if`` block, put the +:command:`add_subdirectory` command from above with some additional list +commands to store information needed to link to the library and add the +subdirectory as an include directory in the ``Tutorial`` target. +The end of the top-level ``CMakeLists.txt`` file will now look like the +following: + +.. literalinclude:: Step3/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-target_link_libraries-EXTRA_LIBS + :language: cmake + :start-after: # add the MathFunctions library + +Note the use of the variable ``EXTRA_LIBS`` to collect up any optional +libraries to later be linked into the executable. The variable +``EXTRA_INCLUDES`` is used similarly for optional header files. This is a +classic approach when dealing with many optional components, we will cover +the modern approach in the next step. + +The corresponding changes to the source code are fairly straightforward. +First, in ``tutorial.cxx``, include the ``MathFunctions.h`` header if we +need it: + +.. literalinclude:: Step3/tutorial.cxx + :caption: tutorial.cxx + :name: tutorial.cxx-ifdef-include + :language: c++ + :start-after: // should we include the MathFunctions header + :end-before: int main + +Then, in the same file, make ``USE_MYMATH`` control which square root +function is used: + +.. literalinclude:: Step3/tutorial.cxx + :caption: tutorial.cxx + :name: tutorial.cxx-ifdef-const + :language: c++ + :start-after: // which square root function should we use? + :end-before: std::cout << "The square root of + +Since the source code now requires ``USE_MYMATH`` we can add it to +``TutorialConfig.h.in`` with the following line: + +.. literalinclude:: Step3/TutorialConfig.h.in + :caption: TutorialConfig.h.in + :name: TutorialConfig.h.in-cmakedefine + :language: c++ + :lines: 4 + +**Exercise**: Why is it important that we configure ``TutorialConfig.h.in`` +after the option for ``USE_MYMATH``? What would happen if we inverted the two? + +Run the :manual:`cmake <cmake(1)>` executable or the +:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it +with your chosen build tool. Then run the built Tutorial executable. + +Now let's update the value of ``USE_MYMATH``. The easiest way is to use the +:manual:`cmake-gui <cmake-gui(1)>` or :manual:`ccmake <ccmake(1)>` if you're +in the terminal. Or, alternatively, if you want to change the option from the +command-line, try: + +.. code-block:: console + + cmake ../Step2 -DUSE_MYMATH=OFF + +Rebuild and run the tutorial again. + +Which function gives better results, ``sqrt`` or ``mysqrt``? diff --git a/Help/guide/tutorial/Complete/CMakeLists.txt b/Help/guide/tutorial/Complete/CMakeLists.txt index 4d8a3ad..41baf64 100644 --- a/Help/guide/tutorial/Complete/CMakeLists.txt +++ b/Help/guide/tutorial/Complete/CMakeLists.txt @@ -10,7 +10,7 @@ target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) # add compiler warning flags just when building this project via # the BUILD_INTERFACE genex -set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU>") +set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>") set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") target_compile_options(tutorial_compiler_flags INTERFACE "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" @@ -73,7 +73,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -81,13 +81,14 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") include(InstallRequiredSystemLibraries) set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") +set(CPACK_SOURCE_GENERATOR "TGZ") include(CPack) # install the configuration targets diff --git a/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt index a47d5e0..40b9fd2 100644 --- a/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt @@ -62,6 +62,6 @@ if(TARGET SqrtLibrary) list(APPEND installable_libs SqrtLibrary) endif() install(TARGETS ${installable_libs} - DESTINATION lib - EXPORT MathFunctionsTargets) + EXPORT MathFunctionsTargets + DESTINATION lib) install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Installing and Testing.rst b/Help/guide/tutorial/Installing and Testing.rst new file mode 100644 index 0000000..394c986 --- /dev/null +++ b/Help/guide/tutorial/Installing and Testing.rst @@ -0,0 +1,95 @@ +Step 4: Installing and Testing +============================== + +Now we can start adding install rules and testing support to our project. + +Install Rules +------------- + +The install rules are fairly simple: for ``MathFunctions`` we want to install +the library and header file and for the application we want to install the +executable and configured header. + +So to the end of ``MathFunctions/CMakeLists.txt`` we add: + +.. literalinclude:: Step5/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-install-TARGETS + :language: cmake + :start-after: # install rules + +And to the end of the top-level ``CMakeLists.txt`` we add: + +.. literalinclude:: Step5/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-install-TARGETS + :language: cmake + :start-after: # add the install targets + :end-before: # enable testing + +That is all that is needed to create a basic local install of the tutorial. + +Now run the :manual:`cmake <cmake(1)>` executable or the +:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it +with your chosen build tool. + +Then run the install step by using the ``install`` option of the +:manual:`cmake <cmake(1)>` command (introduced in 3.15, older versions of +CMake must use ``make install``) from the command line. For +multi-configuration tools, don't forget to use the ``--config`` argument to +specify the configuration. If using an IDE, simply build the ``INSTALL`` +target. This step will install the appropriate header files, libraries, and +executables. For example: + +.. code-block:: console + + cmake --install . + +The CMake variable :variable:`CMAKE_INSTALL_PREFIX` is used to determine the +root of where the files will be installed. If using the ``cmake --install`` +command, the installation prefix can be overridden via the ``--prefix`` +argument. For example: + +.. code-block:: console + + cmake --install . --prefix "/home/myuser/installdir" + +Navigate to the install directory and verify that the installed Tutorial runs. + +.. _`Tutorial Testing Support`: + +Testing Support +--------------- + +Next let's test our application. At the end of the top-level ``CMakeLists.txt`` +file we can enable testing and then add a number of basic tests to verify that +the application is working correctly. + +.. literalinclude:: Step5/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-enable_testing + :language: cmake + :start-after: # enable testing + +The first test simply verifies that the application runs, does not segfault or +otherwise crash, and has a zero return value. This is the basic form of a +CTest test. + +The next test makes use of the :prop_test:`PASS_REGULAR_EXPRESSION` test +property to verify that the output of the test contains certain strings. In +this case, verifying that the usage message is printed when an incorrect number +of arguments are provided. + +Lastly, we have a function called ``do_test`` that runs the application and +verifies that the computed square root is correct for given input. For each +invocation of ``do_test``, another test is added to the project with a name, +input, and expected results based on the passed arguments. + +Rebuild the application and then cd to the binary directory and run the +:manual:`ctest <ctest(1)>` executable: ``ctest -N`` and ``ctest -VV``. For +multi-config generators (e.g. Visual Studio), the configuration type must be +specified with the ``-C <mode>`` flag. For example, to run tests in Debug +mode use ``ctest -C Debug -VV`` from the binary directory +(not the Debug subdirectory!). Release mode would be executed from the same +location but with a ``-C Release``. Alternatively, build the ``RUN_TESTS`` +target from the IDE. diff --git a/Help/guide/tutorial/Packaging Debug and Release.rst b/Help/guide/tutorial/Packaging Debug and Release.rst new file mode 100644 index 0000000..91b46a7 --- /dev/null +++ b/Help/guide/tutorial/Packaging Debug and Release.rst @@ -0,0 +1,86 @@ +Step 12: Packaging Debug and Release +==================================== + +**Note:** This example is valid for single-configuration generators and will +not work for multi-configuration generators (e.g. Visual Studio). + +By default, CMake's model is that a build directory only contains a single +configuration, be it Debug, Release, MinSizeRel, or RelWithDebInfo. It is +possible, however, to setup CPack to bundle multiple build directories and +construct a package that contains multiple configurations of the same project. + +First, we want to ensure that the debug and release builds use different names +for the executables and libraries that will be installed. Let's use `d` as the +postfix for the debug executable and libraries. + +Set :variable:`CMAKE_DEBUG_POSTFIX` near the beginning of the top-level +``CMakeLists.txt`` file: + +.. literalinclude:: Complete/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-CMAKE_DEBUG_POSTFIX-variable + :language: cmake + :start-after: project(Tutorial VERSION 1.0) + :end-before: target_compile_features(tutorial_compiler_flags + +And the :prop_tgt:`DEBUG_POSTFIX` property on the tutorial executable: + +.. literalinclude:: Complete/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-DEBUG_POSTFIX-property + :language: cmake + :start-after: # add the executable + :end-before: # add the binary tree to the search path for include files + +Let's also add version numbering to the ``MathFunctions`` library. In +``MathFunctions/CMakeLists.txt``, set the :prop_tgt:`VERSION` and +:prop_tgt:`SOVERSION` properties: + +.. literalinclude:: Complete/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-VERSION-properties + :language: cmake + :start-after: # setup the version numbering + :end-before: # install rules + +From the ``Step12`` directory, create ``debug`` and ``release`` +subbdirectories. The layout will look like: + +.. code-block:: none + + - Step12 + - debug + - release + +Now we need to setup debug and release builds. We can use +:variable:`CMAKE_BUILD_TYPE` to set the configuration type: + +.. code-block:: console + + cd debug + cmake -DCMAKE_BUILD_TYPE=Debug .. + cmake --build . + cd ../release + cmake -DCMAKE_BUILD_TYPE=Release .. + cmake --build . + +Now that both the debug and release builds are complete, we can use a custom +configuration file to package both builds into a single release. In the +``Step12`` directory, create a file called ``MultiCPackConfig.cmake``. In this +file, first include the default configuration file that was created by the +:manual:`cmake <cmake(1)>` executable. + +Next, use the ``CPACK_INSTALL_CMAKE_PROJECTS`` variable to specify which +projects to install. In this case, we want to install both debug and release. + +.. literalinclude:: Complete/MultiCPackConfig.cmake + :caption: MultiCPackConfig.cmake + :name: MultiCPackConfig.cmake + :language: cmake + +From the ``Step12`` directory, run :manual:`cpack <cpack(1)>` specifying our +custom configuration file with the ``config`` option: + +.. code-block:: console + + cpack --config MultiCPackConfig.cmake diff --git a/Help/guide/tutorial/Packaging an Installer.rst b/Help/guide/tutorial/Packaging an Installer.rst new file mode 100644 index 0000000..0ee5db2 --- /dev/null +++ b/Help/guide/tutorial/Packaging an Installer.rst @@ -0,0 +1,62 @@ +Step 7: Packaging an Installer +============================== + +Next suppose that we want to distribute our project to other people so that +they can use it. We want to provide both binary and source distributions on a +variety of platforms. This is a little different from the install we did +previously in :guide:`tutorial/Installing and Testing`, where we were +installing the binaries that we had built from the source code. In this +example we will be building installation packages that support binary +installations and package management features. To accomplish this we will use +CPack to create platform specific installers. Specifically we need to add a +few lines to the bottom of our top-level ``CMakeLists.txt`` file. + +.. literalinclude:: Step8/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-include-CPack + :language: cmake + :start-after: # setup installer + +That is all there is to it. We start by including +:module:`InstallRequiredSystemLibraries`. This module will include any runtime +libraries that are needed by the project for the current platform. Next we set +some CPack variables to where we have stored the license and version +information for this project. The version information was set earlier in this +tutorial and the ``License.txt`` has been included in the top-level source +directory for this step. The :variable:`CPACK_SOURCE_GENERATOR` variable +selects a file format for the source package. + +Finally we include the :module:`CPack module <CPack>` which will use these +variables and some other properties of the current system to setup an +installer. + +The next step is to build the project in the usual manner and then run the +:manual:`cpack <cpack(1)>` executable. To build a binary distribution, from the +binary directory run: + +.. code-block:: console + + cpack + +To specify the generator, use the ``-G`` option. For multi-config builds, use +``-C`` to specify the configuration. For example: + +.. code-block:: console + + cpack -G ZIP -C Debug + +For a list of available generators, see :manual:`cpack-generators(7)` or call +``cpack --help``. An :cpack_gen:`archive generator <CPack Archive Generator>` +like ZIP creates a compressed archive of all *installed* files. + +To create an archive of the *full* source tree you would type: + +.. code-block:: console + + cpack --config CPackSourceConfig.cmake + +Alternatively, run ``make package`` or right click the ``Package`` target and +``Build Project`` from an IDE. + +Run the installer found in the binary directory. Then run the installed +executable and verify that it works. diff --git a/Help/guide/tutorial/Selecting Static or Shared Libraries.rst b/Help/guide/tutorial/Selecting Static or Shared Libraries.rst new file mode 100644 index 0000000..2d5f70e --- /dev/null +++ b/Help/guide/tutorial/Selecting Static or Shared Libraries.rst @@ -0,0 +1,77 @@ +Step 9: Selecting Static or Shared Libraries +============================================ + +In this section we will show how the :variable:`BUILD_SHARED_LIBS` variable can +be used to control the default behavior of :command:`add_library`, +and allow control over how libraries without an explicit type (``STATIC``, +``SHARED``, ``MODULE`` or ``OBJECT``) are built. + +To accomplish this we need to add :variable:`BUILD_SHARED_LIBS` to the +top-level ``CMakeLists.txt``. We use the :command:`option` command as it allows +users to optionally select if the value should be ``ON`` or ``OFF``. + +Next we are going to refactor ``MathFunctions`` to become a real library that +encapsulates using ``mysqrt`` or ``sqrt``, instead of requiring the calling +code to do this logic. This will also mean that ``USE_MYMATH`` will not control +building ``MathFunctions``, but instead will control the behavior of this +library. + +The first step is to update the starting section of the top-level +``CMakeLists.txt`` to look like: + +.. literalinclude:: Step10/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-option-BUILD_SHARED_LIBS + :language: cmake + :end-before: # add the binary tree + +Now that we have made ``MathFunctions`` always be used, we will need to update +the logic of that library. So, in ``MathFunctions/CMakeLists.txt`` we need to +create a SqrtLibrary that will conditionally be built and installed when +``USE_MYMATH`` is enabled. Now, since this is a tutorial, we are going to +explicitly require that SqrtLibrary is built statically. + +The end result is that ``MathFunctions/CMakeLists.txt`` should look like: + +.. literalinclude:: Step10/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-add_library-STATIC + :language: cmake + :lines: 1-36,42- + +Next, update ``MathFunctions/mysqrt.cxx`` to use the ``mathfunctions`` and +``detail`` namespaces: + +.. literalinclude:: Step10/MathFunctions/mysqrt.cxx + :caption: MathFunctions/mysqrt.cxx + :name: MathFunctions/mysqrt.cxx-namespace + :language: c++ + +We also need to make some changes in ``tutorial.cxx``, so that it no longer +uses ``USE_MYMATH``: + +#. Always include ``MathFunctions.h`` +#. Always use ``mathfunctions::sqrt`` +#. Don't include ``cmath`` + +Finally, update ``MathFunctions/MathFunctions.h`` to use dll export defines: + +.. literalinclude:: Step10/MathFunctions/MathFunctions.h + :caption: MathFunctions/MathFunctions.h + :name: MathFunctions/MathFunctions.h + :language: c++ + +At this point, if you build everything, you may notice that linking fails +as we are combining a static library without position independent code with a +library that has position independent code. The solution to this is to +explicitly set the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property of +SqrtLibrary to be ``True`` no matter the build type. + +.. literalinclude:: Step10/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-POSITION_INDEPENDENT_CODE + :language: cmake + :lines: 37-42 + +**Exercise**: We modified ``MathFunctions.h`` to use dll export defines. +Using CMake documentation can you find a helper module to simplify this? diff --git a/Help/guide/tutorial/Step10/CMakeLists.txt b/Help/guide/tutorial/Step10/CMakeLists.txt index 34ae70c..55dc409 100644 --- a/Help/guide/tutorial/Step10/CMakeLists.txt +++ b/Help/guide/tutorial/Step10/CMakeLists.txt @@ -55,7 +55,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -63,11 +63,12 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") include(InstallRequiredSystemLibraries) set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") +set(CPACK_SOURCE_GENERATOR "TGZ") include(CPack) diff --git a/Help/guide/tutorial/Step11/CMakeLists.txt b/Help/guide/tutorial/Step11/CMakeLists.txt index 4763951..1044748 100644 --- a/Help/guide/tutorial/Step11/CMakeLists.txt +++ b/Help/guide/tutorial/Step11/CMakeLists.txt @@ -8,7 +8,7 @@ target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) # add compiler warning flags just when building this project via # the BUILD_INTERFACE genex -set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU>") +set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>") set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") target_compile_options(tutorial_compiler_flags INTERFACE "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" @@ -63,7 +63,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -71,11 +71,12 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") include(InstallRequiredSystemLibraries) set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") +set(CPACK_SOURCE_GENERATOR "TGZ") include(CPack) diff --git a/Help/guide/tutorial/Step12/CMakeLists.txt b/Help/guide/tutorial/Step12/CMakeLists.txt index eca79d9..63f9643 100644 --- a/Help/guide/tutorial/Step12/CMakeLists.txt +++ b/Help/guide/tutorial/Step12/CMakeLists.txt @@ -8,7 +8,7 @@ target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11) # add compiler warning flags just when building this project via # the BUILD_INTERFACE genex -set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU>") +set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>") set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") target_compile_options(tutorial_compiler_flags INTERFACE "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>" @@ -69,7 +69,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -77,7 +77,7 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") include(InstallRequiredSystemLibraries) @@ -107,9 +107,10 @@ write_basic_package_version_file( COMPATIBILITY AnyNewerVersion ) -# install the configuration file +# install the generated configuration files install(FILES ${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake + ${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfigVersion.cmake DESTINATION lib/cmake/MathFunctions ) diff --git a/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt index ea3861c..d5961da 100644 --- a/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt @@ -58,6 +58,6 @@ if(TARGET SqrtLibrary) list(APPEND installable_libs SqrtLibrary) endif() install(TARGETS ${installable_libs} - DESTINATION lib - EXPORT MathFunctionsTargets) + EXPORT MathFunctionsTargets + DESTINATION lib) install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step5/CMakeLists.txt b/Help/guide/tutorial/Step5/CMakeLists.txt index c3b375a..82d00c8 100644 --- a/Help/guide/tutorial/Step5/CMakeLists.txt +++ b/Help/guide/tutorial/Step5/CMakeLists.txt @@ -54,7 +54,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -62,5 +62,5 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") diff --git a/Help/guide/tutorial/Step6/CMakeLists.txt b/Help/guide/tutorial/Step6/CMakeLists.txt index c3b375a..82d00c8 100644 --- a/Help/guide/tutorial/Step6/CMakeLists.txt +++ b/Help/guide/tutorial/Step6/CMakeLists.txt @@ -54,7 +54,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -62,5 +62,5 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") diff --git a/Help/guide/tutorial/Step7/CMakeLists.txt b/Help/guide/tutorial/Step7/CMakeLists.txt index c3b375a..82d00c8 100644 --- a/Help/guide/tutorial/Step7/CMakeLists.txt +++ b/Help/guide/tutorial/Step7/CMakeLists.txt @@ -54,7 +54,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -62,5 +62,5 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") diff --git a/Help/guide/tutorial/Step8/CMakeLists.txt b/Help/guide/tutorial/Step8/CMakeLists.txt index 19b9913..4c78b94 100644 --- a/Help/guide/tutorial/Step8/CMakeLists.txt +++ b/Help/guide/tutorial/Step8/CMakeLists.txt @@ -54,7 +54,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -62,7 +62,7 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") # setup installer @@ -70,4 +70,5 @@ include(InstallRequiredSystemLibraries) set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") +set(CPACK_SOURCE_GENERATOR "TGZ") include(CPack) diff --git a/Help/guide/tutorial/Step8/CTestConfig.cmake b/Help/guide/tutorial/Step8/CTestConfig.cmake new file mode 100644 index 0000000..73efdb1 --- /dev/null +++ b/Help/guide/tutorial/Step8/CTestConfig.cmake @@ -0,0 +1,7 @@ +set(CTEST_PROJECT_NAME "CMakeTutorial") +set(CTEST_NIGHTLY_START_TIME "00:00:00 EST") + +set(CTEST_DROP_METHOD "http") +set(CTEST_DROP_SITE "my.cdash.org") +set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial") +set(CTEST_DROP_SITE_CDASH TRUE) diff --git a/Help/guide/tutorial/Step9/CMakeLists.txt b/Help/guide/tutorial/Step9/CMakeLists.txt index d5f1cc8..6bae26e 100644 --- a/Help/guide/tutorial/Step9/CMakeLists.txt +++ b/Help/guide/tutorial/Step9/CMakeLists.txt @@ -54,7 +54,7 @@ function(do_test target arg result) set_tests_properties(Comp${arg} PROPERTIES PASS_REGULAR_EXPRESSION ${result} ) -endfunction(do_test) +endfunction() # do a bunch of result based tests do_test(Tutorial 4 "4 is 2") @@ -62,11 +62,12 @@ do_test(Tutorial 9 "9 is 3") do_test(Tutorial 5 "5 is 2.236") do_test(Tutorial 7 "7 is 2.645") do_test(Tutorial 25 "25 is 5") -do_test(Tutorial -25 "-25 is [-nan|nan|0]") +do_test(Tutorial -25 "-25 is (-nan|nan|0)") do_test(Tutorial 0.0001 "0.0001 is 0.01") include(InstallRequiredSystemLibraries) set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt") set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}") set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}") +set(CPACK_SOURCE_GENERATOR "TGZ") include(CPack) diff --git a/Help/guide/tutorial/index.rst b/Help/guide/tutorial/index.rst index 94753d5..09553cb 100644 --- a/Help/guide/tutorial/index.rst +++ b/Help/guide/tutorial/index.rst @@ -1,946 +1,44 @@ CMake Tutorial ************** -.. only:: html - - .. contents:: - Introduction ============ The CMake tutorial provides a step-by-step guide that covers common build system issues that CMake helps address. Seeing how various topics all -work together in an example project can be very helpful. The tutorial -documentation and source code for examples can be found in the -``Help/guide/tutorial`` directory of the CMake source code tree. Each step has -its own subdirectory containing code that may be used as a starting point. The -tutorial examples are progressive so that each step provides the complete -solution for the previous step. - -A Basic Starting Point (Step 1) -=============================== - -The most basic project is an executable built from source code files. -For simple projects, a three line ``CMakeLists.txt`` file is all that is -required. This will be the starting point for our tutorial. Create a -``CMakeLists.txt`` file in the ``Step1`` directory that looks like: - -.. code-block:: cmake - - cmake_minimum_required(VERSION 3.10) - - # set the project name - project(Tutorial) - - # add the executable - add_executable(Tutorial tutorial.cxx) - - -Note that this example uses lower case commands in the ``CMakeLists.txt`` file. -Upper, lower, and mixed case commands are supported by CMake. The source -code for ``tutorial.cxx`` is provided in the ``Step1`` directory and can be -used to compute the square root of a number. - -Adding a Version Number and Configured Header File --------------------------------------------------- - -The first feature we will add is to provide our executable and project with a -version number. While we could do this exclusively in the source code, using -``CMakeLists.txt`` provides more flexibility. - -First, modify the ``CMakeLists.txt`` file to use the :command:`project` command -to set the project name and version number. - -.. literalinclude:: Step2/CMakeLists.txt - :language: cmake - :end-before: # specify the C++ standard - -Then, configure a header file to pass the version number to the source -code: - -.. literalinclude:: Step2/CMakeLists.txt - :language: cmake - :start-after: # to the source code - :end-before: # add the executable - -Since the configured file will be written into the binary tree, we -must add that directory to the list of paths to search for include -files. Add the following lines to the end of the ``CMakeLists.txt`` file: - -.. literalinclude:: Step2/CMakeLists.txt - :language: cmake - :start-after: # so that we will find TutorialConfig.h - -Using your favorite editor, create ``TutorialConfig.h.in`` in the source -directory with the following contents: - -.. literalinclude:: Step2/TutorialConfig.h.in - :language: cmake - -When CMake configures this header file the values for -``@Tutorial_VERSION_MAJOR@`` and ``@Tutorial_VERSION_MINOR@`` will be -replaced. - -Next modify ``tutorial.cxx`` to include the configured header file, -``TutorialConfig.h``. - -Finally, let's print out the executable name and version number by updating -``tutorial.cxx`` as follows: - -.. literalinclude:: Step2/tutorial.cxx - :language: c++ - :start-after: { - :end-before: // convert input to double - -Specify the C++ Standard -------------------------- - -Next let's add some C++11 features to our project by replacing ``atof`` with -``std::stod`` in ``tutorial.cxx``. At the same time, remove -``#include <cstdlib>``. - -.. literalinclude:: Step2/tutorial.cxx - :language: c++ - :start-after: // convert input to double - :end-before: // calculate square root - -We will need to explicitly state in the CMake code that it should use the -correct flags. The easiest way to enable support for a specific C++ standard -in CMake is by using the :variable:`CMAKE_CXX_STANDARD` variable. For this -tutorial, set the :variable:`CMAKE_CXX_STANDARD` variable in the -``CMakeLists.txt`` file to 11 and :variable:`CMAKE_CXX_STANDARD_REQUIRED` to -True. Make sure to add the ``CMAKE_CXX_STANDARD`` declarations above the call -to ``add_executable``. - -.. literalinclude:: Step2/CMakeLists.txt - :language: cmake - :end-before: # configure a header file to pass some of the CMake settings - -Build and Test --------------- - -Run the :manual:`cmake <cmake(1)>` executable or the -:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it -with your chosen build tool. - -For example, from the command line we could navigate to the -``Help/guide/tutorial`` directory of the CMake source code tree and create a -build directory: - -.. code-block:: console - - mkdir Step1_build - -Next, navigate to the build directory and run CMake to configure the project -and generate a native build system: - -.. code-block:: console - - cd Step1_build - cmake ../Step1 - -Then call that build system to actually compile/link the project: - -.. code-block:: console - - cmake --build . - -Finally, try to use the newly built ``Tutorial`` with these commands: - -.. code-block:: console - - Tutorial 4294967296 - Tutorial 10 - Tutorial - -Adding a Library (Step 2) -========================= - -Now we will add a library to our project. This library will contain our own -implementation for computing the square root of a number. The executable can -then use this library instead of the standard square root function provided by -the compiler. - -For this tutorial we will put the library into a subdirectory -called ``MathFunctions``. This directory already contains a header file, -``MathFunctions.h``, and a source file ``mysqrt.cxx``. The source file has one -function called ``mysqrt`` that provides similar functionality to the -compiler's ``sqrt`` function. - -Add the following one line ``CMakeLists.txt`` file to the ``MathFunctions`` -directory: - -.. literalinclude:: Step3/MathFunctions/CMakeLists.txt - :language: cmake - -To make use of the new library we will add an :command:`add_subdirectory` -call in the top-level ``CMakeLists.txt`` file so that the library will get -built. We add the new library to the executable, and add ``MathFunctions`` as -an include directory so that the ``mysqrt.h`` header file can be found. The -last few lines of the top-level ``CMakeLists.txt`` file should now look like: - -.. code-block:: cmake - - # add the MathFunctions library - add_subdirectory(MathFunctions) - - # add the executable - add_executable(Tutorial tutorial.cxx) - - target_link_libraries(Tutorial PUBLIC MathFunctions) - - # add the binary tree to the search path for include files - # so that we will find TutorialConfig.h - target_include_directories(Tutorial PUBLIC - "${PROJECT_BINARY_DIR}" - "${PROJECT_SOURCE_DIR}/MathFunctions" - ) - -Now let us make the MathFunctions library optional. While for the tutorial -there really isn't any need to do so, for larger projects this is a common -occurrence. The first step is to add an option to the top-level -``CMakeLists.txt`` file. - -.. literalinclude:: Step3/CMakeLists.txt - :language: cmake - :start-after: # should we use our own math functions - :end-before: # add the MathFunctions library - -This option will be displayed in the :manual:`cmake-gui <cmake-gui(1)>` and -:manual:`ccmake <ccmake(1)>` -with a default value of ON that can be changed by the user. This setting will -be stored in the cache so that the user does not need to set the value each -time they run CMake on a build directory. - -The next change is to make building and linking the MathFunctions library -conditional. To do this we change the end of the top-level ``CMakeLists.txt`` -file to look like the following: - -.. literalinclude:: Step3/CMakeLists.txt - :language: cmake - :start-after: # add the MathFunctions library - -Note the use of the variable ``EXTRA_LIBS`` to collect up any optional -libraries to later be linked into the executable. The variable -``EXTRA_INCLUDES`` is used similarly for optional header files. This is a -classic approach when dealing with many optional components, we will cover -the modern approach in the next step. - -The corresponding changes to the source code are fairly straightforward. -First, in ``tutorial.cxx``, include the ``MathFunctions.h`` header if we -need it: - -.. literalinclude:: Step3/tutorial.cxx - :language: c++ - :start-after: // should we include the MathFunctions header - :end-before: int main - -Then, in the same file, make ``USE_MYMATH`` control which square root -function is used: - -.. literalinclude:: Step3/tutorial.cxx - :language: c++ - :start-after: // which square root function should we use? - :end-before: std::cout << "The square root of - -Since the source code now requires ``USE_MYMATH`` we can add it to -``TutorialConfig.h.in`` with the following line: - -.. literalinclude:: Step3/TutorialConfig.h.in - :language: c - :lines: 4 - -**Exercise**: Why is it important that we configure ``TutorialConfig.h.in`` -after the option for ``USE_MYMATH``? What would happen if we inverted the two? - -Run the :manual:`cmake <cmake(1)>` executable or the -:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it -with your chosen build tool. Then run the built Tutorial executable. - -Now let's update the value of ``USE_MYMATH``. The easiest way is to use the -:manual:`cmake-gui <cmake-gui(1)>` or :manual:`ccmake <ccmake(1)>` if you're -in the terminal. Or, alternatively, if you want to change the option from the -command-line, try: - -.. code-block:: console - - cmake ../Step2 -DUSE_MYMATH=OFF - -Rebuild and run the tutorial again. - -Which function gives better results, sqrt or mysqrt? - -Adding Usage Requirements for Library (Step 3) -============================================== - -Usage requirements allow for far better control over a library or executable's -link and include line while also giving more control over the transitive -property of targets inside CMake. The primary commands that leverage usage -requirements are: - - - :command:`target_compile_definitions` - - :command:`target_compile_options` - - :command:`target_include_directories` - - :command:`target_link_libraries` - -Let's refactor our code from `Adding a Library (Step 2)`_ to use the modern -CMake approach of usage requirements. We first state that anybody linking to -MathFunctions needs to include the current source directory, while -MathFunctions itself doesn't. So this can become an ``INTERFACE`` usage -requirement. - -Remember ``INTERFACE`` means things that consumers require but the producer -doesn't. Add the following lines to the end of -``MathFunctions/CMakeLists.txt``: - -.. literalinclude:: Step4/MathFunctions/CMakeLists.txt - :language: cmake - :start-after: # to find MathFunctions.h - -Now that we've specified usage requirements for MathFunctions we can safely -remove our uses of the ``EXTRA_INCLUDES`` variable from the top-level -``CMakeLists.txt``, here: - -.. literalinclude:: Step4/CMakeLists.txt - :language: cmake - :start-after: # add the MathFunctions library - :end-before: # add the executable - -And here: - -.. literalinclude:: Step4/CMakeLists.txt - :language: cmake - :start-after: # so that we will find TutorialConfig.h - -Once this is done, run the :manual:`cmake <cmake(1)>` executable or the -:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it -with your chosen build tool or by using ``cmake --build .`` from the build -directory. - -Installing and Testing (Step 4) -=============================== - -Now we can start adding install rules and testing support to our project. - -Install Rules -------------- - -The install rules are fairly simple: for MathFunctions we want to install the -library and header file and for the application we want to install the -executable and configured header. - -So to the end of ``MathFunctions/CMakeLists.txt`` we add: - -.. literalinclude:: Step5/MathFunctions/CMakeLists.txt - :language: cmake - :start-after: # install rules - -And to the end of the top-level ``CMakeLists.txt`` we add: - -.. literalinclude:: Step5/CMakeLists.txt - :language: cmake - :start-after: # add the install targets - :end-before: # enable testing - -That is all that is needed to create a basic local install of the tutorial. - -Now run the :manual:`cmake <cmake(1)>` executable or the -:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it -with your chosen build tool. - -Then run the install step by using the ``install`` option of the -:manual:`cmake <cmake(1)>` command (introduced in 3.15, older versions of -CMake must use ``make install``) from the command line. For -multi-configuration tools, don't forget to use the ``--config`` argument to -specify the configuration. If using an IDE, simply build the ``INSTALL`` -target. This step will install the appropriate header files, libraries, and -executables. For example: - -.. code-block:: console - - cmake --install . - -The CMake variable :variable:`CMAKE_INSTALL_PREFIX` is used to determine the -root of where the files will be installed. If using the ``cmake --install`` -command, the installation prefix can be overridden via the ``--prefix`` -argument. For example: - -.. code-block:: console - - cmake --install . --prefix "/home/myuser/installdir" - -Navigate to the install directory and verify that the installed Tutorial runs. - -Testing Support ---------------- - -Next let's test our application. At the end of the top-level ``CMakeLists.txt`` -file we can enable testing and then add a number of basic tests to verify that -the application is working correctly. - -.. literalinclude:: Step5/CMakeLists.txt - :language: cmake - :start-after: # enable testing - -The first test simply verifies that the application runs, does not segfault or -otherwise crash, and has a zero return value. This is the basic form of a -CTest test. - -The next test makes use of the :prop_test:`PASS_REGULAR_EXPRESSION` test -property to verify that the output of the test contains certain strings. In -this case, verifying that the usage message is printed when an incorrect number -of arguments are provided. - -Lastly, we have a function called ``do_test`` that runs the application and -verifies that the computed square root is correct for given input. For each -invocation of ``do_test``, another test is added to the project with a name, -input, and expected results based on the passed arguments. - -Rebuild the application and then cd to the binary directory and run the -:manual:`ctest <ctest(1)>` executable: ``ctest -N`` and ``ctest -VV``. For -multi-config generators (e.g. Visual Studio), the configuration type must be -specified. To run tests in Debug mode, for example, use ``ctest -C Debug -VV`` -from the build directory (not the Debug subdirectory!). Alternatively, build -the ``RUN_TESTS`` target from the IDE. - -Adding System Introspection (Step 5) -==================================== - -Let us consider adding some code to our project that depends on features the -target platform may not have. For this example, we will add some code that -depends on whether or not the target platform has the ``log`` and ``exp`` -functions. Of course almost every platform has these functions but for this -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 -``MathFunctions/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. - -.. literalinclude:: Step6/MathFunctions/CMakeLists.txt - :language: cmake - :start-after: # does this system provide the log and exp functions? - :end-before: # add compile definitions - -If available, use :command:`target_compile_definitions` to specify -``HAVE_LOG`` and ``HAVE_EXP`` as ``PRIVATE`` compile definitions. - -.. literalinclude:: Step6/MathFunctions/CMakeLists.txt - :language: cmake - :start-after: # add compile definitions - :end-before: # install rules - -If ``log`` and ``exp`` are available on the system, then we will use them to -compute the square root in the ``mysqrt`` function. Add the following code to -the ``mysqrt`` function in ``MathFunctions/mysqrt.cxx`` (don't forget the -``#endif`` before returning the result!): - -.. literalinclude:: Step6/MathFunctions/mysqrt.cxx - :language: c++ - :start-after: // if we have both log and exp then use them - :end-before: // do ten iterations - -We will also need to modify ``mysqrt.cxx`` to include ``cmath``. - -.. literalinclude:: Step6/MathFunctions/mysqrt.cxx - :language: c++ - :end-before: #include <iostream> - -Run the :manual:`cmake <cmake(1)>` executable or the -:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it -with your chosen build tool and run the Tutorial executable. - -Which function gives better results now, sqrt or mysqrt? - -Adding a Custom Command and Generated File (Step 6) -=================================================== - -Suppose, for the purpose of this tutorial, we decide that we never want to use -the platform ``log`` and ``exp`` functions and instead would like to -generate a table of precomputed values to use in the ``mysqrt`` function. -In this section, we will create the table as part of the build process, -and then compile that table into our application. - -First, let's remove the check for the ``log`` and ``exp`` functions in -``MathFunctions/CMakeLists.txt``. Then remove the check for ``HAVE_LOG`` and -``HAVE_EXP`` from ``mysqrt.cxx``. At the same time, we can remove -:code:`#include <cmath>`. - -In the ``MathFunctions`` subdirectory, a new source file named -``MakeTable.cxx`` has been provided to generate the table. - -After reviewing the file, we can see that the table is produced as valid C++ -code and that the output filename is passed in as an argument. - -The next step is to add the appropriate commands to the -``MathFunctions/CMakeLists.txt`` file to build the MakeTable executable and -then run it as part of the build process. A few commands are needed to -accomplish this. - -First, at the top of ``MathFunctions/CMakeLists.txt``, the executable for -``MakeTable`` is added as any other executable would be added. - -.. literalinclude:: Step7/MathFunctions/CMakeLists.txt - :language: cmake - :start-after: # first we add the executable that generates the table - :end-before: # add the command to generate the source code - -Then we add a custom command that specifies how to produce ``Table.h`` -by running MakeTable. - -.. literalinclude:: Step7/MathFunctions/CMakeLists.txt - :language: cmake - :start-after: # add the command to generate the source code - :end-before: # add the main library - -Next we have to let CMake know that ``mysqrt.cxx`` depends on the generated -file ``Table.h``. This is done by adding the generated ``Table.h`` to the list -of sources for the library MathFunctions. - -.. literalinclude:: Step7/MathFunctions/CMakeLists.txt - :language: cmake - :start-after: # add the main library - :end-before: # state that anybody linking - -We also have to add the current binary directory to the list of include -directories so that ``Table.h`` can be found and included by ``mysqrt.cxx``. - -.. literalinclude:: Step7/MathFunctions/CMakeLists.txt - :language: cmake - :start-after: # state that we depend on our bin - :end-before: # install rules - -Now let's use the generated table. First, modify ``mysqrt.cxx`` to include -``Table.h``. Next, we can rewrite the mysqrt function to use the table: - -.. literalinclude:: Step7/MathFunctions/mysqrt.cxx - :language: c++ - :start-after: // a hack square root calculation using simple operations - -Run the :manual:`cmake <cmake(1)>` executable or the -:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it -with your chosen build tool. - -When this project is built it will first build the ``MakeTable`` executable. -It will then run ``MakeTable`` to produce ``Table.h``. Finally, it will -compile ``mysqrt.cxx`` which includes ``Table.h`` to produce the MathFunctions -library. - -Run the Tutorial executable and verify that it is using the table. - -Building an Installer (Step 7) -============================== - -Next suppose that we want to distribute our project to other people so that -they can use it. We want to provide both binary and source distributions on a -variety of platforms. This is a little different from the install we did -previously in `Installing and Testing (Step 4)`_ , where we were -installing the binaries that we had built from the source code. In this -example we will be building installation packages that support binary -installations and package management features. To accomplish this we will use -CPack to create platform specific installers. Specifically we need to add a -few lines to the bottom of our top-level ``CMakeLists.txt`` file. - -.. literalinclude:: Step8/CMakeLists.txt - :language: cmake - :start-after: # setup installer - -That is all there is to it. We start by including -:module:`InstallRequiredSystemLibraries`. This module will include any runtime -libraries that are needed by the project for the current platform. Next we set -some CPack variables to where we have stored the license and version -information for this project. The version information was set earlier in this -tutorial and the ``license.txt`` has been included in the top-level source -directory for this step. - -Finally we include the :module:`CPack module <CPack>` which will use these -variables and some other properties of the current system to setup an -installer. - -The next step is to build the project in the usual manner and then run the -:manual:`cpack <cpack(1)>` executable. To build a binary distribution, from the -binary directory run: - -.. code-block:: console - - cpack - -To specify the generator, use the ``-G`` option. For multi-config builds, use -``-C`` to specify the configuration. For example: - -.. code-block:: console - - cpack -G ZIP -C Debug - -To create a source distribution you would type: - -.. code-block:: console - - cpack --config CPackSourceConfig.cmake - -Alternatively, run ``make package`` or right click the ``Package`` target and -``Build Project`` from an IDE. - -Run the installer found in the binary directory. Then run the installed -executable and verify that it works. - -Adding Support for a Dashboard (Step 8) -======================================= - -Adding support for submitting our test results to a dashboard is simple. We -already defined a number of tests for our project in `Testing Support`_. Now we -just have to run those tests and submit them to a dashboard. To include support -for dashboards we include the :module:`CTest` module in our top-level -``CMakeLists.txt``. - -Replace: - -.. code-block:: cmake - - # enable testing - enable_testing() - -With: - -.. code-block:: cmake - - # enable dashboard scripting - include(CTest) - -The :module:`CTest` module will automatically call ``enable_testing()``, so we -can remove it from our CMake files. - -We will also need to create a ``CTestConfig.cmake`` file in the top-level -directory where we can specify the name of the project and where to submit the -dashboard. - -.. literalinclude:: Step9/CTestConfig.cmake - :language: cmake - -The :manual:`ctest <ctest(1)>` executable will read in this file when it runs. -To create a simple dashboard you can run the :manual:`cmake <cmake(1)>` -executable or the :manual:`cmake-gui <cmake-gui(1)>` to configure the project, -but do not build it yet. Instead, change directory to the binary tree, and then -run: - - ctest [-VV] -D Experimental - -Remember, for multi-config generators (e.g. Visual Studio), the configuration -type must be specified:: - - ctest [-VV] -C Debug -D Experimental - -Or, from an IDE, build the ``Experimental`` target. - -The :manual:`ctest <ctest(1)>` executable will build and test the project and -submit the results to Kitware's public dashboard: -https://my.cdash.org/index.php?project=CMakeTutorial. - -Mixing Static and Shared (Step 9) -================================= - -In this section we will show how the :variable:`BUILD_SHARED_LIBS` variable can -be used to control the default behavior of :command:`add_library`, -and allow control over how libraries without an explicit type (``STATIC``, -``SHARED``, ``MODULE`` or ``OBJECT``) are built. - -To accomplish this we need to add :variable:`BUILD_SHARED_LIBS` to the -top-level ``CMakeLists.txt``. We use the :command:`option` command as it allows -users to optionally select if the value should be ON or OFF. - -Next we are going to refactor MathFunctions to become a real library that -encapsulates using ``mysqrt`` or ``sqrt``, instead of requiring the calling -code to do this logic. This will also mean that ``USE_MYMATH`` will not control -building MathFunctions, but instead will control the behavior of this library. - -The first step is to update the starting section of the top-level -``CMakeLists.txt`` to look like: - -.. literalinclude:: Step10/CMakeLists.txt - :language: cmake - :end-before: # add the binary tree - -Now that we have made MathFunctions always be used, we will need to update -the logic of that library. So, in ``MathFunctions/CMakeLists.txt`` we need to -create a SqrtLibrary that will conditionally be built and installed when -``USE_MYMATH`` is enabled. Now, since this is a tutorial, we are going to -explicitly require that SqrtLibrary is built statically. - -The end result is that ``MathFunctions/CMakeLists.txt`` should look like: - -.. literalinclude:: Step10/MathFunctions/CMakeLists.txt - :language: cmake - :lines: 1-36,42- - -Next, update ``MathFunctions/mysqrt.cxx`` to use the ``mathfunctions`` and -``detail`` namespaces: - -.. literalinclude:: Step10/MathFunctions/mysqrt.cxx - :language: c++ - -We also need to make some changes in ``tutorial.cxx``, so that it no longer -uses ``USE_MYMATH``: - -#. Always include ``MathFunctions.h`` -#. Always use ``mathfunctions::sqrt`` -#. Don't include cmath - -Finally, update ``MathFunctions/MathFunctions.h`` to use dll export defines: - -.. literalinclude:: Step10/MathFunctions/MathFunctions.h - :language: c++ - -At this point, if you build everything, you may notice that linking fails -as we are combining a static library without position independent code with a -library that has position independent code. The solution to this is to -explicitly set the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property of -SqrtLibrary to be True no matter the build type. - -.. literalinclude:: Step10/MathFunctions/CMakeLists.txt - :language: cmake - :lines: 37-42 - -**Exercise**: We modified ``MathFunctions.h`` to use dll export defines. -Using CMake documentation can you find a helper module to simplify this? - - -Adding Generator Expressions (Step 10) -====================================== - -:manual:`Generator expressions <cmake-generator-expressions(7)>` are evaluated -during build system generation to produce information specific to each build -configuration. - -:manual:`Generator expressions <cmake-generator-expressions(7)>` are allowed in -the context of many target properties, such as :prop_tgt:`LINK_LIBRARIES`, -:prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_DEFINITIONS` and others. -They may also be used when using commands to populate those properties, such as -:command:`target_link_libraries`, :command:`target_include_directories`, -:command:`target_compile_definitions` and others. - -:manual:`Generator expressions <cmake-generator-expressions(7)>` may be used -to enable conditional linking, conditional definitions used when compiling, -conditional include directories and more. The conditions may be based on the -build configuration, target properties, platform information or any other -queryable information. - -There are different types of -:manual:`generator expressions <cmake-generator-expressions(7)>` including -Logical, Informational, and Output expressions. - -Logical expressions are used to create conditional output. The basic -expressions are the 0 and 1 expressions. A ``$<0:...>`` results in the empty -string, and ``<1:...>`` results in the content of "...". They can also be -nested. - -A common usage of -:manual:`generator expressions <cmake-generator-expressions(7)>` is to -conditionally add compiler flags, such as those for language levels or -warnings. A nice pattern is to associate this information to an ``INTERFACE`` -target allowing this information to propagate. Let's start by constructing an -``INTERFACE`` target and specifying the required C++ standard level of ``11`` -instead of using :variable:`CMAKE_CXX_STANDARD`. - -So the following code: - -.. literalinclude:: Step10/CMakeLists.txt - :language: cmake - :start-after: project(Tutorial VERSION 1.0) - :end-before: # control where the static and shared libraries are built so that on windows - -Would be replaced with: - -.. literalinclude:: Step11/CMakeLists.txt - :language: cmake - :start-after: project(Tutorial VERSION 1.0) - :end-before: # add compiler warning flags just when building this project via - - -Next we add the desired compiler warning flags that we want for our project. As -warning flags vary based on the compiler we use the ``COMPILE_LANG_AND_ID`` -generator expression to control which flags to apply given a language and a set -of compiler ids as seen below: - -.. literalinclude:: Step11/CMakeLists.txt - :language: cmake - :start-after: # the BUILD_INTERFACE genex - :end-before: # control where the static and shared libraries are built so that on windows - -Looking at this we see that the warning flags are encapsulated inside a -``BUILD_INTERFACE`` condition. This is done so that consumers of our installed -project will not inherit our warning flags. - - -**Exercise**: Modify ``MathFunctions/CMakeLists.txt`` so that all targets have -a :command:`target_link_libraries` call to ``tutorial_compiler_flags``. - - -Adding Export Configuration (Step 11) -===================================== - -During `Installing and Testing (Step 4)`_ of the tutorial we added the ability -for CMake to install the library and headers of the project. During -`Building an Installer (Step 7)`_ we added the ability to package up this -information so it could be distributed to other people. - -The next step is to add the necessary information so that other CMake projects -can use our project, be it from a build directory, a local install or when -packaged. - -The first step is to update our :command:`install(TARGETS)` commands to not -only specify a ``DESTINATION`` but also an ``EXPORT``. The ``EXPORT`` keyword -generates and installs a CMake file containing code to import all targets -listed in the install command from the installation tree. So let's go ahead and -explicitly ``EXPORT`` the MathFunctions library by updating the ``install`` -command in ``MathFunctions/CMakeLists.txt`` to look like: - -.. literalinclude:: Complete/MathFunctions/CMakeLists.txt - :language: cmake - :start-after: # install rules - -Now that we have MathFunctions being exported, we also need to explicitly -install the generated ``MathFunctionsTargets.cmake`` file. This is done by -adding the following to the bottom of the top-level ``CMakeLists.txt``: - -.. literalinclude:: Complete/CMakeLists.txt - :language: cmake - :start-after: # install the configuration targets - :end-before: include(CMakePackageConfigHelpers) - -At this point you should try and run CMake. If everything is setup properly -you will see that CMake will generate an error that looks like: - -.. code-block:: console - - Target "MathFunctions" INTERFACE_INCLUDE_DIRECTORIES property contains - path: - - "/Users/robert/Documents/CMakeClass/Tutorial/Step11/MathFunctions" - - which is prefixed in the source directory. - -What CMake is trying to say is that during generating the export information -it will export a path that is intrinsically tied to the current machine and -will not be valid on other machines. The solution to this is to update the -MathFunctions :command:`target_include_directories` to understand that it needs -different ``INTERFACE`` locations when being used from within the build -directory and from an install / package. This means converting the -:command:`target_include_directories` call for MathFunctions to look like: - -.. literalinclude:: Step12/MathFunctions/CMakeLists.txt - :language: cmake - :start-after: # to find MathFunctions.h, while we don't. - :end-before: # should we use our own math functions - -Once this has been updated, we can re-run CMake and verify that it doesn't -warn anymore. - -At this point, we have CMake properly packaging the target information that is -required but we will still need to generate a ``MathFunctionsConfig.cmake`` so -that the CMake :command:`find_package` command can find our project. So let's go -ahead and add a new file to the top-level of the project called -``Config.cmake.in`` with the following contents: - -.. literalinclude:: Step12/Config.cmake.in - -Then, to properly configure and install that file, add the following to the -bottom of the top-level ``CMakeLists.txt``: - -.. literalinclude:: Step12/CMakeLists.txt - :language: cmake - :start-after: # install the configuration targets - :end-before: # generate the export - -At this point, we have generated a relocatable CMake Configuration for our -project that can be used after the project has been installed or packaged. If -we want our project to also be used from a build directory we only have to add -the following to the bottom of the top level ``CMakeLists.txt``: - -.. literalinclude:: Step12/CMakeLists.txt - :language: cmake - :start-after: # needs to be after the install(TARGETS ) command - -With this export call we now generate a ``Targets.cmake``, allowing the -configured ``MathFunctionsConfig.cmake`` in the build directory to be used by -other projects, without needing it to be installed. - -Packaging Debug and Release (Step 12) -===================================== - -**Note:** This example is valid for single-configuration generators and will -not work for multi-configuration generators (e.g. Visual Studio). - -By default, CMake's model is that a build directory only contains a single -configuration, be it Debug, Release, MinSizeRel, or RelWithDebInfo. It is -possible, however, to setup CPack to bundle multiple build directories and -construct a package that contains multiple configurations of the same project. - -First, we want to ensure that the debug and release builds use different names -for the executables and libraries that will be installed. Let's use `d` as the -postfix for the debug executable and libraries. - -Set :variable:`CMAKE_DEBUG_POSTFIX` near the beginning of the top-level -``CMakeLists.txt`` file: - -.. literalinclude:: Complete/CMakeLists.txt - :language: cmake - :start-after: project(Tutorial VERSION 1.0) - :end-before: target_compile_features(tutorial_compiler_flags - -And the :prop_tgt:`DEBUG_POSTFIX` property on the tutorial executable: - -.. literalinclude:: Complete/CMakeLists.txt - :language: cmake - :start-after: # add the executable - :end-before: # add the binary tree to the search path for include files - -Let's also add version numbering to the MathFunctions library. In -``MathFunctions/CMakeLists.txt``, set the :prop_tgt:`VERSION` and -:prop_tgt:`SOVERSION` properties: - -.. literalinclude:: Complete/MathFunctions/CMakeLists.txt - :language: cmake - :start-after: # setup the version numbering - :end-before: # install rules - -From the ``Step12`` directory, create ``debug`` and ``release`` -subbdirectories. The layout will look like: - -.. code-block:: none - - - Step12 - - debug - - release - -Now we need to setup debug and release builds. We can use -:variable:`CMAKE_BUILD_TYPE` to set the configuration type: - -.. code-block:: console - - cd debug - cmake -DCMAKE_BUILD_TYPE=Debug .. - cmake --build . - cd ../release - cmake -DCMAKE_BUILD_TYPE=Release .. - cmake --build . - -Now that both the debug and release builds are complete, we can use a custom -configuration file to package both builds into a single release. In the -``Step12`` directory, create a file called ``MultiCPackConfig.cmake``. In this -file, first include the default configuration file that was created by the -:manual:`cmake <cmake(1)>` executable. - -Next, use the ``CPACK_INSTALL_CMAKE_PROJECTS`` variable to specify which -projects to install. In this case, we want to install both debug and release. - -.. literalinclude:: Complete/MultiCPackConfig.cmake - :language: cmake - -From the ``Step12`` directory, run :manual:`cpack <cpack(1)>` specifying our -custom configuration file with the ``config`` option: - -.. code-block:: console - - cpack --config MultiCPackConfig.cmake +work together in an example project can be very helpful. + +Steps +===== + +.. include:: source.txt + +|tutorial_source| +Each step has its own subdirectory containing code that may be used as a +starting point. The tutorial examples are progressive so that each step +provides the complete solution for the previous step. + +.. toctree:: + :maxdepth: 2 + + A Basic Starting Point + Adding a Library + Adding Usage Requirements for a Library + Installing and Testing + Adding System Introspection + Adding a Custom Command and Generated File + Packaging an Installer + Adding Support for a Testing Dashboard + Selecting Static or Shared Libraries + Adding Generator Expressions + Adding Export Configuration + Packaging Debug and Release + +.. + Whenever a step above is renamed or removed, leave forwarding text in + its original document file, and list it below to preserve old links + to cmake.org/cmake/help/latest/ URLs. + +.. toctree:: + :maxdepth: 1 + :hidden: diff --git a/Help/guide/tutorial/source.txt b/Help/guide/tutorial/source.txt new file mode 100644 index 0000000..bb45e86 --- /dev/null +++ b/Help/guide/tutorial/source.txt @@ -0,0 +1,3 @@ +.. |tutorial_source| replace:: + The tutorial documentation and source code examples can be found in + the ``Help/guide/tutorial`` directory of the CMake source code tree. diff --git a/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt b/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt index a54d728..73e1907 100644 --- a/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt +++ b/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt @@ -1,11 +1,11 @@ -Note that it is not advisable to populate the ``INSTALL_INTERFACE`` of the -|INTERFACE_PROPERTY_LINK| of a target with absolute paths to the include +Note that it is not advisable to populate the :genex:`INSTALL_INTERFACE` of +the |INTERFACE_PROPERTY_LINK| of a target with absolute paths to the include directories of dependencies. That would hard-code into installed packages the include directory paths for dependencies **as found on the machine the package was made on**. -The ``INSTALL_INTERFACE`` of the |INTERFACE_PROPERTY_LINK| is only +The :genex:`INSTALL_INTERFACE` of the |INTERFACE_PROPERTY_LINK| is only suitable for specifying the required include directories for headers provided with the target itself, not those provided by the transitive dependencies listed in its :prop_tgt:`INTERFACE_LINK_LIBRARIES` target diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt index 0947e41..8e23b77 100644 --- a/Help/manual/OPTIONS_BUILD.txt +++ b/Help/manual/OPTIONS_BUILD.txt @@ -76,6 +76,14 @@ native build system to choose a compiler or SDK. See the :variable:`CMAKE_GENERATOR_PLATFORM` variable for details. +``--toolchain <path-to-file>`` + Specify the cross compiling toolchain file, equivalent to setting + :variable:`CMAKE_TOOLCHAIN_FILE` variable. + +``--install-prefix <directory>`` + Specify the installation directory, used by the + :variable:`CMAKE_INSTALL_PREFIX` variable. Must be an absolute path. + ``-Wno-dev`` Suppress developer warnings. diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 7008383..f48313a 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -21,9 +21,9 @@ Binary Targets Executables and libraries are defined using the :command:`add_executable` and :command:`add_library` commands. The resulting binary files have -appropriate :prop_tgt:`PREFIX`, :prop_tgt:`SUFFIX` and extensions for the platform targeted. -Dependencies between binary targets are expressed using the -:command:`target_link_libraries` command: +appropriate :prop_tgt:`PREFIX`, :prop_tgt:`SUFFIX` and extensions for the +platform targeted. Dependencies between binary targets are expressed using +the :command:`target_link_libraries` command: .. code-block:: cmake @@ -530,38 +530,6 @@ the calculated "compatible" value of a property may be read with the In this case, the ``exe1`` source files will be compiled with ``-DCONTAINER_SIZE=200``. -Configuration determined build specifications may be conveniently set using -the ``CONFIG`` generator expression. - -.. code-block:: cmake - - target_compile_definitions(exe1 PRIVATE - $<$<CONFIG:Debug>:DEBUG_BUILD> - ) - -The ``CONFIG`` parameter is compared case-insensitively with the configuration -being built. In the presence of :prop_tgt:`IMPORTED` targets, the content of -:prop_tgt:`MAP_IMPORTED_CONFIG_DEBUG <MAP_IMPORTED_CONFIG_<CONFIG>>` is also -accounted for by this expression. - -Some buildsystems generated by :manual:`cmake(1)` have a predetermined -build-configuration set in the :variable:`CMAKE_BUILD_TYPE` variable. The -buildsystem for the IDEs such as Visual Studio and Xcode are generated -independent of the build-configuration, and the actual build configuration -is not known until build-time. Therefore, code such as - -.. code-block:: cmake - - string(TOLOWER ${CMAKE_BUILD_TYPE} _type) - if (_type STREQUAL debug) - target_compile_definitions(exe1 PRIVATE DEBUG_BUILD) - endif() - -may appear to work for :ref:`Makefile Generators` and :generator:`Ninja` -generators, but is not portable to IDE generators. Additionally, -the :prop_tgt:`IMPORTED` configuration-mappings are not accounted for -with code like this, so it should be avoided. - The unary ``TARGET_PROPERTY`` generator expression and the ``TARGET_POLICY`` generator expression are evaluated with the consuming target context. This means that a usage requirement specification may be evaluated differently based @@ -707,7 +675,9 @@ listed in the :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` of the dependency. This can result in omission of compiler warnings for headers found in those directories. This behavior for :ref:`imported targets` may be controlled by setting the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target -property on the *consumers* of imported targets. +property on the *consumers* of imported targets, or by setting the +:prop_tgt:`IMPORTED_NO_SYSTEM` target property on the imported targets +themselves. If a binary target is linked transitively to a macOS :prop_tgt:`FRAMEWORK`, the ``Headers`` directory of the framework is also treated as a usage requirement. @@ -840,6 +810,121 @@ target at a time. The commands :command:`add_compile_definitions`, a similar function, but operate at directory scope instead of target scope for convenience. +.. _`Build Configurations`: + +Build Configurations +==================== + +Configurations determine specifications for a certain type of build, such +as ``Release`` or ``Debug``. The way this is specified depends on the type +of :manual:`generator <cmake-generators(7)>` being used. For single +configuration generators like :ref:`Makefile Generators` and +:generator:`Ninja`, the configuration is specified at configure time by the +:variable:`CMAKE_BUILD_TYPE` variable. For multi-configuration generators +like :ref:`Visual Studio <Visual Studio Generators>`, :generator:`Xcode`, and +:generator:`Ninja Multi-Config`, the configuration is chosen by the user at +build time and :variable:`CMAKE_BUILD_TYPE` is ignored. In the +multi-configuration case, the set of *available* configurations is specified +at configure time by the :variable:`CMAKE_CONFIGURATION_TYPES` variable, +but the actual configuration used cannot be known until the build stage. +This difference is often misunderstood, leading to problematic code like the +following: + +.. code-block:: cmake + + # WARNING: This is wrong for multi-config generators because they don't use + # and typically don't even set CMAKE_BUILD_TYPE + string(TOLOWER ${CMAKE_BUILD_TYPE} build_type) + if (build_type STREQUAL debug) + target_compile_definitions(exe1 PRIVATE DEBUG_BUILD) + endif() + +:manual:`Generator expressions <cmake-generator-expressions(7)>` should be +used instead to handle configuration-specific logic correctly, regardless of +the generator used. For example: + +.. code-block:: cmake + + # Works correctly for both single and multi-config generators + target_compile_definitions(exe1 PRIVATE + $<$<CONFIG:Debug>:DEBUG_BUILD> + ) + +In the presence of :prop_tgt:`IMPORTED` targets, the content of +:prop_tgt:`MAP_IMPORTED_CONFIG_DEBUG <MAP_IMPORTED_CONFIG_<CONFIG>>` is also +accounted for by the above ``$<CONFIG:Debug>`` expression. + + +Case Sensitivity +---------------- + +:variable:`CMAKE_BUILD_TYPE` and :variable:`CMAKE_CONFIGURATION_TYPES` are +just like other variables in that any string comparisons made with their +values will be case-sensitive. The ``$<CONFIG>`` generator expression also +preserves the casing of the configuration as set by the user or CMake defaults. +For example: + +.. code-block:: cmake + + # NOTE: Don't use these patterns, they are for illustration purposes only. + + set(CMAKE_BUILD_TYPE Debug) + if(CMAKE_BUILD_TYPE STREQUAL DEBUG) + # ... will never get here, "Debug" != "DEBUG" + endif() + add_custom_target(print_config ALL + # Prints "Config is Debug" in this single-config case + COMMAND ${CMAKE_COMMAND} -E echo "Config is $<CONFIG>" + VERBATIM + ) + + set(CMAKE_CONFIGURATION_TYPES Debug Release) + if(DEBUG IN_LIST CMAKE_CONFIGURATION_TYPES) + # ... will never get here, "Debug" != "DEBUG" + endif() + +In contrast, CMake treats the configuration type case-insensitively when +using it internally in places that modify behavior based on the configuration. +For example, the ``$<CONFIG:Debug>`` generator expression will evaluate to 1 +for a configuration of not only ``Debug``, but also ``DEBUG``, ``debug`` or +even ``DeBuG``. Therefore, you can specify configuration types in +:variable:`CMAKE_BUILD_TYPE` and :variable:`CMAKE_CONFIGURATION_TYPES` with +any mixture of upper and lowercase, although there are strong conventions +(see the next section). If you must test the value in string comparisons, +always convert the value to upper or lowercase first and adjust the test +accordingly. + +Default And Custom Configurations +--------------------------------- + +By default, CMake defines a number of standard configurations: + +* ``Debug`` +* ``Release`` +* ``RelWithDebInfo`` +* ``MinSizeRel`` + +In multi-config generators, the :variable:`CMAKE_CONFIGURATION_TYPES` variable +will be populated with (potentially a subset of) the above list by default, +unless overridden by the project or user. The actual configuration used is +selected by the user at build time. + +For single-config generators, the configuration is specified with the +:variable:`CMAKE_BUILD_TYPE` variable at configure time and cannot be changed +at build time. The default value will often be none of the above standard +configurations and will instead be an empty string. A common misunderstanding +is that this is the same as ``Debug``, but that is not the case. Users should +always explicitly specify the build type instead to avoid this common problem. + +The above standard configuration types provide reasonable behavior on most +platforms, but they can be extended to provide other types. Each configuration +defines a set of compiler and linker flag variables for the language in use. +These variables follow the convention :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`, +where ``<CONFIG>`` is always the uppercase configuration name. When defining +a custom configuration type, make sure these variables are set appropriately, +typically as cache variables. + + Pseudo Targets ============== diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index 2c2b04c..8073511 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -115,16 +115,17 @@ of at-least C++ 11 (or C++ 14, C++ 17, ...), adding flags such as ``-std=gnu++11`` if necessary. This applies to sources within ``mylib`` as well as any dependents (that may include headers from ``mylib``). +.. include:: ../prop_gbl/CMAKE_LANG_STD_FLAGS.txt + Availability of Compiler Extensions ----------------------------------- -Because the :prop_tgt:`CXX_EXTENSIONS` target property is ``ON`` by default, -CMake uses extended variants of language dialects by default, such as -``-std=gnu++11`` instead of ``-std=c++11``. That target property may be -set to ``OFF`` to use the non-extended variant of the dialect flag. Note -that because most compilers enable extensions by default, this could -expose cross-platform bugs in user code or in the headers of third-party -dependencies. +The :prop_tgt:`<LANG>_EXTENSIONS` target property defaults to the compiler's +default (see :variable:`CMAKE_<LANG>_EXTENSIONS_DEFAULT`). Note that because +most compilers enable extensions by default, this may expose portability bugs +in user code or in the headers of third-party dependencies. + +:prop_tgt:`<LANG>_EXTENSIONS` used to default to ``ON``. See :policy:`CMP0128`. Optional Compile Features ========================= @@ -261,6 +262,7 @@ following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: * ``Cray``: Cray Compiler Environment version 8.1+. +* ``Fujitsu``: Fujitsu HPC compiler 4.0+. * ``PGI``: PGI version 12.10+. * ``NVHPC``: NVIDIA HPC compilers version 11.0+. * ``TI``: Texas Instruments compiler. diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index af9a8ab..fe146de 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -350,6 +350,24 @@ look. PATHS ${PC_Foo_LIBRARY_DIRS} ) +Alternatively, if the library is available with multiple configurations, you can +use :module:`SelectLibraryConfigurations` to automatically set the +``Foo_LIBRARY`` variable instead: + +.. code-block:: cmake + + find_library(Foo_LIBRARY_RELEASE + NAMES foo + PATHS ${PC_Foo_LIBRARY_DIRS}/Release + ) + find_library(Foo_LIBRARY_DEBUG + NAMES foo + PATHS ${PC_Foo_LIBRARY_DIRS}/Debug + ) + + include(SelectLibraryConfigurations) + select_library_configurations(Foo) + If you have a good way of getting the version (from a header file, for example), you can use that information to set ``Foo_VERSION`` (although note that find modules have traditionally used ``Foo_VERSION_STRING``, diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index bc1fa1d..0799fdd 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -30,16 +30,21 @@ Environment Variables that Control the Build /envvar/CMAKE_APPLE_SILICON_PROCESSOR /envvar/CMAKE_BUILD_PARALLEL_LEVEL + /envvar/CMAKE_BUILD_TYPE + /envvar/CMAKE_CONFIGURATION_TYPES /envvar/CMAKE_CONFIG_TYPE /envvar/CMAKE_EXPORT_COMPILE_COMMANDS /envvar/CMAKE_GENERATOR /envvar/CMAKE_GENERATOR_INSTANCE /envvar/CMAKE_GENERATOR_PLATFORM /envvar/CMAKE_GENERATOR_TOOLSET + /envvar/CMAKE_INSTALL_MODE /envvar/CMAKE_LANG_COMPILER_LAUNCHER + /envvar/CMAKE_LANG_LINKER_LAUNCHER /envvar/CMAKE_MSVCIDE_RUN_PATH /envvar/CMAKE_NO_VERBOSE /envvar/CMAKE_OSX_ARCHITECTURES + /envvar/CMAKE_TOOLCHAIN_FILE /envvar/DESTDIR /envvar/LDFLAGS /envvar/MACOSX_DEPLOYMENT_TARGET @@ -65,6 +70,8 @@ Environment Variables for Languages /envvar/CXXFLAGS /envvar/FC /envvar/FFLAGS + /envvar/HIPCXX + /envvar/HIPFLAGS /envvar/ISPC /envvar/ISPCFLAGS /envvar/OBJC diff --git a/Help/manual/cmake-file-api.7.rst b/Help/manual/cmake-file-api.7.rst index 89739b7..4b8ac65 100644 --- a/Help/manual/cmake-file-api.7.rst +++ b/Help/manual/cmake-file-api.7.rst @@ -425,7 +425,7 @@ Version 1 does not exist to avoid confusion with that from { "kind": "codemodel", - "version": { "major": 2, "minor": 2 }, + "version": { "major": 2, "minor": 4 }, "paths": { "source": "/path/to/top-level-source-dir", "build": "/path/to/top-level-build-dir" @@ -443,7 +443,8 @@ Version 1 does not exist to avoid confusion with that from "hasInstallRule": true, "minimumCMakeVersion": { "string": "3.14" - } + }, + "jsonFile": "<file>" }, { "source": "sub", @@ -453,7 +454,8 @@ Version 1 does not exist to avoid confusion with that from "targetIndexes": [ 1 ], "minimumCMakeVersion": { "string": "3.14" - } + }, + "jsonFile": "<file>" } ], "projects": [ @@ -569,6 +571,13 @@ The members specific to ``codemodel`` objects are: :command:`install` rules, i.e. whether a ``make install`` or equivalent rule is available. + ``jsonFile`` + A JSON string specifying a path relative to the codemodel file + to another JSON file containing a + `"codemodel" version 2 "directory" object`_. + + This field was added in codemodel version 2.3. + ``projects`` A JSON array of entries corresponding to the top-level project and sub-projects defined in the build system. Each (sub-)project @@ -633,6 +642,260 @@ The members specific to ``codemodel`` objects are: to another JSON file containing a `"codemodel" version 2 "target" object`_. +"codemodel" version 2 "directory" object +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A codemodel "directory" object is referenced by a `"codemodel" version 2`_ +object's ``directories`` array. Each "directory" object is a JSON object +with members: + +``paths`` + A JSON object containing members: + + ``source`` + A string specifying the path to the source directory, represented + with forward slashes. If the directory is inside the top-level + source directory then the path is specified relative to that + directory (with ``.`` for the top-level source directory itself). + Otherwise the path is absolute. + + ``build`` + A string specifying the path to the build directory, represented + with forward slashes. If the directory is inside the top-level + build directory then the path is specified relative to that + directory (with ``.`` for the top-level build directory itself). + Otherwise the path is absolute. + +``installers`` + A JSON array of entries corresponding to :command:`install` rules. + Each entry is a JSON object containing members: + + ``component`` + A string specifying the component selected by the corresponding + :command:`install` command invocation. + + ``destination`` + Optional member that is present for specific ``type`` values below. + The value is a string specifying the install destination path. + The path may be absolute or relative to the install prefix. + + ``paths`` + Optional member that is present for specific ``type`` values below. + The value is a JSON array of entries corresponding to the paths + (files or directories) to be installed. Each entry is one of: + + * A string specifying the path from which a file or directory + is to be installed. The portion of the path not preceded by + a ``/`` also specifies the path (name) to which the file + or directory is to be installed under the destination. + + * A JSON object with members: + + ``from`` + A string specifying the path from which a file or directory + is to be installed. + + ``to`` + A string specifying the path to which the file or directory + is to be installed under the destination. + + In both cases the paths are represented with forward slashes. If + the "from" path is inside the top-level directory documented by the + corresponding ``type`` value, then the path is specified relative + to that directory. Otherwise the path is absolute. + + ``type`` + A string specifying the type of installation rule. The value is one + of the following, with some variants providing additional members: + + ``file`` + An :command:`install(FILES)` or :command:`install(PROGRAMS)` call. + The ``destination`` and ``paths`` members are populated, with paths + under the top-level *source* directory expressed relative to it. + The ``isOptional`` member may exist. + This type has no additional members. + + ``directory`` + An :command:`install(DIRECTORY)` call. + The ``destination`` and ``paths`` members are populated, with paths + under the top-level *source* directory expressed relative to it. + The ``isOptional`` member may exist. + This type has no additional members. + + ``target`` + An :command:`install(TARGETS)` call. + The ``destination`` and ``paths`` members are populated, with paths + under the top-level *build* directory expressed relative to it. + The ``isOptional`` member may exist. + This type has additional members ``targetId``, ``targetIndex``, + ``targetIsImportLibrary``, and ``targetInstallNamelink``. + + ``export`` + An :command:`install(EXPORT)` call. + The ``destination`` and ``paths`` members are populated, with paths + under the top-level *build* directory expressed relative to it. + The ``paths`` entries refer to files generated automatically by + CMake for installation, and their actual values are considered + private implementation details. + This type has additional members ``exportName`` and ``exportTargets``. + + ``script`` + An :command:`install(SCRIPT)` call. + This type has additional member ``scriptFile``. + + ``code`` + An :command:`install(CODE)` call. + This type has no additional members. + + ``importedRuntimeArtifacts`` + An :command:`install(IMPORTED_RUNTIME_ARTIFACTS)` call. + The ``destination`` member is populated. The ``isOptional`` member may + exist. This type has no additional members. + + ``runtimeDependencySet`` + An :command:`install(RUNTIME_DEPENDENCY_SET)` call or an + :command:`install(TARGETS)` call with ``RUNTIME_DEPENDENCIES``. The + ``destination`` member is populated. This type has additional members + ``runtimeDependencySetName`` and ``runtimeDependencySetType``. + + ``fileSet`` + An :command:`install(TARGETS)` call with ``FILE_SET``. + The ``destination`` and ``paths`` members are populated. + The ``isOptional`` member may exist. + This type has additional members ``fileSetName``, ``fileSetType``, + ``fileSetDirectories``, and ``fileSetTarget``. + + This type was added in codemodel version 2.4. + + ``isExcludeFromAll`` + Optional member that is present with boolean value ``true`` when + :command:`install` is called with the ``EXCLUDE_FROM_ALL`` option. + + ``isForAllComponents`` + Optional member that is present with boolean value ``true`` when + :command:`install(SCRIPT|CODE)` is called with the + ``ALL_COMPONENTS`` option. + + ``isOptional`` + Optional member that is present with boolean value ``true`` when + :command:`install` is called with the ``OPTIONAL`` option. + This is allowed when ``type`` is ``file``, ``directory``, or ``target``. + + ``targetId`` + Optional member that is present when ``type`` is ``target``. + The value is a string uniquely identifying the target to be installed. + This matches the ``id`` member of the target in the main + "codemodel" object's ``targets`` array. + + ``targetIndex`` + Optional member that is present when ``type`` is ``target``. + The value is an unsigned integer 0-based index into the main "codemodel" + object's ``targets`` array for the target to be installed. + + ``targetIsImportLibrary`` + Optional member that is present when ``type`` is ``target`` and + the installer is for a Windows DLL import library file or for an + AIX linker import file. If present, it has boolean value ``true``. + + ``targetInstallNamelink`` + Optional member that is present when ``type`` is ``target`` and + the installer corresponds to a target that may use symbolic links + to implement the :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` + target properties. + The value is a string indicating how the installer is supposed to + handle the symlinks: ``skip`` means the installer should skip the + symlinks and install only the real file, and ``only`` means the + installer should install only the symlinks and not the real file. + In all cases the ``paths`` member lists what it actually installs. + + ``exportName`` + Optional member that is present when ``type`` is ``export``. + The value is a string specifying the name of the export. + + ``exportTargets`` + Optional member that is present when ``type`` is ``export``. + The value is a JSON array of entries corresponding to the targets + included in the export. Each entry is a JSON object with members: + + ``id`` + A string uniquely identifying the target. This matches + the ``id`` member of the target in the main "codemodel" + object's ``targets`` array. + + ``index`` + An unsigned integer 0-based index into the main "codemodel" + object's ``targets`` array for the target. + + ``runtimeDependencySetName`` + Optional member that is present when ``type`` is ``runtimeDependencySet`` + and the installer was created by an + :command:`install(RUNTIME_DEPENDENCY_SET)` call. The value is a string + specifying the name of the runtime dependency set that was installed. + + ``runtimeDependencySetType`` + Optional member that is present when ``type`` is ``runtimeDependencySet``. + The value is a string with one of the following values: + + ``library`` + Indicates that this installer installs dependencies that are not macOS + frameworks. + + ``framework`` + Indicates that this installer installs dependencies that are macOS + frameworks. + + ``fileSetName`` + Optional member that is present when ``type`` is ``fileSet``. The value is + a string with the name of the file set. + + This field was added in codemodel version 2.4. + + ``fileSetType`` + Optional member that is present when ``type`` is ``fileSet``. The value is + a string with the type of the file set. + + This field was added in codemodel version 2.4. + + ``fileSetDirectories`` + Optional member that is present when ``type`` is ``fileSet``. The value + is a list of strings with the file set's base directories (determined by + genex-evaluation of :prop_tgt:`HEADER_DIRS` or + :prop_tgt:`HEADER_DIRS_<NAME>`). + + This field was added in codemodel version 2.4. + + ``fileSetTarget`` + Optional member that is present when ``type`` is ``fileSet``. The value + is a JSON object with members: + + ``id`` + A string uniquely identifying the target. This matches + the ``id`` member of the target in the main "codemodel" + object's ``targets`` array. + + ``index`` + An unsigned integer 0-based index into the main "codemodel" + object's ``targets`` array for the target. + + This field was added in codemodel version 2.4. + + ``scriptFile`` + Optional member that is present when ``type`` is ``script``. + The value is a string specifying the path to the script file on disk, + represented with forward slashes. If the file is inside the top-level + source directory then the path is specified relative to that directory. + Otherwise the path is absolute. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to + the :command:`install` or other command invocation that added this + installer is available. The value is an unsigned integer 0-based + index into the ``backtraceGraph`` member's ``nodes`` array. + +``backtraceGraph`` + A `"codemodel" version 2 "backtrace graph"`_ whose nodes are referenced + from ``backtrace`` members elsewhere in this "directory" object. + "codemodel" version 2 "target" object ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -964,40 +1227,48 @@ with members: with forward slashes. ``backtraceGraph`` - A JSON object describing the graph of backtraces whose nodes are - referenced from ``backtrace`` members elsewhere. The members are: + A `"codemodel" version 2 "backtrace graph"`_ whose nodes are referenced + from ``backtrace`` members elsewhere in this "target" object. - ``nodes`` - A JSON array listing nodes in the backtrace graph. Each entry - is a JSON object with members: +"codemodel" version 2 "backtrace graph" +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - ``file`` - An unsigned integer 0-based index into the backtrace ``files`` array. +The ``backtraceGraph`` member of a `"codemodel" version 2 "directory" object`_, +or `"codemodel" version 2 "target" object`_ is a JSON object describing a +graph of backtraces. Its nodes are referenced from ``backtrace`` members +elsewhere in the containing object. The backtrace graph object members are: - ``line`` - An optional member present when the node represents a line within - the file. The value is an unsigned integer 1-based line number. +``nodes`` + A JSON array listing nodes in the backtrace graph. Each entry + is a JSON object with members: - ``command`` - An optional member present when the node represents a command - invocation within the file. The value is an unsigned integer - 0-based index into the backtrace ``commands`` array. + ``file`` + An unsigned integer 0-based index into the backtrace ``files`` array. - ``parent`` - An optional member present when the node is not the bottom of - the call stack. The value is an unsigned integer 0-based index - of another entry in the backtrace ``nodes`` array. + ``line`` + An optional member present when the node represents a line within + the file. The value is an unsigned integer 1-based line number. - ``commands`` - A JSON array listing command names referenced by backtrace nodes. - Each entry is a string specifying a command name. + ``command`` + An optional member present when the node represents a command + invocation within the file. The value is an unsigned integer + 0-based index into the backtrace ``commands`` array. - ``files`` - A JSON array listing CMake language files referenced by backtrace nodes. - Each entry is a string specifying the path to a file, represented - with forward slashes. If the file is inside the top-level source - directory then the path is specified relative to that directory. - Otherwise the path is absolute. + ``parent`` + An optional member present when the node is not the bottom of + the call stack. The value is an unsigned integer 0-based index + of another entry in the backtrace ``nodes`` array. + +``commands`` + A JSON array listing command names referenced by backtrace nodes. + Each entry is a string specifying a command name. + +``files`` + A JSON array listing CMake language files referenced by backtrace nodes. + Each entry is a string specifying the path to a file, represented + with forward slashes. If the file is inside the top-level source + directory then the path is specified relative to that directory. + Otherwise the path is absolute. Object Kind "cache" ------------------- @@ -1244,7 +1515,7 @@ The members specific to ``toolchains`` objects are: ``language`` A JSON string specifying the toolchain language, like C or CXX. Language - names are the same as langauge names that can be passed to the + names are the same as language names that can be passed to the :command:`project` command. Because CMake only supports a single toolchain per language, this field can be used as a key. diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 7bc490f..a6d2a05 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -94,6 +94,8 @@ String Comparisons .. genex:: $<IN_LIST:string,list> + .. versionadded:: 3.12 + ``1`` if ``string`` is member of the semicolon-separated ``list``, else ``0``. Uses case-sensitive comparisons. @@ -111,10 +113,14 @@ String Comparisons .. genex:: $<VERSION_LESS_EQUAL:v1,v2> + .. versionadded:: 3.7 + ``1`` if ``v1`` is a version less than or equal to ``v2``, else ``0``. .. genex:: $<VERSION_GREATER_EQUAL:v1,v2> + .. versionadded:: 3.7 + ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``. Variable Queries @@ -122,12 +128,14 @@ Variable Queries .. genex:: $<TARGET_EXISTS:target> + .. versionadded:: 3.12 + ``1`` if ``target`` exists, else ``0``. .. genex:: $<CONFIG:cfgs> - ``1`` if config is any one of the entries in ``cfgs``, else ``0``. This is a - case-insensitive comparison. The mapping in + ``1`` if config is any one of the entries in comma-separated list + ``cfgs``, else ``0``. This is a case-insensitive comparison. The mapping in :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by this expression when it is evaluated on a property on an :prop_tgt:`IMPORTED` target. @@ -155,6 +163,8 @@ Variable Queries .. genex:: $<CUDA_COMPILER_ID:compiler_ids> + .. versionadded:: 3.15 + where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the CUDA compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. @@ -162,6 +172,8 @@ Variable Queries .. genex:: $<OBJC_COMPILER_ID:compiler_ids> + .. versionadded:: 3.16 + where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the Objective-C compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. @@ -169,6 +181,8 @@ Variable Queries .. genex:: $<OBJCXX_COMPILER_ID:compiler_ids> + .. versionadded:: 3.16 + where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the Objective-C++ compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. @@ -181,8 +195,19 @@ Variable Queries of the entries in ``compiler_ids``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +.. genex:: $<HIP_COMPILER_ID:compiler_ids> + + .. versionadded:: 3.21 + + where ``compiler_ids`` is a comma-separated list. + ``1`` if the CMake's compiler id of the HIP compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. + .. genex:: $<ISPC_COMPILER_ID:compiler_ids> + .. versionadded:: 3.19 + where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the ISPC compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. @@ -200,16 +225,22 @@ Variable Queries .. genex:: $<CUDA_COMPILER_VERSION:version> + .. versionadded:: 3.15 + ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<OBJC_COMPILER_VERSION:version> + .. versionadded:: 3.16 + ``1`` if the version of the OBJC compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<OBJCXX_COMPILER_VERSION:version> + .. versionadded:: 3.16 + ``1`` if the version of the OBJCXX compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. @@ -218,8 +249,17 @@ Variable Queries ``1`` if the version of the Fortran compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +.. genex:: $<HIP_COMPILER_VERSION:version> + + .. versionadded:: 3.21 + + ``1`` if the version of the HIP compiler matches ``version``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. + .. genex:: $<ISPC_COMPILER_VERSION:version> + .. versionadded:: 3.19 + ``1`` if the version of the ISPC compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. @@ -232,6 +272,8 @@ Variable Queries .. genex:: $<COMPILE_FEATURES:features> + .. versionadded:: 3.1 + where ``features`` is a comma-spearated list. Evaluates to ``1`` if all of the ``features`` are available for the 'head' target, and ``0`` otherwise. If this expression is used while evaluating @@ -245,6 +287,8 @@ Variable Queries .. genex:: $<COMPILE_LANG_AND_ID:language,compiler_ids> + .. versionadded:: 3.15 + ``1`` when the language used for compilation unit matches ``language`` and the CMake's compiler id of the language compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. This expression is a short form @@ -282,6 +326,8 @@ Variable Queries .. genex:: $<COMPILE_LANGUAGE:languages> + .. versionadded:: 3.3 + ``1`` when the language used for compilation unit matches any of the entries in ``languages``, otherwise ``0``. This expression may be used to specify compile options, compile definitions, and include directories for source files of a @@ -328,6 +374,8 @@ Variable Queries .. genex:: $<LINK_LANG_AND_ID:language,compiler_ids> + .. versionadded:: 3.18 + ``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 @@ -368,6 +416,8 @@ Variable Queries .. genex:: $<LINK_LANGUAGE:languages> + .. versionadded:: 3.18 + ``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 @@ -431,6 +481,8 @@ Variable Queries .. genex:: $<DEVICE_LINK:list> + .. versionadded:: 3.18 + 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 and @@ -439,6 +491,8 @@ Variable Queries .. genex:: $<HOST_LINK:list> + .. versionadded:: 3.18 + 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 @@ -521,6 +575,8 @@ that must be ``0`` or ``1``. .. genex:: $<IF:condition,true_string,false_string> + .. versionadded:: 3.8 + Evaluates to ``true_string`` if ``condition`` is ``1``. Otherwise evaluates to ``false_string``. @@ -545,10 +601,14 @@ String Transformations .. genex:: $<REMOVE_DUPLICATES:list> + .. versionadded:: 3.15 + Removes duplicated items in the given ``list``. .. genex:: $<FILTER:list,INCLUDE|EXCLUDE,regex> + .. versionadded:: 3.15 + Includes or removes items from ``list`` that match the regular expression ``regex``. .. genex:: $<LOWER_CASE:string> @@ -561,12 +621,16 @@ String Transformations .. genex:: $<GENEX_EVAL:expr> + .. versionadded:: 3.12 + Content of ``expr`` evaluated as a generator expression in the current context. This enables consumption of generator expressions whose evaluation results itself in generator expressions. .. genex:: $<TARGET_GENEX_EVAL:tgt,expr> + .. versionadded:: 3.12 + Content of ``expr`` evaluated as a generator expression in the context of ``tgt`` target. This enables consumption of custom target properties that themselves contain generator expressions. @@ -635,11 +699,15 @@ Variable Queries .. genex:: $<OBJC_COMPILER_ID> + .. versionadded:: 3.16 + The CMake's compiler id of the OBJC compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. .. genex:: $<OBJCXX_COMPILER_ID> + .. versionadded:: 3.16 + The CMake's compiler id of the OBJCXX compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. @@ -648,8 +716,17 @@ Variable Queries The CMake's compiler id of the Fortran compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +.. genex:: $<HIP_COMPILER_ID> + + .. versionadded:: 3.21 + + The CMake's compiler id of the HIP compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. + .. genex:: $<ISPC_COMPILER_ID> + .. versionadded:: 3.19 + The CMake's compiler id of the ISPC compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. @@ -670,11 +747,15 @@ Variable Queries .. genex:: $<OBJC_COMPILER_VERSION> + .. versionadded:: 3.16 + The version of the OBJC compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<OBJCXX_COMPILER_VERSION> + .. versionadded:: 3.16 + The version of the OBJCXX compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. @@ -683,13 +764,24 @@ Variable Queries The version of the Fortran compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +.. genex:: $<HIP_COMPILER_VERSION> + + .. versionadded:: 3.21 + + The version of the HIP compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. + .. genex:: $<ISPC_COMPILER_VERSION> + .. versionadded:: 3.19 + The version of the ISPC compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<COMPILE_LANGUAGE> + .. versionadded:: 3.3 + The compile language of source files when evaluating compile options. See :ref:`the related boolean expression <Boolean COMPILE_LANGUAGE Generator Expression>` @@ -698,6 +790,8 @@ Variable Queries .. genex:: $<LINK_LANGUAGE> + .. versionadded:: 3.18 + The link language of target when evaluating link options. See :ref:`the related boolean expression <Boolean LINK_LANGUAGE Generator Expression>` ``$<LINK_LANGUAGE:language>`` @@ -728,6 +822,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_NAME_IF_EXISTS:tgt> + .. versionadded:: 3.12 + The target name ``tgt`` if the target exists, an empty string otherwise. Note that ``tgt`` is not added as a dependency of the target this @@ -739,6 +835,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_FILE_BASE_NAME:tgt> + .. versionadded:: 3.15 + 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``. @@ -758,6 +856,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_FILE_PREFIX:tgt> + .. versionadded:: 3.15 + Prefix of the ``tgt`` filename (such as ``lib``). See also the :prop_tgt:`PREFIX` target property. @@ -767,6 +867,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_FILE_SUFFIX:tgt> + .. versionadded:: 3.15 + Suffix of the ``tgt`` filename (extension such as ``.so`` or ``.exe``). See also the :prop_tgt:`SUFFIX` target property. @@ -797,6 +899,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_LINKER_FILE_BASE_NAME:tgt> + .. versionadded:: 3.15 + 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``. @@ -815,6 +919,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_LINKER_FILE_PREFIX:tgt> + .. versionadded:: 3.15 + Prefix of file used to link target ``tgt``. See also the :prop_tgt:`PREFIX` and :prop_tgt:`IMPORT_PREFIX` target @@ -825,6 +931,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_LINKER_FILE_SUFFIX:tgt> + .. versionadded:: 3.15 + Suffix of file used to link where ``tgt`` is the name of a target. The suffix corresponds to the file extension (such as ".so" or ".lib"). @@ -868,6 +976,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_PDB_FILE:tgt> + .. versionadded:: 3.1 + Full path to the linker generated program database file (.pdb) where ``tgt`` is the name of a target. @@ -877,6 +987,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_PDB_FILE_BASE_NAME:tgt> + .. versionadded:: 3.15 + Base name of the linker generated program database file (.pdb) where ``tgt`` is the name of a target. @@ -895,6 +1007,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_PDB_FILE_NAME:tgt> + .. versionadded:: 3.1 + Name of the linker generated program database file (.pdb). Note that ``tgt`` is not added as a dependency of the target this @@ -902,6 +1016,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_PDB_FILE_DIR:tgt> + .. versionadded:: 3.1 + Directory of the linker generated program database file (.pdb). Note that ``tgt`` is not added as a dependency of the target this @@ -909,6 +1025,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_BUNDLE_DIR:tgt> + .. versionadded:: 3.9 + Full path to the bundle directory (``my.app``, ``my.framework``, or ``my.bundle``) where ``tgt`` is the name of a target. @@ -917,6 +1035,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_BUNDLE_CONTENT_DIR:tgt> + .. versionadded:: 3.9 + Full path to the bundle content directory where ``tgt`` is the name of a target. For the macOS SDK it leads to ``my.app/Contents``, ``my.framework``, or ``my.bundle/Contents``. For all other SDKs (e.g. iOS) it leads to @@ -940,11 +1060,46 @@ which is just the string ``tgt``. :ref:`Target Usage Requirements` this is the consuming target rather than the target specifying the requirement. +.. genex:: $<TARGET_RUNTIME_DLLS:tgt> + + .. versionadded:: 3.21 + + List of DLLs that the target depends on at runtime. This is determined by + the locations of all the ``SHARED`` targets in the target's transitive + dependencies. Using this generator expression on targets other than + executables, ``SHARED`` libraries, and ``MODULE`` libraries is an error. On + non-DLL platforms, it evaluates to an empty string. + + This generator expression can be used to copy all of the DLLs that a target + depends on into its output directory in a ``POST_BUILD`` custom command. For + example: + + .. code-block:: cmake + + find_package(foo CONFIG REQUIRED) # package generated by install(EXPORT) + + add_executable(exe main.c) + target_link_libraries(exe PRIVATE foo::foo foo::bar) + add_custom_command(TARGET exe POST_BUILD + COMMAND ${CMAKE_COMMAND} -E copy $<TARGET_RUNTIME_DLLS:exe> $<TARGET_FILE_DIR:exe> + COMMAND_EXPAND_LISTS + ) + + .. note:: + + :ref:`Imported Targets` are supported only if they know the location + of their ``.dll`` files. An imported ``SHARED`` library must have + :prop_tgt:`IMPORTED_LOCATION` set to its ``.dll`` file. See the + :ref:`add_library imported libraries <add_library imported libraries>` + section for details. Many :ref:`Find Modules` produce imported targets + with the ``UNKNOWN`` type and therefore will be ignored. + .. genex:: $<INSTALL_PREFIX> Content of the install prefix when the target is exported via - :command:`install(EXPORT)`, or when evaluated in - :prop_tgt:`INSTALL_NAME_DIR`, and empty otherwise. + :command:`install(EXPORT)`, or when evaluated in the + :prop_tgt:`INSTALL_NAME_DIR` property or the ``INSTALL_NAME_DIR`` argument of + :command:`install(RUNTIME_DEPENDENCY_SET)`, and empty otherwise. Output-Related Expressions -------------------------- @@ -957,6 +1112,8 @@ Output-Related Expressions .. genex:: $<LINK_ONLY:...> + .. versionadded:: 3.1 + Content of ``...`` except when evaluated in a link interface while propagating :ref:`Target Usage Requirements`, in which case it is the empty string. @@ -982,18 +1139,24 @@ Output-Related Expressions .. genex:: $<TARGET_OBJECTS:objLib> + .. versionadded:: 3.1 + List of objects resulting from build of ``objLib``. .. genex:: $<SHELL_PATH:...> + .. versionadded:: 3.4 + Content of ``...`` converted to shell path style. For example, slashes are converted to backslashes in Windows shells and drive letters are converted to posix paths in MSYS shells. The ``...`` must be an absolute path. - The ``...`` may be a :ref:`semicolon-separated list <CMake Language Lists>` - of paths, in which case each path is converted individually and a result - list is generated using the shell path separator (``:`` on POSIX and - ``;`` on Windows). Be sure to enclose the argument containing this genex - in double quotes in CMake source code so that ``;`` does not split arguments. + + .. versionadded:: 3.14 + The ``...`` may be a :ref:`semicolon-separated list <CMake Language Lists>` + of paths, in which case each path is converted individually and a result + list is generated using the shell path separator (``:`` on POSIX and + ``;`` on Windows). Be sure to enclose the argument containing this genex + in double quotes in CMake source code so that ``;`` does not split arguments. .. genex:: $<OUTPUT_CONFIG:...> diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index 8ca2bf6..034e218 100644 --- a/Help/manual/cmake-generators.7.rst +++ b/Help/manual/cmake-generators.7.rst @@ -91,6 +91,7 @@ Visual Studio Generators /generator/Visual Studio 14 2015 /generator/Visual Studio 15 2017 /generator/Visual Studio 16 2019 + /generator/Visual Studio 17 2022 Other Generators ^^^^^^^^^^^^^^^^ @@ -101,6 +102,8 @@ Other Generators /generator/Green Hills MULTI /generator/Xcode +.. _`Extra Generators`: + Extra Generators ================ diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index b7f0861..e7d2694 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -627,3 +627,45 @@ in list elements, thus flattening nested lists: .. code-block:: cmake set(x a "b;c") # sets "x" to "a;b;c", not "a;b\;c" + +In general, lists do not support elements containing ``;`` characters. +To avoid problems, consider the following advice: + +* The interfaces of many CMake commands, variables, and properties accept + semicolon-separated lists. Avoid passing lists with elements containing + semicolons to these interfaces unless they document either direct support + or some way to escape or encode semicolons. + +* When constructing a list, substitute an otherwise-unused placeholder + for ``;`` in elements when. Then substitute ``;`` for the placeholder + when processing list elements. + For example, the following code uses ``|`` in place of ``;`` characters: + + .. code-block:: cmake + + set(mylist a "b|c") + foreach(entry IN LISTS mylist) + string(REPLACE "|" ";" entry "${entry}") + # use "${entry}" normally + endforeach() + + The :module:`ExternalProject` module's ``LIST_SEPARATOR`` option is an + example of an interface built using this approach. + +* In lists of :manual:`generator expressions <cmake-generator-expressions(7)>`, + use the :genex:`$<SEMICOLON>` generator expression. + +* In command calls, use `Quoted Argument`_ syntax whenever possible. + The called command will receive the content of the argument with + semicolons preserved. An `Unquoted Argument`_ will be split on + semicolons. + +* In :command:`function` implementations, avoid ``ARGV`` and ``ARGN``, + which do not distinguish semicolons in values from those separating values. + Instead, prefer using named positional arguments and the ``ARGC`` and + ``ARGV#`` variables. + When using :command:`cmake_parse_arguments` to parse arguments, prefer + its ``PARSE_ARGV`` signature, which uses the ``ARGV#`` variables. + + Note that this approach does not apply to :command:`macro` implementations + because they reference arguments using placeholders, not real variables. diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 17c1a1e..141eeaa 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -185,6 +185,7 @@ They are normally called through the :command:`find_package` command. /module/FindMPEG /module/FindMPEG2 /module/FindMPI + /module/FindMsys /module/FindODBC /module/FindOpenACC /module/FindOpenAL diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst index 4b2934a..ed85dc4 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -74,7 +74,9 @@ package. By setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``, the ``<PackageName>`` package will not be searched, and will always -be ``NOTFOUND``. +be ``NOTFOUND``. Likewise, setting the +:variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` to ``TRUE`` will make the +package REQUIRED. .. _`Config File Packages`: @@ -444,10 +446,10 @@ be true. This can be tested with logic in the package configuration file: include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake") include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsMacros.cmake") - set(_supported_components Plot Table) + set(_ClimbingStats_supported_components Plot Table) foreach(_comp ${ClimbingStats_FIND_COMPONENTS}) - if (NOT ";${_supported_components};" MATCHES _comp) + if (NOT ";${_ClimbingStats_supported_components};" MATCHES ";${_comp};") set(ClimbingStats_FOUND False) set(ClimbingStats_NOT_FOUND_MESSAGE "Unsupported component: ${_comp}") endif() diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index bd6b2f0..0939a82 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,37 @@ 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.23 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0129: Compiler id for MCST LCC compilers is now LCC, not GNU. </policy/CMP0129> + +Policies Introduced by CMake 3.22 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0128: Selection of language standard and extension flags improved. </policy/CMP0128> + CMP0127: cmake_dependent_option() supports full Condition Syntax. </policy/CMP0127> + +Policies Introduced by CMake 3.21 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0126: set(CACHE) does not remove a normal variable of the same name. </policy/CMP0126> + CMP0125: find_(path|file|library|program) have consistent behavior for cache variables. </policy/CMP0125> + CMP0124: foreach() loop variables are only available in the loop scope. </policy/CMP0124> + CMP0123: ARMClang cpu/arch compile and link flags must be set explicitly. </policy/CMP0123> + CMP0122: UseSWIG use standard library name conventions for csharp language. </policy/CMP0122> + CMP0121: The list command detects invalid indices. </policy/CMP0121> + Policies Introduced by CMake 3.20 ================================= diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst index 467818d..03bb5aa 100644 --- a/Help/manual/cmake-presets.7.rst +++ b/Help/manual/cmake-presets.7.rst @@ -12,18 +12,21 @@ Introduction One problem that CMake users often face is sharing settings with other people for common ways to configure a project. This may be done to support CI builds, -or for users who frequently use the same build. CMake supports two files, +or for users who frequently use the same build. CMake supports two main files, ``CMakePresets.json`` and ``CMakeUserPresets.json``, that allow users to -specify common configure options and share them with others. +specify common configure options and share them with others. CMake also +supports files included with the ``include`` field. ``CMakePresets.json`` and ``CMakeUserPresets.json`` live in the project's root directory. They both have exactly the same format, and both are optional -(though at least one must be present if ``--preset`` is specified.) -``CMakePresets.json`` is meant to save project-wide builds, while -``CMakeUserPresets.json`` is meant for developers to save their own local -builds. ``CMakePresets.json`` may be checked into a version control system, and -``CMakeUserPresets.json`` should NOT be checked in. For example, if a project -is using Git, ``CMakePresets.json`` may be tracked, and +(though at least one must be present if ``--preset`` is specified). +``CMakePresets.json`` is meant to specify project-wide build details, while +``CMakeUserPresets.json`` is meant for developers to specify their own local +build details. + +``CMakePresets.json`` may be checked into a version control system, and +``CMakeUserPresets.json`` should NOT be checked in. For example, if a +project is using Git, ``CMakePresets.json`` may be tracked, and ``CMakeUserPresets.json`` should be added to the ``.gitignore``. Format @@ -39,7 +42,7 @@ The root object recognizes the following fields: ``version`` A required integer representing the version of the JSON schema. - The supported versions are ``1`` and ``2``. + The supported versions are ``1``, ``2``, ``3``, and ``4``. ``cmakeMinimumRequired`` @@ -58,6 +61,13 @@ The root object recognizes the following fields: An optional integer representing the patch version. +``include`` + + An optional array of strings representing files to include. If the filenames + are not absolute, they are considered relative to the current file. + This is allowed in preset files specifying version ``4`` or above. + See `Includes`_ for discussion of the constraints on included files. + ``vendor`` An optional map containing vendor-specific information. CMake does not @@ -70,17 +80,37 @@ The root object recognizes the following fields: ``configurePresets`` An optional array of `Configure Preset`_ objects. - This is allowed in preset files specifying version 1 or above. + This is allowed in preset files specifying version ``1`` or above. ``buildPresets`` An optional array of `Build Preset`_ objects. - This is allowed in preset files specifying version 2 or above. + This is allowed in preset files specifying version ``2`` or above. ``testPresets`` An optional array of `Test Preset`_ objects. - This is allowed in preset files specifying version 2 or above. + This is allowed in preset files specifying version ``2`` or above. + +Includes +^^^^^^^^ + +``CMakePresets.json`` and ``CMakeUserPresets.json`` can include other files +with the ``include`` field in file version ``4`` and later. Files included +by these files can also include other files. If ``CMakePresets.json`` and +``CMakeUserPresets.json`` are both present, ``CMakeUserPresets.json`` +implicitly includes ``CMakePresets.json``, even with no ``include`` field, +in all versions of the format. + +If a preset file contains presets that inherit from presets in another file, +the file must include the other file either directly or indirectly. +Include cycles are not allowed among files. If ``a.json`` includes +``b.json``, ``b.json`` cannot include ``a.json``. However, a file may be +included multiple times from the same file or from different files. + +Files directly or indirectly included from ``CMakePresets.json`` should be +guaranteed to be provided by the project. ``CMakeUserPresets.json`` may +include files from anywhere. Configure Preset ^^^^^^^^^^^^^^^^ @@ -108,16 +138,25 @@ that may contain the following fields: ``inherits`` An optional array of strings representing the names of presets to inherit - from. The preset will inherit all of the fields from the ``inherits`` + from. This field can also be a string, which is equivalent to an array + containing one string. + + The preset will inherit all of the fields from the ``inherits`` presets by default (except ``name``, ``hidden``, ``inherits``, ``description``, and ``displayName``), but can override them as desired. If multiple ``inherits`` presets provide conflicting values for the same field, the earlier preset in the ``inherits`` list will be - preferred. Presets in ``CMakePresets.json`` may not inherit from presets - in ``CMakeUserPresets.json``. + preferred. - This field can also be a string, which is equivalent to an array - containing one string. + A preset can only inherit from another preset that is defined in the + same file or in one of the files it includes (directly or indirectly). + Presets in ``CMakePresets.json`` may not inherit from presets in + ``CMakeUserPresets.json``. + +``condition`` + + An optional `Condition`_ object. This is allowed in preset files specifying + version ``3`` or above. ``vendor`` @@ -140,7 +179,9 @@ that may contain the following fields: An optional string representing the generator to use for the preset. If ``generator`` is not specified, it must be inherited from the - ``inherits`` preset (unless this preset is ``hidden``). + ``inherits`` preset (unless this preset is ``hidden``). In version ``3`` + or above, this field may be omitted to fall back to regular generator + discovery procedure. Note that for Visual Studio generators, unlike in the command line ``-G`` argument, you cannot include the platform name in the generator name. Use @@ -175,13 +216,30 @@ that may contain the following fields: ignore the field, but the IDE can use them to set up the environment before invoking CMake. +``toolchainFile`` + + An optional string representing the path to the toolchain file. + This field supports `macro expansion`_. If a relative path is specified, + it is calculated relative to the build directory, and if not found, + relative to the source directory. This field takes precedence over any + :variable:`CMAKE_TOOLCHAIN_FILE` value. It is allowed in preset files + specifying version ``3`` or above. + ``binaryDir`` An optional string representing the path to the output binary directory. This field supports `macro expansion`_. If a relative path is specified, it is calculated relative to the source directory. If ``binaryDir`` is not specified, it must be inherited from the ``inherits`` preset (unless this - preset is ``hidden``). + preset is ``hidden``). In version ``3`` or above, this field may be + omitted. + +``installDir`` + + An optional string representing the path to the installation directory. + This field supports `macro expansion`_. If a relative path is specified, + it is calculated relative to the source directory. This is allowed in + preset files specifying version ``3`` or above. ``cmakeExecutable`` @@ -326,17 +384,26 @@ that may contain the following fields: ``inherits`` - An optional array of strings representing the names of presets to - inherit from. The preset will inherit all of the fields from the + An optional array of strings representing the names of presets to inherit + from. This field can also be a string, which is equivalent to an array + containing one string. + + The preset will inherit all of the fields from the ``inherits`` presets by default (except ``name``, ``hidden``, ``inherits``, ``description``, and ``displayName``), but can override them as desired. If multiple ``inherits`` presets provide conflicting values for the same field, the earlier preset in the ``inherits`` list - will be preferred. Presets in ``CMakePresets.json`` may not inherit from - presets in ``CMakeUserPresets.json``. + will be preferred. - This field can also be a string, which is equivalent to an array - containing one string. + A preset can only inherit from another preset that is defined in the + same file or in one of the files it includes (directly or indirectly). + Presets in ``CMakePresets.json`` may not inherit from presets in + ``CMakeUserPresets.json``. + +``condition`` + + An optional `Condition`_ object. This is allowed in preset files specifying + version ``3`` or above. ``vendor`` @@ -373,6 +440,19 @@ that may contain the following fields: are applied. Setting a variable to ``null`` causes it to not be set, even if a value was inherited from another preset. + .. note:: + + For a CMake project using ExternalProject with a configuration preset + having environment variables needed in the ExternalProject, use a build + preset that inherits that configuration preset or the ExternalProject + will not have the environment variables set in the configuration preset. + Example: suppose the host defaults to one compiler (say Clang) + and the user wishes to use another compiler (say GCC). Set configuration + preset environment variables ``CC`` and ``CXX`` and use a build preset + that inherits that configuration preset. Otherwise the ExternalProject + may use a different (system default) compiler than the top-level CMake + project. + ``configurePreset`` An optional string specifying the name of a configure preset to @@ -411,6 +491,42 @@ that may contain the following fields: An optional bool. If true, equivalent to passing ``--clean-first`` on the command line. +``resolvePackageReferences`` + + An optional string that specifies the package resolve mode. This is + allowed in preset files specifying version ``4`` or above. + + Package references are used to define dependencies to packages from + external package managers. Currently only NuGet in combination with the + Visual Studio generator is supported. If there are no targets that define + package references, this option does nothing. Valid values are: + + ``on`` + + Causes package references to be resolved before attempting a build. + + ``off`` + + Package references will not be resolved. Note that this may cause + errors in some build environments, such as .NET SDK style projects. + + ``only`` + + Only resolve package references, but do not perform a build. + + .. note:: + + The command line parameter ``--resolve-package-references`` will take + priority over this setting. If the command line parameter is not provided + and this setting is not specified, an environment-specific cache variable + will be evaluated to decide, if package restoration should be performed. + + When using the Visual Studio generator, package references are defined + using the :prop_tgt:`VS_PACKAGE_REFERENCES` property. Package references + are restored using NuGet. It can be disabled by setting the + ``CMAKE_VS_NUGET_PACKAGE_RESTORE`` variable to ``OFF``. This can also be + done from within a configure preset. + ``verbose`` An optional bool. If true, equivalent to passing ``--verbose`` on the @@ -445,17 +561,26 @@ that may contain the following fields: ``inherits`` - An optional array of strings representing the names of presets to - inherit from. The preset will inherit all of the fields from the + An optional array of strings representing the names of presets to inherit + from. This field can also be a string, which is equivalent to an array + containing one string. + + The preset will inherit all of the fields from the ``inherits`` presets by default (except ``name``, ``hidden``, ``inherits``, ``description``, and ``displayName``), but can override them as desired. If multiple ``inherits`` presets provide conflicting values for the same field, the earlier preset in the ``inherits`` list - will be preferred. Presets in ``CMakePresets.json`` may not inherit from - presets in ``CMakeUserPresets.json``. + will be preferred. - This field can also be a string, which is equivalent to an array - containing one string. + A preset can only inherit from another preset that is defined in the + same file or in one of the files it includes (directly or indirectly). + Presets in ``CMakePresets.json`` may not inherit from presets in + ``CMakeUserPresets.json``. + +``condition`` + + An optional `Condition`_ object. This is allowed in preset files specifying + version ``3`` or above. ``vendor`` @@ -609,7 +734,8 @@ that may contain the following fields: An optional string specifying a regex for test names. Equivalent to passing ``--tests-regex`` on the command line. This field supports - macro expansion. + macro expansion. CMake regex syntax is described under + :ref:`string(REGEX) <Regex Specification>`. ``label`` @@ -782,6 +908,103 @@ that may contain the following fields: Equivalent to passing ``--no-tests=ignore`` on the command line. +Condition +^^^^^^^^^ + +The ``condition`` field of a preset, allowed in preset files specifying version +``3`` or above, is used to determine whether or not the preset is enabled. For +example, this can be used to disable a preset on platforms other than Windows. +``condition`` may be either a boolean, ``null``, or an object. If it is a +boolean, the boolean indicates whether the preset is enabled or disabled. If it +is ``null``, the preset is enabled, but the ``null`` condition is not inherited +by any presets that may inherit from the preset. Sub-conditions (for example in +a ``not``, ``anyOf``, or ``allOf`` condition) may not be ``null``. If it is an +object, it has the following fields: + +``type`` + + A required string with one of the following values: + + ``"const"`` + + Indicates that the condition is constant. This is equivalent to using a + boolean in place of the object. The condition object will have the + following additional fields: + + ``value`` + + A required boolean which provides a constant value for the condition's + evaluation. + + ``"equals"`` + + ``"notEquals"`` + + Indicates that the condition compares two strings to see if they are equal + (or not equal). The condition object will have the following additional + fields: + + ``lhs`` + + First string to compare. This field supports macro expansion. + + ``rhs`` + + Second string to compare. This field supports macro expansion. + + ``"inList"`` + + ``"notInList"`` + + Indicates that the condition searches for a string in a list of strings. + The condition object will have the following additional fields: + + ``string`` + + A required string to search for. This field supports macro expansion. + + ``list`` + + A required list of strings to search. This field supports macro + expansion, and uses short-circuit evaluation. + + ``"matches"`` + + ``"notMatches"`` + + Indicates that the condition searches for a regular expression in a string. + The condition object will have the following additional fields: + + ``string`` + + A required string to search. This field supports macro expansion. + + ``regex`` + + A required regular expression to search for. This field supports macro + expansion. + + ``"anyOf"`` + + ``"allOf"`` + + Indicates that the condition is an aggregation of zero or more nested + conditions. The condition object will have the following additional fields: + + ``conditions`` + + A required array of condition objects. These conditions use short-circuit + evaluation. + + ``"not"`` + + Indicates that the condition is an inversion of another condition. The + condition object will have the following additional fields: + + ``condition`` + + A required condition object. + Macro Expansion ^^^^^^^^^^^^^^^ @@ -802,7 +1025,8 @@ Recognized macros include: ``${sourceDir}`` - Path to the project source directory. + Path to the project source directory (i.e. the same as + :variable:`CMAKE_SOURCE_DIR`). ``${sourceParentDir}`` @@ -823,6 +1047,17 @@ Recognized macros include: test presets, this will evaluate to the generator specified by ``configurePreset``. +``${hostSystemName}`` + + The name of the host operating system. Contains the same value as + :variable:`CMAKE_HOST_SYSTEM_NAME`. This is allowed in preset files + specifying version ``3`` or above. + +``${fileDir}`` + + Path to the directory containing the preset file which contains the macro. + This is allowed in preset files specifying version ``4`` or above. + ``${dollar}`` A literal dollar sign (``$``). diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index af170da..ddb917a 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -21,6 +21,7 @@ Properties of Global Scope /prop_gbl/AUTOMOC_SOURCE_GROUP /prop_gbl/AUTOMOC_TARGETS_FOLDER /prop_gbl/AUTORCC_SOURCE_GROUP + /prop_gbl/AUTOUIC_SOURCE_GROUP /prop_gbl/CMAKE_C_KNOWN_FEATURES /prop_gbl/CMAKE_CUDA_KNOWN_FEATURES /prop_gbl/CMAKE_CXX_KNOWN_FEATURES @@ -73,6 +74,7 @@ Properties on Directories /prop_dir/DEFINITIONS /prop_dir/EXCLUDE_FROM_ALL /prop_dir/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM + /prop_dir/IMPORTED_TARGETS /prop_dir/INCLUDE_DIRECTORIES /prop_dir/INCLUDE_REGULAR_EXPRESSION /prop_dir/INTERPROCEDURAL_OPTIMIZATION @@ -189,6 +191,7 @@ Properties on Targets /prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY /prop_tgt/DEPRECATION /prop_tgt/DISABLE_PRECOMPILE_HEADERS + /prop_tgt/DOTNET_SDK /prop_tgt/DOTNET_TARGET_FRAMEWORK /prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION /prop_tgt/EchoString @@ -200,6 +203,7 @@ Properties on Targets /prop_tgt/EXPORT_NAME /prop_tgt/EXPORT_PROPERTIES /prop_tgt/FOLDER + /prop_tgt/Fortran_BUILDING_INSTRINSIC_MODULES /prop_tgt/Fortran_FORMAT /prop_tgt/Fortran_MODULE_DIRECTORY /prop_tgt/Fortran_PREPROCESS @@ -211,6 +215,15 @@ Properties on Targets /prop_tgt/GHS_NO_SOURCE_GROUP_FILE /prop_tgt/GNUtoMS /prop_tgt/HAS_CXX + /prop_tgt/HEADER_DIRS + /prop_tgt/HEADER_DIRS_NAME + /prop_tgt/HEADER_SET + /prop_tgt/HEADER_SET_NAME + /prop_tgt/HEADER_SETS + /prop_tgt/HIP_ARCHITECTURES + /prop_tgt/HIP_EXTENSIONS + /prop_tgt/HIP_STANDARD + /prop_tgt/HIP_STANDARD_REQUIRED /prop_tgt/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM /prop_tgt/IMPORTED /prop_tgt/IMPORTED_COMMON_LANGUAGE_RUNTIME @@ -232,6 +245,7 @@ Properties on Targets /prop_tgt/IMPORTED_LOCATION_CONFIG /prop_tgt/IMPORTED_NO_SONAME /prop_tgt/IMPORTED_NO_SONAME_CONFIG + /prop_tgt/IMPORTED_NO_SYSTEM /prop_tgt/IMPORTED_OBJECTS /prop_tgt/IMPORTED_OBJECTS_CONFIG /prop_tgt/IMPORTED_SONAME @@ -247,6 +261,7 @@ Properties on Targets /prop_tgt/INTERFACE_COMPILE_DEFINITIONS /prop_tgt/INTERFACE_COMPILE_FEATURES /prop_tgt/INTERFACE_COMPILE_OPTIONS + /prop_tgt/INTERFACE_HEADER_SETS /prop_tgt/INTERFACE_INCLUDE_DIRECTORIES /prop_tgt/INTERFACE_LINK_DEPENDS /prop_tgt/INTERFACE_LINK_DIRECTORIES @@ -270,7 +285,11 @@ Properties on Targets /prop_tgt/LANG_COMPILER_LAUNCHER /prop_tgt/LANG_CPPCHECK /prop_tgt/LANG_CPPLINT + /prop_tgt/LANG_EXTENSIONS /prop_tgt/LANG_INCLUDE_WHAT_YOU_USE + /prop_tgt/LANG_LINKER_LAUNCHER + /prop_tgt/LANG_STANDARD + /prop_tgt/LANG_STANDARD_REQUIRED /prop_tgt/LANG_VISIBILITY_PRESET /prop_tgt/LIBRARY_OUTPUT_DIRECTORY /prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG @@ -286,6 +305,7 @@ Properties on Targets /prop_tgt/LINK_INTERFACE_MULTIPLICITY /prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG /prop_tgt/LINK_LIBRARIES + /prop_tgt/LINK_LIBRARIES_ONLY_TARGETS /prop_tgt/LINK_OPTIONS /prop_tgt/LINK_SEARCH_END_STATIC /prop_tgt/LINK_SEARCH_START_STATIC @@ -402,7 +422,9 @@ Properties on Targets /prop_tgt/XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY /prop_tgt/XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY /prop_tgt/XCODE_EMBED_type + /prop_tgt/XCODE_EMBED_type_CODE_SIGN_ON_COPY /prop_tgt/XCODE_EMBED_type_PATH + /prop_tgt/XCODE_EMBED_type_REMOVE_HEADERS_ON_COPY /prop_tgt/XCODE_EXPLICIT_FILE_TYPE /prop_tgt/XCODE_GENERATE_SCHEME /prop_tgt/XCODE_LINK_BUILD_PHASE_MODE @@ -412,6 +434,7 @@ Properties on Targets /prop_tgt/XCODE_SCHEME_ARGUMENTS /prop_tgt/XCODE_SCHEME_DEBUG_AS_ROOT /prop_tgt/XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING + /prop_tgt/XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE /prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER /prop_tgt/XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS /prop_tgt/XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE @@ -444,6 +467,7 @@ Properties on Tests /prop_test/DEPENDS /prop_test/DISABLED /prop_test/ENVIRONMENT + /prop_test/ENVIRONMENT_MODIFICATION /prop_test/FAIL_REGULAR_EXPRESSION /prop_test/FIXTURES_CLEANUP /prop_test/FIXTURES_REQUIRED diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index 1ededee..a941310 100644 --- a/Help/manual/cmake-toolchains.7.rst +++ b/Help/manual/cmake-toolchains.7.rst @@ -96,8 +96,8 @@ Cross Compiling =============== If :manual:`cmake(1)` is invoked with the command line parameter -``-DCMAKE_TOOLCHAIN_FILE=path/to/file``, the file will be loaded early to set -values for the compilers. +``--toolchain path/to/file`` or ``-DCMAKE_TOOLCHAIN_FILE=path/to/file``, the +file will be loaded early to set values for the compilers. The :variable:`CMAKE_CROSSCOMPILING` variable is set to true when CMake is cross-compiling. diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 4317dd4..4df0237 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -49,10 +49,12 @@ Variables that Provide Information /variable/CMAKE_DEBUG_TARGET_PROPERTIES /variable/CMAKE_DIRECTORY_LABELS /variable/CMAKE_DL_LIBS + /variable/CMAKE_DOTNET_SDK /variable/CMAKE_DOTNET_TARGET_FRAMEWORK /variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION /variable/CMAKE_EDIT_COMMAND /variable/CMAKE_EXECUTABLE_SUFFIX + /variable/CMAKE_EXECUTABLE_SUFFIX_LANG /variable/CMAKE_EXTRA_GENERATOR /variable/CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES /variable/CMAKE_FIND_DEBUG_MODE @@ -70,6 +72,7 @@ Variables that Provide Information /variable/CMAKE_JOB_POOL_PRECOMPILE_HEADER /variable/CMAKE_JOB_POOLS /variable/CMAKE_LANG_COMPILER_AR + /variable/CMAKE_LANG_COMPILER_FRONTEND_VARIANT /variable/CMAKE_LANG_COMPILER_RANLIB /variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX /variable/CMAKE_LINK_LIBRARY_SUFFIX @@ -116,6 +119,7 @@ Variables that Provide Information /variable/CMAKE_VS_DEVENV_COMMAND /variable/CMAKE_VS_MSBUILD_COMMAND /variable/CMAKE_VS_NsightTegra_VERSION + /variable/CMAKE_VS_NUGET_PACKAGE_RESTORE /variable/CMAKE_VS_PLATFORM_NAME /variable/CMAKE_VS_PLATFORM_NAME_DEFAULT /variable/CMAKE_VS_PLATFORM_TOOLSET @@ -123,6 +127,9 @@ Variables that Provide Information /variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR /variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE /variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION + /variable/CMAKE_VS_TARGET_FRAMEWORK_VERSION + /variable/CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER + /variable/CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM /variable/CMAKE_XCODE_BUILD_SYSTEM @@ -130,6 +137,7 @@ Variables that Provide Information /variable/PROJECT-NAME_BINARY_DIR /variable/PROJECT-NAME_DESCRIPTION /variable/PROJECT-NAME_HOMEPAGE_URL + /variable/PROJECT-NAME_IS_TOP_LEVEL /variable/PROJECT-NAME_SOURCE_DIR /variable/PROJECT-NAME_VERSION /variable/PROJECT-NAME_VERSION_MAJOR @@ -139,6 +147,7 @@ Variables that Provide Information /variable/PROJECT_BINARY_DIR /variable/PROJECT_DESCRIPTION /variable/PROJECT_HOMEPAGE_URL + /variable/PROJECT_IS_TOP_LEVEL /variable/PROJECT_NAME /variable/PROJECT_SOURCE_DIR /variable/PROJECT_VERSION @@ -203,6 +212,7 @@ Variables that Change Behavior /variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY /variable/CMAKE_FRAMEWORK_PATH /variable/CMAKE_IGNORE_PATH + /variable/CMAKE_IGNORE_PREFIX_PATH /variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE /variable/CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE /variable/CMAKE_INCLUDE_PATH @@ -213,6 +223,7 @@ Variables that Change Behavior /variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT /variable/CMAKE_LIBRARY_PATH /variable/CMAKE_LINK_DIRECTORIES_BEFORE + /variable/CMAKE_LINK_LIBRARIES_ONLY_TARGETS /variable/CMAKE_MFC_FLAG /variable/CMAKE_MAXIMUM_RECURSION_DEPTH /variable/CMAKE_MESSAGE_CONTEXT @@ -228,6 +239,7 @@ Variables that Change Behavior /variable/CMAKE_PROJECT_INCLUDE_BEFORE /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE + /variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY /variable/CMAKE_STAGING_PREFIX /variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS @@ -239,10 +251,13 @@ Variables that Change Behavior /variable/CMAKE_SYSTEM_APPBUNDLE_PATH /variable/CMAKE_SYSTEM_FRAMEWORK_PATH /variable/CMAKE_SYSTEM_IGNORE_PATH + /variable/CMAKE_SYSTEM_IGNORE_PREFIX_PATH /variable/CMAKE_SYSTEM_INCLUDE_PATH /variable/CMAKE_SYSTEM_LIBRARY_PATH /variable/CMAKE_SYSTEM_PREFIX_PATH /variable/CMAKE_SYSTEM_PROGRAM_PATH + /variable/CMAKE_TLS_CAINFO + /variable/CMAKE_TLS_VERIFY /variable/CMAKE_USER_MAKE_RULES_OVERRIDE /variable/CMAKE_WARN_DEPRECATED /variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION @@ -252,6 +267,7 @@ Variables that Change Behavior /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN /variable/CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING + /variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE /variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE @@ -297,7 +313,7 @@ Variables that Describe the System /variable/CMAKE_SYSTEM_PROCESSOR /variable/CMAKE_SYSTEM_VERSION /variable/CYGWIN - /variable/GHS-MULTI + /variable/GHSMULTI /variable/IOS /variable/MINGW /variable/MSVC @@ -421,8 +437,10 @@ Variables that Control the Build /variable/CMAKE_LANG_CPPCHECK /variable/CMAKE_LANG_CPPLINT /variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE + /variable/CMAKE_LANG_LINKER_LAUNCHER /variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LANG_LINK_LIBRARY_FLAG + /variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG /variable/CMAKE_LANG_VISIBILITY_PRESET /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG @@ -433,6 +451,7 @@ Variables that Control the Build /variable/CMAKE_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LINK_LIBRARY_FLAG /variable/CMAKE_LINK_WHAT_YOU_USE + /variable/CMAKE_LINK_WHAT_YOU_USE_CHECK /variable/CMAKE_MACOSX_BUNDLE /variable/CMAKE_MACOSX_RPATH /variable/CMAKE_MAP_IMPORTED_CONFIG_CONFIG @@ -453,6 +472,7 @@ Variables that Control the Build /variable/CMAKE_PCH_INSTANTIATE_TEMPLATES /variable/CMAKE_PDB_OUTPUT_DIRECTORY /variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG + /variable/CMAKE_PLATFORM_NO_VERSIONED_SONAME /variable/CMAKE_POSITION_INDEPENDENT_CODE /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG @@ -519,6 +539,10 @@ Variables for Languages /variable/CMAKE_Fortran_MODDIR_DEFAULT /variable/CMAKE_Fortran_MODDIR_FLAG /variable/CMAKE_Fortran_MODOUT_FLAG + /variable/CMAKE_HIP_ARCHITECTURES + /variable/CMAKE_HIP_EXTENSIONS + /variable/CMAKE_HIP_STANDARD + /variable/CMAKE_HIP_STANDARD_REQUIRED /variable/CMAKE_ISPC_HEADER_DIRECTORY /variable/CMAKE_ISPC_HEADER_SUFFIX /variable/CMAKE_ISPC_INSTRUCTION_SETS @@ -540,6 +564,8 @@ Variables for Languages /variable/CMAKE_LANG_CREATE_SHARED_LIBRARY /variable/CMAKE_LANG_CREATE_SHARED_MODULE /variable/CMAKE_LANG_CREATE_STATIC_LIBRARY + /variable/CMAKE_LANG_EXTENSIONS + /variable/CMAKE_LANG_EXTENSIONS_DEFAULT /variable/CMAKE_LANG_FLAGS /variable/CMAKE_LANG_FLAGS_CONFIG /variable/CMAKE_LANG_FLAGS_CONFIG_INIT @@ -559,8 +585,6 @@ Variables for Languages /variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES /variable/CMAKE_LANG_LIBRARY_ARCHITECTURE /variable/CMAKE_LANG_LINK_EXECUTABLE - /variable/CMAKE_LANG_LINKER_PREFERENCE - /variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES /variable/CMAKE_LANG_LINKER_WRAPPER_FLAG /variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP /variable/CMAKE_LANG_OUTPUT_EXTENSION @@ -568,8 +592,11 @@ Variables for Languages /variable/CMAKE_LANG_SIMULATE_VERSION /variable/CMAKE_LANG_SIZEOF_DATA_PTR /variable/CMAKE_LANG_SOURCE_FILE_EXTENSIONS + /variable/CMAKE_LANG_STANDARD + /variable/CMAKE_LANG_STANDARD_DEFAULT /variable/CMAKE_LANG_STANDARD_INCLUDE_DIRECTORIES /variable/CMAKE_LANG_STANDARD_LIBRARIES + /variable/CMAKE_LANG_STANDARD_REQUIRED /variable/CMAKE_OBJC_EXTENSIONS /variable/CMAKE_OBJC_STANDARD /variable/CMAKE_OBJC_STANDARD_REQUIRED @@ -644,7 +671,9 @@ Variables for CTest /variable/CTEST_RESOURCE_SPEC_FILE /variable/CTEST_RUN_CURRENT_SCRIPT /variable/CTEST_SCP_COMMAND + /variable/CTEST_SCRIPT_DIRECTORY /variable/CTEST_SITE + /variable/CTEST_SUBMIT_INACTIVITY_TIMEOUT /variable/CTEST_SUBMIT_URL /variable/CTEST_SOURCE_DIRECTORY /variable/CTEST_SVN_COMMAND @@ -667,6 +696,7 @@ Variables for CPack /variable/CPACK_ABSOLUTE_DESTINATION_FILES /variable/CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY + /variable/CPACK_CUSTOM_INSTALL_VARIABLES /variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION /variable/CPACK_INCLUDE_TOPLEVEL_DIRECTORY /variable/CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS @@ -699,6 +729,8 @@ are subject to change, and not recommended for use in project code. /variable/CMAKE_LANG_COMPILER_ABI /variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID /variable/CMAKE_LANG_COMPILER_VERSION_INTERNAL + /variable/CMAKE_LANG_LINKER_PREFERENCE + /variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES /variable/CMAKE_LANG_PLATFORM_ID /variable/CMAKE_NOT_USING_CONFIG_FLAGS /variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 02828ac..18bdc5f 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -151,6 +151,33 @@ source and build trees and generate a buildsystem: In all cases the ``<options>`` may be zero or more of the `Options`_ below. +The above styles for specifying the source and build trees may be mixed. +Paths specified with ``-S`` or ``-B`` are always classified as source or +build trees, respectively. Paths specified with plain arguments are +classified based on their content and the types of paths given earlier. +If only one type of path is given, the current working directory (cwd) +is used for the other. For example: + +============================== ============ =========== + Command Line Source Dir Build Dir +============================== ============ =========== + ``cmake src`` ``src`` `cwd` + ``cmake build`` (existing) `loaded` ``build`` + ``cmake -S src`` ``src`` `cwd` + ``cmake -S src build`` ``src`` ``build`` + ``cmake -S src -B build`` ``src`` ``build`` + ``cmake -B build`` `cwd` ``build`` + ``cmake -B build src`` ``src`` ``build`` + ``cmake -B build -S src`` ``src`` ``build`` +============================== ============ =========== + +.. versionchanged:: 3.23 + + CMake warns when multiple source paths are specified. This has never + been officially documented or supported, but older versions accidentally + accepted multiple source paths and used the last path specified. + Avoid passing multiple source path arguments. + After generating a buildsystem one may use the corresponding native build tool to build the project. For example, after using the :generator:`Unix Makefiles` generator one may run ``make`` directly: @@ -250,6 +277,21 @@ Options See also the :variable:`CMAKE_FIND_DEBUG_MODE` variable for debugging a more local part of the project. +``--debug-find-pkg=<pkg>[,...]`` + Put cmake find commands in a debug mode when running under calls + to :command:`find_package(\<pkg\>) <find_package>`, where ``<pkg>`` + is an entry in the given comma-separated list of case-sensitive package + names. + + Like ``--debug-find``, but limiting scope to the specified packages. + +``--debug-find-var=<var>[,...]`` + Put cmake find commands in a debug mode when called with ``<var>`` + as the result variable, where ``<var>`` is an entry in the given + comma-separated list. + + Like ``--debug-find``, but limiting scope to the specified variable names. + ``--trace`` Put cmake in trace mode. @@ -381,9 +423,9 @@ Options ``--preset <preset>``, ``--preset=<preset>`` Reads a :manual:`preset <cmake-presets(7)>` from ``<path-to-source>/CMakePresets.json`` and - ``<path-to-source>/CMakeUserPresets.json``. The preset specifies the - generator and the build directory, and optionally a list of variables and - other arguments to pass to CMake. The current working directory must contain + ``<path-to-source>/CMakeUserPresets.json``. The preset may specify the + generator and the build directory, and a list of variables and other + arguments to pass to CMake. The current working directory must contain CMake preset files. The :manual:`CMake GUI <cmake-gui(1)>` can also recognize ``CMakePresets.json`` and ``CMakeUserPresets.json`` files. For full details on these files, see :manual:`cmake-presets(7)`. @@ -408,7 +450,8 @@ project binary tree: .. code-block:: shell - cmake --build [<dir> | --preset <preset>] [<options>] [-- <build-tool-options>] + cmake --build <dir> [<options>] [-- <build-tool-options>] + cmake --build --preset <preset> [<options>] [-- <build-tool-options>] This abstracts a native build tool's command-line interface with the following options: @@ -448,6 +491,29 @@ following options: Build target ``clean`` first, then build. (To clean only, use ``--target clean``.) +``--resolve-package-references=<on|off|only>`` + .. versionadded:: 3.23 + + Resolve remote package references from external package managers (e.g. NuGet) + before build. When set to ``on`` (default), packages will be restored before + building a target. When set to ``only``, the packages will be restored, but no + build will be performed. When set to ``off``, no packages will be restored. + + If the target does not define any package references, this option does nothing. + + This setting can be specified in a build preset (using + ``resolvePackageReferences``). The preset setting will be ignored, if this + command line option is specified. + + If no command line parameter or preset option are provided, an environment- + specific cache variable will be evaluated to decide, if package restoration + should be performed. + + When using the Visual Studio generator, package references are defined + using the :prop_tgt:`VS_PACKAGE_REFERENCES` property. Package references + are restored using NuGet. It can be disabled by setting the + ``CMAKE_VS_NUGET_PACKAGE_RESTORE`` variable to ``OFF``. + ``--use-stderr`` Ignored. Behavior is default in CMake >= 3.0. @@ -546,6 +612,8 @@ Run ``cmake -E`` or ``cmake -E help`` for a summary of commands. Available commands are: ``capabilities`` + .. versionadded:: 3.7 + Report cmake capabilities in JSON format. The output is a JSON object with the following keys: @@ -575,6 +643,12 @@ Available commands are: ``true`` if the generator supports toolsets and ``false`` otherwise. ``platformSupport`` ``true`` if the generator supports platforms and ``false`` otherwise. + ``supportedPlatforms`` + .. versionadded:: 3.21 + + Optional member that may be present when the generator supports + platform specification via :variable:`CMAKE_GENERATOR_PLATFORM` + (``-A ...``). The value is a list of platforms known to be supported. ``extraGenerators`` A list of strings with all the extra generators compatible with the generator. @@ -600,6 +674,8 @@ Available commands are: Always false since CMake 3.20. ``cat <files>...`` + .. versionadded:: 3.18 + Concatenate files and print on the standard output. ``chdir <dir> <cmd> [<arg>...]`` @@ -608,8 +684,11 @@ Available commands are: ``compare_files [--ignore-eol] <file1> <file2>`` Check if ``<file1>`` is same as ``<file2>``. If files are the same, then returns ``0``, if not it returns ``1``. In case of invalid - arguments, it returns 2. The ``--ignore-eol`` option - implies line-wise comparison and ignores LF/CRLF differences. + arguments, it returns 2. + + .. versionadded:: 3.14 + The ``--ignore-eol`` option implies line-wise comparison and ignores + LF/CRLF differences. ``copy <file>... <destination>`` Copy files to ``<destination>`` (either file or directory). @@ -618,11 +697,21 @@ Available commands are: ``copy`` does follow symlinks. That means it does not copy symlinks, but the files or directories it point to. + .. versionadded:: 3.5 + Support for multiple input files. + ``copy_directory <dir>... <destination>`` Copy content of ``<dir>...`` directories to ``<destination>`` directory. If ``<destination>`` directory does not exist it will be created. ``copy_directory`` does follow symlinks. + .. versionadded:: 3.5 + Support for multiple input directories. + + .. versionadded:: 3.15 + The command now fails when the source directory does not exist. + Previously it succeeded by creating an empty destination directory. + ``copy_if_different <file>... <destination>`` Copy files to ``<destination>`` (either file or directory) if they have changed. @@ -630,13 +719,21 @@ Available commands are: directory and it must exist. ``copy_if_different`` does follow symlinks. + .. versionadded:: 3.5 + Support for multiple input files. + ``create_symlink <old> <new>`` Create a symbolic link ``<new>`` naming ``<old>``. + .. versionadded:: 3.13 + Support for creating symlinks on Windows. + .. note:: Path to where ``<new>`` symbolic link will be created has to exist beforehand. ``create_hardlink <old> <new>`` + .. versionadded:: 3.19 + Create a hard link ``<new>`` naming ``<old>``. .. note:: @@ -650,12 +747,16 @@ Available commands are: Displays arguments as text but no new line. ``env [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...`` + .. versionadded:: 3.1 + Run command in a modified environment. ``environment`` Display the current environment variables. ``false`` + .. versionadded:: 3.16 + Do nothing, with an exit code of 1. ``make_directory <dir>...`` @@ -663,6 +764,9 @@ Available commands are: directories too. If a directory already exists it will be silently ignored. + .. versionadded:: 3.5 + Support for multiple input directories. + ``md5sum <file>...`` Create MD5 checksum of files in ``md5sum`` compatible format:: @@ -670,30 +774,40 @@ Available commands are: 052f86c15bbde68af55c7f7b340ab639 file2.txt ``sha1sum <file>...`` + .. versionadded:: 3.10 + Create SHA1 checksum of files in ``sha1sum`` compatible format:: 4bb7932a29e6f73c97bb9272f2bdc393122f86e0 file1.txt 1df4c8f318665f9a5f2ed38f55adadb7ef9f559c file2.txt ``sha224sum <file>...`` + .. versionadded:: 3.10 + Create SHA224 checksum of files in ``sha224sum`` compatible format:: b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930 file1.txt 6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24 file2.txt ``sha256sum <file>...`` + .. versionadded:: 3.10 + Create SHA256 checksum of files in ``sha256sum`` compatible format:: 76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc file1.txt 15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea file2.txt ``sha384sum <file>...`` + .. versionadded:: 3.10 + Create SHA384 checksum of files in ``sha384sum`` compatible format:: acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434 file1.txt 668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d file2.txt ``sha512sum <file>...`` + .. versionadded:: 3.10 + Create SHA512 checksum of files in ``sha512sum`` compatible format:: 2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89 file1.txt @@ -702,7 +816,7 @@ Available commands are: ``remove [-f] <file>...`` .. deprecated:: 3.17 - Remove the file(s). The planned behaviour was that if any of the + Remove the file(s). The planned behavior was that if any of the listed files already do not exist, the command returns a non-zero exit code, but no message is logged. The ``-f`` option changes the behavior to return a zero exit code (i.e. success) in such situations instead. @@ -716,16 +830,24 @@ Available commands are: .. deprecated:: 3.17 Remove ``<dir>`` directories and their contents. If a directory does - not exist it will be silently ignored. If ``<dir>`` is a symlink to - a directory, just the symlink will be removed. + not exist it will be silently ignored. Use ``rm`` instead. + .. versionadded:: 3.15 + Support for multiple directories. + + .. versionadded:: 3.16 + If ``<dir>`` is a symlink to a directory, just the symlink will be removed. + ``rename <oldname> <newname>`` Rename a file or directory (on one volume). If file with the ``<newname>`` name already exists, then it will be silently replaced. ``rm [-rRf] <file> <dir>...`` - Remove the files ``<file>`` or directories ``dir``. + .. versionadded:: 3.17 + + Remove the files ``<file>`` or directories ``<dir>``. + Use ``-r`` or ``-R`` to remove directories and their contents recursively. If any of the listed files/directories do not exist, the command returns a non-zero exit code, but no message is logged. The ``-f`` option changes @@ -736,6 +858,8 @@ Available commands are: Launch :manual:`cmake-server(7)` mode. ``sleep <number>...`` + .. versionadded:: 3.0 + Sleep for given number of seconds. ``tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]`` @@ -744,45 +868,85 @@ Available commands are: ``c`` Create a new archive containing the specified files. If used, the ``<pathname>...`` argument is mandatory. + ``x`` Extract to disk from the archive. - The ``<pathname>...`` argument could be used to extract only selected files - or directories. - When extracting selected files or directories, you must provide their exact - names including the path, as printed by list (``-t``). + + .. versionadded:: 3.15 + The ``<pathname>...`` argument could be used to extract only selected files + or directories. + When extracting selected files or directories, you must provide their exact + names including the path, as printed by list (``-t``). + ``t`` List archive contents. - The ``<pathname>...`` argument could be used to list only selected files - or directories. + + .. versionadded:: 3.15 + The ``<pathname>...`` argument could be used to list only selected files + or directories. + ``v`` Produce verbose output. + ``z`` Compress the resulting archive with gzip. + ``j`` Compress the resulting archive with bzip2. + ``J`` + .. versionadded:: 3.1 + Compress the resulting archive with XZ. + ``--zstd`` + .. versionadded:: 3.15 + Compress the resulting archive with Zstandard. + ``--files-from=<file>`` + .. versionadded:: 3.1 + Read file names from the given file, one per line. Blank lines are ignored. Lines may not start in ``-`` except for ``--add-file=<name>`` to add files whose names start in ``-``. + ``--format=<format>`` + .. versionadded:: 3.3 + Specify the format of the archive to be created. Supported formats are: ``7zip``, ``gnutar``, ``pax``, ``paxr`` (restricted pax, default), and ``zip``. + ``--mtime=<date>`` + .. versionadded:: 3.1 + Specify modification time recorded in tarball entries. + ``--`` + .. versionadded:: 3.1 + Stop interpreting options and treat all remaining arguments as file names, even if they start with ``-``. + .. versionadded:: 3.1 + LZMA (7zip) support. + + .. versionadded:: 3.15 + The command now continues adding files to an archive even if some of the + files are not readable. This behavior is more consistent with the classic + ``tar`` tool. The command now also parses all flags, and if an invalid flag + was provided, a warning is issued. ``time <command> [<args>...]`` Run command and display elapsed time. + .. versionadded:: 3.5 + The command now properly passes arguments with spaces or special characters + through to the child process. This may break scripts that worked around the + bug with their own extra quoting or escaping. + ``touch <file>...`` Creates ``<file>`` if file do not exist. If ``<file>`` exists, it is changing ``<file>`` access and modification times. @@ -792,6 +956,8 @@ Available commands are: not exist it will be silently ignored. ``true`` + .. versionadded:: 3.16 + Do nothing, with an exit code of 0. Windows-specific Command-Line Tools @@ -803,10 +969,14 @@ The following ``cmake -E`` commands are available only on Windows: Delete Windows registry value. ``env_vs8_wince <sdkname>`` + .. versionadded:: 3.2 + Displays a batch file which sets the environment for the provided Windows CE SDK installed in VS2005. ``env_vs9_wince <sdkname>`` + .. versionadded:: 3.2 + Displays a batch file which sets the environment for the provided Windows CE SDK installed in VS2008. diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 175359d..1e7b077 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -134,6 +134,14 @@ Options This option tells CTest to write all its output to a ``<file>`` log file. +``--output-junit <file>`` + Write test results in JUnit format. + + This option tells CTest to write test results to ``<file>`` in JUnit XML + format. If ``<file>`` already exists, it will be overwritten. If using the + ``-S`` option to run a dashboard script, use the ``OUTPUT_JUNIT`` keyword + with the :command:`ctest_test` command instead. + ``-N,--show-only[=<format>]`` Disable actual execution of tests. @@ -152,10 +160,14 @@ Options See `Show as JSON Object Model`_. ``-L <regex>, --label-regex <regex>`` - Run tests with labels matching regular expression. + Run tests with labels matching regular expression as described under + :ref:`string(REGEX) <Regex Specification>`. This option tells CTest to run only the tests whose labels match the - given regular expression. + given regular expression. When more than one ``-L`` option is given, + a test will only be run if each regular expression matches at least one + of the test's labels (i.e. the multiple ``-L`` labels form an ``AND`` + relationship). See `Label Matching`_. ``-R <regex>, --tests-regex <regex>`` Run tests matching regular expression. @@ -173,7 +185,10 @@ Options Exclude tests with labels matching regular expression. This option tells CTest to NOT run the tests whose labels match the - given regular expression. + given regular expression. When more than one ``-LE`` option is given, + a test will only be excluded if each regular expression matches at least one + of the test's labels (i.e. the multiple ``-LE`` labels form an ``AND`` + relationship). See `Label Matching`_. ``-FA <regex>, --fixture-exclude-any <regex>`` Exclude fixtures matching ``<regex>`` from automatically adding any tests to @@ -309,11 +324,13 @@ Options Set the interactive mode to ``0`` or ``1``. This option causes CTest to run tests in either an interactive mode - or a non-interactive mode. On Windows this means that in - non-interactive mode, all system debug pop up windows are blocked. - In dashboard mode (``Experimental``, ``Nightly``, ``Continuous``), the default - is non-interactive. When just running tests not for a dashboard the - default is to allow popups and interactive debugging. + or a non-interactive mode. In dashboard mode (``Experimental``, ``Nightly``, + ``Continuous``), the default is non-interactive. In non-interactive mode, + the environment variable :envvar:`DASHBOARD_TEST_FROM_CTEST` is set. + + Prior to CMake 3.11, interactive mode on Windows allowed system debug + popup windows to appear. Now, due to CTest's use of ``libuv`` to launch + test processes, all system debug popup windows are always blocked. ``--no-label-summary`` Disable timing summary information for labels. @@ -398,6 +415,46 @@ Specify the directory in which to look for tests. .. include:: OPTIONS_HELP.txt +.. _`Label Matching`: + +Label Matching +============== + +Tests may have labels attached to them. Tests may be included +or excluded from a test run by filtering on the labels. +Each individual filter is a regular expression applied to +the labels attached to a test. + +When ``-L`` is used, in order for a test to be included in a +test run, each regular expression must match at least one +label. Using more than one ``-L`` option means "match **all** +of these". + +The ``-LE`` option works just like ``-L``, but excludes tests +rather than including them. A test is excluded if each regular +expression matches at least one label. + +If a test has no labels attached to it, then ``-L`` will never +include that test, and ``-LE`` will never exclude that test. +As an example of tests with labels, consider five tests, +with the following labels: + +* *test1* has labels *tuesday* and *production* +* *test2* has labels *tuesday* and *test* +* *test3* has labels *wednesday* and *production* +* *test4* has label *wednesday* +* *test5* has labels *friday* and *test* + +Running ``ctest`` with ``-L tuesday -L test`` will select *test2*, which has +both labels. Running CTest with ``-L test`` will select *test2* and +*test5*, because both of them have a label that matches that regular +expression. + +Because the matching works with regular expressions, take note that +running CTest with ``-L es`` will match all five tests. +To select the *tuesday* and *wednesday* tests together, use a single +regular expression that matches either of them, like ``-L "tue|wed"``. + .. _`Label and Subproject Summary`: Label and Subproject Summary @@ -407,6 +464,10 @@ CTest prints timing summary information for each ``LABEL`` and subproject associated with the tests run. The label time summary will not include labels that are mapped to subprojects. +.. versionadded:: 3.22 + Labels added dynamically during test execution are also reported in the + timing summary. See :ref:`Additional Labels`. + When the :prop_test:`PROCESSORS` test property is set, CTest will display a weighted test timing result in label and subproject summaries. The time is reported with `sec*proc` instead of just `sec`. @@ -1043,6 +1104,8 @@ Configuration settings include: * `CTest Script`_ variable: :variable:`CTEST_TEST_TIMEOUT` * :module:`CTest` module variable: ``DART_TESTING_TIMEOUT`` +To report extra test values to CDash, see :ref:`Additional Test Measurements`. + .. _`CTest Coverage Step`: CTest Coverage Step @@ -1290,6 +1353,13 @@ Configuration settings include: * :module:`CTest` module variable: ``SUBMIT_URL`` if set, else ``CTEST_SUBMIT_URL`` +``SubmitInactivityTimeout`` + The time to wait for the submission after which it is canceled + if not completed. Specify a zero value to disable timeout. + + * `CTest Script`_ variable: :variable:`CTEST_SUBMIT_INACTIVITY_TIMEOUT` + * :module:`CTest` module variable: ``CTEST_SUBMIT_INACTIVITY_TIMEOUT`` + ``TriggerSite`` Legacy option. Not used. @@ -1619,4 +1689,4 @@ See Also .. include:: LINKS.txt -.. _`CDash`: http://cdash.org/ +_`CDash`: https://cdash.org diff --git a/Help/manual/presets/example.json b/Help/manual/presets/example.json index dfc2910..873c4ad 100644 --- a/Help/manual/presets/example.json +++ b/Help/manual/presets/example.json @@ -1,10 +1,14 @@ { - "version": 2, + "version": 4, "cmakeMinimumRequired": { "major": 3, - "minor": 20, + "minor": 23, "patch": 0 }, + "include": [ + "otherThings.json", + "moreThings.json" + ], "configurePresets": [ { "name": "default", @@ -35,6 +39,17 @@ "displayName": "Ninja Multi-Config", "description": "Default build using Ninja Multi-Config generator", "generator": "Ninja Multi-Config" + }, + { + "name": "windows-only", + "inherits": "default", + "displayName": "Windows-only configuration", + "description": "This build is only available on Windows", + "condition": { + "type": "equals", + "lhs": "${hostSystemName}", + "rhs": "Windows" + } } ], "buildPresets": [ diff --git a/Help/manual/presets/schema.json b/Help/manual/presets/schema.json index f8faf3d..12f8b5e 100644 --- a/Help/manual/presets/schema.json +++ b/Help/manual/presets/schema.json @@ -11,7 +11,7 @@ }, "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, "vendor": { "$ref": "#/definitions/vendor" }, - "configurePresets": { "$ref": "#/definitions/configurePresets"} + "configurePresets": { "$ref": "#/definitions/configurePresetsV1"} }, "additionalProperties": false }, @@ -23,9 +23,38 @@ }, "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, "vendor": { "$ref": "#/definitions/vendor" }, - "configurePresets": { "$ref": "#/definitions/configurePresets"}, - "buildPresets": { "$ref": "#/definitions/buildPresets"}, - "testPresets": { "$ref": "#/definitions/testPresets"} + "configurePresets": { "$ref": "#/definitions/configurePresetsV1"}, + "buildPresets": { "$ref": "#/definitions/buildPresetsV2"}, + "testPresets": { "$ref": "#/definitions/testPresetsV2"} + }, + "additionalProperties": false + }, + { + "properties": { + "version": { + "const": 3, + "description": "A required integer representing the version of the JSON schema." + }, + "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, + "vendor": { "$ref": "#/definitions/vendor" }, + "configurePresets": { "$ref": "#/definitions/configurePresetsV3"}, + "buildPresets": { "$ref": "#/definitions/buildPresetsV3"}, + "testPresets": { "$ref": "#/definitions/testPresetsV3"} + }, + "additionalProperties": false + }, + { + "properties": { + "version": { + "const": 4, + "description": "A required integer representing the version of the JSON schema." + }, + "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, + "vendor": { "$ref": "#/definitions/vendor" }, + "configurePresets": { "$ref": "#/definitions/configurePresetsV3"}, + "buildPresets": { "$ref": "#/definitions/buildPresetsV4"}, + "testPresets": { "$ref": "#/definitions/testPresetsV3"}, + "include": { "$ref": "#/definitions/include"} }, "additionalProperties": false } @@ -58,7 +87,34 @@ "description": "An optional map containing vendor-specific information. CMake does not interpret the contents of this field except to verify that it is a map if it does exist. However, the keys should be a vendor-specific domain name followed by a /-separated path. For example, the Example IDE 1.0 could use example.com/ExampleIDE/1.0. The value of each field can be anything desired by the vendor, though will typically be a map.", "properties": {} }, - "configurePresets": { + "configurePresetsItemsV3": { + "type": "array", + "description": "A configure preset object.", + "items": { + "type": "object", + "description": "A configure preset object.", + "properties": { + "binaryDir": { + "type": "string", + "description": "An optional string representing the path to the output binary directory. This field supports macro expansion. If a relative path is specified, it is calculated relative to the source directory. If binaryDir is not specified, the path is calculated using regular methods." + }, + "generator": { + "type": "string", + "description": "An optional string representing the generator to use for the preset. If generator is not specified, the normal generator discovery procedure is used. Note that for Visual Studio generators, unlike in the command line -G argument, you cannot include the platform name in the generator name. Use the architecture field instead." + }, + "toolchainFile": { + "type": "string", + "description": "An optional string representing the path to the toolchain file. This field supports macro expansion. If a relative path is specified, it is calculated relative to the build directory, and if not found, relative to the source directory." + }, + "installDir": { + "type": "string", + "description": "An optional string representing the path to the installation directory. This field supports macro expansion. If a relative path is specified, it is calculated relative to the source directory." + }, + "condition": { "$ref": "#/definitions/topCondition" } + } + } + }, + "configurePresetsItemsV1": { "type": "array", "description": "An optional array of configure preset objects.", "items": { @@ -83,7 +139,7 @@ }, { "type": "array", - "description": "An optional array of strings representing the names of presets to inherit from. The preset will inherit all of the fields from the inherits presets by default (except name, hidden, inherits, description, and displayName), but can override them as desired. If multiple inherits presets provide conflicting values for the same field, the earlier preset in the inherits list will be preferred. Presets in CMakePresets.json may not inherit from presets in CMakeUserPresets.json.", + "description": "An optional array of strings representing the names of presets to inherit from. The preset will inherit all of the fields from the inherits presets by default (except name, hidden, inherits, description, and displayName), but can override them as desired. If multiple inherits presets provide conflicting values for the same field, the earlier preset in the inherits list will be preferred. Presets in CMakePresets.json must not inherit from presets in CMakeUserPresets.json.", "items": { "type": "string", "description": "An optional string representing the name of the preset to inherit from.", @@ -302,6 +358,68 @@ }, "additionalProperties": false } + } + } + }, + "configurePresetsV3": { + "type": "array", + "description": "An optional array of configure preset objects.", + "allOf": [ + { "$ref": "#/definitions/configurePresetsItemsV1" }, + { "$ref": "#/definitions/configurePresetsItemsV3" } + ], + "items": { + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "generator": {}, + "architecture": {}, + "toolset": {}, + "toolchainFile": {}, + "binaryDir": {}, + "installDir": {}, + "cmakeExecutable": {}, + "cacheVariables": {}, + "environment": {}, + "warnings": {}, + "errors": {}, + "debug": {}, + "condition": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, + "configurePresetsV1": { + "type": "array", + "description": "An optional array of configure preset objects.", + "allOf": [ + { "$ref": "#/definitions/configurePresetsItemsV1" } + ], + "items": { + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "generator": {}, + "architecture": {}, + "toolset": {}, + "binaryDir": {}, + "cmakeExecutable": {}, + "cacheVariables": {}, + "environment": {}, + "warnings": {}, + "errors": {}, + "debug": {} }, "required": [ "name" @@ -309,7 +427,33 @@ "additionalProperties": false } }, - "buildPresets": { + "buildPresetsItemsV4": { + "type": "array", + "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 4 and higher.", + "items": { + "type": "object", + "properties": { + "resolvePackageReferences": { + "type": "string", + "description": "An optional string specifying the package resolve behavior. Valid values are \"on\" (packages are resolved prior to the build), \"off\" (packages are not resolved prior to the build), and \"only\" (packages are resolved, but no build will be performed).", + "enum": [ + "on", "off", "only" + ] + } + } + } + }, + "buildPresetsItemsV3": { + "type": "array", + "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 3 and higher.", + "items": { + "type": "object", + "properties": { + "condition": { "$ref": "#/definitions/topCondition" } + } + } + }, + "buildPresetsItemsV2": { "type": "array", "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.", "items": { @@ -333,7 +477,7 @@ }, { "type": "array", - "description": "An optional array of strings representing the names of build presets to inherit from. The preset will inherit all of the fields from the inherits presets by default (except name, hidden, inherits, description, and displayName), but can override them as desired. If multiple inherits presets provide conflicting values for the same field, the earlier preset in the inherits list will be preferred. Presets in CMakePresets.json may not inherit from presets in CMakeUserPresets.json.", + "description": "An optional array of strings representing the names of build presets to inherit from. The preset will inherit all of the fields from the inherits presets by default (except name, hidden, inherits, description, and displayName), but can override them as desired. If multiple inherits presets provide conflicting values for the same field, the earlier preset in the inherits list will be preferred. Presets in CMakePresets.json must not inherit from presets in CMakeUserPresets.json.", "items": { "type": "string", "description": "An optional string representing the name of the preset to inherit from.", @@ -427,11 +571,119 @@ }, "required": [ "name" + ] + } + }, + "buildPresetsV4": { + "type": "array", + "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 4 and higher.", + "allOf": [ + { "$ref": "#/definitions/buildPresetsItemsV4" }, + { "$ref": "#/definitions/buildPresetsItemsV3" }, + { "$ref": "#/definitions/buildPresetsItemsV2" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "jobs": {}, + "targets": {}, + "configuration": {}, + "cleanFirst": {}, + "resolvePackageReferences": {}, + "verbose": {}, + "nativeToolOptions": {}, + "condition": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, + "buildPresetsV3": { + "type": "array", + "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 3 and higher.", + "allOf": [ + { "$ref": "#/definitions/buildPresetsItemsV3" }, + { "$ref": "#/definitions/buildPresetsItemsV2" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "jobs": {}, + "targets": {}, + "configuration": {}, + "cleanFirst": {}, + "verbose": {}, + "nativeToolOptions": {}, + "condition": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, + "buildPresetsV2": { + "type": "array", + "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.", + "allOf": [ + { "$ref": "#/definitions/buildPresetsItemsV2" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "jobs": {}, + "targets": {}, + "configuration": {}, + "cleanFirst": {}, + "verbose": {}, + "nativeToolOptions": {} + }, + "required": [ + "name" ], "additionalProperties": false } }, - "testPresets": { + "testPresetsItemsV3": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 3 and higher.", + "items": { + "type": "object", + "properties": { + "condition": { "$ref": "#/definitions/topCondition" } + } + } + }, + "testPresetsItemsV2": { "type": "array", "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.", "items": { @@ -455,7 +707,7 @@ }, { "type": "array", - "description": "An optional array of strings representing the names of test presets to inherit from. The preset will inherit all of the fields from the inherits presets by default (except name, hidden, inherits, description, and displayName), but can override them as desired. If multiple inherits presets provide conflicting values for the same field, the earlier preset in the inherits list will be preferred. Presets in CMakePresets.json may not inherit from presets in CMakeUserPresets.json.", + "description": "An optional array of strings representing the names of test presets to inherit from. The preset will inherit all of the fields from the inherits presets by default (except name, hidden, inherits, description, and displayName), but can override them as desired. If multiple inherits presets provide conflicting values for the same field, the earlier preset in the inherits list will be preferred. Presets in CMakePresets.json must not inherit from presets in CMakeUserPresets.json.", "items": { "type": "string", "description": "An optional string representing the name of the preset to inherit from.", @@ -743,9 +995,319 @@ }, "required": [ "name" + ] + } + }, + "testPresetsV3": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 3 and higher.", + "allOf": [ + { "$ref": "#/definitions/testPresetsItemsV2" }, + { "$ref": "#/definitions/testPresetsItemsV3" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "configuration": {}, + "overwriteConfigurationFile": {}, + "output": {}, + "filter": {}, + "execution": {}, + "condition": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, + "testPresetsV2": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.", + "allOf": [ + { "$ref": "#/definitions/testPresetsItemsV2" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "configuration": {}, + "overwriteConfigurationFile": {}, + "output": {}, + "filter": {}, + "execution": {} + }, + "required": [ + "name" ], "additionalProperties": false } + }, + "condition": { + "anyOf": [ + { + "type": "boolean", + "description": "A boolean which provides a constant value for the condition's evaluation." + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "const" + }, + "value": { + "type": "boolean", + "description": "A required boolean which provides a constant value for the condition's evaluation." + } + }, + "required": [ + "type", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "equals" + }, + "lhs": { + "type": "string", + "description": "First string to compare. This field supports macro expansion." + }, + "rhs": { + "type": "string", + "description": "Second string to compare. This field supports macro expansion." + } + }, + "required": [ + "type", + "lhs", + "rhs" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "notEquals" + }, + "lhs": { + "type": "string", + "description": "First string to compare. This field supports macro expansion." + }, + "rhs": { + "type": "string", + "description": "Second string to compare. This field supports macro expansion." + } + }, + "required": [ + "type", + "lhs", + "rhs" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "inList" + }, + "string": { + "type": "string", + "description": "A required string to search for. This field supports macro expansion." + }, + "list": { + "type": "array", + "description": "A required list of strings to search. This field supports macro expansion, and uses short-circuit evaluation.", + "items": { + "type": "string" + } + } + }, + "required": [ + "type", + "string", + "list" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "notInList" + }, + "string": { + "type": "string", + "description": "A required string to search for. This field supports macro expansion." + }, + "list": { + "type": "array", + "description": "A required list of strings to search. This field supports macro expansion, and uses short-circuit evaluation.", + "items": { + "type": "string" + } + } + }, + "required": [ + "type", + "string", + "list" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "matches" + }, + "string": { + "type": "string", + "description": "A required string to search. This field supports macro expansion." + }, + "regex": { + "type": "string", + "description": "A required regular expression to search for. This field supports macro expansion." + } + }, + "required": [ + "type", + "string", + "regex" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "notMatches" + }, + "string": { + "type": "string", + "description": "A required string to search. This field supports macro expansion." + }, + "regex": { + "type": "string", + "description": "A required regular expression to search for. This field supports macro expansion." + } + }, + "required": [ + "type", + "string", + "regex" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "anyOf" + }, + "conditions": { + "type": "array", + "description": "A required array of condition objects. These conditions use short-circuit evaluation.", + "items": { "$ref": "#/definitions/condition" } + } + }, + "required": [ + "type", + "conditions" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "allOf" + }, + "conditions": { + "type": "array", + "description": "A required array of condition objects. These conditions use short-circuit evaluation.", + "items": { "$ref": "#/definitions/condition" } + } + }, + "required": [ + "type", + "conditions" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "not" + }, + "condition": { "$ref": "#/definitions/condition" } + }, + "required": [ + "type", + "condition" + ], + "additionalProperties": false + } + ] + }, + "topCondition": { + "anyOf": [ + { "$ref": "#/definitions/condition" }, + { + "type": "null", + "description": "Null indicates that the condition always evaluates to true and is not inherited." + } + ] + }, + "include": { + "type": "array", + "description": "An optional array of strings representing files to include. If the filenames are not absolute, they are considered relative to the current file.", + "items": { + "type": "string" + } } } } diff --git a/Help/module/FindMsys.rst b/Help/module/FindMsys.rst new file mode 100644 index 0000000..fc5495c --- /dev/null +++ b/Help/module/FindMsys.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindMsys.cmake diff --git a/Help/policy/CMP0028.rst b/Help/policy/CMP0028.rst index ab38229..dcd39d8 100644 --- a/Help/policy/CMP0028.rst +++ b/Help/policy/CMP0028.rst @@ -13,6 +13,8 @@ on disk. Previously, if a target was not found with a matching name, the name was considered to refer to a file on disk. This can lead to confusing error messages if there is a typo in what should be a target name. +See also the :prop_tgt:`LINK_LIBRARIES_ONLY_TARGETS` target property. + The ``OLD`` behavior for this policy is to search for targets, then files on disk, even if the search term contains double-colons. The ``NEW`` behavior for this policy is to issue a ``FATAL_ERROR`` if a link dependency contains diff --git a/Help/policy/CMP0077.rst b/Help/policy/CMP0077.rst index 174cde9..482125a 100644 --- a/Help/policy/CMP0077.rst +++ b/Help/policy/CMP0077.rst @@ -46,9 +46,15 @@ name: variable of the same name exists. The normal variable is not removed. The cache entry is not created or updated and is ignored if it exists. +See :policy:`CMP0126` for a similar policy for the :command:`set(CACHE)` +command, but note that there are some differences in ``NEW`` behavior +between the two policies. + This policy was introduced in CMake version 3.13. 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. +explicitly within a project. Use the :variable:`CMAKE_POLICY_DEFAULT_CMP0077 +<CMAKE_POLICY_DEFAULT_CMP\<NNNN\>>` variable to set the policy for +a third-party project in a subdirectory without modifying it. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0102.rst b/Help/policy/CMP0102.rst index 78b5584..08024bf 100644 --- a/Help/policy/CMP0102.rst +++ b/Help/policy/CMP0102.rst @@ -22,6 +22,8 @@ already exist in the cache. 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. +when this policy is not set and simply uses ``OLD`` behavior. See +documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0102 +<CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0104.rst b/Help/policy/CMP0104.rst index 7c7a16e..b125729 100644 --- a/Help/policy/CMP0104.rst +++ b/Help/policy/CMP0104.rst @@ -41,7 +41,7 @@ Examples .. code-block:: cmake - set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES 35 50 72) + set_target_properties(tgt PROPERTIES CUDA_ARCHITECTURES "35;50;72") Generates code for real and virtual architectures ``30``, ``50`` and ``72``. diff --git a/Help/policy/CMP0110.rst b/Help/policy/CMP0110.rst index 25a0008..6977d41 100644 --- a/Help/policy/CMP0110.rst +++ b/Help/policy/CMP0110.rst @@ -8,7 +8,7 @@ CMP0110 :command:`add_test` can now (officially) create tests with whitespace and other special characters in its name. Before CMake version 3.19 that was not allowed, however, it was possible to work around this limitation by explicitly -putting escaped quotes arount the test's name in the ``add_test`` command. +putting escaped quotes around the test's name in the ``add_test`` command. Although never officially supported several projects in the wild found and implemented this workaround. However, the new change which officially allows diff --git a/Help/policy/CMP0112.rst b/Help/policy/CMP0112.rst index 313a51e..5b00d07 100644 --- a/Help/policy/CMP0112.rst +++ b/Help/policy/CMP0112.rst @@ -24,7 +24,9 @@ file name components no longer add a dependency on the evaluated target. In CMake 3.18 and lower a dependency on the evaluated target of the above generator expressions would always be added. CMake 3.19 and above prefer to not add this dependency. This policy provides compatibility for projects -that have not been updated to expect the new behavior. +that have not been updated to expect the new behavior. The policy setting +is recorded on each target when it is created, and decides whether generator +expressions referencing that target imply a dependency on it. The ``OLD`` behavior for this policy is to add a dependency on the evaluated target for the above generator expressions. The ``NEW`` behavior of diff --git a/Help/policy/CMP0121.rst b/Help/policy/CMP0121.rst new file mode 100644 index 0000000..326e7d5 --- /dev/null +++ b/Help/policy/CMP0121.rst @@ -0,0 +1,21 @@ +CMP0121 +------- + +.. versionadded:: 3.21 + +The :command:`list` command now detects invalid indices. + +Prior to CMake version 3.21, the :command:`list` command's ``GET``, +``INSERT``, ``SUBLIST``, and ``REMOVE_AT`` subcommands did not detect invalid +index arguments. + +The ``OLD`` behavior of this policy is for invalid indices to be treated as +their integer value (if any) at the start of the string. For example, +``2good4you`` is a ``2`` and ``not_an_integer`` is a ``0``. The ``NEW`` +behavior is for invalid indices to trigger an error. + +This policy was introduced in CMake version 3.21. 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/CMP0122.rst b/Help/policy/CMP0122.rst new file mode 100644 index 0000000..1ff8c48 --- /dev/null +++ b/Help/policy/CMP0122.rst @@ -0,0 +1,17 @@ +CMP0122 +------- + +.. versionadded:: 3.21 + +:module:`UseSWIG` use library name conventions for ``CSharp`` language. + +Starting with CMake 3.21, :module:`UseSWIG` generates now a library using +default naming conventions. This policy provides compatibility with projects +that expect the legacy behavior. + +This policy was introduced in CMake version 3.21. 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/CMP0123.rst b/Help/policy/CMP0123.rst new file mode 100644 index 0000000..e09b5ec --- /dev/null +++ b/Help/policy/CMP0123.rst @@ -0,0 +1,32 @@ +CMP0123 +------- + +.. versionadded:: 3.21 + +``ARMClang`` cpu/arch compile and link flags must be set explicitly. + +CMake 3.20 and lower automatically maps the :variable:`CMAKE_SYSTEM_PROCESSOR` +variable and an undocumented ``CMAKE_SYSTEM_ARCH`` to compile and link options +for ``ARMClang``. For example, the ``-mcpu=cortex-m33`` flag is added when +:variable:`CMAKE_SYSTEM_PROCESSOR` equals ``cortex-m33``. CMake requires +projects to set either variable or it raises a fatal error. However, the +project may need to additionally specify CPU features using e.g. +``-mcpu=cortex-m33+nodsp``, conflicting with the ``-mcpu=cortex-m33`` added +by CMake. This results in either link errors or unusable binaries. + +CMake 3.21 and above prefer instead to not add any cpu/arch compile and link +flags automatically. Instead, projects must specify them explicitly. +This policy provides compatibility for projects that have not been updated. + +The ``OLD`` behavior of this policy requires projects that use ``ARMClang`` +to set either :variable:`CMAKE_SYSTEM_PROCESSOR` or ``CMAKE_SYSTEM_ARCH`` +and it automatically adds a compile option ``-mcpu=`` or ``-march=`` and +a link option ``--cpu=`` based on those variables. The ``NEW`` behavior +does not add compile or link options, and projects are responsible for +setting correct options. + +This policy was introduced in CMake version 3.21. 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/CMP0124.rst b/Help/policy/CMP0124.rst new file mode 100644 index 0000000..3935166 --- /dev/null +++ b/Help/policy/CMP0124.rst @@ -0,0 +1,18 @@ +CMP0124 +------- + +.. versionadded:: 3.21 + +When this policy is set to ``NEW``, the scope of loop variables defined by the +:command:`foreach` command is restricted to the loop only. They will be unset +at the end of the loop. + +The ``OLD`` behavior for this policy still clears the loop variables at the end +of the loop, but does not unset them. This leaves them as defined, but empty. + +This policy was introduced in CMake version 3.21. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike many policies, CMake version |release| does *not* warn when the policy +is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0125.rst b/Help/policy/CMP0125.rst new file mode 100644 index 0000000..0b1704e --- /dev/null +++ b/Help/policy/CMP0125.rst @@ -0,0 +1,42 @@ +CMP0125 +------- + +.. versionadded:: 3.21 + +The :command:`find_file`, :command:`find_path`, :command:`find_library` and +:command:`find_program` commands cache their result in the variable specified +by their first argument. Prior to CMake 3.21, if a cache variable of that +name already existed before the call but the cache variable had no type, any +non-cache variable of the same name would be discarded and the cache variable +was always used (see also :policy:`CMP0126` for a different but similar +behavior). This contradicts the convention that a non-cache variable should +take precedence over a cache variable of the same name. Such a situation can +arise if a user sets a cache variable on the command line without specifying +a type, such as ``cmake -DMYVAR=blah ...`` instead of +``cmake -DMYVAR:FILEPATH=blah``. + +Related to the above, if a cache variable of the specified name already exists +and it *does* have a type, the various ``find_...()`` commands would return +that value unchanged. In particular, if it contained a relative path, it +would not be converted to an absolute path in this situation. + +When policy ``CMP0125`` is set to ``OLD`` or is unset, the behavior is as +described above. When it is set to ``NEW``, the behavior is as follows: + +* If a non-cache variable of the specified name exists when the ``find_...()`` + command is called, its value will be used regardless of whether a cache + variable of the same name already exists or not. A cache variable will not + be created in this case if no such cache variable existed before. + If a cache variable of the specified name did already exist, the cache will + be updated to match the non-cache variable. + +* The various ``find...()`` commands will always provide an absolute path in + the result variable, except where a relative path provided by a cache or + non-cache variable cannot be resolved to an existing path. + +This policy was introduced in CMake version 3.21. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike many policies, CMake version |release| does *not* warn when the policy +is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0126.rst b/Help/policy/CMP0126.rst new file mode 100644 index 0000000..a389512 --- /dev/null +++ b/Help/policy/CMP0126.rst @@ -0,0 +1,37 @@ +CMP0126 +------- + +.. versionadded:: 3.21 + +When this policy is set to ``NEW``, the :command:`set(CACHE)` command does not +remove any normal variable of the same name from the current scope. +The ``OLD`` behavior removes any normal variable of the same name from the +current scope in the following situations: + +* No cache variable of that name existed previously. + +* A cache variable of that name existed previously, but it had no type. + This can occur when the variable was set on the command line using a form + like ``cmake -DMYVAR=blah`` instead of ``cmake -DMYVAR:STRING=blah``. + +* The ``FORCE`` or ``INTERNAL`` keywords were used when setting the cache + variable. + +Note that the ``NEW`` behavior has an important difference to the similar +``NEW`` behavior of policy :policy:`CMP0077`. The :command:`set(CACHE)` +command always sets the cache variable if it did not exist previously, +regardless of the ``CMP0126`` policy setting. The :command:`option` command +will *not* set the cache variable if a non-cache variable of the same name +already exists and :policy:`CMP0077` is set to ``NEW``. + +Policy ``CMP0126`` was introduced in CMake version 3.21. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly +within a project. Use the :variable:`CMAKE_POLICY_DEFAULT_CMP0126 +<CMAKE_POLICY_DEFAULT_CMP\<NNNN\>>` variable to set the policy for +a third-party project in a subdirectory without modifying it. +Unlike many policies, CMake version |release| does *not* warn when the policy +is not set and simply uses ``OLD`` behavior. See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0126 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0127.rst b/Help/policy/CMP0127.rst new file mode 100644 index 0000000..2106110 --- /dev/null +++ b/Help/policy/CMP0127.rst @@ -0,0 +1,34 @@ +CMP0127 +------- + +.. versionadded:: 3.22 + +:command:`cmake_dependent_option` supports full :ref:`Condition Syntax`. + +The ``<depends>`` parameter accepts a :ref:`semicolon-separated list <CMake +Language Lists>` of conditions. CMake 3.21 and lower evaluates each +``condition`` as ``if(${condition})``, which does not properly handle +conditions with nested paren groups. CMake 3.22 and above instead prefer +to evaluate each ``condition`` as ``if(<condition>)``, where ``<condition>`` +is re-parsed as if literally written in a call to :command:`if`. This +allows expressions like:: + + "A AND (B OR C)" + +but requires expressions like:: + + "FOO MATCHES (UPPER|lower)" + +to be re-written as:: + + "FOO MATCHES \"(UPPER|lower)\"" + +Policy ``CMP0127`` provides compatibility for projects that have not +been updated to expect the new behavior. + +This policy was introduced in CMake version 3.22. 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/CMP0128.rst b/Help/policy/CMP0128.rst new file mode 100644 index 0000000..604a146 --- /dev/null +++ b/Help/policy/CMP0128.rst @@ -0,0 +1,71 @@ +CMP0128 +------- + +.. versionadded:: 3.22 + +When this policy is set to ``NEW``: + +* :prop_tgt:`<LANG>_EXTENSIONS` is initialized to + :variable:`CMAKE_<LANG>_EXTENSIONS` if set, otherwise falling back to + :variable:`CMAKE_<LANG>_EXTENSIONS_DEFAULT`. + +* Extensions are correctly enabled/disabled if :prop_tgt:`<LANG>_STANDARD` is + unset or satisfied by the default. + +* Standard mode-affecting flags aren't added unless necessary to achieve the + specified mode. + +The ``OLD`` behavior: + +* Initializes :prop_tgt:`<LANG>_EXTENSIONS` to + :variable:`CMAKE_<LANG>_EXTENSIONS` if set, otherwise falling back to ``ON``. + +* Always adds a flag if :prop_tgt:`<LANG>_STANDARD` is set and + :prop_tgt:`<LANG>_STANDARD_REQUIRED` is ``OFF``. + +* If :prop_tgt:`<LANG>_STANDARD` is unset: + + * Doesn't disable extensions even if :prop_tgt:`<LANG>_EXTENSIONS` is + ``OFF``. + + * Fails to enable extensions if :prop_tgt:`<LANG>_EXTENSIONS` is ``ON`` + except for the ``IAR`` compiler. + +Code may need to be updated for the ``NEW`` behavior in the following cases: + +* If a standard mode flag previously overridden by CMake's and not used during + compiler detection now takes effect due to CMake no longer adding one as the + default detected is appropriate. + + Such code should be converted to either: + + * Use :prop_tgt:`<LANG>_STANDARD` and :prop_tgt:`<LANG>_EXTENSIONS` instead + of manually adding flags. + + * Or ensure the manually-specified flags are used during compiler detection. + +* If extensions were disabled without :prop_tgt:`<LANG>_STANDARD` being set + CMake previously wouldn't actually disable extensions. + + Such code should be updated to not disable extensions if they are required. + +* If extensions were enabled/disabled when :prop_tgt:`<LANG>_STANDARD` was + satisfied by the compiler's default CMake previously wouldn't actually + enable/disable extensions. + + Such code should be updated to set the correct extensions mode. + +If compiler flags affecting the standard mode are used during compiler +detection (for example in :manual:`a toolchain file <cmake-toolchains(7)>` +using :variable:`CMAKE_<LANG>_FLAGS_INIT`) then they will affect the detected +default :variable:`standard <CMAKE_<LANG>_STANDARD_DEFAULT>` and +:variable:`extensions <CMAKE_<LANG>_EXTENSIONS_DEFAULT>`. + +Unlike many policies, CMake version |release| does *not* warn when the policy +is not set and simply uses the ``OLD`` behavior. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0128 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0129.rst b/Help/policy/CMP0129.rst new file mode 100644 index 0000000..31a26e5 --- /dev/null +++ b/Help/policy/CMP0129.rst @@ -0,0 +1,34 @@ +CMP0129 +------- + +.. versionadded:: 3.23 + +Compiler id for MCST LCC compilers is now ``LCC``, not ``GNU``. + +CMake 3.23 and above recognize MCST LCC compiler as a different from ``GNU``, +with its own command line and set of capabilities. +CMake now prefers to present this to projects by setting the +:variable:`CMAKE_<LANG>_COMPILER_ID` variable to ``LCC`` instead +of ``GNU``. However, existing projects may assume the compiler id for +LCC is ``GNU`` as it was in CMake versions prior to 3.23. +Therefore this policy determines for MCST LCC compiler which +compiler id to report in the :variable:`CMAKE_<LANG>_COMPILER_ID` +variable after language ``<LANG>`` is enabled by the :command:`project` +or :command:`enable_language` command. The policy must be set prior +to the invocation of either command. + +The ``OLD`` behavior for this policy is to use compiler id ``GNU`` (and set +:variable:`CMAKE_<LANG>_COMPILER_VERSION` to the supported GNU compiler version.) +``NEW`` behavior for this policy is to use compiler id ``LCC``, and set +:variable:`CMAKE_<LANG>_SIMULATE_ID` to ``GNU``, and +:variable:`CMAKE_<LANG>_SIMULATE_VERSION` to the supported GNU compiler version. + +This policy was introduced in CMake version 3.23. Use the +:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW`` explicitly. +Unlike most policies, CMake version |release| does *not* warn +by default when this policy is not set and simply uses ``OLD`` behavior. +See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0129 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/prop_dir/BUILDSYSTEM_TARGETS.rst b/Help/prop_dir/BUILDSYSTEM_TARGETS.rst index 5c5893d..c998488 100644 --- a/Help/prop_dir/BUILDSYSTEM_TARGETS.rst +++ b/Help/prop_dir/BUILDSYSTEM_TARGETS.rst @@ -11,3 +11,5 @@ and :command:`add_custom_target` commands. The list does not include any :ref:`Interface Libraries`. Each entry in the list is the logical name of a target, suitable to pass to the :command:`get_property` command ``TARGET`` option. + +See also the :prop_dir:`IMPORTED_TARGETS` directory property. diff --git a/Help/prop_dir/IMPORTED_TARGETS.rst b/Help/prop_dir/IMPORTED_TARGETS.rst new file mode 100644 index 0000000..fea8a93 --- /dev/null +++ b/Help/prop_dir/IMPORTED_TARGETS.rst @@ -0,0 +1,14 @@ +IMPORTED_TARGETS +---------------- + +.. versionadded:: 3.21 + +This read-only directory property contains a +:ref:`semicolon-separated list <CMake Language Lists>` of +:ref:`Imported Targets` added in the directory by calls to the +:command:`add_library` and :command:`add_executable` commands. +Each entry in the list is the logical name of a target, suitable +to pass to the :command:`get_property` command ``TARGET`` option +when called in the same directory. + +See also the :prop_dir:`BUILDSYSTEM_TARGETS` directory property. diff --git a/Help/prop_gbl/AUTOGEN_SOURCE_GROUP.rst b/Help/prop_gbl/AUTOGEN_SOURCE_GROUP.rst index 2e32320..07c732b 100644 --- a/Help/prop_gbl/AUTOGEN_SOURCE_GROUP.rst +++ b/Help/prop_gbl/AUTOGEN_SOURCE_GROUP.rst @@ -3,15 +3,16 @@ AUTOGEN_SOURCE_GROUP .. versionadded:: 3.9 -Name of the :command:`source_group` for :prop_tgt:`AUTOMOC` and -:prop_tgt:`AUTORCC` generated files. +Name of the :command:`source_group` for :prop_tgt:`AUTOMOC`, +:prop_tgt:`AUTORCC` and :prop_tgt:`AUTOUIC` generated files. -Files generated by :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTORCC` are not always -known at configure time and therefore can't be passed to -:command:`source_group`. -:prop_gbl:`AUTOGEN_SOURCE_GROUP` an be used instead to generate or select -a source group for :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTORCC` generated files. +Files generated by :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTORCC` and +:prop_tgt:`AUTOUIC` are not always known at configure time and therefore can't +be passed to :command:`source_group`. +:prop_gbl:`AUTOGEN_SOURCE_GROUP` can be used instead to generate or select +a source group for :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTORCC` and +:prop_tgt:`AUTOUIC` generated files. -For :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTORCC` specific overrides see -:prop_gbl:`AUTOMOC_SOURCE_GROUP` and :prop_gbl:`AUTORCC_SOURCE_GROUP` -respectively. +For :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTORCC` and :prop_tgt:`AUTOUIC` specific +overrides see :prop_gbl:`AUTOMOC_SOURCE_GROUP`, :prop_gbl:`AUTORCC_SOURCE_GROUP` +and :prop_gbl:`AUTOUIC_SOURCE_GROUP` respectively. diff --git a/Help/prop_gbl/AUTOUIC_SOURCE_GROUP.rst b/Help/prop_gbl/AUTOUIC_SOURCE_GROUP.rst new file mode 100644 index 0000000..79ebfe0 --- /dev/null +++ b/Help/prop_gbl/AUTOUIC_SOURCE_GROUP.rst @@ -0,0 +1,9 @@ +AUTOUIC_SOURCE_GROUP +-------------------- + +.. versionadded:: 3.21 + +Name of the :command:`source_group` for :prop_tgt:`AUTOUIC` generated files. + +When set this is used instead of :prop_gbl:`AUTOGEN_SOURCE_GROUP` for +files generated by :prop_tgt:`AUTOUIC`. diff --git a/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst index 6bbb870..d93a9c1 100644 --- a/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst @@ -32,4 +32,8 @@ The features known to this version of CMake are: Compiler mode is at least CUDA/C++ 20. ``cuda_std_23`` + .. versionadded:: 3.20 + Compiler mode is at least CUDA/C++ 23. + +.. include:: CMAKE_LANG_STD_FLAGS.txt diff --git a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst index 73c0b34..6846850 100644 --- a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst @@ -18,6 +18,8 @@ The features known to this version of CMake are listed below. High level meta features indicating C++ standard support ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. versionadded:: 3.8 + The following meta features indicate general support for the associated language standard. It reflects the language support claimed by the compiler, but it does not necessarily imply complete conformance to that standard. @@ -35,11 +37,17 @@ but it does not necessarily imply complete conformance to that standard. Compiler mode is at least C++ 17. ``cxx_std_20`` + .. versionadded:: 3.12 + Compiler mode is at least C++ 20. ``cxx_std_23`` + .. versionadded:: 3.20 + Compiler mode is at least C++ 23. +.. include:: CMAKE_LANG_STD_FLAGS.txt + Low level individual compile features ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst index 7166381..7aca9e8 100644 --- a/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst @@ -13,7 +13,12 @@ The features listed here may be used with the :command:`target_compile_features` command. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. -The features known to this version of CMake are: +The features known to this version of CMake are listed below. + +High level meta features indicating C standard support +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 3.8 ``c_std_90`` Compiler mode is at least C 90. @@ -24,6 +29,21 @@ The features known to this version of CMake are: ``c_std_11`` Compiler mode is at least C 11. +``c_std_17`` + .. versionadded:: 3.21 + + Compiler mode is at least C 17. + +``c_std_23`` + .. versionadded:: 3.21 + + Compiler mode is at least C 23. + +.. include:: CMAKE_LANG_STD_FLAGS.txt + +Low level individual compile features +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + ``c_function_prototypes`` Function prototypes, as defined in ``ISO/IEC 9899:1990``. diff --git a/Help/prop_gbl/CMAKE_LANG_STD_FLAGS.txt b/Help/prop_gbl/CMAKE_LANG_STD_FLAGS.txt new file mode 100644 index 0000000..0de2d3d --- /dev/null +++ b/Help/prop_gbl/CMAKE_LANG_STD_FLAGS.txt @@ -0,0 +1,7 @@ +.. note:: + + If the compiler's default standard level is at least that + of the requested feature, CMake may omit the ``-std=`` flag. + The flag may still be added if the compiler's default extensions mode + does not match the :prop_tgt:`<LANG>_EXTENSIONS` target property, + or if the :prop_tgt:`<LANG>_STANDARD` target property is set. diff --git a/Help/prop_sf/COMPILE_FLAGS.rst b/Help/prop_sf/COMPILE_FLAGS.rst index c211b89..eefe7bf 100644 --- a/Help/prop_sf/COMPILE_FLAGS.rst +++ b/Help/prop_sf/COMPILE_FLAGS.rst @@ -4,8 +4,11 @@ COMPILE_FLAGS Additional flags to be added when compiling this source file. The ``COMPILE_FLAGS`` property, managed as a string, sets additional compiler -flags used to build source files. Use :prop_sf:`COMPILE_DEFINITIONS` to pass -additional preprocessor definitions. +flags used that will be added to the list of compile flags when this source +file builds. The flags will be added after target-wide flags (except in +some cases not supported by the :generator:`Visual Studio 9 2008` generator). + +Use :prop_sf:`COMPILE_DEFINITIONS` to pass additional preprocessor definitions. Contents of ``COMPILE_FLAGS`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` diff --git a/Help/prop_sf/COMPILE_OPTIONS.rst b/Help/prop_sf/COMPILE_OPTIONS.rst index a694c3e..84c543a 100644 --- a/Help/prop_sf/COMPILE_OPTIONS.rst +++ b/Help/prop_sf/COMPILE_OPTIONS.rst @@ -5,9 +5,10 @@ COMPILE_OPTIONS 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. +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. The options will be added after target-wide options (except in +some cases not supported by the :generator:`Visual Studio 9 2008` generator). Contents of ``COMPILE_OPTIONS`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual diff --git a/Help/prop_sf/GENERATED.rst b/Help/prop_sf/GENERATED.rst index 6ef4580..216dfe8 100644 --- a/Help/prop_sf/GENERATED.rst +++ b/Help/prop_sf/GENERATED.rst @@ -32,9 +32,10 @@ The :ref:`Makefile Generators` will remove ``GENERATED`` files during ``make clean``. Generated sources may be hidden in some IDE tools, while in others they might -be shown. For the special case of sources generated by CMake's :prop_tgt:`AUTOMOC` -or :prop_tgt:`AUTORCC` functionality, the :prop_gbl:`AUTOGEN_SOURCE_GROUP`, -:prop_gbl:`AUTOMOC_SOURCE_GROUP` and :prop_gbl:`AUTORCC_SOURCE_GROUP` target +be shown. For the special case of sources generated by CMake's :prop_tgt:`AUTOMOC`, +:prop_tgt:`AUTORCC` or :prop_tgt:`AUTOUIC` functionality, the +:prop_gbl:`AUTOGEN_SOURCE_GROUP`, :prop_gbl:`AUTOMOC_SOURCE_GROUP`, +:prop_gbl:`AUTORCC_SOURCE_GROUP` and :prop_gbl:`AUTOUIC_SOURCE_GROUP` target properties may influence where the generated sources are grouped in the project's file lists. diff --git a/Help/prop_sf/LANGUAGE.rst b/Help/prop_sf/LANGUAGE.rst index f14c176..92bd227 100644 --- a/Help/prop_sf/LANGUAGE.rst +++ b/Help/prop_sf/LANGUAGE.rst @@ -6,9 +6,9 @@ Specify the programming language in which a source file is written. A property that can be set to indicate what programming language the source file is. If it is not set the language is determined based on the file extension. Typical values are ``CXX`` (i.e. C++), ``C``, -``CSharp``, ``CUDA``, ``Fortran``, ``ISPC``, and ``ASM``. Setting this -property for a file means this file will be compiled. Do not set this -for headers or files that should not be compiled. +``CSharp``, ``CUDA``, ``Fortran``, ``HIP``, ``ISPC``, and ``ASM``. Setting +this property for a file means this file will be compiled, unless +:prop_sf:`HEADER_FILE_ONLY` is set. .. versionchanged:: 3.20 Setting this property causes the source file to be compiled as the diff --git a/Help/prop_sf/VS_SETTINGS.rst b/Help/prop_sf/VS_SETTINGS.rst index 322f5a6..871e36e 100644 --- a/Help/prop_sf/VS_SETTINGS.rst +++ b/Help/prop_sf/VS_SETTINGS.rst @@ -3,7 +3,12 @@ VS_SETTINGS .. versionadded:: 3.18 -Set any item metadata on a non-built file. +Set any item metadata on a file. + +.. versionadded:: 3.22 + + This property is honored for all source file types. + Previously it worked only for non-built files. Takes a list of ``Key=Value`` pairs. Tells the Visual Studio generator to set ``Key`` to ``Value`` as item metadata on the file. diff --git a/Help/prop_test/ENVIRONMENT.rst b/Help/prop_test/ENVIRONMENT.rst index 102c792..07b96bb 100644 --- a/Help/prop_test/ENVIRONMENT.rst +++ b/Help/prop_test/ENVIRONMENT.rst @@ -3,7 +3,7 @@ ENVIRONMENT Specify environment variables that should be defined for running a test. -If set to a list of environment variables and values of the form -``MYVAR=value`` those environment variables will be defined while running -the test. The environment is restored to its previous state after the -test is done. +Set to a :ref:`semicolon-separated list <CMake Language Lists>` list +of environment variables and values of the form ``MYVAR=value``. +Those environment variables will be defined while running the test. +The environment changes from this property do not affect other tests. diff --git a/Help/prop_test/ENVIRONMENT_MODIFICATION.rst b/Help/prop_test/ENVIRONMENT_MODIFICATION.rst new file mode 100644 index 0000000..a80651a --- /dev/null +++ b/Help/prop_test/ENVIRONMENT_MODIFICATION.rst @@ -0,0 +1,39 @@ +ENVIRONMENT_MODIFICATION +------------------------ + +.. versionadded:: 3.22 + +Specify environment variables that should be modified for running a test. Note +that the operations performed by this property are performed after the +:prop_test:`ENVIRONMENT` property is already applied. + +Set to a :ref:`semicolon-separated list <CMake Language Lists>` of +environment variables and values of the form ``MYVAR=OP:VALUE``, +where ``MYVAR`` is the case-sensitive name of an environment variable +to be modified. Entries are considered in the order specified in the +property's value. The ``OP`` may be one of: + + - ``reset``: Reset to the unmodified value, ignoring all modifications to + ``MYVAR`` prior to this entry. Note that this will reset the variable to + the value set by :prop_test:`ENVIRONMENT`, if it was set, and otherwise + to its state from the rest of the CTest execution. + - ``set``: Replaces the current value of ``MYVAR`` with ``VALUE``. + - ``unset``: Unsets the current value of ``MYVAR``. + - ``string_append``: Appends ``VALUE`` to the current value of ``MYVAR``. + - ``string_prepend``: Prepends ``VALUE`` to the current value of ``MYVAR``. + - ``path_list_append``: Appends ``VALUE`` to the current value of ``MYVAR`` + using the host platform's path list separator (``;`` on Windows and ``:`` + elsewhere). + - ``path_list_prepend``: Prepends ``VALUE`` to the current value of + ``MYVAR`` using the host platform's path list separator (``;`` on Windows + and ``:`` elsewhere). + - ``cmake_list_append``: Appends ``VALUE`` to the current value of ``MYVAR`` + using ``;`` as the separator. + - ``cmake_list_prepend``: Prepends ``VALUE`` to the current value of + ``MYVAR`` using ``;`` as the separator. + +Unrecognized ``OP`` values will result in the test failing before it is +executed. This is so that future operations may be added without changing +valid behavior of existing tests. + +The environment changes from this property do not affect other tests. diff --git a/Help/prop_test/FAIL_REGULAR_EXPRESSION.rst b/Help/prop_test/FAIL_REGULAR_EXPRESSION.rst index facf902..1ec4517 100644 --- a/Help/prop_test/FAIL_REGULAR_EXPRESSION.rst +++ b/Help/prop_test/FAIL_REGULAR_EXPRESSION.rst @@ -1,7 +1,8 @@ FAIL_REGULAR_EXPRESSION ----------------------- -If the output matches this regular expression the test will fail. +If the output matches this regular expression the test will fail, +regardless of the process exit code. If set, if the output matches one of specified regular expressions, the test will fail. Example: @@ -13,3 +14,6 @@ the test will fail. Example: ) ``FAIL_REGULAR_EXPRESSION`` expects a list of regular expressions. + +See also the :prop_test:`PASS_REGULAR_EXPRESSION` and +:prop_test:`SKIP_REGULAR_EXPRESSION` test properties. diff --git a/Help/prop_test/FIXTURES_REQUIRED.rst b/Help/prop_test/FIXTURES_REQUIRED.rst index d92808a..f850830 100644 --- a/Help/prop_test/FIXTURES_REQUIRED.rst +++ b/Help/prop_test/FIXTURES_REQUIRED.rst @@ -35,9 +35,9 @@ The concept of a fixture is different to that of a resource specified by set of tests which share setup and cleanup requirements, whereas a resource lock has the effect of ensuring a particular set of tests do not run in parallel. Some situations may need both, such as setting up a database, -serialising test access to that database and deleting the database again at the +serializing test access to that database and deleting the database again at the end. For such cases, tests would populate both ``FIXTURES_REQUIRED`` and -:prop_test:`RESOURCE_LOCK` to combine the two behaviours. Names used for +:prop_test:`RESOURCE_LOCK` to combine the two behaviors. Names used for :prop_test:`RESOURCE_LOCK` have no relationship with names of fixtures, so note that a resource lock does not imply a fixture and vice versa. diff --git a/Help/prop_test/LABELS.rst b/Help/prop_test/LABELS.rst index 8d75570..a06f152 100644 --- a/Help/prop_test/LABELS.rst +++ b/Help/prop_test/LABELS.rst @@ -1,6 +1,10 @@ LABELS ------ -Specify a list of text labels associated with a test. +Specify a list of text labels associated with a test. The labels are +reported in both the ``ctest`` output summary and in dashboard submissions. +They can also be used to filter the set of tests to be executed (see the +``ctest -L`` and ``ctest -LE`` :ref:`CTest Options`). -The list is reported in dashboard submissions. +See :ref:`Additional Labels` for adding labels to a test dynamically during +test execution. diff --git a/Help/prop_test/PASS_REGULAR_EXPRESSION.rst b/Help/prop_test/PASS_REGULAR_EXPRESSION.rst index 0cd6215..96468c0 100644 --- a/Help/prop_test/PASS_REGULAR_EXPRESSION.rst +++ b/Help/prop_test/PASS_REGULAR_EXPRESSION.rst @@ -2,6 +2,7 @@ PASS_REGULAR_EXPRESSION ----------------------- The output must match this regular expression for the test to pass. +The process exit code is ignored. If set, the test output will be checked against the specified regular expressions and at least one of the regular expressions has to match, @@ -14,3 +15,6 @@ otherwise the test will fail. Example: ) ``PASS_REGULAR_EXPRESSION`` expects a list of regular expressions. + +See also the :prop_test:`FAIL_REGULAR_EXPRESSION` and +:prop_test:`SKIP_REGULAR_EXPRESSION` test properties. diff --git a/Help/prop_test/SKIP_REGULAR_EXPRESSION.rst b/Help/prop_test/SKIP_REGULAR_EXPRESSION.rst index 46c4363..60038e4 100644 --- a/Help/prop_test/SKIP_REGULAR_EXPRESSION.rst +++ b/Help/prop_test/SKIP_REGULAR_EXPRESSION.rst @@ -16,4 +16,6 @@ the test will be marked as skipped. Example: ``SKIP_REGULAR_EXPRESSION`` expects a list of regular expressions. -See also the :prop_test:`SKIP_RETURN_CODE` property. +See also the :prop_test:`SKIP_RETURN_CODE`, +:prop_test:`PASS_REGULAR_EXPRESSION`, and :prop_test:`FAIL_REGULAR_EXPRESSION` +test properties. diff --git a/Help/prop_tgt/AUTOMOC.rst b/Help/prop_tgt/AUTOMOC.rst index 52d96e0..ed8b262 100644 --- a/Help/prop_tgt/AUTOMOC.rst +++ b/Help/prop_tgt/AUTOMOC.rst @@ -4,9 +4,9 @@ AUTOMOC Should the target be processed with auto-moc (for Qt projects). :prop_tgt:`AUTOMOC` is a boolean specifying whether CMake will handle the Qt -``moc`` preprocessor automatically, i.e. without having to use the -:module:`QT4_WRAP_CPP() <FindQt4>` or ``QT5_WRAP_CPP()`` macro. -Currently Qt4 and Qt5 are supported. +``moc`` preprocessor automatically, i.e. without having to use commands like +:module:`QT4_WRAP_CPP() <FindQt4>`, ``QT5_WRAP_CPP()``, etc. +Currently, Qt versions 4 to 6 are supported. This property is initialized by the value of the :variable:`CMAKE_AUTOMOC` variable if it is set when a target is created. @@ -148,10 +148,13 @@ Qt version detection :prop_tgt:`AUTOMOC` enabled targets need to know the Qt major and minor version they're working with. The major version usually is provided by the -``INTERFACE_QT_MAJOR_VERSION`` property of the ``Qt[45]Core`` library, +``INTERFACE_QT_MAJOR_VERSION`` property of the ``Qt[456]Core`` library, that the target links to. To find the minor version, CMake builds a list of available Qt versions from +- ``Qt6Core_VERSION_MAJOR`` and ``Qt6Core_VERSION_MINOR`` variables + (usually set by ``find_package(Qt6...)``) +- ``Qt6Core_VERSION_MAJOR`` and ``Qt6Core_VERSION_MINOR`` directory properties - ``Qt5Core_VERSION_MAJOR`` and ``Qt5Core_VERSION_MINOR`` variables (usually set by ``find_package(Qt5...)``) - ``Qt5Core_VERSION_MAJOR`` and ``Qt5Core_VERSION_MINOR`` directory properties @@ -167,13 +170,13 @@ version was found, an error is generated. If ``INTERFACE_QT_MAJOR_VERSION`` is not a valid number, the first entry in the list is taken. -A ``find_package(Qt[45]...)`` call sets the ``QT/Qt5Core_VERSION_MAJOR/MINOR`` +A ``find_package(Qt[456]...)`` call sets the ``QT/Qt[56]Core_VERSION_MAJOR/MINOR`` variables. If the call is in a different context than the :command:`add_executable` or :command:`add_library` call, e.g. in a function, then the version variables might not be available to the :prop_tgt:`AUTOMOC` enabled target. In that case the version variables can be forwarded from the -``find_package(Qt[45]...)`` calling context to the :command:`add_executable` +``find_package(Qt[456]...)`` calling context to the :command:`add_executable` or :command:`add_library` calling context as directory properties. The following Qt5 example demonstrates the procedure. diff --git a/Help/prop_tgt/AUTORCC.rst b/Help/prop_tgt/AUTORCC.rst index 9a98f44..0a0c2a1 100644 --- a/Help/prop_tgt/AUTORCC.rst +++ b/Help/prop_tgt/AUTORCC.rst @@ -5,8 +5,8 @@ Should the target be processed with auto-rcc (for Qt projects). :prop_tgt:`AUTORCC` is a boolean specifying whether CMake will handle the Qt ``rcc`` code generator automatically, i.e. without having to use -the :module:`QT4_ADD_RESOURCES() <FindQt4>` or ``QT5_ADD_RESOURCES()`` -macro. Currently Qt4 and Qt5 are supported. +commands like :module:`QT4_ADD_RESOURCES() <FindQt4>`, ``QT5_ADD_RESOURCES()``, +etc. Currently, Qt versions 4 to 6 are supported. When this property is ``ON``, CMake will handle ``.qrc`` files added as target sources at build time and invoke ``rcc`` accordingly. diff --git a/Help/prop_tgt/AUTOUIC.rst b/Help/prop_tgt/AUTOUIC.rst index cd24f5e..e0cea97 100644 --- a/Help/prop_tgt/AUTOUIC.rst +++ b/Help/prop_tgt/AUTOUIC.rst @@ -5,8 +5,8 @@ Should the target be processed with auto-uic (for Qt projects). :prop_tgt:`AUTOUIC` is a boolean specifying whether CMake will handle the Qt ``uic`` code generator automatically, i.e. without having to use -the :module:`QT4_WRAP_UI() <FindQt4>` or ``QT5_WRAP_UI()`` macro. Currently -Qt4 and Qt5 are supported. +commands like :module:`QT4_WRAP_UI() <FindQt4>`, ``QT5_WRAP_UI()``, etc. +Currently, Qt versions 4 to 6 are supported. This property is initialized by the value of the :variable:`CMAKE_AUTOUIC` variable if it is set when a target is created. diff --git a/Help/prop_tgt/COMPILE_OPTIONS.rst b/Help/prop_tgt/COMPILE_OPTIONS.rst index 0cd6836..0fd6aac 100644 --- a/Help/prop_tgt/COMPILE_OPTIONS.rst +++ b/Help/prop_tgt/COMPILE_OPTIONS.rst @@ -3,9 +3,13 @@ COMPILE_OPTIONS List of options to pass to the compiler. -This property holds a :ref:`semicolon-separated list <CMake Language Lists>` of options -specified so far for its target. Use the :command:`target_compile_options` -command to append more options. +This property holds a :ref:`semicolon-separated list <CMake Language Lists>` +of options specified so far for its target. Use the +:command:`target_compile_options` command to append more options. +The options will be added after after flags in the +:variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` +variables, but before those propagated from dependencies by the +:prop_tgt:`INTERFACE_COMPILE_OPTIONS` property. This property is initialized by the :prop_dir:`COMPILE_OPTIONS` directory property when a target is created, and is used by the generators to set @@ -15,3 +19,5 @@ Contents of ``COMPILE_OPTIONS`` may use "generator expressions" 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:: ../command/OPTIONS_SHELL.txt diff --git a/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst b/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst index d7fb9b1..8b777e4 100644 --- a/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst +++ b/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst @@ -8,9 +8,10 @@ This command will be added as a prefix to :command:`add_test`, :command:`add_custom_command`, and :command:`add_custom_target` commands for built target system executables. -If this property contains a :ref:`semicolon-separated list <CMake Language -Lists>`, then the first value is the command and remaining values are its -arguments. +.. versionadded:: 3.15 + If this property contains a :ref:`semicolon-separated list <CMake Language + Lists>`, then the first value is the command and remaining values are its + arguments. This property is initialized by the value of the :variable:`CMAKE_CROSSCOMPILING_EMULATOR` variable if it is set when a target diff --git a/Help/prop_tgt/CUDA_ARCHITECTURES.rst b/Help/prop_tgt/CUDA_ARCHITECTURES.rst index d56b769..191f78f 100644 --- a/Help/prop_tgt/CUDA_ARCHITECTURES.rst +++ b/Help/prop_tgt/CUDA_ARCHITECTURES.rst @@ -20,12 +20,26 @@ 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`. +The ``CUDA_ARCHITECTURES`` may be set to one of the following special values: + +``all`` + .. versionadded:: 3.23 + + Compile for all supported major and minor real architectures, + and the highest major virtual architecture. + +``all-major`` + .. versionadded:: 3.23 + + Compile for all supported major real architectures, and the highest + major virtual architecture. + Examples ^^^^^^^^ .. code-block:: cmake - set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES 35 50 72) + set_target_properties(tgt PROPERTIES CUDA_ARCHITECTURES "35;50;72") Generates code for real and virtual architectures ``30``, ``50`` and ``72``. diff --git a/Help/prop_tgt/CUDA_EXTENSIONS.rst b/Help/prop_tgt/CUDA_EXTENSIONS.rst index 2ddba0b..ab467ac 100644 --- a/Help/prop_tgt/CUDA_EXTENSIONS.rst +++ b/Help/prop_tgt/CUDA_EXTENSIONS.rst @@ -15,5 +15,7 @@ See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. This property is initialized by the value of -the :variable:`CMAKE_CUDA_EXTENSIONS` variable if it is set when a target -is created. +the :variable:`CMAKE_CUDA_EXTENSIONS` variable if set when a target is created +and otherwise by the value of +:variable:`CMAKE_CUDA_EXTENSIONS_DEFAULT <CMAKE_<LANG>_EXTENSIONS_DEFAULT>` +(see :policy:`CMP0128`). diff --git a/Help/prop_tgt/CUDA_STANDARD.rst b/Help/prop_tgt/CUDA_STANDARD.rst index 6517035..950ba12 100644 --- a/Help/prop_tgt/CUDA_STANDARD.rst +++ b/Help/prop_tgt/CUDA_STANDARD.rst @@ -9,7 +9,35 @@ 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``, ``03``, ``11``, ``14``, ``17``, ``20``, ``23``. +Supported values are: + +``98`` + CUDA C++98. Note that this maps to the same as ``03`` internally. + +``03`` + CUDA C++03 + +``11`` + CUDA C++11 + +``14`` + CUDA C++14. While CMake 3.8 and later *recognize* ``14`` as a valid value, + CMake 3.9 was the first version to include support for any compiler. + +``17`` + CUDA C++17. While CMake 3.8 and later *recognize* ``17`` as a valid value, + CMake 3.18 was the first version to include support for any compiler. + +``20`` + .. versionadded:: 3.12 + + CUDA C++20. While CMake 3.12 and later *recognize* ``20`` as a valid value, + CMake 3.18 was the first version to include support for any compiler. + +``23`` + .. versionadded:: 3.20 + + CUDA C++23 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 @@ -21,7 +49,7 @@ means that using: with a compiler which does not support ``-std=gnu++11`` or an equivalent flag will not result in an error or warning, but will instead add the -``-std=gnu++98`` flag if supported. This "decay" behavior may be controlled +``-std=gnu++03`` flag if supported. This "decay" behavior may be controlled with the :prop_tgt:`CUDA_STANDARD_REQUIRED` target property. Additionally, the :prop_tgt:`CUDA_EXTENSIONS` target property may be used to control whether compiler-specific extensions are enabled on a per-target basis. diff --git a/Help/prop_tgt/CXX_EXTENSIONS.rst b/Help/prop_tgt/CXX_EXTENSIONS.rst index bda531e..9b52504 100644 --- a/Help/prop_tgt/CXX_EXTENSIONS.rst +++ b/Help/prop_tgt/CXX_EXTENSIONS.rst @@ -15,5 +15,7 @@ See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. This property is initialized by the value of -the :variable:`CMAKE_CXX_EXTENSIONS` variable if it is set when a target -is created. +the :variable:`CMAKE_CXX_EXTENSIONS` variable if set when a target is created +and otherwise by the value of +:variable:`CMAKE_CXX_EXTENSIONS_DEFAULT <CMAKE_<LANG>_EXTENSIONS_DEFAULT>` (see +:policy:`CMP0128`). diff --git a/Help/prop_tgt/CXX_STANDARD.rst b/Help/prop_tgt/CXX_STANDARD.rst index be0dab5..b10d201 100644 --- a/Help/prop_tgt/CXX_STANDARD.rst +++ b/Help/prop_tgt/CXX_STANDARD.rst @@ -11,7 +11,31 @@ flag such as ``-std=gnu++11`` to the compile line. For compilers that have no notion of a standard level, such as Microsoft Visual C++ before 2015 Update 3, this has no effect. -Supported values are ``98``, ``11``, ``14``, ``17``, ``20``, ``23``. +Supported values are: + +``98`` + C++98 + +``11`` + C++11 + +``14`` + C++14 + +``17`` + .. versionadded:: 3.8 + + C++17 + +``20`` + .. versionadded:: 3.12 + + C++20 + +``23`` + .. versionadded:: 3.20 + + C++23 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/C_EXTENSIONS.rst b/Help/prop_tgt/C_EXTENSIONS.rst index b2abb46..a53090c 100644 --- a/Help/prop_tgt/C_EXTENSIONS.rst +++ b/Help/prop_tgt/C_EXTENSIONS.rst @@ -15,5 +15,7 @@ See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. This property is initialized by the value of -the :variable:`CMAKE_C_EXTENSIONS` variable if it is set when a target -is created. +the :variable:`CMAKE_C_EXTENSIONS` variable if set when a target is created and +otherwise by the value of +:variable:`CMAKE_C_EXTENSIONS_DEFAULT <CMAKE_<LANG>_EXTENSIONS_DEFAULT>` (see +:policy:`CMP0128`). diff --git a/Help/prop_tgt/C_STANDARD.rst b/Help/prop_tgt/C_STANDARD.rst index 3f0d242..ecba2a8 100644 --- a/Help/prop_tgt/C_STANDARD.rst +++ b/Help/prop_tgt/C_STANDARD.rst @@ -11,7 +11,26 @@ flag such as ``-std=gnu11`` to the compile line. For compilers that have no notion of a C standard level, such as Microsoft Visual C++ before VS 16.7, this property has no effect. -Supported values are ``90``, ``99`` and ``11``. +Supported values are: + +``90`` + C89/C90 + +``99`` + C99 + +``11`` + C11 + +``17`` + .. versionadded:: 3.21 + + C17 + +``23`` + .. versionadded:: 3.21 + + C23 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/DEPRECATION.rst b/Help/prop_tgt/DEPRECATION.rst index 45ca848..2945c98 100644 --- a/Help/prop_tgt/DEPRECATION.rst +++ b/Help/prop_tgt/DEPRECATION.rst @@ -7,3 +7,8 @@ Deprecation message from imported target's developer. ``DEPRECATION`` is the message regarding a deprecation status to be displayed to downstream users of a target. + +The message is formatted as follows: + +* Lines that do not start in whitespace are wrapped as paragraph text. +* Lines that start in whitespace are preserved as preformatted text. diff --git a/Help/prop_tgt/DOTNET_SDK.rst b/Help/prop_tgt/DOTNET_SDK.rst new file mode 100644 index 0000000..ca1dcac --- /dev/null +++ b/Help/prop_tgt/DOTNET_SDK.rst @@ -0,0 +1,25 @@ +DOTNET_SDK +---------- + +.. versionadded:: 3.23 + +Specify the .NET SDK for C# projects. For example: ``Microsoft.NET.Sdk``. + +This property tells :ref:`Visual Studio Generators` for VS 2019 and +above to generate a .NET SDK-style project using the specified SDK. +The property is meaningful only to these generators, and only in C# +targets. It is ignored for C++ projects, even if they are managed +(e.g. using :prop_tgt:`COMMON_LANGUAGE_RUNTIME`). + +This property must be a non-empty string to generate .NET SDK-style projects. +CMake does not perform any validations for the value of the property. + +This property may be initialized for all targets using the +:variable:`CMAKE_DOTNET_SDK` variable. + +.. note:: + + The :ref:`Visual Studio Generators` in this version of CMake have not + yet learned to support :command:`add_custom_command` in .NET SDK-style + projects. It is currently an error to attach a custom command to a + target with the ``DOTNET_SDK`` property set. diff --git a/Help/prop_tgt/Fortran_BUILDING_INSTRINSIC_MODULES.rst b/Help/prop_tgt/Fortran_BUILDING_INSTRINSIC_MODULES.rst new file mode 100644 index 0000000..3533ef9 --- /dev/null +++ b/Help/prop_tgt/Fortran_BUILDING_INSTRINSIC_MODULES.rst @@ -0,0 +1,16 @@ +Fortran_BUILDING_INSTRINSIC_MODULES +----------------------------------- + +.. versionadded:: 3.22 + +Instructs the CMake Fortran preprocessor that the target is building +Fortran intrinsics for building a Fortran compiler. + +This property is off by default and should be turned only on projects +that build a Fortran compiler. It should not be turned on for projects +that use a Fortran compiler. + +Turning this property on will correctly add dependencies for building +Fortran intrinsic modules whereas turning the property off will ignore +Fortran intrinsic modules in the dependency graph as they are supplied +by the compiler itself. diff --git a/Help/prop_tgt/HEADER_DIRS.rst b/Help/prop_tgt/HEADER_DIRS.rst new file mode 100644 index 0000000..d095345 --- /dev/null +++ b/Help/prop_tgt/HEADER_DIRS.rst @@ -0,0 +1,14 @@ +HEADER_DIRS +----------- + +.. versionadded:: 3.23 + +Semicolon-separated list of base directories of the target's default +header set (i.e. the file set with name and type ``HEADERS``). The property +supports :manual:`generator expressions <cmake-generator-expressions(7)>`. + +This property is normally only set by :command:`target_sources(FILE_SET)` +rather than being manipulated directly. + +See :prop_tgt:`HEADER_DIRS_<NAME>` for the list of base directories in +other header sets. diff --git a/Help/prop_tgt/HEADER_DIRS_NAME.rst b/Help/prop_tgt/HEADER_DIRS_NAME.rst new file mode 100644 index 0000000..dc73df7 --- /dev/null +++ b/Help/prop_tgt/HEADER_DIRS_NAME.rst @@ -0,0 +1,15 @@ +HEADER_DIRS_<NAME> +------------------ + +.. versionadded:: 3.23 + +Semicolon-separated list of base directories of the target's ``<NAME>`` +header set, which has the set type ``HEADERS``. The property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +This property is normally only set by :command:`target_sources(FILE_SET)` +rather than being manipulated directly. + +See :prop_tgt:`HEADER_DIRS` for the list of base directories in the +default header set. See :prop_tgt:`HEADER_SETS` for the file set names of all +header sets. diff --git a/Help/prop_tgt/HEADER_SET.rst b/Help/prop_tgt/HEADER_SET.rst new file mode 100644 index 0000000..a703fc1 --- /dev/null +++ b/Help/prop_tgt/HEADER_SET.rst @@ -0,0 +1,15 @@ +HEADER_SET +---------- + +.. versionadded:: 3.23 + +Semicolon-separated list of files in the target's default header set, +(i.e. the file set with name and type ``HEADERS``). If any of the paths +are relative, they are computed relative to the target's source directory. +The property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`. + +This property is normally only set by :command:`target_sources(FILE_SET)` +rather than being manipulated directly. + +See :prop_tgt:`HEADER_SET_<NAME>` for the list of files in other header sets. diff --git a/Help/prop_tgt/HEADER_SETS.rst b/Help/prop_tgt/HEADER_SETS.rst new file mode 100644 index 0000000..ceb1df5 --- /dev/null +++ b/Help/prop_tgt/HEADER_SETS.rst @@ -0,0 +1,15 @@ +HEADER_SETS +----------- + +.. versionadded:: 3.23 + +Read-only list of the target's ``PRIVATE`` and ``PUBLIC`` header sets (i.e. +all file sets with the type ``HEADERS``). Files listed in these file sets are +treated as source files for the purpose of IDE integration. The files also +have their :prop_sf:`HEADER_FILE_ONLY` property set to ``TRUE``. + +Header sets may be defined using the :command:`target_sources` command +``FILE_SET`` option with type ``HEADERS``. + +See also :prop_tgt:`HEADER_SET_<NAME>`, :prop_tgt:`HEADER_SET` and +:prop_tgt:`INTERFACE_HEADER_SETS`. diff --git a/Help/prop_tgt/HEADER_SET_NAME.rst b/Help/prop_tgt/HEADER_SET_NAME.rst new file mode 100644 index 0000000..e537f5a --- /dev/null +++ b/Help/prop_tgt/HEADER_SET_NAME.rst @@ -0,0 +1,15 @@ +HEADER_SET_<NAME> +----------------- + +.. versionadded:: 3.23 + +Semicolon-separated list of files in the target's ``<NAME>`` header set, +which has the set type ``HEADERS``. If any of the paths are relative, +they are computed relative to the target's source directory. The property +supports :manual:`generator expressions <cmake-generator-expressions(7)>`. + +This property is normally only set by :command:`target_sources(FILE_SET)` +rather than being manipulated directly. + +See :prop_tgt:`HEADER_SET` for the list of files in the default header set. +See :prop_tgt:`HEADER_SETS` for the file set names of all header sets. diff --git a/Help/prop_tgt/HIP_ARCHITECTURES.rst b/Help/prop_tgt/HIP_ARCHITECTURES.rst new file mode 100644 index 0000000..06f956b --- /dev/null +++ b/Help/prop_tgt/HIP_ARCHITECTURES.rst @@ -0,0 +1,27 @@ +HIP_ARCHITECTURES +----------------- + +.. versionadded:: 3.21 + +List of AMD GPU architectures to generate device code for. + +A non-empty false value (e.g. ``OFF``) disables adding architectures. +This is intended to support packagers and rare cases where full control +over the passed flags is required. + +This property is initialized by the value of the :variable:`CMAKE_HIP_ARCHITECTURES` +variable if it is set when a target is created. + +The HIP compilation model has two modes: whole and separable. Whole compilation +generates device code at compile time. Separable compilation generates device +code at link time. Therefore the ``HIP_ARCHITECTURES`` target property should +be set on targets that compile or link with any HIP sources. + +Examples +^^^^^^^^ + +.. code-block:: cmake + + set_property(TARGET tgt PROPERTY HIP_ARCHITECTURES gfx801 gfx900) + +Generates code for both ``gfx801`` and ``gfx900``. diff --git a/Help/prop_tgt/HIP_EXTENSIONS.rst b/Help/prop_tgt/HIP_EXTENSIONS.rst new file mode 100644 index 0000000..d1475c9 --- /dev/null +++ b/Help/prop_tgt/HIP_EXTENSIONS.rst @@ -0,0 +1,21 @@ +HIP_EXTENSIONS +-------------- + +.. versionadded:: 3.21 + +Boolean specifying whether compiler specific extensions are requested. + +This property specifies whether compiler specific extensions should be +used. For some compilers, this results in adding a flag such +as ``-std=gnu++11`` instead of ``-std=c++11`` to the compile line. This +property is ``ON`` by default. The basic HIP/C++ standard level is +controlled by the :prop_tgt:`HIP_STANDARD` target property. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_HIP_EXTENSIONS` variable if set when a target is created +and otherwise by the value of +:variable:`CMAKE_HIP_EXTENSIONS_DEFAULT <CMAKE_<LANG>_EXTENSIONS_DEFAULT>` (see +:policy:`CMP0128`). diff --git a/Help/prop_tgt/HIP_STANDARD.rst b/Help/prop_tgt/HIP_STANDARD.rst new file mode 100644 index 0000000..0c767c6 --- /dev/null +++ b/Help/prop_tgt/HIP_STANDARD.rst @@ -0,0 +1,48 @@ +HIP_STANDARD +------------ + +.. versionadded:: 3.21 + +The HIP/C++ standard requested to build this target. + +Supported values are: + +``98`` + HIP C++98 + +``11`` + HIP C++11 + +``14`` + HIP C++14 + +``17`` + HIP C++17 + +``20`` + HIP C++20 + +``23`` + HIP C++23 + +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 +means that using: + +.. code-block:: cmake + + set_property(TARGET tgt PROPERTY HIP_STANDARD 11) + +with a compiler which does not support ``-std=gnu++11`` or an equivalent +flag will not result in an error or warning, but will instead add the +``-std=gnu++98`` flag if supported. This "decay" behavior may be controlled +with the :prop_tgt:`HIP_STANDARD_REQUIRED` target property. +Additionally, the :prop_tgt:`HIP_EXTENSIONS` target property may be used to +control whether compiler-specific extensions are enabled on a per-target basis. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_HIP_STANDARD` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/HIP_STANDARD_REQUIRED.rst b/Help/prop_tgt/HIP_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..e56209a --- /dev/null +++ b/Help/prop_tgt/HIP_STANDARD_REQUIRED.rst @@ -0,0 +1,19 @@ +HIP_STANDARD_REQUIRED +--------------------- + +.. versionadded:: 3.21 + +Boolean describing whether the value of :prop_tgt:`HIP_STANDARD` is a requirement. + +If this property is set to ``ON``, then the value of the +:prop_tgt:`HIP_STANDARD` target property is treated as a requirement. If this +property is ``OFF`` or unset, the :prop_tgt:`HIP_STANDARD` target property is +treated as optional and may "decay" to a previous standard if the requested is +not available. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_HIP_STANDARD_REQUIRED` variable if it is set when a +target is created. diff --git a/Help/prop_tgt/IMPORTED_NO_SYSTEM.rst b/Help/prop_tgt/IMPORTED_NO_SYSTEM.rst new file mode 100644 index 0000000..ee22d6f --- /dev/null +++ b/Help/prop_tgt/IMPORTED_NO_SYSTEM.rst @@ -0,0 +1,21 @@ +IMPORTED_NO_SYSTEM +------------------ + +.. versionadded:: 3.23 + +Specifies that an :ref:`Imported Target <Imported Targets>` is not +a ``SYSTEM`` library. This has the following effects: + +* Entries of :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` are not treated + as ``SYSTEM`` include directories when compiling consumers, as they + would be by default. Entries of + :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` are not affected, + and will always be treated as ``SYSTEM`` include directories. + +This property can also be enabled on a non-imported target. Doing so does +not affect the build system, but does tell the :command:`install(EXPORT)` and +:command:`export` commands to enable it on the imported targets they generate. + +See the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target property to set this +behavior on the target consuming the include directories rather than +providing them. diff --git a/Help/prop_tgt/IMPORTED_OBJECTS.rst b/Help/prop_tgt/IMPORTED_OBJECTS.rst index f3577eb..d71c219 100644 --- a/Help/prop_tgt/IMPORTED_OBJECTS.rst +++ b/Help/prop_tgt/IMPORTED_OBJECTS.rst @@ -68,26 +68,24 @@ architecture: # /path/to/somewhere/objects-iphonesimulator/x86_64/func.o In some cases, you may want to have configuration-specific object files -as well. The :variable:`CMAKE_CFG_INTDIR` variable can be a convenient -way of capturing this in combination with the SDK: +as well. The ``$(CONFIGURATION)`` Xcode variable is often used for this and +can be used in conjunction with the others mentioned above: .. code-block:: cmake add_library(someObjs OBJECT IMPORTED) set_property(TARGET someObjs PROPERTY IMPORTED_OBJECTS - "/path/to/somewhere/${CMAKE_CFG_INTDIR}/$(CURRENT_ARCH)/func.o" + "/path/to/somewhere/$(CONFIGURATION)$(EFFECTIVE_PLATFORM_NAME)/$(CURRENT_ARCH)/func.o" ) # Example paths: # /path/to/somewhere/Release-iphoneos/arm64/func.o # /path/to/somewhere/Debug-iphonesimulator/x86_64/func.o -When any Xcode variable or :variable:`CMAKE_CFG_INTDIR` is used, CMake is -not able to fully evaluate the path(s) at configure time. One consequence -of this is that the configuration-specific -:prop_tgt:`IMPORTED_OBJECTS_<CONFIG>` properties cannot be used, since -CMake cannot determine whether an object file exists at a particular -``<CONFIG>`` location. The ``IMPORTED_OBJECTS`` property must be used for -these situations and the configuration-specific aspects of the path must be -handled by using :variable:`CMAKE_CFG_INTDIR` or with another Xcode variable -``$(CONFIGURATION)``. +When any Xcode variable is used, CMake is not able to fully evaluate the +path(s) at configure time. One consequence of this is that the +configuration-specific :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>` properties cannot +be used, since CMake cannot determine whether an object file exists at a +particular ``<CONFIG>`` location. The ``IMPORTED_OBJECTS`` property must be +used for these situations and the configuration-specific aspects of the path +should be handled by the ``$(CONFIGURATION)`` Xcode variable. diff --git a/Help/prop_tgt/INTERFACE_HEADER_SETS.rst b/Help/prop_tgt/INTERFACE_HEADER_SETS.rst new file mode 100644 index 0000000..2d3bdac --- /dev/null +++ b/Help/prop_tgt/INTERFACE_HEADER_SETS.rst @@ -0,0 +1,14 @@ +INTERFACE_HEADER_SETS +--------------------- + +.. versionadded:: 3.23 + +Read-only list of the target's ``INTERFACE`` and ``PUBLIC`` header sets (i.e. +all file sets with the type ``HEADERS``). Files listed in these header sets +can be installed with :command:`install(TARGETS)` and exported with +:command:`install(EXPORT)` and :command:`export`. + +Header sets may be defined using the :command:`target_sources` command +``FILE_SET`` option with type ``HEADERS``. + +See also :prop_tgt:`HEADER_SETS`. diff --git a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst index bf7f72f..af3d9c2 100644 --- a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst +++ b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst @@ -12,6 +12,13 @@ other target also. This property is overridden by the :prop_tgt:`LINK_INTERFACE_LIBRARIES_<CONFIG>` property if policy :policy:`CMP0022` is ``OLD`` or unset. +The value of this property is used by the generators when constructing +the link rule for a dependent target. A dependent target's direct +link dependencies, specified by its :prop_tgt:`LINK_LIBRARIES` target +property, are linked first, followed by indirect dependencies from the +transitive closure of the direct dependencies' +``INTERFACE_LINK_LIBRARIES`` properties. See policy :policy:`CMP0022`. + Contents of ``INTERFACE_LINK_LIBRARIES`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. See the :manual:`cmake-buildsystem(7)` diff --git a/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst b/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst index a0a97ad..b37bb0c 100644 --- a/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst +++ b/Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst @@ -5,9 +5,12 @@ List of public system include directories for a library. Targets may populate this property to publish the include directories which contain system headers, and therefore should not result in -compiler warnings. The :command:`target_include_directories(SYSTEM)` -command signature populates this property with values given to the -``PUBLIC`` and ``INTERFACE`` keywords. +compiler warnings. Additionally, system include directories are searched +after normal include directories regardless of the order specified. + +The :command:`target_include_directories(SYSTEM)` command signature +populates this property with values given to the ``PUBLIC`` and +``INTERFACE`` keywords. Projects may also get and set the property directly, but must be aware that adding directories to this property does not make those directories used diff --git a/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst b/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst index 16be3cd..cba8ac9 100644 --- a/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst +++ b/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst @@ -4,7 +4,7 @@ .. versionadded:: 3.4 This property is implemented only when ``<LANG>`` is ``C``, ``CXX``, -``Fortran``, ``ISPC``, ``OBJC``, ``OBJCXX``, or ``CUDA``. +``Fortran``, ``HIP``, ``ISPC``, ``OBJC``, ``OBJCXX``, or ``CUDA``. Specify a :ref:`semicolon-separated list <CMake Language Lists>` containing a command line for a compiler launching tool. The :ref:`Makefile Generators` and the diff --git a/Help/prop_tgt/LANG_EXTENSIONS.rst b/Help/prop_tgt/LANG_EXTENSIONS.rst new file mode 100644 index 0000000..afc2ad3 --- /dev/null +++ b/Help/prop_tgt/LANG_EXTENSIONS.rst @@ -0,0 +1,24 @@ +<LANG>_EXTENSIONS +----------------- + +The variations are: + +* :prop_tgt:`C_EXTENSIONS` +* :prop_tgt:`CXX_EXTENSIONS` +* :prop_tgt:`CUDA_EXTENSIONS` +* :prop_tgt:`HIP_EXTENSIONS` +* :prop_tgt:`OBJC_EXTENSIONS` +* :prop_tgt:`OBJCXX_EXTENSIONS` + +These properties specify whether compiler-specific extensions are requested. + +These properties are initialized by the value of the +:variable:`CMAKE_<LANG>_EXTENSIONS` variable if it is set when a target is +created and otherwise by the value of +:variable:`CMAKE_<LANG>_EXTENSIONS_DEFAULT` (see :policy:`CMP0128`). + +For supported CMake versions see the respective pages. +To control language standard versions see :prop_tgt:`<LANG>_STANDARD`. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/prop_tgt/LANG_LINKER_LAUNCHER.rst b/Help/prop_tgt/LANG_LINKER_LAUNCHER.rst new file mode 100644 index 0000000..f6ca5ad --- /dev/null +++ b/Help/prop_tgt/LANG_LINKER_LAUNCHER.rst @@ -0,0 +1,16 @@ +<LANG>_LINKER_LAUNCHER +---------------------- + +.. versionadded:: 3.21 + +This property is implemented only when ``<LANG>`` is ``C``, ``CXX``, +``OBJC``, or ``OBJCXX`` + +Specify a :ref:`semicolon-separated list <CMake Language Lists>` containing a +command line for a linker launching tool. The :ref:`Makefile Generators` and the +:generator:`Ninja` generator will run this tool and pass the linker and its +arguments to the tool. This is useful for tools such as static analyzers. + +This property is initialized by the value of the +:variable:`CMAKE_<LANG>_LINKER_LAUNCHER` variable if it is set when a target is +created. diff --git a/Help/prop_tgt/LANG_STANDARD.rst b/Help/prop_tgt/LANG_STANDARD.rst new file mode 100644 index 0000000..c83da01 --- /dev/null +++ b/Help/prop_tgt/LANG_STANDARD.rst @@ -0,0 +1,33 @@ +<LANG>_STANDARD +--------------- + +The variations are: + +* :prop_tgt:`C_STANDARD` +* :prop_tgt:`CXX_STANDARD` +* :prop_tgt:`CUDA_STANDARD` +* :prop_tgt:`HIP_STANDARD` +* :prop_tgt:`OBJC_STANDARD` +* :prop_tgt:`OBJCXX_STANDARD` + +These properties specify language standard versions which are requested. When a +newer standard is specified than is supported by the compiler, then it will +fallback to the latest supported standard. This "decay" behavior may be +controlled with the :prop_tgt:`<LANG>_STANDARD_REQUIRED` target property. + +Note that the actual language standard used may be higher than that specified +by ``<LANG>_STANDARD``, regardless of the value of +:prop_tgt:`<LANG>_STANDARD_REQUIRED`. In particular, +:ref:`transitive usage requirements <Target Usage Requirements>` or the use of +:manual:`compile features <cmake-compile-features(7)>` can raise the required +language standard above what ``<LANG>_STANDARD`` specifies. + +These properties are initialized by the value of the +:variable:`CMAKE_<LANG>_STANDARD` variable if it is set when a target is +created. + +For supported values and CMake versions see the respective pages. +To control compiler-specific extensions see :prop_tgt:`<LANG>_EXTENSIONS`. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst b/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..e61125b --- /dev/null +++ b/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst @@ -0,0 +1,32 @@ +<LANG>_STANDARD_REQUIRED +------------------------ + +The variations are: + +* :prop_tgt:`C_STANDARD_REQUIRED` +* :prop_tgt:`CXX_STANDARD_REQUIRED` +* :prop_tgt:`CUDA_STANDARD_REQUIRED` +* :prop_tgt:`HIP_STANDARD_REQUIRED` +* :prop_tgt:`OBJC_STANDARD_REQUIRED` +* :prop_tgt:`OBJCXX_STANDARD_REQUIRED` + +These properties specify whether the value of :prop_tgt:`<LANG>_STANDARD` is a +requirement. When false or unset, the :prop_tgt:`<LANG>_STANDARD` target +property is treated as optional and may "decay" to a previous standard if the +requested standard is not available. When ``<LANG>_STANDARD_REQUIRED`` is set +to true, :prop_tgt:`<LANG>_STANDARD` becomes a hard requirement and a fatal +error will be issued if that requirement cannot be met. + +Note that the actual language standard used may be higher than that specified +by :prop_tgt:`<LANG>_STANDARD`, regardless of the value of +``<LANG>_STANDARD_REQUIRED``. In particular, +:ref:`transitive usage requirements <Target Usage Requirements>` or the use of +:manual:`compile features <cmake-compile-features(7)>` can raise the required +language standard above what :prop_tgt:`<LANG>_STANDARD` specifies. + +These properties are initialized by the value of the +:variable:`CMAKE_<LANG>_STANDARD_REQUIRED` variable if it is set when a target +is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/prop_tgt/LINKER_LANGUAGE.rst b/Help/prop_tgt/LINKER_LANGUAGE.rst index b0a572b..f47b488 100644 --- a/Help/prop_tgt/LINKER_LANGUAGE.rst +++ b/Help/prop_tgt/LINKER_LANGUAGE.rst @@ -7,8 +7,10 @@ For executables, shared libraries, and modules, this sets the language whose compiler is used to link the target (such as "C" or "CXX"). A typical value for an executable is the language of the source file providing the program entry point (main). If not set, the language -with the highest linker preference value is the default. See -documentation of :variable:`CMAKE_<LANG>_LINKER_PREFERENCE` variables. +with the highest linker preference value is the default. Details of +the linker preferences are considered internal, but some limited +discussion can be found under the internal +:variable:`CMAKE_<LANG>_LINKER_PREFERENCE` variables. If this property is not set by the user, it will be calculated at generate-time by CMake. diff --git a/Help/prop_tgt/LINK_DEPENDS_NO_SHARED.rst b/Help/prop_tgt/LINK_DEPENDS_NO_SHARED.rst index 5c6778d..dc2dc9e 100644 --- a/Help/prop_tgt/LINK_DEPENDS_NO_SHARED.rst +++ b/Help/prop_tgt/LINK_DEPENDS_NO_SHARED.rst @@ -10,5 +10,6 @@ to re-link this target. Logical target-level dependencies will not be affected so the linked shared libraries will still be brought up to date before this target is built. -This property is initialized by the value of the variable -CMAKE_LINK_DEPENDS_NO_SHARED if it is set when a target is created. +This property is initialized by the value of the +:variable:`CMAKE_LINK_DEPENDS_NO_SHARED` variable if it is set when a +target is created. diff --git a/Help/prop_tgt/LINK_LIBRARIES.rst b/Help/prop_tgt/LINK_LIBRARIES.rst index d88e798..29baf8c 100644 --- a/Help/prop_tgt/LINK_LIBRARIES.rst +++ b/Help/prop_tgt/LINK_LIBRARIES.rst @@ -8,8 +8,11 @@ used for linking. In addition to accepting values from the :command:`target_link_libraries` command, values may be set directly on any target using the :command:`set_property` command. -The value of this property is used by the generators to set the link -libraries for the compiler. +The value of this property is used by the generators to construct the +link rule for the target. The direct link dependencies are linked first, +followed by indirect dependencies from the transitive closure of the +direct dependencies' :prop_tgt:`INTERFACE_LINK_LIBRARIES` properties. +See policy :policy:`CMP0022`. Contents of ``LINK_LIBRARIES`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual diff --git a/Help/prop_tgt/LINK_LIBRARIES_ONLY_TARGETS.rst b/Help/prop_tgt/LINK_LIBRARIES_ONLY_TARGETS.rst new file mode 100644 index 0000000..a9af74d --- /dev/null +++ b/Help/prop_tgt/LINK_LIBRARIES_ONLY_TARGETS.rst @@ -0,0 +1,54 @@ +LINK_LIBRARIES_ONLY_TARGETS +--------------------------- + +.. versionadded:: 3.23 + +Enforce that link items that can be target names are actually existing targets. + +Set this property to a true value to enable additional checks on the contents +of the :prop_tgt:`LINK_LIBRARIES` and :prop_tgt:`INTERFACE_LINK_LIBRARIES` +target properties, typically populated by :command:`target_link_libraries`. +CMake will verify that link items that might be target names actually name +existing targets. An item is considered a possible target name if: + +* it does not contain a ``/`` or ``\``, and +* it does not start in ``-``, and +* (for historical reasons) it does not start in ``$`` or `````. + +This property is initialized by the value of the +:variable:`CMAKE_LINK_LIBRARIES_ONLY_TARGETS` variable when a non-imported +target is created. The property may be explicitly enabled on an imported +target to check its link interface. + +In the following example, CMake will halt with an error at configure time +because ``miLib`` is not a target: + +.. code-block:: cmake + + set(CMAKE_LINK_LIBRARIES_ONLY_TARGETS ON) + add_library(myLib STATIC myLib.c) + add_executable(myExe myExe.c) + target_link_libraries(myExe PRIVATE miLib) # typo for myLib + +In order to link toolchain-provided libraries by name while still +enforcing ``LINK_LIBRARIES_ONLY_TARGETS``, use an +:ref:`imported <Imported Targets>` +:ref:`Interface Library <Interface Libraries>` with the +:prop_tgt:`IMPORTED_LIBNAME` target property: + +.. code-block:: cmake + + add_library(toolchain::m INTERFACE IMPORTED) + set_property(TARGET toolchain::m PROPERTY IMPORTED_LIBNAME "m") + target_link_libraries(myExe PRIVATE toolchain::m) + +See also policy :policy:`CMP0028`. + +.. note:: + + If :prop_tgt:`INTERFACE_LINK_LIBRARIES` contains generator expressions, + its actual list of link items may depend on the type and properties of + the consuming target. In such cases CMake may not always detect names + of missing targets that only appear for specific consumers. + A future version of CMake with improved heuristics may start triggering + errors on projects accepted by previous versions of CMake. diff --git a/Help/prop_tgt/LINK_OPTIONS.rst b/Help/prop_tgt/LINK_OPTIONS.rst index 8c0dfc4..27eadf9 100644 --- a/Help/prop_tgt/LINK_OPTIONS.rst +++ b/Help/prop_tgt/LINK_OPTIONS.rst @@ -28,3 +28,9 @@ for more on defining buildsystem properties. .. note:: This property must be used in preference to :prop_tgt:`LINK_FLAGS` property. + +.. include:: ../command/DEVICE_LINK_OPTIONS.txt + +.. include:: ../command/OPTIONS_SHELL.txt + +.. include:: ../command/LINK_OPTIONS_LINKER.txt diff --git a/Help/prop_tgt/LINK_WHAT_YOU_USE.rst b/Help/prop_tgt/LINK_WHAT_YOU_USE.rst index 2ed93ad..d6de0d4 100644 --- a/Help/prop_tgt/LINK_WHAT_YOU_USE.rst +++ b/Help/prop_tgt/LINK_WHAT_YOU_USE.rst @@ -1,16 +1,22 @@ LINK_WHAT_YOU_USE ---------------------------- +----------------- .. versionadded:: 3.7 -This is a boolean option that when set to ``TRUE`` will automatically run -``ldd -r -u`` on the target after it is linked. In addition, the linker flag -``-Wl,--no-as-needed`` will be passed to the target with the link command so -that all libraries specified on the command line will be linked into the -target. This will result in the link producing a list of libraries that -provide no symbols used by this target but are being linked to it. -This is only applicable to executable and shared library targets and -will only work when ld and ldd accept the flags used. +This is a boolean option that, when set to ``TRUE``, will automatically run +contents of variable :variable:`CMAKE_LINK_WHAT_YOU_USE_CHECK` on the target +after it is linked. In addition, the linker flag specified by variable +:variable:`CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG` will be passed to the target +with the link command so that all libraries specified on the command line will +be linked into the target. This will result in the link producing a list of +libraries that provide no symbols used by this target but are being linked to +it. + +.. note:: + + For now, it is only supported for ``ELF`` platforms and is only applicable to + executable and shared or module library targets. This property will be + ignored for any other targets and configurations. This property is initialized by the value of the :variable:`CMAKE_LINK_WHAT_YOU_USE` variable if it is set diff --git a/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst b/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst index 880343d..39a13ee 100644 --- a/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst +++ b/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst @@ -8,8 +8,13 @@ The contents of the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property of imported targets are treated as ``SYSTEM`` includes by default. If this property is enabled on a target, compilation of sources in that target will not treat the contents of the ``INTERFACE_INCLUDE_DIRECTORIES`` of consumed -imported targets as system includes. +imported targets as system includes. Either way, entries of +:prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` are not affected, +and will always be treated as ``SYSTEM`` include directories. This property is initialized by the value of the :variable:`CMAKE_NO_SYSTEM_FROM_IMPORTED` variable if it is set when a target is created. + +See the :prop_tgt:`IMPORTED_NO_SYSTEM` target property to set this behavior +on the target providing the include directories rather than consuming them. diff --git a/Help/prop_tgt/OBJCXX_EXTENSIONS.rst b/Help/prop_tgt/OBJCXX_EXTENSIONS.rst index 8a254f2..2a15dec 100644 --- a/Help/prop_tgt/OBJCXX_EXTENSIONS.rst +++ b/Help/prop_tgt/OBJCXX_EXTENSIONS.rst @@ -18,5 +18,7 @@ If the property is not set, and the project has set the :prop_tgt:`CXX_EXTENSION the value of :prop_tgt:`CXX_EXTENSIONS` is set for :prop_tgt:`OBJCXX_EXTENSIONS`. This property is initialized by the value of -the :variable:`CMAKE_OBJCXX_EXTENSIONS` variable if it is set when a target -is created. +the :variable:`CMAKE_OBJCXX_EXTENSIONS` variable if set when a target is +created and otherwise by the value of +:variable:`CMAKE_OBJCXX_EXTENSIONS_DEFAULT <CMAKE_<LANG>_EXTENSIONS_DEFAULT>` +(see :policy:`CMP0128`). diff --git a/Help/prop_tgt/OBJCXX_STANDARD.rst b/Help/prop_tgt/OBJCXX_STANDARD.rst index 96088af..654e687 100644 --- a/Help/prop_tgt/OBJCXX_STANDARD.rst +++ b/Help/prop_tgt/OBJCXX_STANDARD.rst @@ -9,7 +9,27 @@ This property specifies the ObjC++ 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``, ``17``, ``20``, ``23``. +Supported values are: + +``98`` + Objective C++98 + +``11`` + Objective C++11 + +``14`` + Objective C++14 + +``17`` + Objective C++17 + +``20`` + Objective C++20 + +``23`` + .. versionadded:: 3.20 + + Objective C++23 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/OBJC_EXTENSIONS.rst b/Help/prop_tgt/OBJC_EXTENSIONS.rst index ef1c754..cd72e5f 100644 --- a/Help/prop_tgt/OBJC_EXTENSIONS.rst +++ b/Help/prop_tgt/OBJC_EXTENSIONS.rst @@ -18,5 +18,7 @@ See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. This property is initialized by the value of -the :variable:`CMAKE_OBJC_EXTENSIONS` variable if it is set when a target -is created. +the :variable:`CMAKE_OBJC_EXTENSIONS` variable if set when a target is created +and otherwise by the value of +:variable:`CMAKE_OBJC_EXTENSIONS_DEFAULT <CMAKE_<LANG>_EXTENSIONS_DEFAULT>` +(see :policy:`CMP0128`). diff --git a/Help/prop_tgt/OBJC_STANDARD.rst b/Help/prop_tgt/OBJC_STANDARD.rst index 2143ff9..2d27bcf 100644 --- a/Help/prop_tgt/OBJC_STANDARD.rst +++ b/Help/prop_tgt/OBJC_STANDARD.rst @@ -9,7 +9,16 @@ This property specifies the OBJC standard whose features are requested to build this target. For some compilers, this results in adding a flag such as ``-std=gnu11`` to the compile line. -Supported values are ``90``, ``99`` and ``11``. +Supported values are: + +``90`` + Objective C89/C90 + +``99`` + Objective C99 + +``11`` + Objective C11 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/SOURCES.rst b/Help/prop_tgt/SOURCES.rst index 493643e..1ebfa14 100644 --- a/Help/prop_tgt/SOURCES.rst +++ b/Help/prop_tgt/SOURCES.rst @@ -1,6 +1,38 @@ SOURCES ------- -Source names specified for a target. +This specifies the list of paths to source files for the target. +The following commands all set or add to the ``SOURCES`` target property +and are the usual way to manipulate it: -List of sources specified for a target. +* :command:`add_executable` +* :command:`add_library` +* :command:`add_custom_target` +* :command:`target_sources` + +Contents of ``SOURCES`` may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. +If a path starts with a generator expression, it is expected to +evaluate to an absolute path. Not doing so is considered undefined behavior. + +Paths that are for files generated by the build will be treated +as relative to the build directory of the target, if the path is not +already specified as an absolute path. Note that whether a file is seen as +generated may be affected by policy :policy:`CMP0118`. + +If a path does not start with a generator expression, is not an +absolute path and is not a generated file, it will be treated as relative to +the location selected by the first of the following that matches: + +* If a file by the specified path exists relative to the target's source + directory, use that file. +* If policy :policy:`CMP0115` is not set to ``NEW``, try appending each + known source file extension to the path and check if that exists + relative to the target's source directory. +* Repeat the above two steps, this time relative to the target's binary + directory instead. + +Note that the above decisions are made at generation time, not build time. + +See the :manual:`cmake-buildsystem(7)` manual for more on defining +buildsystem properties. diff --git a/Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst b/Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst index 2f4a3ba..f5d9437 100644 --- a/Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst +++ b/Help/prop_tgt/STATIC_LIBRARY_OPTIONS.rst @@ -20,3 +20,5 @@ for more on defining buildsystem properties. This property must be used in preference to :prop_tgt:`STATIC_LIBRARY_FLAGS` property. + +.. include:: ../command/OPTIONS_SHELL.txt diff --git a/Help/prop_tgt/Swift_MODULE_DIRECTORY.rst b/Help/prop_tgt/Swift_MODULE_DIRECTORY.rst index a6484f2..619377a 100644 --- a/Help/prop_tgt/Swift_MODULE_DIRECTORY.rst +++ b/Help/prop_tgt/Swift_MODULE_DIRECTORY.rst @@ -9,4 +9,4 @@ If the target contains Swift source files, this specifies the directory in which the modules will be placed. When this property is not set, the modules will be placed in the build directory corresponding to the target's source directory. If the variable :variable:`CMAKE_Swift_MODULE_DIRECTORY` is set when a target is -created its value is used to initialise this property. +created its value is used to initialize this property. diff --git a/Help/prop_tgt/UNITY_BUILD_UNIQUE_ID.rst b/Help/prop_tgt/UNITY_BUILD_UNIQUE_ID.rst index 2c95e02..d288dd3 100644 --- a/Help/prop_tgt/UNITY_BUILD_UNIQUE_ID.rst +++ b/Help/prop_tgt/UNITY_BUILD_UNIQUE_ID.rst @@ -50,6 +50,6 @@ be used to avoid that with code like the following: return MY_UNITY_ID::i; } -The pseudononymous namespace is used within a truly anonymous namespace. +The pseudonymous namespace is used within a truly anonymous namespace. On many platforms, this maintains the invariant that the symbols within do not get external linkage when performing a unity build. diff --git a/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY.rst b/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY.rst index 7b68126..2a4d666 100644 --- a/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY.rst +++ b/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY.rst @@ -6,3 +6,8 @@ XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY Tell the :generator:`Xcode` generator to perform code signing for all the frameworks and libraries that are embedded using the :prop_tgt:`XCODE_EMBED_FRAMEWORKS <XCODE_EMBED_<type>>` property. + +.. versionadded:: 3.21 + +This property was generalized to other types of embedded items. See +:prop_tgt:`XCODE_EMBED_<type>_CODE_SIGN_ON_COPY` for the more general form. diff --git a/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY.rst b/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY.rst index 29f8c5c..04daa85 100644 --- a/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY.rst +++ b/Help/prop_tgt/XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY.rst @@ -6,3 +6,9 @@ XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY Tell the :generator:`Xcode` generator to remove headers from all the frameworks that are embedded using the :prop_tgt:`XCODE_EMBED_FRAMEWORKS <XCODE_EMBED_<type>>` property. + +.. versionadded:: 3.21 + +This property was generalized to other types of embedded items. See +:prop_tgt:`XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY` for the more +general form. diff --git a/Help/prop_tgt/XCODE_EMBED_type.rst b/Help/prop_tgt/XCODE_EMBED_type.rst index 90c5bc7..e8383c2 100644 --- a/Help/prop_tgt/XCODE_EMBED_type.rst +++ b/Help/prop_tgt/XCODE_EMBED_type.rst @@ -5,10 +5,26 @@ XCODE_EMBED_<type> Tell the :generator:`Xcode` generator to embed the specified list of items into the target bundle. ``<type>`` specifies the embed build phase to use. +See the Xcode documentation for the base location of each ``<type>``. + +The supported values for ``<type>`` are: + +``FRAMEWORKS`` + The specified items will be added to the ``Embed Frameworks`` build phase. + The items can be CMake target names or paths to frameworks or libraries. + +``APP_EXTENSIONS`` + .. versionadded:: 3.21 + + The specified items will be added to the ``Embed App Extensions`` build phase. + They must be CMake target names. + +``PLUGINS`` + .. versionadded:: 3.23 + + The specified items will be added to the ``Embed PlugIns`` build phase. + They must be CMake target names. -Currently, the only supported value for ``<type>`` is ``FRAMEWORKS``. -The specified items will be added to the ``Embed Frameworks`` build phase. -The items can be CMake target names or paths to frameworks or libraries. See also :prop_tgt:`XCODE_EMBED_<type>_PATH`, -:prop_tgt:`XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY` and -:prop_tgt:`XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY`. +:prop_tgt:`XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY` and +:prop_tgt:`XCODE_EMBED_<type>_CODE_SIGN_ON_COPY`. diff --git a/Help/prop_tgt/XCODE_EMBED_type_CODE_SIGN_ON_COPY.rst b/Help/prop_tgt/XCODE_EMBED_type_CODE_SIGN_ON_COPY.rst new file mode 100644 index 0000000..cb449ac --- /dev/null +++ b/Help/prop_tgt/XCODE_EMBED_type_CODE_SIGN_ON_COPY.rst @@ -0,0 +1,21 @@ +XCODE_EMBED_<type>_CODE_SIGN_ON_COPY +------------------------------------ + +.. versionadded:: 3.20 + +Boolean property used only by the :generator:`Xcode` generator. It specifies +whether to perform code signing for the items that are embedded using the +:prop_tgt:`XCODE_EMBED_<type>` property. + +The supported values for ``<type>`` are: + +``FRAMEWORKS`` + +``APP_EXTENSIONS`` + .. versionadded:: 3.21 + +``PLUGINS`` + .. versionadded:: 3.23 + +If a ``XCODE_EMBED_<type>_CODE_SIGN_ON_COPY`` property is not defined on the +target, no code signing on copy will be performed for that ``<type>``. diff --git a/Help/prop_tgt/XCODE_EMBED_type_PATH.rst b/Help/prop_tgt/XCODE_EMBED_type_PATH.rst index 887cf57..160f765 100644 --- a/Help/prop_tgt/XCODE_EMBED_type_PATH.rst +++ b/Help/prop_tgt/XCODE_EMBED_type_PATH.rst @@ -3,7 +3,19 @@ XCODE_EMBED_<type>_PATH .. versionadded:: 3.20 -Tell the :generator:`Xcode` generator the relative path to use when embedding -the items specified by :prop_tgt:`XCODE_EMBED_<type>`. The path is relative +This property is used only by the :generator:`Xcode` generator. When defined, +it specifies the relative path to use when embedding the items specified by +:prop_tgt:`XCODE_EMBED_<type>`. The path is relative to the base location of the ``Embed XXX`` build phase associated with +``<type>``. See the Xcode documentation for the base location of each ``<type>``. + +The supported values for ``<type>`` are: + +``FRAMEWORKS`` + +``APP_EXTENSIONS`` + .. versionadded:: 3.21 + +``PLUGINS`` + .. versionadded:: 3.23 diff --git a/Help/prop_tgt/XCODE_EMBED_type_REMOVE_HEADERS_ON_COPY.rst b/Help/prop_tgt/XCODE_EMBED_type_REMOVE_HEADERS_ON_COPY.rst new file mode 100644 index 0000000..e3a7ced --- /dev/null +++ b/Help/prop_tgt/XCODE_EMBED_type_REMOVE_HEADERS_ON_COPY.rst @@ -0,0 +1,23 @@ +XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY +----------------------------------------- + +.. versionadded:: 3.20 + +Boolean property used only by the :generator:`Xcode` generator. It specifies +whether to remove headers from all the frameworks that are embedded using the +:prop_tgt:`XCODE_EMBED_<type>` property. + +The supported values for ``<type>`` are: + +``FRAMEWORKS`` + If the ``XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY`` property is not + defined, headers will not be removed on copy by default. + +``APP_EXTENSIONS`` + .. versionadded:: 3.21 + + If the ``XCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPY`` property is not + defined, headers WILL be removed on copy by default. + +``PLUGINS`` + .. versionadded:: 3.23 diff --git a/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst b/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst index 06a3cf9..8f46d2f 100644 --- a/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst +++ b/Help/prop_tgt/XCODE_GENERATE_SCHEME.rst @@ -38,6 +38,7 @@ The following target properties will be applied on the - :prop_tgt:`XCODE_SCHEME_ARGUMENTS` - :prop_tgt:`XCODE_SCHEME_DEBUG_AS_ROOT` - :prop_tgt:`XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING` +- :prop_tgt:`XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE` - :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` - :prop_tgt:`XCODE_SCHEME_EXECUTABLE` - :prop_tgt:`XCODE_SCHEME_WORKING_DIRECTORY` diff --git a/Help/prop_tgt/XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE.rst b/Help/prop_tgt/XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE.rst new file mode 100644 index 0000000..6ffd694 --- /dev/null +++ b/Help/prop_tgt/XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE.rst @@ -0,0 +1,15 @@ +XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE +------------------------------------------ + +.. versionadded:: 3.23 + +Property value for ``GPU Frame Capture`` in the Options section of +the generated Xcode scheme. Example values are `Metal` and +`Disabled`. + +This property is initialized by the value of the variable +:variable:`CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE` +if it is set when a target is created. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/release/3.15.rst b/Help/release/3.15.rst index e68e7d3..6b1a800 100644 --- a/Help/release/3.15.rst +++ b/Help/release/3.15.rst @@ -40,7 +40,7 @@ Languages customize the Swift module name. * The :prop_sf:`Swift_DIAGNOSTICS_FILE` source property was added to - indicate where to write the serialised Swift diagnostics. + indicate where to write the serialized Swift diagnostics. The Swift support is experimental, not considered stable, and may change in future releases of CMake. diff --git a/Help/release/3.16.rst b/Help/release/3.16.rst index 84d96cd..28273a7 100644 --- a/Help/release/3.16.rst +++ b/Help/release/3.16.rst @@ -233,7 +233,7 @@ Deprecated and Removed Features instead. * The :module:`GetPrerequisites` module has been deprecated, as it has been - superceded by :command:`file(GET_RUNTIME_DEPENDENCIES)`. + superseded by :command:`file(GET_RUNTIME_DEPENDENCIES)`. * The ``CPACK_INSTALL_SCRIPT`` variable has been deprecated in favor of the new, more accurately named :variable:`CPACK_INSTALL_SCRIPTS` variable. diff --git a/Help/release/3.21.rst b/Help/release/3.21.rst new file mode 100644 index 0000000..847f82d --- /dev/null +++ b/Help/release/3.21.rst @@ -0,0 +1,343 @@ +CMake 3.21 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.20 include the following. + +New Features +============ + +Presets +------- + +* :manual:`cmake-presets(7)` gained support for specifying the install prefix + in a configure preset. + +* :manual:`cmake-presets(7)` gained support for conditional enabling of presets. + +* :manual:`cmake-presets(7)` gained support for a ``${hostSystemName}`` macro. + +* :manual:`cmake-presets(7)` gained support for omitting the ``generator`` and + ``binaryDir`` fields. + +Generators +---------- + +* The :generator:`Visual Studio 17 2022` generator was added. + +* The :ref:`Makefile Generators` and the :generator:`Ninja` generator + learned to add linker launcher tools along with the linker for ``C``, + ``CXX``, ``OBJC``, and ``OBJCXX`` languages. + See the :variable:`CMAKE_<LANG>_LINKER_LAUNCHER` variable + and :prop_tgt:`<LANG>_LINKER_LAUNCHER` target property for details. + +Languages +--------- + +* CMake learned to support ``HIP`` as a first-class language that can be + enabled via the :command:`project` and :command:`enable_language` commands. + +* :prop_tgt:`C_STANDARD`, :prop_tgt:`OBJC_STANDARD`, and the + :manual:`Compile Features <cmake-compile-features(7)>` functionality gained + support for C17 and C23. + +* Source file extensions ``.ixx`` and ``.cppm`` are now treated as C++. + +Command-Line +------------ + +* :manual:`cmake(1)` gained the ``--install-prefix <dir>`` + command-line option to specify the location of the install prefix. + +* :manual:`cmake(1)` gained the ``--toolchain <path/to/file>`` + command-line option to specify a toolchain file. + +* :manual:`cmake(1)` ``-E capabilities`` output, for some generators, + may now contain a ``supportedPlatforms`` field listing platforms + known to be supported in :variable:`CMAKE_GENERATOR_PLATFORM`. + +* Messages printed to a terminal now may be colored by message type. + +Compilers +--------- + +* The Fujitsu compiler is now supported using compiler id ``Fujitsu`` + in traditional (``Trad``) mode, and compiler id ``FujitsuClang`` + in ``Clang`` mode. + +Platforms +--------- + +* CMake now supports the MSYS runtime environment, much like CYGWIN. + +File-Based API +-------------- + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field + has been updated to 2.3. + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 gained a + new "directory" object containing directory-level information. + This includes a list of installers generated by the :command:`install` + command. + +Commands +-------- + +* The :command:`add_custom_command` command ``DEPFILE`` option: + + * may now use + :manual:`generator expressions <cmake-generator-expressions(7)>`, + + * is now supported by :ref:`Visual Studio Generators` for VS 2012 + and above, and + + * is now supported by the :generator:`Xcode` generator. + +* The :command:`add_custom_command(TARGET)` command + (for :ref:`Build Events <add_custom_command(TARGET)>`) + gained support for resolving target-dependent generator expressions. + +* The :command:`build_command` command gained a ``PARALLEL_LEVEL`` option. + +* The :command:`file(COPY_FILE)` command was added to copy a single file. + +* The :command:`file(GET_RUNTIME_DEPENDENCIES)` command gained new + ``POST_INCLUDE_FILES`` and ``POST_EXCLUDE_FILES`` arguments. + +* The :command:`file(REAL_PATH)` command gained the option ``EXPAND_TILDE`` to + replace any leading tilde with the path to the user's home directory. + +* The :command:`file(RENAME)` command learned to optionally capture + failure in a result variable. It also gained a ``NO_REPLACE`` + option to fail if the destination exists. + +* The :command:`install` command gained a new ``IMPORTED_RUNTIME_ARTIFACTS`` + mode, which can be used to install the runtime artifacts of imported targets. + +* The :command:`install` command gained a new ``RUNTIME_DEPENDENCY_SET`` mode, + which can be used to install runtime dependencies using + :command:`file(GET_RUNTIME_DEPENDENCIES)`. + +* The :command:`install(TARGETS)` command gained new ``RUNTIME_DEPENDENCIES`` + and ``RUNTIME_DEPENDENCY_SET`` arguments, which can be used to install + runtime dependencies using :command:`file(GET_RUNTIME_DEPENDENCIES)`. + +* The :command:`install(SCRIPT|CODE)` command + supports a new option ``ALL_COMPONENTS`` which allows + the corresponding code to run for every component of + a per component installation. + +* The :command:`project` command now sets variables + :variable:`PROJECT_IS_TOP_LEVEL` and :variable:`<PROJECT-NAME>_IS_TOP_LEVEL` + to indicate whether it was called in a top-level ``CMakeLists.txt`` file. + +Variables +--------- + +* The :envvar:`CMAKE_TOOLCHAIN_FILE` environment variable was added to + provide a default value for the :variable:`CMAKE_TOOLCHAIN_FILE` variable. + +Properties +---------- + +* The :prop_dir:`IMPORTED_TARGETS` directory property was added to + get a list of :ref:`Imported Targets` created in the current + directory. + +* The :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS <XCODE_EMBED_<type>>` target property + was added to tell the :generator:`Xcode` generator to embed app extensions + such as iMessage sticker packs. + Aspects of the embedding can be customized with the + :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_PATH <XCODE_EMBED_<type>>`, + :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_CODE_SIGN_ON_COPY <XCODE_EMBED_<type>_CODE_SIGN_ON_COPY>` and + :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPY <XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY>` + properties. + +Modules +------- + +* The :module:`FindBLAS` and :module:`FindLAPACK` modules learned to support + the serial ``Fujitsu_SSL2`` and parallel ``Fujitsu_SSL2BLAMP`` libraries. + +* The :module:`FindDevIL` module now provides imported targets. + +* The :module:`FindIconv` module now has version support. + +* The :module:`FindIntl` module now has version support. + +* The :module:`FindMPI` module learned to support ``Fujitsu`` and + ``FujitsuClang`` in both host and cross compiling modes. + +* The :module:`FindMsys` module was added to find MSYS installations. + Like :module:`FindCygwin`, it is used automatically by some other + find modules to locate UNIX-style tools on Windows. + +* The :module:`FindOpenMP` module learned to support ``Fujitsu`` and + ``FujitsuClang``. + +* The :module:`FindVulkan` module gained imported targets + ``Vulkan::Headers`` and ``Vulkan::glslangValidator``. + +* The :module:`UseJava` module command ``add_jar`` gained a ``RESOURCES`` + option to allow explicit naming of resources with non-optional namespace. + +* The :module:`UseSWIG` module use now standard library naming conventions + for the ``CSharp`` language. See policy :policy:`CMP0122`. + +* The :module:`UseSWIG` module now supports using the ``swig`` tool to + generate implicit dependencies with the :generator:`Xcode` generator. + +Generator Expressions +--------------------- + +* A new :genex:`TARGET_RUNTIME_DLLS` generator expression was added. + +CTest +----- + +* :manual:`ctest(1)` gained documentation for its ability to capture + :ref:`Additional Test Measurements`. + +* :manual:`ctest(1)` learned to recognize files attached to a test at run time. + Previously it was only possible to attach files to tests at configure time + by using the :prop_test:`ATTACHED_FILES` or + :prop_test:`ATTACHED_FILES_ON_FAIL` test properties. + See :ref:`Additional Test Measurements` for more information. + +* :manual:`ctest(1)` gained a ``--output-junit`` option to write test results + to a JUnit XML file. + +* The :command:`ctest_build` command gained a ``PARALLEL_LEVEL`` option. + +CPack +----- + +* The :cpack_gen:`CPack DragNDrop Generator` gained option + :variable:`CPACK_DMG_FILESYSTEM` to control the ``.dmg`` filesystem. + +* The :cpack_gen:`CPack IFW Generator` now supports hyphens in names + given to :command:`cpack_ifw_configure_component` or + :command:`cpack_ifw_configure_component_group` as ``DEPENDS`` or + ``DEPENDENCIES`` arguments. This requires QtIFW 3.1 or later. + +* The :cpack_gen:`CPack NSIS Generator` gained a new + :variable:`CPACK_NSIS_EXECUTABLE` variable to specify the ``makensis`` + executable to use instead of the default one. + +* The :variable:`CPACK_CUSTOM_INSTALL_VARIABLES` variable was added to set + variables in ``cmake_install.cmake`` script invocations made by CPack. + +Deprecated and Removed Features +=============================== + +* Undocumented :variable:`CMAKE_SYSTEM_NAME` version-stripping behavior has + been removed entirely. If it is set by a ``-D`` flag or by a + :manual:`toolchain file <cmake-toolchains(7)>`, it is left unaltered, + even if it still contains a version number. + Similar :variable:`CMAKE_HOST_SYSTEM_NAME` version-stripping behavior, + also undocumented, has been moved earlier, before :command:`project` or + :command:`enable_language` is called. + +* ``ARMClang`` cpu/arch compile and link flags are no longer added + automatically based on the :variable:`CMAKE_SYSTEM_PROCESSOR` + variable or the undocumented ``CMAKE_SYSTEM_ARCH`` variable. + They must be specified explicitly. See policy :policy:`CMP0123`. + +Other Changes +============= + +* The :command:`find_file`, :command:`find_path`, :command:`find_program`, + and :command:`find_library` commands handle cache variables in the same way + regardless how they are defined. See policy :policy:`CMP0125` for details. + +* The :command:`find_file`, :command:`find_path`, :command:`find_program`, + and :command:`find_library` commands gained the option ``NO_CACHE`` to store + find result in normal variable. + +* The :command:`foreach` command now isolates loop variables in the loop scope. + See policy :policy:`CMP0124` for details. + +* The :command:`list` command's ``GET``, ``INSERT``, ``SUBLIST``, and + ``REMOVE_AT`` subcommands now error with invalid (i.e., non-integer) values + are given as any of their index arguments based on the setting of policy + :policy:`CMP0121`. + +* The :command:`set(CACHE)` command no longer removes a normal variable + of the same name, if any. See policy :policy:`CMP0126`. + +* :command:`target_link_libraries` calls referencing object libraries + via the :genex:`TARGET_OBJECTS` generator expression now place the + object files before all libraries on the link line, regardless of + their specified order. See documentation on + :ref:`Linking Object Libraries via \$\<TARGET_OBJECTS\>` for details. + +* The :ref:`Ninja Generators` now pass source files and include directories + to the compiler using absolute paths. This makes diagnostic messages and + debug symbols more consistent, and matches the :ref:`Makefile Generators`. + +* The :generator:`NMake Makefiles` generator now encodes the generated + makefiles as UTF-8 with a BOM when using ``nmake`` from VS 9 or above. + +* The :ref:`Visual Studio Generators` for VS 2010 and above now place + per-source preprocessor definitions after target-wide preprocssor + definitions. This makes VS consistent with the :ref:`Ninja Generators` + and the :ref:`Makefile Generators`. + +* The precompiled binaries provided on + `cmake.org <https://cmake.org/download/>`_ now support + ``liblzma`` multi-threading. See the :variable:`CPACK_THREADS` and + :variable:`CPACK_ARCHIVE_THREADS` variables. + +Updates +======= + +Changes made since CMake 3.21.0 include the following. + +3.21.1 +------ + +* The :generator:`Visual Studio 17 2022` generator is now based on + "Visual Studio 2022 Preview 2". Previously it was based on "Preview 1.1". + +3.21.2 +------ + +* ``CUDA`` targets with :prop_tgt:`CUDA_SEPARABLE_COMPILATION` enabled are now + correctly generated in non-root directories. + +* The :generator:`Visual Studio 17 2022` generator is now based on + "Visual Studio 2022 Preview 3.1". Previously it was based on "Preview 2". + +3.21.3 +------ + +* The :generator:`Visual Studio 17 2022` generator is now based on + "Visual Studio 2022 Preview 4". Previously it was based on "Preview 3.1". + +* The AMD ROCm Platform ``hipcc`` compiler was identifed by CMake 3.21.0 + through 3.21.2 as a distinct compiler with id ``ROCMClang``. This has + been removed because it caused regressions. Instead: + + * ``hipcc`` may no longer be used as a ``HIP`` compiler because it + interferes with flags CMake needs to pass to Clang. Use Clang directly. + + * ``hipcc`` may once again be used as a ``CXX`` compiler, and is treated as + whatever compiler it selects underneath, as CMake 3.20 and below did. + +3.21.4 +------ + +* The :generator:`Visual Studio 17 2022` generator is now based on the + "Visual Studio 2022" release candidates. Previously it was based on + preview versions. + +3.21.5, 3.21.6 +-------------- + +These versions made no changes to documented features or interfaces. +Some implementation updates were made to support ecosystem changes +and/or fix regressions. diff --git a/Help/release/3.22.rst b/Help/release/3.22.rst new file mode 100644 index 0000000..00e93f6 --- /dev/null +++ b/Help/release/3.22.rst @@ -0,0 +1,178 @@ +CMake 3.22 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.21 include the following. + +New Features +============ + +Commands +-------- + +* The :command:`cmake_host_system_information` command can now query + `OS identification variables`_ from the :file:`/etc/os-release` file. + +* The :command:`string(TIMESTAMP)` command now supports the ``%V`` + specifier for ISO 8601 week numbers. + +.. _`OS identification variables`: https://www.freedesktop.org/software/systemd/man/os-release.html + +Variables +--------- + +* The :envvar:`CMAKE_BUILD_TYPE` environment variable was added to + provide a default value for the :variable:`CMAKE_BUILD_TYPE` variable. + +* The :envvar:`CMAKE_CONFIGURATION_TYPES` environment variable was added to + provide a default value for the :variable:`CMAKE_CONFIGURATION_TYPES` + variable. + +* The :envvar:`CMAKE_INSTALL_MODE` environment variable was added to + tell :command:`install` rules (implemented by :command:`file(INSTALL)`) + to install symbolic links instead of copying of files. + +* The :variable:`CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG` and + :variable:`CMAKE_LINK_WHAT_YOU_USE_CHECK` variables were added to + control the linker flag and check used by the + :prop_tgt:`LINK_WHAT_YOU_USE` target property. + +* The :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable + was added to turn a non-REQUIRED :command:`find_package` call into + a REQUIRED one. + +Properties +---------- + +* The :prop_tgt:`<LANG>_EXTENSIONS` target property is now initialized to + :variable:`CMAKE_<LANG>_EXTENSIONS_DEFAULT`, detected from the compiler. + See :policy:`CMP0128`. + +* The :prop_sf:`VS_SETTINGS` source file property is now supported for + all source file types. Previously it worked only for non-built sources. + +Modules +------- + +* The :module:`CMakeDependentOption` module :command:`cmake_dependent_option` + macro now supports full :ref:`Condition Syntax`. + See policy :policy:`CMP0127`. + +* The :module:`FetchContent` module now passes through the + :variable:`CMAKE_TLS_VERIFY`, :variable:`CMAKE_TLS_CAINFO`, + :variable:`CMAKE_NETRC` and :variable:`CMAKE_NETRC_FILE` variables (when + defined) to the underlying :module:`ExternalProject` sub-build. + Previously, those variables were silently ignored by :module:`FetchContent`. + +* The :module:`FindBLAS` and :module:`FindLAPACK` modules gained + a ``BLA_SIZEOF_INTEGER`` option to find a BLAS/LAPACK whose ABI + uses a specific integer size. + +* The :module:`FindJasper` module now provides an imported target. + +* The :module:`FindMatlab` module now provides imported targets. + +* The :module:`FindPkgConfig` module gained a :variable:`PKG_CONFIG_ARGN` + variable to specify arguments to ``pkg-config`` calls. + +* The :module:`GoogleTest` module :command:`gtest_discover_tests` + function gained a ``TEST_FILTER`` option to filter tests using + ``--gtest_filter`` during test discovery. + +* The :module:`UseSWIG` module, for :ref:`Visual Studio Generators`, + can now use the ``swig`` tool to generate implicit dependencies. + +CTest +----- + +* :manual:`ctest(1)` learned to recognize labels attached to a test at run time. + Previously it was only possible to attach labels to tests at configure time + by using the :prop_test:`LABELS` test property. + See :ref:`Additional Test Measurements` for more information. + +* :manual:`ctest(1)` learned to be able to modify the environment for a test + through the :prop_test:`ENVIRONMENT_MODIFICATION` property. This is allows + for updates to environment variables based on the environment present at + test time. + +* The :command:`ctest_memcheck` command now also generates a + :file:`DynamicAnalysis-Test.xml` file which may be used to submit test + results to CDash. + +CPack +----- + +* The :cpack_gen:`CPack DEB Generator` gained the + option to set :variable:`CPACK_DEBIAN_COMPRESSION_TYPE` to ``zstd``, + which enables Zstandard compression for deb packages. + +* The :cpack_gen:`CPack NSIS Generator` gained a new + :variable:`CPACK_NSIS_IGNORE_LICENSE_PAGE` variable to suppress + the license page in the installer. + +* The :cpack_gen:`CPack RPM Generator` gained the + :variable:`CPACK_RPM_REQUIRES_EXCLUDE_FROM` option to avoid scanning + specific paths for dependencies. + +Deprecated and Removed Features +=============================== + +* The :generator:`Visual Studio 10 2010` generator is now deprecated + and will be removed in a future version of CMake. + +Other Changes +============= + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality now + correctly disables or enables compiler extensions when no standard level is + specified and avoids unnecessarily adding language standard flags if the + requested settings match the compiler's defaults. See :policy:`CMP0128`. + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + now ignores features for languages that are not enabled. + +* The :ref:`Ninja Generators` now implement the ``edit_cache`` target + using :manual:`ccmake(1)` if available. + +* The :generator:`Ninja` and :generator:`NMake Makefiles` generators + now use the MSVC ``-external:I`` flag for system includes. + This became available as of VS 16.10 (toolchain version 14.29.30037). + +* The :cpack_gen:`CPack NSIS Generator` now requires NSIS 3.03 or later. + +Updates +======= + +Changes made since CMake 3.22.0 include the following. + +3.22.1 +------ + +* This version made no changes to documented features or interfaces. + Some implementation updates were made to support ecosystem changes + and/or fix regressions. + +3.22.2 +------ + +* The ``OLD`` behavior of :policy:`CMP0128` was fixed to add flags even when + the specified standard matches the compiler default. + +3.22.3 +------ + +* The :command:`while` command again ignores errors in condition evaluation + as CMake 3.21 and below did. This bug was fixed in 3.22.0, but exposed + errors in existing projects. The fix has been reverted to restore + compatibility. The fix may be restored in a future version of CMake + via a policy. + +3.22.4 +------ + +* This version made no changes to documented features or interfaces. + Some implementation updates were made to support ecosystem changes + and/or fix regressions. diff --git a/Help/release/3.23.rst b/Help/release/3.23.rst new file mode 100644 index 0000000..47c4243 --- /dev/null +++ b/Help/release/3.23.rst @@ -0,0 +1,311 @@ +CMake 3.23 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.22 include the following. + +New Features +============ + +Presets +------- + +* :manual:`cmake-presets(7)` files now support schema version ``4``. + +* :manual:`cmake-presets(7)` files now have an optional ``include`` field, + which allows the files to include other files. + +* :manual:`cmake-presets(7)` files now support a ``${fileDir}`` macro, which + contains the directory containing the preset file. + +* :manual:`cmake-presets(7)` gained support for specifying the + ``resolvePackageReferences`` command line option in a build preset to control + restoration behavior of package references from external package managers. + Currently this is only supported by the Visual Studio generator to support + restoring packages from NuGet. Other generators ignore this option. + +Generators +---------- + +* The :ref:`Visual Studio Generators` for VS 2019 and above learned to + support .NET SDK-style project files (``.csproj``) for C# projects. + See the :prop_tgt:`DOTNET_SDK` target property and corresponding + :variable:`CMAKE_DOTNET_SDK` variable. :command:`add_custom_command` + is not yet supported in .NET SDK-style projects. + +* The :ref:`Visual Studio Generators` for VS 2017 and above learned to + use portable instances of Visual Studio not known to the VS installer. + See the :variable:`CMAKE_GENERATOR_INSTANCE` variable. + +Command-Line +------------ + +* The :manual:`cmake(1)` ``--build`` command, when used with + :ref:`Visual Studio Generators` on projects that set the + :prop_tgt:`VS_PACKAGE_REFERENCES` target property, now automatically + restores package references from NuGet. The cache variable + :variable:`CMAKE_VS_NUGET_PACKAGE_RESTORE` may be set to toggle this behavior + in a build tree. Use the ``--resolve-package-references=<on|off|only>`` + command-line option to control the behavior on one invocation. + +* The :manual:`cmake(1)` command line tool gained a ``--debug-find-pkg=`` + option to enable debug messages under specific :command:`find_package` + calls. + +* The :manual:`cmake(1)` command line tool gained a ``--debug-find-var=`` + option to enable debug messages for ``find_*`` calls that use specific + result variables. + +Compilers +--------- + +* The IBM Open XL C/C++ compiler, based on LLVM, is now supported with + compiler id ``IBMClang``. + +* The MCST LCC compiler is now supported with compiler id ``LCC``. + See policy :policy:`CMP0129`. + +File-Based API +-------------- + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field + has been updated to ``2.4``. + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``directory`` + object ``installers`` field gained a new ``fileSet`` installer type. + +Commands +-------- + +* The :command:`define_property` command gained a new + ``INITIALIZE_FROM_VARIABLE`` option to cause a target property to be + initialized from a variable when a target is created. + +* The :command:`install(TARGETS)` command gained a new ``FILE_SET`` argument, + which can be used to install header file sets associated with a target. + +* The :command:`string(TIMESTAMP)` and :command:`file(TIMESTAMP)` commands now + support the ``%f`` specifier for microseconds. + +* The :command:`target_sources` command gained a new ``FILE_SET`` mode, which + can be used to add headers as header-only source files of a target. + +Variables +--------- + +* The :variable:`CMAKE_CUDA_ARCHITECTURES` variable and associated + :prop_tgt:`CUDA_ARCHITECTURES` target property now support the + ``all``, and ``all-major`` values for CUDA toolkit 7.0+. + +* The :variable:`CMAKE_IGNORE_PREFIX_PATH` and + :variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` variables were added + to tell the :command:`find_package`, :command:`find_program`, + :command:`find_library`, :command:`find_path`, and :command:`find_file` + commands to ignore specified prefixes. + +* The :variable:`CMAKE_LINK_LIBRARIES_ONLY_TARGETS` variable and + corresponding :prop_tgt:`LINK_LIBRARIES_ONLY_TARGETS` target + property were added to optionally require that all link items + that can be target names are actually names of existing targets. + +Properties +---------- + +* The :prop_tgt:`HEADER_SETS` and :prop_tgt:`INTERFACE_HEADER_SETS` read-only + target properties were added to list header sets associated with a target. + +* The :prop_tgt:`HEADER_SET` and :prop_tgt:`HEADER_SET_<NAME>` target + properties were added to list files in the default header set + and named header sets, respectively. + +* The :prop_tgt:`HEADER_DIRS` and :prop_tgt:`HEADER_DIRS_<NAME>` target + properties were added to specify the base directories of the default + header set and named header sets, respectively. + +* The :prop_tgt:`IMPORTED_NO_SYSTEM` target property was added to + specify that an :ref:`Imported Target <Imported Targets>` should + not be treated as a system library (i.e. its include directories + are not automatically ``SYSTEM``). + +* The :prop_tgt:`XCODE_EMBED_PLUGINS <XCODE_EMBED_<type>>` target property + was added to tell the :generator:`Xcode` generator what targets to put in + the ``Embed PlugIns`` build phase. + +* The :prop_tgt:`XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE` target property + and supporting :variable:`CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE` + variable were added to tell the :generator:`Xcode` generator to enable + specifying the Xcode scheme option property ``GPU Frame Capture``. + +Modules +------- + +* The :module:`CheckPIESupported` module now supports the ``OBJC``, + ``OBJCXX``, ``CUDA``, and ``HIP`` languages. It also now honors + :variable:`CMAKE_SYSROOT` and :variable:`CMAKE_OSX_SYSROOT`. + +* The :module:`ExternalProject` module's :command:`ExternalProject_Add` + command gained support for a ``USES_TERMINAL_PATCH`` option to give + the patch step exclusive terminal access. + +* The :module:`FindCUDAToolkit` module now provides a target for + ``libcufft_static_nocallback``, if found. + +* The :module:`FindGLUT` module now provides the ``GLUT_INCLUDE_DIRS`` + result variable to conform with naming conventions documented in the + :manual:`cmake-developer(7)` manual. This supersedes the legacy + ``GLUT_INCLUDE_DIR`` variable. + +* The :module:`FindGTest` module now provides a target for GMock, if found. + +* The :module:`FindVulkan` module now provides a ``Vulkan_VERSION`` result + variable reporting the version number. + +CTest +----- + +* :manual:`ctest(1)` gained a new :variable:`CTEST_SUBMIT_INACTIVITY_TIMEOUT` + variable, which can be used to specify a timeout for submission inactivity. + +CPack +----- + +* The :cpack_gen:`CPack productbuild Generator` gained the new + :variable:`CPACK_PRODUCTBUILD_DOMAINS`, + :variable:`CPACK_PRODUCTBUILD_DOMAINS_ANYWHERE`, + :variable:`CPACK_PRODUCTBUILD_DOMAINS_USER`, and + :variable:`CPACK_PRODUCTBUILD_DOMAINS_ROOT` variables for + adding the domains element to the Distribution XML. With these variables, + it is now possible to install products to the user's home directory + without requiring administrative privileges. + +* The :cpack_gen:`CPack productbuild Generator` gained a new variable, + :variable:`CPACK_PRODUCTBUILD_IDENTIFIER`, used to customize the unique + product identifier associated with the product. + +* The ``CPack.distribution.dist.in`` template used by the + :cpack_gen:`CPack productbuild Generator` and + :cpack_gen:`CPack PackageMaker Generator` was updated to use a new + ``CPACK_APPLE_PKG_INSTALLER_CONTENT`` variable for its main content. + This replaced the previously undocumented and now deprecated + ``CPACK_PACKAGEMAKER_CHOICES`` variable. + +* The :cpack_gen:`CPack IFW Generator` gained the new + :variable:`CPACK_IFW_ARCHIVE_FORMAT` and + :variable:`CPACK_IFW_ARCHIVE_COMPRESSION` variables for setting the + format used when packaging new component data archives, and choosing + the compression level used. + These features are available for QtIFW 4.2 and newer. + +* The :cpack_gen:`CPack IFW Generator` gained new + :variable:`CPACK_IFW_PACKAGE_DISABLE_COMMAND_LINE_INTERFACE` variable to + prevent the user from passing any consumer command to the installer, like + ``install``, ``update``, and ``remove``. + This feature is available for QtIFW 4.0 and newer. + +* The :cpack_gen:`CPack IFW Generator` gained the new + :variable:`CPACK_IFW_PACKAGE_PRODUCT_IMAGES` variable for adding a + list of images to be shown on the ``PerformInstallationPage``. + This feature is available for QtIFW 4.0 and newer. + +* The :cpack_gen:`CPack IFW Generator` gained the new + :variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM`, + :variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM_ARGUMENTS`, and + :variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM_DESCRIPTION` variables for + executing a command after the installer is done if the user accepts + the action. This feature is available for QtIFW 4.0 and newer. + +* The :cpack_gen:`CPack IFW Generator` gained the new + :variable:`CPACK_IFW_PACKAGE_SIGNING_IDENTITY` variable for specifying a + code signing identity to be used for signing the generated app bundle. + This feature is available on macOS only, and for QtIFW 3.0 and newer. + +* The :cpack_gen:`CPack WIX Generator` gained a new variable, + :variable:`CPACK_WIX_SKIP_WIX_UI_EXTENSION`, to skip the inclusion + of WixUIExtensions. + +Deprecated and Removed Features +=============================== + +* :manual:`cmake(1)` now warns when multiple source paths are specified, + as in ``cmake -S src1 src2``. This has never been officially documented + or supported, but older versions accidentally accepted multiple source + paths and used the last path specified. Update scripts to avoid + passing multiple source path arguments. + +* The :manual:`cpack(1)` undocumented ``OSXX11`` generator has been removed. + +* The previously undocumented ``CPACK_PACKAGEMAKER_CHOICES`` variable used in + the ``CPack.distribution.dist.in`` template has been replaced by a new + ``CPACK_APPLE_PKG_INSTALLER_CONTENT`` variable. This only affects projects + that were providing their own custom ``CPack.distribution.dist.in`` template + file, but still relied on ``CPACK_PACKAGEMAKER_CHOICES`` being set. Those + custom template files should be updated to use + ``CPACK_APPLE_PKG_INSTALLER_CONTENT`` instead, or to fully define all the + template file's contents without relying on substitution of either variable. + +Other Changes +============= + +* The :cpack_gen:`CPack DragNDrop Generator` no longer attaches + :variable:`CPACK_RESOURCE_FILE_LICENSE` as the license agreement in + the generated ``.dmg`` unless explicitly activated by a + :variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` option. + In CMake projects, the :module:`CPack` module enables the option + by default for compatibility. + +* ``CUDA`` targets may now enable both :prop_tgt:`CUDA_SEPARABLE_COMPILATION` + and :prop_tgt:`CUDA_PTX_COMPILATION`. + +* ``CUDA`` compiler detection now: + + * issues an error in all cases when it's unable to compute the default + architecture(s) if required (see :policy:`CMP0104`), + + * handles ``OFF`` for :variable:`CMAKE_CUDA_ARCHITECTURES` on Clang, + + * supports the theoretical case of multiple default architectures, and + + * tries to detect invalid architectures and issue an error. + +* ``CUDA`` with Clang now implements policy :policy:`CMP0105` and + the ``$<DEVICE_LINK:...>`` and ``$<HOST_LINK:...>`` + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +* The :command:`define_property` command's ``BRIEF_DOCS`` and ``FULL_DOCS`` + arguments are now optional. + +* :manual:`ccmake(1)` may now be enabled on Windows when building + CMake from source. This is experimental, and so is not included + in official distributions. + +Updates +======= + +Changes made since CMake 3.23.0 include the following. + +3.23.1 +------ + +* The :command:`target_sources` ``FILE_SET`` feature added in CMake 3.23.0 + does not yet place header files properly in Apple :prop_tgt:`FRAMEWORK` + targets. Pending further work in a future version of CMake, it is now + an error to add a ``FILE_SET`` of type ``HEADERS`` to such targets on + Apple platforms. + +* The :prop_tgt:`HEADER_SETS` and :prop_tgt:`INTERFACE_HEADER_SETS` target + properties added in CMake 3.23.0 are now read-only records of the header + sets created by the :command:`target_sources` command. + +3.23.2 +------ + +* The ``CPACK_PACKAGEMAKER_CHOICES`` variable used in the + ``CPack.distribution.dist.in`` template file was replaced by a new + ``CPACK_APPLE_PKG_INSTALLER_CONTENT`` variable in CMake 3.23.0. + This broke projects that provided their own template file but still + expected the ``CPACK_PACKAGEMAKER_CHOICES`` variable to be defined. + The old ``CPACK_PACKAGEMAKER_CHOICES`` variable is now also set to the + same content as it was before, but it is formally deprecated. diff --git a/Help/release/3.6.rst b/Help/release/3.6.rst index f0add07..b798f0d 100644 --- a/Help/release/3.6.rst +++ b/Help/release/3.6.rst @@ -170,7 +170,7 @@ CPack is used for dependency auto detection. * The :cpack_gen:`CPack DEB Generator` learned how to generate - ``DEBIAN/shlibs`` contorl file when package contains shared libraries. + ``DEBIAN/shlibs`` control file when package contains shared libraries. * The :cpack_gen:`CPack DEB Generator` learned how to generate ``DEBIAN/postinst`` and ``DEBIAN/postrm`` files if the package installs diff --git a/Help/release/index.rst b/Help/release/index.rst index 95b41fb..ee677a3 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -13,6 +13,9 @@ Releases .. toctree:: :maxdepth: 1 + 3.23 <3.23> + 3.22 <3.22> + 3.21 <3.21> 3.20 <3.20> 3.19 <3.19> 3.18 <3.18> diff --git a/Help/variable/CMAKE_AUTOMOC_RELAXED_MODE.rst b/Help/variable/CMAKE_AUTOMOC_RELAXED_MODE.rst index 6c0c61b..0b0b114 100644 --- a/Help/variable/CMAKE_AUTOMOC_RELAXED_MODE.rst +++ b/Help/variable/CMAKE_AUTOMOC_RELAXED_MODE.rst @@ -8,7 +8,7 @@ Switch between strict and relaxed automoc mode. By default, :prop_tgt:`AUTOMOC` behaves exactly as described in the documentation of the :prop_tgt:`AUTOMOC` target property. When set to ``TRUE``, it accepts more input and tries to find the correct input file for -``moc`` even if it differs from the documented behaviour. In this mode it +``moc`` even if it differs from the documented behavior. In this mode it e.g. also checks whether a header file is intended to be processed by moc when a ``"foo.moc"`` file has been included. diff --git a/Help/variable/CMAKE_BUILD_TYPE.rst b/Help/variable/CMAKE_BUILD_TYPE.rst index 405f7d5..bb95436 100644 --- a/Help/variable/CMAKE_BUILD_TYPE.rst +++ b/Help/variable/CMAKE_BUILD_TYPE.rst @@ -1,25 +1,21 @@ CMAKE_BUILD_TYPE ---------------- -Specifies the build type on single-configuration generators. +Specifies the build type on single-configuration generators (e.g. +:ref:`Makefile Generators` or :generator:`Ninja`). Typical values include +``Debug``, ``Release``, ``RelWithDebInfo`` and ``MinSizeRel``, but custom +build types can also be defined. -This statically specifies what build type (configuration) will be -built in this build tree. Possible values are empty, ``Debug``, ``Release``, -``RelWithDebInfo``, ``MinSizeRel``, ... This variable is only meaningful to -single-configuration generators (such as :ref:`Makefile Generators` and -:generator:`Ninja`) i.e. those which choose a single configuration when CMake -runs to generate a build tree as opposed to multi-configuration generators -which offer selection of the build configuration within the generated build -environment. There are many per-config properties and variables -(usually following clean ``SOME_VAR_<CONFIG>`` order conventions), such as -``CMAKE_C_FLAGS_<CONFIG>``, specified as uppercase: -``CMAKE_C_FLAGS_[DEBUG|RELEASE|RELWITHDEBINFO|MINSIZEREL|...]``. For example, -in a build tree configured to build type ``Debug``, CMake will see to -having :variable:`CMAKE_C_FLAGS_DEBUG <CMAKE_<LANG>_FLAGS_DEBUG>` settings get -added to the :variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>` settings. See -also :variable:`CMAKE_CONFIGURATION_TYPES`. +This variable is initialized by the first :command:`project` or +:command:`enable_language` command called in a project when a new build +tree is first created. If the :envvar:`CMAKE_BUILD_TYPE` environment +variable is set, its value is used. Otherwise, a toolchain-specific +default is chosen when a language is enabled. The default value is often +an empty string, but this is usually not desirable and one of the other +standard build types is usually more appropriate. -Note that configuration names are case-insensitive. The value of this -variable will be the same as it is specified when invoking CMake. -For instance, if ``-DCMAKE_BUILD_TYPE=ReLeAsE`` is specified, then the -value of ``CMAKE_BUILD_TYPE`` will be ``ReLeAsE``. +Depending on the situation, the value of this variable may be treated +case-sensitively or case-insensitively. See :ref:`Build Configurations` +for discussion of this and other related topics. + +For multi-config generators, see :variable:`CMAKE_CONFIGURATION_TYPES`. diff --git a/Help/variable/CMAKE_CACHEFILE_DIR.rst b/Help/variable/CMAKE_CACHEFILE_DIR.rst index 8604d0e..3fee09f 100644 --- a/Help/variable/CMAKE_CACHEFILE_DIR.rst +++ b/Help/variable/CMAKE_CACHEFILE_DIR.rst @@ -1,7 +1,6 @@ CMAKE_CACHEFILE_DIR ------------------- -The directory with the ``CMakeCache.txt`` file. - -This is the full path to the directory that has the ``CMakeCache.txt`` -file in it. This is the same as :variable:`CMAKE_BINARY_DIR`. +This variable is used internally by CMake, and may not be set during +the first configuration of a build tree. When it is set, it has the +same value as :variable:`CMAKE_BINARY_DIR`. Use that variable instead. diff --git a/Help/variable/CMAKE_CFG_INTDIR.rst b/Help/variable/CMAKE_CFG_INTDIR.rst index 842654e..43668ea 100644 --- a/Help/variable/CMAKE_CFG_INTDIR.rst +++ b/Help/variable/CMAKE_CFG_INTDIR.rst @@ -1,6 +1,12 @@ CMAKE_CFG_INTDIR ---------------- +.. deprecated:: 3.21 + + This variable has poor support on :generator:`Ninja Multi-Config`, and + predates the existence of the :genex:`$<CONFIG>` generator expression. Use + ``$<CONFIG>`` instead. + Build-time reference to per-configuration output subdirectory. For native build systems supporting multiple configurations in the @@ -19,11 +25,6 @@ Example values: . = Ninja ${CONFIGURATION} = Ninja Multi-Config -Note that this variable only has limited support on -:generator:`Ninja Multi-Config`. It is recommended that you use the -``$<CONFIG>`` :manual:`generator expression <cmake-generator-expressions(7)>` -instead. - Since these values are evaluated by the native build system, this variable is suitable only for use in command lines that will be evaluated at build time. Example of intended usage: diff --git a/Help/variable/CMAKE_CONFIGURATION_TYPES.rst b/Help/variable/CMAKE_CONFIGURATION_TYPES.rst index 34e99eb..75ff8a1 100644 --- a/Help/variable/CMAKE_CONFIGURATION_TYPES.rst +++ b/Help/variable/CMAKE_CONFIGURATION_TYPES.rst @@ -1,10 +1,20 @@ CMAKE_CONFIGURATION_TYPES ------------------------- -Specifies the available build types on multi-config generators. +Specifies the available build types (configurations) on multi-config +generators (e.g. :ref:`Visual Studio <Visual Studio Generators>`, +:generator:`Xcode`, or :generator:`Ninja Multi-Config`). Typical values +include ``Debug``, ``Release``, ``RelWithDebInfo`` and ``MinSizeRel``, +but custom build types can also be defined. -This specifies what build types (configurations) will be available -such as ``Debug``, ``Release``, ``RelWithDebInfo`` etc. This has reasonable -defaults on most platforms, but can be extended to provide other build -types. See also :variable:`CMAKE_BUILD_TYPE` for details of managing -configuration data, and :variable:`CMAKE_CFG_INTDIR`. +This variable is initialized by the first :command:`project` or +:command:`enable_language` command called in a project when a new build +tree is first created. If the :envvar:`CMAKE_CONFIGURATION_TYPES` +environment variable is set, its value is used. Otherwise, the default +value is generator-specific. + +Depending on the situation, the values in this variable may be treated +case-sensitively or case-insensitively. See :ref:`Build Configurations` +for discussion of this and other related topics. + +For single-config generators, see :variable:`CMAKE_BUILD_TYPE`. diff --git a/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst b/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst index 815da00..e21b35d 100644 --- a/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst +++ b/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst @@ -7,9 +7,10 @@ This variable is only used when :variable:`CMAKE_CROSSCOMPILING` is on. It should point to a command on the host system that can run executable built for the target system. -If this variable contains a :ref:`semicolon-separated list <CMake Language -Lists>`, then the first value is the command and remaining values are its -arguments. +.. versionadded:: 3.15 + If this variable contains a :ref:`semicolon-separated list <CMake Language + Lists>`, then the first value is the command and remaining values are its + arguments. The command will be used to run :command:`try_run` generated executables, which avoids manual population of the ``TryRunResults.cmake`` file. diff --git a/Help/variable/CMAKE_CUDA_EXTENSIONS.rst b/Help/variable/CMAKE_CUDA_EXTENSIONS.rst index b86c0ea..12749ce 100644 --- a/Help/variable/CMAKE_CUDA_EXTENSIONS.rst +++ b/Help/variable/CMAKE_CUDA_EXTENSIONS.rst @@ -3,11 +3,8 @@ CMAKE_CUDA_EXTENSIONS .. versionadded:: 3.8 -Default value for :prop_tgt:`CUDA_EXTENSIONS` property of targets. - -This variable is used to initialize the :prop_tgt:`CUDA_EXTENSIONS` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`CUDA_EXTENSIONS` target property if set when a +target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst index d5fcb7d..9817b1a 100644 --- a/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst +++ b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst @@ -23,3 +23,7 @@ is read-only and changes to it are undefined behavior. :variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` is ``NVIDIA``, it does not make sense to set ``CMAKE_CUDA_HOST_COMPILER`` without also setting ``CMAKE_CUDA_COMPILER`` to NVCC. + +.. note:: + + Ignored when using :ref:`Visual Studio Generators`. diff --git a/Help/variable/CMAKE_CUDA_STANDARD.rst b/Help/variable/CMAKE_CUDA_STANDARD.rst index 798ab1e..ee9395a 100644 --- a/Help/variable/CMAKE_CUDA_STANDARD.rst +++ b/Help/variable/CMAKE_CUDA_STANDARD.rst @@ -3,11 +3,8 @@ CMAKE_CUDA_STANDARD .. versionadded:: 3.8 -Default value for :prop_tgt:`CUDA_STANDARD` property of targets. - -This variable is used to initialize the :prop_tgt:`CUDA_STANDARD` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`CUDA_STANDARD` target property if set when a +target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CUDA_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_CUDA_STANDARD_REQUIRED.rst index ae2f52f..0c85a04d 100644 --- a/Help/variable/CMAKE_CUDA_STANDARD_REQUIRED.rst +++ b/Help/variable/CMAKE_CUDA_STANDARD_REQUIRED.rst @@ -3,11 +3,8 @@ CMAKE_CUDA_STANDARD_REQUIRED .. versionadded:: 3.8 -Default value for :prop_tgt:`CUDA_STANDARD_REQUIRED` property of targets. - -This variable is used to initialize the :prop_tgt:`CUDA_STANDARD_REQUIRED` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`CUDA_STANDARD_REQUIRED` target property if set +when a target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst b/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst index 40496b5..8fc85ee 100644 --- a/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst +++ b/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst @@ -3,7 +3,7 @@ CMAKE_CURRENT_BINARY_DIR The path to the binary directory currently being processed. -This the full path to the build directory that is currently being +This is the full path to the build directory that is currently being processed by cmake. Each directory added by :command:`add_subdirectory` will create a binary directory in the build tree, and as it is being processed this variable will be set. For in-source builds this is the diff --git a/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst b/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst index c1b755a..1a25efc 100644 --- a/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst +++ b/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst @@ -3,7 +3,7 @@ CMAKE_CURRENT_SOURCE_DIR The path to the source directory currently being processed. -This the full path to the source directory that is currently being +This is the full path to the source directory that is currently being processed by cmake. When run in -P script mode, CMake sets the variables diff --git a/Help/variable/CMAKE_CXX_EXTENSIONS.rst b/Help/variable/CMAKE_CXX_EXTENSIONS.rst index ea8c4be..017f503 100644 --- a/Help/variable/CMAKE_CXX_EXTENSIONS.rst +++ b/Help/variable/CMAKE_CXX_EXTENSIONS.rst @@ -3,11 +3,8 @@ CMAKE_CXX_EXTENSIONS .. versionadded:: 3.1 -Default value for :prop_tgt:`CXX_EXTENSIONS` property of targets. - -This variable is used to initialize the :prop_tgt:`CXX_EXTENSIONS` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`CXX_EXTENSIONS` target property if set when a +target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CXX_STANDARD.rst b/Help/variable/CMAKE_CXX_STANDARD.rst index 8ef8c80..33eb89e 100644 --- a/Help/variable/CMAKE_CXX_STANDARD.rst +++ b/Help/variable/CMAKE_CXX_STANDARD.rst @@ -3,11 +3,8 @@ CMAKE_CXX_STANDARD .. versionadded:: 3.1 -Default value for :prop_tgt:`CXX_STANDARD` property of targets. - -This variable is used to initialize the :prop_tgt:`CXX_STANDARD` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`CXX_STANDARD` target property if set when a target +is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst index f7b2ae9..1c6c0cc 100644 --- a/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst +++ b/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst @@ -3,11 +3,8 @@ CMAKE_CXX_STANDARD_REQUIRED .. versionadded:: 3.1 -Default value for :prop_tgt:`CXX_STANDARD_REQUIRED` property of targets. - -This variable is used to initialize the :prop_tgt:`CXX_STANDARD_REQUIRED` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`CXX_STANDARD_REQUIRED` target property if set when +a target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_C_EXTENSIONS.rst b/Help/variable/CMAKE_C_EXTENSIONS.rst index fce8fc7..6680521 100644 --- a/Help/variable/CMAKE_C_EXTENSIONS.rst +++ b/Help/variable/CMAKE_C_EXTENSIONS.rst @@ -3,11 +3,8 @@ CMAKE_C_EXTENSIONS .. versionadded:: 3.1 -Default value for :prop_tgt:`C_EXTENSIONS` property of targets. - -This variable is used to initialize the :prop_tgt:`C_EXTENSIONS` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`C_EXTENSIONS` target property if set when a target +is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_C_STANDARD.rst b/Help/variable/CMAKE_C_STANDARD.rst index 64ef8ce..ec1e513 100644 --- a/Help/variable/CMAKE_C_STANDARD.rst +++ b/Help/variable/CMAKE_C_STANDARD.rst @@ -3,11 +3,8 @@ CMAKE_C_STANDARD .. versionadded:: 3.1 -Default value for :prop_tgt:`C_STANDARD` property of targets. - -This variable is used to initialize the :prop_tgt:`C_STANDARD` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`C_STANDARD` target property if set when a target +is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst index e70b6bd..2bd9d51 100644 --- a/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst +++ b/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst @@ -3,11 +3,8 @@ CMAKE_C_STANDARD_REQUIRED .. versionadded:: 3.1 -Default value for :prop_tgt:`C_STANDARD_REQUIRED` property of targets. - -This variable is used to initialize the :prop_tgt:`C_STANDARD_REQUIRED` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`C_STANDARD_REQUIRED` target property if set when +a target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst b/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst index ed60020..f77e939 100644 --- a/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst +++ b/Help/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.rst @@ -14,3 +14,5 @@ the package has already been found in a previous CMake run, the variables which have been stored in the cache will still be there. In that case it is recommended to remove the cache variables for this package from the cache using the cache editor or :manual:`cmake(1)` ``-U`` + +See also the :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable. diff --git a/Help/variable/CMAKE_DOTNET_SDK.rst b/Help/variable/CMAKE_DOTNET_SDK.rst new file mode 100644 index 0000000..dc8806a --- /dev/null +++ b/Help/variable/CMAKE_DOTNET_SDK.rst @@ -0,0 +1,9 @@ +CMAKE_DOTNET_SDK +---------------- + +.. versionadded:: 3.23 + +Default value for :prop_tgt:`DOTNET_SDK` property of targets. + +This variable is used to initialize the :prop_tgt:`DOTNET_SDK` +property on all targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_EXECUTABLE_SUFFIX.rst b/Help/variable/CMAKE_EXECUTABLE_SUFFIX.rst index 356590f..bc4b9df 100644 --- a/Help/variable/CMAKE_EXECUTABLE_SUFFIX.rst +++ b/Help/variable/CMAKE_EXECUTABLE_SUFFIX.rst @@ -6,4 +6,5 @@ The suffix for executables on this platform. The suffix to use for the end of an executable filename if any, ``.exe`` on Windows. -``CMAKE_EXECUTABLE_SUFFIX_<LANG>`` overrides this for language ``<LANG>``. +:variable:`CMAKE_EXECUTABLE_SUFFIX_<LANG>` overrides this for +language ``<LANG>``. diff --git a/Help/variable/CMAKE_EXECUTABLE_SUFFIX_LANG.rst b/Help/variable/CMAKE_EXECUTABLE_SUFFIX_LANG.rst new file mode 100644 index 0000000..a68150e --- /dev/null +++ b/Help/variable/CMAKE_EXECUTABLE_SUFFIX_LANG.rst @@ -0,0 +1,7 @@ +CMAKE_EXECUTABLE_SUFFIX_<LANG> +------------------------------ + +The suffix to use for the end of an executable filename of ``<LANG>`` +compiler target architecture, if any. + +It overrides :variable:`CMAKE_EXECUTABLE_SUFFIX` for language ``<LANG>``. diff --git a/Help/variable/CMAKE_FIND_LIBRARY_SUFFIXES.rst b/Help/variable/CMAKE_FIND_LIBRARY_SUFFIXES.rst index 4a64e33..c2c2609 100644 --- a/Help/variable/CMAKE_FIND_LIBRARY_SUFFIXES.rst +++ b/Help/variable/CMAKE_FIND_LIBRARY_SUFFIXES.rst @@ -5,5 +5,8 @@ Suffixes to append when looking for libraries. This specifies what suffixes to add to library names when the :command:`find_library` command looks for libraries. On Windows systems this -is typically ``.lib`` and ``.dll``, meaning that when trying to find the -``foo`` library it will look for ``foo.dll`` etc. +is typically ``.lib`` and, depending on the compiler, ``.dll.a``, ``.a`` +(e.g. GCC and Clang), so when it tries to find the ``foo`` library, it will +look for ``[<prefix>]foo.lib`` and/or ``[<prefix>]foo[.dll].a``, depending on +the compiler used and the ``<prefix>`` specified in the +:variable:`CMAKE_FIND_LIBRARY_PREFIXES`. diff --git a/Help/variable/CMAKE_GENERATOR_INSTANCE.rst b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst index 5858d7a..6bfabe0 100644 --- a/Help/variable/CMAKE_GENERATOR_INSTANCE.rst +++ b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst @@ -18,10 +18,60 @@ variable may initialize ``CMAKE_GENERATOR_INSTANCE`` as a cache entry. Once a given build tree has been initialized with a particular value for this variable, changing the value has undefined behavior. -Instance specification is supported only on specific generators: +Instance specification is supported only on specific generators. -* For the :generator:`Visual Studio 15 2017` generator (and above) - this specifies the absolute path to the VS installation directory - of the selected VS instance. +Visual Studio Instance Selection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -See native build system documentation for allowed instance values. +:ref:`Visual Studio Generators` support instance specification for +Visual Studio 2017 and above. The ``CMAKE_GENERATOR_INSTANCE`` variable +may be set as a cache entry selecting an instance of Visual Studio +via one of the following forms: + +* ``location`` +* ``location[,key=value]*`` +* ``key=value[,key=value]*`` + +The ``location`` specifies the absolute path to the top-level directory +of the VS installation. + +The ``key=value`` pairs form a comma-separated list of options to +specify details of the instance selection. +Supported pairs are: + +``version=<major>.<minor>.<date>.<build>`` + .. versionadded:: 3.23 + + Specify the 4-component VS Build Version, a.k.a. Build Number. + The components are: + + ``<major>.<minor>`` + + The VS major and minor version numbers. + These are the same as the release version numbers. + + ``<date>`` + + A build date in the format ``MMMDD``, where ``MMM`` is a month index + since an epoch used by Microsoft, and ``DD`` is a day in that month. + + ``<build>`` + + A build index on the day represented by ``<date>``. + + The build number is reported by ``vswhere`` as ``installationVersion``. + For example, VS 16.11.10 has build number ``16.11.32126.315``. + +.. versionadded:: 3.23 + + A portable VS instance, which is not known to the Visual Studio Installer, + may be specified by providing both ``location`` and ``version=``. + +If the value of ``CMAKE_GENERATOR_INSTANCE`` is not specified explicitly +by the user or a toolchain file, CMake queries the Visual Studio Installer +to locate VS instances, chooses one, and sets the variable as a cache entry +to hold the value persistently. If an environment variable of the form +``VS##0COMNTOOLS``, where ``##`` the Visual Studio major version number, +is set and points to the ``Common7/Tools`` directory within one of the +VS instances, that instance will be used. Otherwise, if more than one +VS instance is installed we do not define which one is chosen by default. diff --git a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst index 53ad2f3..45f2d32 100644 --- a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst +++ b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst @@ -63,3 +63,27 @@ Supported pairs are: Specify an alternative ``VCTargetsPath`` value for Visual Studio project files. This allows use of VS platform extension configuration files (``.props`` and ``.targets``) that are not installed with VS. + +Visual Studio Toolset Customization +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**These are unstable interfaces with no compatibility guarantees** +because they hook into undocumented internal CMake implementation details. +Institutions may use these to internally maintain support for non-public +Visual Studio platforms and toolsets, but must accept responsibility to +make updates as changes are made to CMake. + +Additional ``key=value`` pairs are available: + +``customFlagTableDir=<path>`` + .. versionadded:: 3.21 + + Specify the absolute path to a directory from which to load custom + flag tables stored as JSON documents with file names of the form + ``<platform>_<toolset>_<tool>.json`` or ``<platform>_<tool>.json``, + where ``<platform>`` is the :variable:`CMAKE_VS_PLATFORM_NAME`, + ``<toolset>`` is the :variable:`CMAKE_VS_PLATFORM_TOOLSET`, + and ``<tool>`` is the tool for which the flag table is meant. + **This naming pattern is an internal CMake implementation detail.** + The ``<tool>`` names are undocumented. The format of the ``.json`` + flag table files is undocumented. diff --git a/Help/variable/CMAKE_HIP_ARCHITECTURES.rst b/Help/variable/CMAKE_HIP_ARCHITECTURES.rst new file mode 100644 index 0000000..bcc6b35 --- /dev/null +++ b/Help/variable/CMAKE_HIP_ARCHITECTURES.rst @@ -0,0 +1,12 @@ +CMAKE_HIP_ARCHITECTURES +----------------------- + +.. versionadded:: 3.21 + +Default value for :prop_tgt:`HIP_ARCHITECTURES` property of targets. + +This is initialized to the architectures reported by ``rocm_agent_enumerator``, +if available, and otherwise to the default chosen by the compiler. + +This variable is used to initialize the :prop_tgt:`HIP_ARCHITECTURES` property +on all targets. See the target property for additional information. diff --git a/Help/variable/CMAKE_HIP_EXTENSIONS.rst b/Help/variable/CMAKE_HIP_EXTENSIONS.rst new file mode 100644 index 0000000..13987dc --- /dev/null +++ b/Help/variable/CMAKE_HIP_EXTENSIONS.rst @@ -0,0 +1,10 @@ +CMAKE_HIP_EXTENSIONS +-------------------- + +.. versionadded:: 3.21 + +Default value for :prop_tgt:`HIP_EXTENSIONS` target property if set when a +target is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_HIP_STANDARD.rst b/Help/variable/CMAKE_HIP_STANDARD.rst new file mode 100644 index 0000000..5f15145 --- /dev/null +++ b/Help/variable/CMAKE_HIP_STANDARD.rst @@ -0,0 +1,10 @@ +CMAKE_HIP_STANDARD +------------------ + +.. versionadded:: 3.21 + +Default value for :prop_tgt:`HIP_STANDARD` target property if set when a target +is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_HIP_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_HIP_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..5d35e4e --- /dev/null +++ b/Help/variable/CMAKE_HIP_STANDARD_REQUIRED.rst @@ -0,0 +1,10 @@ +CMAKE_HIP_STANDARD_REQUIRED +--------------------------- + +.. versionadded:: 3.21 + +Default value for :prop_tgt:`HIP_STANDARD_REQUIRED` target property if set when +a target is created. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_IGNORE_PATH.rst b/Help/variable/CMAKE_IGNORE_PATH.rst index 4bca34b..4b2bd8a 100644 --- a/Help/variable/CMAKE_IGNORE_PATH.rst +++ b/Help/variable/CMAKE_IGNORE_PATH.rst @@ -1,18 +1,18 @@ CMAKE_IGNORE_PATH ----------------- -:ref:`Semicolon-separated list <CMake Language Lists>` of directories to be *ignored* by -the :command:`find_program`, :command:`find_library`, :command:`find_file`, -and :command:`find_path` commands. This is useful in cross-compiling -environments where some system directories contain incompatible but -possibly linkable libraries. For example, on cross-compiled cluster -environments, this allows a user to ignore directories containing -libraries meant for the front-end machine. +.. |CMAKE_IGNORE_VAR| replace:: ``CMAKE_IGNORE_PATH`` +.. |CMAKE_IGNORE_PREFIX_VAR| replace:: :variable:`CMAKE_IGNORE_PREFIX_PATH` -By default this is empty; it is intended to be set by the project. -Note that ``CMAKE_IGNORE_PATH`` takes a list of directory names, *not* -a list of prefixes. To ignore paths under prefixes (``bin``, ``include``, -``lib``, etc.), specify them explicitly. +.. include:: IGNORE_SEARCH_PATH.txt +.. include:: IGNORE_SEARCH_LOCATIONS.txt +.. include:: IGNORE_SEARCH_NONSYSTEM.txt -See also the :variable:`CMAKE_PREFIX_PATH`, :variable:`CMAKE_LIBRARY_PATH`, -:variable:`CMAKE_INCLUDE_PATH`, and :variable:`CMAKE_PROGRAM_PATH` variables. +See also the following variables: + +- :variable:`CMAKE_IGNORE_PREFIX_PATH` +- :variable:`CMAKE_SYSTEM_IGNORE_PATH` +- :variable:`CMAKE_PREFIX_PATH` +- :variable:`CMAKE_LIBRARY_PATH` +- :variable:`CMAKE_INCLUDE_PATH` +- :variable:`CMAKE_PROGRAM_PATH` diff --git a/Help/variable/CMAKE_IGNORE_PREFIX_PATH.rst b/Help/variable/CMAKE_IGNORE_PREFIX_PATH.rst new file mode 100644 index 0000000..b81cc57 --- /dev/null +++ b/Help/variable/CMAKE_IGNORE_PREFIX_PATH.rst @@ -0,0 +1,20 @@ +CMAKE_IGNORE_PREFIX_PATH +------------------------ + +.. versionadded:: 3.23 + +.. |CMAKE_IGNORE_VAR| replace:: ``CMAKE_IGNORE_PREFIX_PATH`` +.. |CMAKE_IGNORE_NONPREFIX_VAR| replace:: :variable:`CMAKE_IGNORE_PATH` + +.. include:: IGNORE_SEARCH_PREFIX.txt +.. include:: IGNORE_SEARCH_LOCATIONS.txt +.. include:: IGNORE_SEARCH_NONSYSTEM.txt + +See also the following variables: + +- :variable:`CMAKE_IGNORE_PATH` +- :variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` +- :variable:`CMAKE_PREFIX_PATH` +- :variable:`CMAKE_LIBRARY_PATH` +- :variable:`CMAKE_INCLUDE_PATH` +- :variable:`CMAKE_PROGRAM_PATH` diff --git a/Help/variable/CMAKE_INSTALL_PREFIX.rst b/Help/variable/CMAKE_INSTALL_PREFIX.rst index 02ba645..6d42ea8 100644 --- a/Help/variable/CMAKE_INSTALL_PREFIX.rst +++ b/Help/variable/CMAKE_INSTALL_PREFIX.rst @@ -10,14 +10,26 @@ See :variable:`CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT` for how a project might choose its own default. On UNIX one can use the ``DESTDIR`` mechanism in order to relocate the -whole installation. See :envvar:`DESTDIR` for more information. +whole installation to a staging area. See the :envvar:`DESTDIR` environment +variable for more information. The installation prefix is also added to :variable:`CMAKE_SYSTEM_PREFIX_PATH` so that :command:`find_package`, :command:`find_program`, :command:`find_library`, :command:`find_path`, and :command:`find_file` -will search the prefix for other software. +will search the prefix for other software. This behavior can be disabled by +setting the :variable:`CMAKE_FIND_NO_INSTALL_PREFIX` to ``TRUE`` before the +first :command:`project` invocation. .. note:: Use the :module:`GNUInstallDirs` module to provide GNU-style options for the layout of directories within the installation. + +The ``CMAKE_INSTALL_PREFIX`` may be defined when configuring a build tree +to set its installation prefix. Or, when using the :manual:`cmake(1)` +command-line tool's ``--install`` mode, one may specify a different prefix +using the ``--prefix`` option: + +.. code-block:: shell + + cmake --install . --prefix /my/install/prefix diff --git a/Help/variable/CMAKE_LANG_COMPILER_FRONTEND_VARIANT.rst b/Help/variable/CMAKE_LANG_COMPILER_FRONTEND_VARIANT.rst new file mode 100644 index 0000000..128b1fb --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_FRONTEND_VARIANT.rst @@ -0,0 +1,18 @@ +CMAKE_<LANG>_COMPILER_FRONTEND_VARIANT +-------------------------------------- + +.. versionadded:: 3.14 + +Identification string of the compiler frontend variant. + +Some compilers have multiple, different frontends for accepting command +line options. (For example ``Clang`` originally only had a frontend +compatible with the ``GNU`` compiler but since its port to Windows +(``Clang-Cl``) it now also supports a frontend compatible with ``MSVC``.) +When CMake detects such a compiler it sets this +variable to what would have been the :variable:`CMAKE_<LANG>_COMPILER_ID` for +the compiler whose frontend it resembles. + +.. note:: + In other words, this variable describes what command line options + and language extensions the compiler frontend expects. diff --git a/Help/variable/CMAKE_LANG_COMPILER_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_ID.rst index 89d9e27..cd7d5cd 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_ID.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_ID.rst @@ -19,6 +19,8 @@ include: Cray = Cray Compiler (cray.com) Embarcadero, Borland = Embarcadero (embarcadero.com) Flang = Flang LLVM Fortran Compiler + Fujitsu = Fujitsu HPC compiler (Trad mode) + FujitsuClang = Fujitsu HPC compiler (Clang mode) G95 = G95 Fortran (g95.org) GNU = GNU Compiler Collection (gcc.gnu.org) GHS = Green Hills Software (www.ghs.com) @@ -26,6 +28,7 @@ include: IAR = IAR Systems (iar.com) Intel = Intel Compiler (intel.com) IntelLLVM = Intel LLVM-Based Compiler (intel.com) + LCC = MCST Elbrus C/C++/Fortran Compiler (mcst.ru) MSVC = Microsoft Visual Studio (microsoft.com) NVHPC = NVIDIA HPC SDK Compiler (nvidia.com) NVIDIA = NVIDIA CUDA Compiler (nvidia.com) @@ -38,6 +41,7 @@ include: TinyCC = Tiny C Compiler (tinycc.org) XL, VisualAge, zOS = IBM XL (ibm.com) XLClang = IBM Clang-based XL (ibm.com) + IBMClang = IBM LLVM-based Compiler (ibm.com) This variable is not guaranteed to be defined for all compilers or languages. diff --git a/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst b/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst index 89fd7bc..f16e594 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst @@ -6,7 +6,7 @@ CMAKE_<LANG>_COMPILER_LAUNCHER Default value for :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property. This variable is used to initialize the property on each target as it is created. This is done only when ``<LANG>`` is ``C``, ``CXX``, ``Fortran``, -``ISPC``, ``OBJC``, ``OBJCXX``, or ``CUDA``. +``HIP``, ``ISPC``, ``OBJC``, ``OBJCXX``, or ``CUDA``. This variable is initialized to the :envvar:`CMAKE_<LANG>_COMPILER_LAUNCHER` environment variable if it is set. diff --git a/Help/variable/CMAKE_LANG_EXTENSIONS.rst b/Help/variable/CMAKE_LANG_EXTENSIONS.rst new file mode 100644 index 0000000..3a32002 --- /dev/null +++ b/Help/variable/CMAKE_LANG_EXTENSIONS.rst @@ -0,0 +1,20 @@ +CMAKE_<LANG>_EXTENSIONS +----------------------- + +The variations are: + +* :variable:`CMAKE_C_EXTENSIONS` +* :variable:`CMAKE_CXX_EXTENSIONS` +* :variable:`CMAKE_CUDA_EXTENSIONS` +* :variable:`CMAKE_HIP_EXTENSIONS` +* :variable:`CMAKE_OBJC_EXTENSIONS` +* :variable:`CMAKE_OBJCXX_EXTENSIONS` + +Default values for :prop_tgt:`<LANG>_EXTENSIONS` target properties if set when +a target is created. For the compiler's default setting see +:variable:`CMAKE_<LANG>_EXTENSIONS_DEFAULT`. + +For supported CMake versions see the respective pages. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_LANG_EXTENSIONS_DEFAULT.rst b/Help/variable/CMAKE_LANG_EXTENSIONS_DEFAULT.rst new file mode 100644 index 0000000..a66453a --- /dev/null +++ b/Help/variable/CMAKE_LANG_EXTENSIONS_DEFAULT.rst @@ -0,0 +1,10 @@ +CMAKE_<LANG>_EXTENSIONS_DEFAULT +------------------------------- + +.. versionadded:: 3.22 + +Compiler's default extensions mode. Used as the default for the +:prop_tgt:`<LANG>_EXTENSIONS` target property when +:variable:`CMAKE_<LANG>_EXTENSIONS` is not set (see :policy:`CMP0128`). + +This variable is read-only. Modifying it is undefined behavior. diff --git a/Help/variable/CMAKE_LANG_FLAGS.rst b/Help/variable/CMAKE_LANG_FLAGS.rst index 14b2694..2784397 100644 --- a/Help/variable/CMAKE_LANG_FLAGS.rst +++ b/Help/variable/CMAKE_LANG_FLAGS.rst @@ -15,3 +15,11 @@ This is initialized for each language from environment variables: Initialized by the :envvar:`CUDAFLAGS` environment variable. * ``CMAKE_Fortran_FLAGS``: Initialized by the :envvar:`FFLAGS` environment variable. + +This value is a command-line string fragment. Therefore, multiple options +should be separated by spaces, and options with spaces should be quoted. + +The flags in this variable will be passed to the compiler before those +in the per-configuration :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variant, +and before flags added by the :command:`add_compile_options` or +:command:`target_compile_options` commands. diff --git a/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst b/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst index 628b62b..f0900fd 100644 --- a/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst +++ b/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst @@ -1,6 +1,9 @@ CMAKE_<LANG>_FLAGS_<CONFIG> --------------------------- -.. versionadded:: 3.11 - Flags for language ``<LANG>`` when building for the ``<CONFIG>`` configuration. + +The flags in this variable will be passed to the compiler after those +in the :variable:`CMAKE_<LANG>_FLAGS` variable, but before flags added +by the :command:`add_compile_options` or :command:`target_compile_options` +commands. diff --git a/Help/variable/CMAKE_LANG_FLAGS_INIT.rst b/Help/variable/CMAKE_LANG_FLAGS_INIT.rst index 67ff2cb..ca13a29 100644 --- a/Help/variable/CMAKE_LANG_FLAGS_INIT.rst +++ b/Help/variable/CMAKE_LANG_FLAGS_INIT.rst @@ -12,6 +12,8 @@ the contents of a ``xxxFLAGS`` environment variable will be prepended, where ``xxx`` will be language-specific but not necessarily the same as ``<LANG>`` (e.g. :envvar:`CXXFLAGS` for ``CXX``, :envvar:`FFLAGS` for ``Fortran``, and so on). +This value is a command-line string fragment. Therefore, multiple options +should be separated by spaces, and options with spaces should be quoted. See also the configuration-specific :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>_INIT` variable. diff --git a/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst index e9e04be..081c4da 100644 --- a/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst +++ b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES.rst @@ -6,8 +6,20 @@ Implicit linker search path detected for language ``<LANG>``. Compilers typically pass directories containing language runtime libraries and default library search paths when they invoke a linker. These paths are implicit linker search directories for the compiler's -language. CMake automatically detects these directories for each -language and reports the results in this variable. +language. For each language enabled by the :command:`project` or +:command:`enable_language` command, CMake automatically detects these +directories and reports the results in this variable. + +When linking to a static library, CMake adds the implicit link directories +from this variable for each language used in the static library (except +the language whose compiler is used to drive linking). In the case of an +imported static library, the :prop_tgt:`IMPORTED_LINK_INTERFACE_LANGUAGES` +target property lists the languages whose implicit link information is +needed. If any of the languages is not enabled, its value for the +``CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES`` variable may instead be provided +by the project. Or, a :variable:`toolchain file <CMAKE_TOOLCHAIN_FILE>` +may set the variable to a value known for the specified toolchain. It will +either be overridden when the language is enabled, or used as a fallback. Some toolchains read implicit directories from an environment variable such as ``LIBRARY_PATH``. If using such an environment variable, keep its value @@ -18,3 +30,5 @@ If policy :policy:`CMP0060` is not set to ``NEW``, then when a library in one of these directories is given by full path to :command:`target_link_libraries` CMake will generate the ``-l<name>`` form on link lines for historical purposes. + +See also the :variable:`CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES` variable. diff --git a/Help/variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES.rst b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES.rst index ec16477..0c25489 100644 --- a/Help/variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES.rst +++ b/Help/variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES.rst @@ -5,6 +5,20 @@ Implicit link libraries and flags detected for language ``<LANG>``. Compilers typically pass language runtime library names and other flags when they invoke a linker. These flags are implicit link -options for the compiler's language. CMake automatically detects -these libraries and flags for each language and reports the results in -this variable. +options for the compiler's language. For each language enabled +by the :command:`project` or :command:`enable_language` command, +CMake automatically detects these libraries and flags and reports +the results in this variable. + +When linking to a static library, CMake adds the implicit link libraries and +flags from this variable for each language used in the static library (except +the language whose compiler is used to drive linking). In the case of an +imported static library, the :prop_tgt:`IMPORTED_LINK_INTERFACE_LANGUAGES` +target property lists the languages whose implicit link information is +needed. If any of the languages is not enabled, its value for the +``CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES`` variable may instead be provided +by the project. Or, a :variable:`toolchain file <CMAKE_TOOLCHAIN_FILE>` +may set the variable to a value known for the specified toolchain. It will +either be overridden when the language is enabled, or used as a fallback. + +See also the :variable:`CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES` variable. diff --git a/Help/variable/CMAKE_LANG_LINKER_LAUNCHER.rst b/Help/variable/CMAKE_LANG_LINKER_LAUNCHER.rst new file mode 100644 index 0000000..b76b939 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINKER_LAUNCHER.rst @@ -0,0 +1,11 @@ +CMAKE_<LANG>_LINKER_LAUNCHER +---------------------------- + +.. versionadded:: 3.21 + +Default value for :prop_tgt:`<LANG>_LINKER_LAUNCHER` target property. This +variable is used to initialize the property on each target as it is created. +This is done only when ``<LANG>`` is ``C``, ``CXX``, ``OBJC``, or ``OBJCXX``. + +This variable is initialized to the :envvar:`CMAKE_<LANG>_LINKER_LAUNCHER` +environment variable if it is set. diff --git a/Help/variable/CMAKE_LANG_LINKER_PREFERENCE.rst b/Help/variable/CMAKE_LANG_LINKER_PREFERENCE.rst index ff82f8b..a4035bd 100644 --- a/Help/variable/CMAKE_LANG_LINKER_PREFERENCE.rst +++ b/Help/variable/CMAKE_LANG_LINKER_PREFERENCE.rst @@ -1,6 +1,8 @@ CMAKE_<LANG>_LINKER_PREFERENCE ------------------------------ +An internal variable subject to change. + Preference value for linker language selection. The "linker language" for executable, shared library, and module diff --git a/Help/variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES.rst b/Help/variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES.rst index dbbeb0a..df33edb 100644 --- a/Help/variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES.rst +++ b/Help/variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES.rst @@ -1,6 +1,8 @@ CMAKE_<LANG>_LINKER_PREFERENCE_PROPAGATES ----------------------------------------- +An internal variable subject to change. + True if :variable:`CMAKE_<LANG>_LINKER_PREFERENCE` propagates across targets. This is used when CMake selects a linker language for a target. diff --git a/Help/variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG.rst b/Help/variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG.rst new file mode 100644 index 0000000..5004530 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG.rst @@ -0,0 +1,9 @@ +CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG +----------------------------------- + +.. versionadded:: 3.22 + +Linker flag to be used to configure linker so that all specified libraries on +the command line will be linked into the target. + +See also variable :variable:`CMAKE_LINK_WHAT_YOU_USE_CHECK`. diff --git a/Help/variable/CMAKE_LANG_SIMULATE_ID.rst b/Help/variable/CMAKE_LANG_SIMULATE_ID.rst index 15c87a1..3226352 100644 --- a/Help/variable/CMAKE_LANG_SIMULATE_ID.rst +++ b/Help/variable/CMAKE_LANG_SIMULATE_ID.rst @@ -1,9 +1,13 @@ CMAKE_<LANG>_SIMULATE_ID ------------------------ -Identification string of "simulated" compiler. +Identification string of the "simulated" compiler. Some compilers simulate other compilers to serve as drop-in replacements. When CMake detects such a compiler it sets this variable to what would have been the :variable:`CMAKE_<LANG>_COMPILER_ID` for the simulated compiler. + +.. note:: + In other words, this variable describes the ABI compatibility + of the generated code. diff --git a/Help/variable/CMAKE_LANG_STANDARD.rst b/Help/variable/CMAKE_LANG_STANDARD.rst new file mode 100644 index 0000000..0c41e19 --- /dev/null +++ b/Help/variable/CMAKE_LANG_STANDARD.rst @@ -0,0 +1,19 @@ +CMAKE_<LANG>_STANDARD +--------------------- + +The variations are: + +* :variable:`CMAKE_C_STANDARD` +* :variable:`CMAKE_CXX_STANDARD` +* :variable:`CMAKE_CUDA_STANDARD` +* :variable:`CMAKE_HIP_STANDARD` +* :variable:`CMAKE_OBJC_STANDARD` +* :variable:`CMAKE_OBJCXX_STANDARD` + +Default values for :prop_tgt:`<LANG>_STANDARD` target properties if set when a +target is created. + +For supported CMake versions see the respective pages. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_LANG_STANDARD_DEFAULT.rst b/Help/variable/CMAKE_LANG_STANDARD_DEFAULT.rst new file mode 100644 index 0000000..eb63d20 --- /dev/null +++ b/Help/variable/CMAKE_LANG_STANDARD_DEFAULT.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_STANDARD_DEFAULT +----------------------------- + +.. versionadded:: 3.9 + +The compiler's default standard for the language ``<LANG>``. Empty if the +compiler has no conception of standard levels. diff --git a/Help/variable/CMAKE_LANG_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_LANG_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..d7fa9b6 --- /dev/null +++ b/Help/variable/CMAKE_LANG_STANDARD_REQUIRED.rst @@ -0,0 +1,19 @@ +CMAKE_<LANG>_STANDARD_REQUIRED +------------------------------ + +The variations are: + +* :variable:`CMAKE_C_STANDARD_REQUIRED` +* :variable:`CMAKE_CXX_STANDARD_REQUIRED` +* :variable:`CMAKE_CUDA_STANDARD_REQUIRED` +* :variable:`CMAKE_HIP_STANDARD_REQUIRED` +* :variable:`CMAKE_OBJC_STANDARD_REQUIRED` +* :variable:`CMAKE_OBJCXX_STANDARD_REQUIRED` + +Default values for :prop_tgt:`<LANG>_STANDARD_REQUIRED` target properties if +set when a target is created. + +For supported CMake versions see the respective pages. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_LINK_LIBRARIES_ONLY_TARGETS.rst b/Help/variable/CMAKE_LINK_LIBRARIES_ONLY_TARGETS.rst new file mode 100644 index 0000000..513c3d0 --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARIES_ONLY_TARGETS.rst @@ -0,0 +1,10 @@ +CMAKE_LINK_LIBRARIES_ONLY_TARGETS +--------------------------------- + +.. versionadded:: 3.23 + +Set this variable to initialize the :prop_tgt:`LINK_LIBRARIES_ONLY_TARGETS` +property of non-imported targets when they are created. Setting it to true +enables an additional check that all items named by +:command:`target_link_libraries` that can be target names are actually names +of existing targets. See the target property documentation for details. diff --git a/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst b/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst index 06b3aa8..bca4519 100644 --- a/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst +++ b/Help/variable/CMAKE_LINK_WHAT_YOU_USE.rst @@ -1,5 +1,5 @@ CMAKE_LINK_WHAT_YOU_USE ---------------------------------- +----------------------- .. versionadded:: 3.7 diff --git a/Help/variable/CMAKE_LINK_WHAT_YOU_USE_CHECK.rst b/Help/variable/CMAKE_LINK_WHAT_YOU_USE_CHECK.rst new file mode 100644 index 0000000..e626641 --- /dev/null +++ b/Help/variable/CMAKE_LINK_WHAT_YOU_USE_CHECK.rst @@ -0,0 +1,10 @@ +CMAKE_LINK_WHAT_YOU_USE_CHECK +----------------------------- + +.. versionadded:: 3.22 + +Defines the command executed after the link step to check libraries usage. +This check is currently only defined on ``ELF`` platforms with value +``ldd -u -r``. + +See also :variable:`CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG` variables. diff --git a/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst b/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst index f466468..8d6b533 100644 --- a/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst +++ b/Help/variable/CMAKE_MINIMUM_REQUIRED_VERSION.rst @@ -2,4 +2,5 @@ CMAKE_MINIMUM_REQUIRED_VERSION ------------------------------ The ``<min>`` version of CMake given to the most recent call to the -:command:`cmake_minimum_required(VERSION)` command. +:command:`cmake_minimum_required(VERSION)` command in the current +variable scope or any parent variable scope. diff --git a/Help/variable/CMAKE_NETRC.rst b/Help/variable/CMAKE_NETRC.rst index 2c64a81..bddfca5 100644 --- a/Help/variable/CMAKE_NETRC.rst +++ b/Help/variable/CMAKE_NETRC.rst @@ -3,9 +3,11 @@ CMAKE_NETRC .. versionadded:: 3.11 -This variable is used to initialize the ``NETRC`` option for -:command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands and the -module :module:`ExternalProject`. See those commands for additional -information. +This variable is used to initialize the ``NETRC`` option for the +:command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands. +See those commands for additional information. + +This variable is also used by the :module:`ExternalProject` and +:module:`FetchContent` modules for internal calls to :command:`file(DOWNLOAD)`. The local option takes precedence over this variable. diff --git a/Help/variable/CMAKE_NETRC_FILE.rst b/Help/variable/CMAKE_NETRC_FILE.rst index 97a645e..af98170 100644 --- a/Help/variable/CMAKE_NETRC_FILE.rst +++ b/Help/variable/CMAKE_NETRC_FILE.rst @@ -3,9 +3,11 @@ CMAKE_NETRC_FILE .. versionadded:: 3.11 -This variable is used to initialize the ``NETRC_FILE`` option for -:command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands and the -module :module:`ExternalProject`. See those commands for additional -information. +This variable is used to initialize the ``NETRC_FILE`` option for the +:command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands. +See those commands for additional information. + +This variable is also used by the :module:`ExternalProject` and +:module:`FetchContent` modules for internal calls to :command:`file(DOWNLOAD)`. The local option takes precedence over this variable. diff --git a/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst b/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst index b5225ea..46736aa 100644 --- a/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst +++ b/Help/variable/CMAKE_OBJCXX_EXTENSIONS.rst @@ -3,11 +3,8 @@ CMAKE_OBJCXX_EXTENSIONS .. versionadded:: 3.16 -Default value for :prop_tgt:`OBJCXX_EXTENSIONS` property of targets. - -This variable is used to initialize the :prop_tgt:`OBJCXX_EXTENSIONS` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`OBJCXX_EXTENSIONS` target property if set when a +target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJCXX_STANDARD.rst b/Help/variable/CMAKE_OBJCXX_STANDARD.rst index 98e4624..0913382 100644 --- a/Help/variable/CMAKE_OBJCXX_STANDARD.rst +++ b/Help/variable/CMAKE_OBJCXX_STANDARD.rst @@ -3,11 +3,8 @@ CMAKE_OBJCXX_STANDARD .. versionadded:: 3.16 -Default value for :prop_tgt:`OBJCXX_STANDARD` property of targets. - -This variable is used to initialize the :prop_tgt:`OBJCXX_STANDARD` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`OBJCXX_STANDARD` target property if set when a +target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJCXX_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_OBJCXX_STANDARD_REQUIRED.rst index 4b5e77c..9afc4ea 100644 --- a/Help/variable/CMAKE_OBJCXX_STANDARD_REQUIRED.rst +++ b/Help/variable/CMAKE_OBJCXX_STANDARD_REQUIRED.rst @@ -3,11 +3,8 @@ CMAKE_OBJCXX_STANDARD_REQUIRED .. versionadded:: 3.16 -Default value for :prop_tgt:`OBJCXX_STANDARD_REQUIRED` property of targets. - -This variable is used to initialize the :prop_tgt:`OBJCXX_STANDARD_REQUIRED` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`OBJCXX_STANDARD_REQUIRED` target property if set +when a target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJC_EXTENSIONS.rst b/Help/variable/CMAKE_OBJC_EXTENSIONS.rst index d6e3c7d..9df11f1 100644 --- a/Help/variable/CMAKE_OBJC_EXTENSIONS.rst +++ b/Help/variable/CMAKE_OBJC_EXTENSIONS.rst @@ -3,11 +3,8 @@ CMAKE_OBJC_EXTENSIONS .. versionadded:: 3.16 -Default value for :prop_tgt:`OBJC_EXTENSIONS` property of targets. - -This variable is used to initialize the :prop_tgt:`OBJC_EXTENSIONS` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`OBJC_EXTENSIONS` target property if set when a +target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJC_STANDARD.rst b/Help/variable/CMAKE_OBJC_STANDARD.rst index fde367d..0b9b63f 100644 --- a/Help/variable/CMAKE_OBJC_STANDARD.rst +++ b/Help/variable/CMAKE_OBJC_STANDARD.rst @@ -3,11 +3,8 @@ CMAKE_OBJC_STANDARD .. versionadded:: 3.16 -Default value for :prop_tgt:`OBJC_STANDARD` property of targets. - -This variable is used to initialize the :prop_tgt:`OBJC_STANDARD` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`OBJC_STANDARD` target property if set when a +target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_OBJC_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_OBJC_STANDARD_REQUIRED.rst index 8d26d95..c74db55 100644 --- a/Help/variable/CMAKE_OBJC_STANDARD_REQUIRED.rst +++ b/Help/variable/CMAKE_OBJC_STANDARD_REQUIRED.rst @@ -3,11 +3,8 @@ CMAKE_OBJC_STANDARD_REQUIRED .. versionadded:: 3.16 -Default value for :prop_tgt:`OBJC_STANDARD_REQUIRED` property of targets. - -This variable is used to initialize the :prop_tgt:`OBJC_STANDARD_REQUIRED` -property on all targets. See that target property for additional -information. +Default value for :prop_tgt:`OBJC_STANDARD_REQUIRED` target property if set +when a target is created. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_PLATFORM_NO_VERSIONED_SONAME.rst b/Help/variable/CMAKE_PLATFORM_NO_VERSIONED_SONAME.rst new file mode 100644 index 0000000..bf15fc8 --- /dev/null +++ b/Help/variable/CMAKE_PLATFORM_NO_VERSIONED_SONAME.rst @@ -0,0 +1,14 @@ +CMAKE_PLATFORM_NO_VERSIONED_SONAME +---------------------------------- + +.. versionadded:: 3.1 + +This variable is used to globally control whether the +:prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` target +properties should be used for shared libraries. +When set to true, adding version information to each +shared library target is disabled. + +By default this variable is set only on platforms where +CMake knows it is needed. On other platforms, the +specified properties will be used for shared libraries. diff --git a/Help/variable/CMAKE_POLICY_DEFAULT_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_DEFAULT_CMPNNNN.rst index 43582be..d643fb8 100644 --- a/Help/variable/CMAKE_POLICY_DEFAULT_CMPNNNN.rst +++ b/Help/variable/CMAKE_POLICY_DEFAULT_CMPNNNN.rst @@ -9,9 +9,16 @@ the given version unset. Set ``CMAKE_POLICY_DEFAULT_CMP<NNNN>`` to ``OLD`` or ``NEW`` to specify the default for policy ``CMP<NNNN>``, where ``<NNNN>`` is the policy number. -This variable should not be set by a project in CMake code; use -:command:`cmake_policy(SET)` instead. Users running CMake may set this -variable in the cache (e.g. ``-DCMAKE_POLICY_DEFAULT_CMP<NNNN>=<OLD|NEW>``) -to set a policy not otherwise set by the project. Set to ``OLD`` to quiet a -policy warning while using old behavior or to ``NEW`` to try building the -project with new behavior. +This variable should not be set by a project in CMake code as a way to +set its own policies; use :command:`cmake_policy(SET)` instead. This +variable is meant to externally set policies for which a project has +not itself been updated: + +* Users running CMake may set this variable in the cache + (e.g. ``-DCMAKE_POLICY_DEFAULT_CMP<NNNN>=<OLD|NEW>``). Set it to ``OLD`` + to quiet a policy warning while using old behavior or to ``NEW`` to + try building the project with new behavior. + +* Projects may set this variable before a call to :command:`add_subdirectory` + that adds a third-party project in order to set its policies without + modifying third-party code. diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst index 9f68741..8c84f91 100644 --- a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -2,8 +2,9 @@ CMAKE_POLICY_WARNING_CMP<NNNN> ------------------------------ Explicitly enable or disable the warning when CMake Policy ``CMP<NNNN>`` -is not set. This is meaningful only for the few policies that do not -warn by default: +has not been set explicitly by :command:`cmake_policy` or implicitly +by :command:`cmake_minimum_required`. This is meaningful +only for the policies that do not warn by default: * ``CMAKE_POLICY_WARNING_CMP0025`` controls the warning for policy :policy:`CMP0025`. @@ -29,6 +30,12 @@ warn by default: policy :policy:`CMP0112`. * ``CMAKE_POLICY_WARNING_CMP0116`` controls the warning for policy :policy:`CMP0116`. +* ``CMAKE_POLICY_WARNING_CMP0126`` controls the warning for + policy :policy:`CMP0126`. +* ``CMAKE_POLICY_WARNING_CMP0128`` controls the warning for + policy :policy:`CMP0128`. +* ``CMAKE_POLICY_WARNING_CMP0129`` controls the warning for + policy :policy:`CMP0129`. This variable should not be set by a project in CMake code. Project developers running CMake may set this variable in their cache to diff --git a/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst b/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst new file mode 100644 index 0000000..893f1ae --- /dev/null +++ b/Help/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.rst @@ -0,0 +1,14 @@ +CMAKE_REQUIRE_FIND_PACKAGE_<PackageName> +---------------------------------------- + +.. versionadded:: 3.22 + +Variable for making :command:`find_package` call ``REQUIRED``. + +Every non-``REQUIRED`` :command:`find_package` call in a project can be +turned into ``REQUIRED`` by setting the variable +``CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>`` to ``TRUE``. +This can be used to assert assumptions about build environment and to +ensure the build will fail early if they do not hold. + +See also the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable. diff --git a/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst b/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst index 6afbd33..a6d8016 100644 --- a/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst @@ -1,18 +1,18 @@ CMAKE_SYSTEM_IGNORE_PATH ------------------------ -:ref:`Semicolon-separated list <CMake Language Lists>` of directories to be *ignored* by -the :command:`find_program`, :command:`find_library`, :command:`find_file`, -and :command:`find_path` commands. This is useful in cross-compiling -environments where some system directories contain incompatible but -possibly linkable libraries. For example, on cross-compiled cluster -environments, this allows a user to ignore directories containing -libraries meant for the front-end machine. +.. |CMAKE_IGNORE_VAR| replace:: ``CMAKE_SYSTEM_IGNORE_PATH`` +.. |CMAKE_IGNORE_PREFIX_VAR| replace:: :variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` +.. |CMAKE_IGNORE_NONSYSTEM_VAR| replace:: :variable:`CMAKE_IGNORE_PATH` -By default this contains a list of directories containing incompatible -binaries for the host system. See the :variable:`CMAKE_IGNORE_PATH` variable -that is intended to be set by the project. +.. include:: IGNORE_SEARCH_PATH.txt +.. include:: IGNORE_SEARCH_LOCATIONS.txt +.. include:: IGNORE_SEARCH_SYSTEM.txt -See also the :variable:`CMAKE_SYSTEM_PREFIX_PATH`, -:variable:`CMAKE_SYSTEM_LIBRARY_PATH`, :variable:`CMAKE_SYSTEM_INCLUDE_PATH`, -and :variable:`CMAKE_SYSTEM_PROGRAM_PATH` variables. +See also the following variables: + +- :variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` +- :variable:`CMAKE_SYSTEM_PREFIX_PATH` +- :variable:`CMAKE_SYSTEM_LIBRARY_PATH` +- :variable:`CMAKE_SYSTEM_INCLUDE_PATH` +- :variable:`CMAKE_SYSTEM_PROGRAM_PATH` diff --git a/Help/variable/CMAKE_SYSTEM_IGNORE_PREFIX_PATH.rst b/Help/variable/CMAKE_SYSTEM_IGNORE_PREFIX_PATH.rst new file mode 100644 index 0000000..48a2994 --- /dev/null +++ b/Help/variable/CMAKE_SYSTEM_IGNORE_PREFIX_PATH.rst @@ -0,0 +1,20 @@ +CMAKE_SYSTEM_IGNORE_PREFIX_PATH +------------------------------- + +.. versionadded:: 3.23 + +.. |CMAKE_IGNORE_VAR| replace:: ``CMAKE_SYSTEM_IGNORE_PREFIX_PATH`` +.. |CMAKE_IGNORE_NONPREFIX_VAR| replace:: :variable:`CMAKE_SYSTEM_IGNORE_PATH` +.. |CMAKE_IGNORE_NONSYSTEM_VAR| replace:: :variable:`CMAKE_IGNORE_PREFIX_PATH` + +.. include:: IGNORE_SEARCH_PREFIX.txt +.. include:: IGNORE_SEARCH_LOCATIONS.txt +.. include:: IGNORE_SEARCH_SYSTEM.txt + +See also the following variables: + +- :variable:`CMAKE_SYSTEM_IGNORE_PATH` +- :variable:`CMAKE_SYSTEM_PREFIX_PATH` +- :variable:`CMAKE_SYSTEM_LIBRARY_PATH` +- :variable:`CMAKE_SYSTEM_INCLUDE_PATH` +- :variable:`CMAKE_SYSTEM_PROGRAM_PATH` diff --git a/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst index 81a7a0b..c8b5815 100644 --- a/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst @@ -11,7 +11,8 @@ documentation. 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 :variable:`CMAKE_FIND_NO_INSTALL_PREFIX` variable before the +first :command:`project` invocation. The system directories that are contained in ``CMAKE_SYSTEM_PREFIX_PATH`` are locations that typically include installed software. An example being diff --git a/Help/variable/CMAKE_Swift_MODULE_DIRECTORY.rst b/Help/variable/CMAKE_Swift_MODULE_DIRECTORY.rst index 3694973..6036c04 100644 --- a/Help/variable/CMAKE_Swift_MODULE_DIRECTORY.rst +++ b/Help/variable/CMAKE_Swift_MODULE_DIRECTORY.rst @@ -5,6 +5,6 @@ CMAKE_Swift_MODULE_DIRECTORY Swift module output directory. -This variable is used to initialise the :prop_tgt:`Swift_MODULE_DIRECTORY` +This variable is used to initialize the :prop_tgt:`Swift_MODULE_DIRECTORY` property on all the targets. See the target property for additional information. diff --git a/Help/variable/CMAKE_TLS_CAINFO.rst b/Help/variable/CMAKE_TLS_CAINFO.rst new file mode 100644 index 0000000..07f6366 --- /dev/null +++ b/Help/variable/CMAKE_TLS_CAINFO.rst @@ -0,0 +1,9 @@ +CMAKE_TLS_CAINFO +---------------- + +Specify the default value for the :command:`file(DOWNLOAD)` and +:command:`file(UPLOAD)` commands' ``TLS_CAINFO`` options. +It is unset by default. + +This variable is also used by the :module:`ExternalProject` and +:module:`FetchContent` modules for internal calls to :command:`file(DOWNLOAD)`. diff --git a/Help/variable/CMAKE_TLS_VERIFY.rst b/Help/variable/CMAKE_TLS_VERIFY.rst new file mode 100644 index 0000000..b22f1ce --- /dev/null +++ b/Help/variable/CMAKE_TLS_VERIFY.rst @@ -0,0 +1,17 @@ +CMAKE_TLS_VERIFY +---------------- + +Specify the default value for the :command:`file(DOWNLOAD)` and +:command:`file(UPLOAD)` commands' ``TLS_VERIFY`` options. +If not set, the default is *off*. + +This variable is also used by the :module:`ExternalProject` and +:module:`FetchContent` modules for internal calls to :command:`file(DOWNLOAD)`. + +TLS verification can help provide confidence that one is connecting +to the desired server. When downloading known content, one should +also use file hashes to verify it. + +.. code-block:: cmake + + set(CMAKE_TLS_VERIFY TRUE) diff --git a/Help/variable/CMAKE_TOOLCHAIN_FILE.rst b/Help/variable/CMAKE_TOOLCHAIN_FILE.rst index 168ee74..ff8d59a 100644 --- a/Help/variable/CMAKE_TOOLCHAIN_FILE.rst +++ b/Help/variable/CMAKE_TOOLCHAIN_FILE.rst @@ -7,3 +7,9 @@ This variable is specified on the command line when cross-compiling with CMake. It is the path to a file which is read early in the CMake run and which specifies locations for compilers and toolchain utilities, and other target platform and compiler related information. + +Relative paths are allowed and are interpreted first as relative to the +build directory, and if not found, relative to the source directory. + +This is initialized by the :envvar:`CMAKE_TOOLCHAIN_FILE` environment +variable if it is set when a new build tree is first created. diff --git a/Help/variable/CMAKE_VS_NUGET_PACKAGE_RESTORE.rst b/Help/variable/CMAKE_VS_NUGET_PACKAGE_RESTORE.rst new file mode 100644 index 0000000..7160726 --- /dev/null +++ b/Help/variable/CMAKE_VS_NUGET_PACKAGE_RESTORE.rst @@ -0,0 +1,22 @@ +CMAKE_VS_NUGET_PACKAGE_RESTORE +------------------------------ + +.. versionadded:: 3.23 + +When using a Visual Studio generator, this cache variable controls +if msbuild should automatically attempt to restore NuGet packages +prior to a build. NuGet packages can be defined using the +:prop_tgt:`VS_PACKAGE_REFERENCES` property on a target. If no +package references are defined, this setting will do nothing. + +The command line option ``--resolve-package-references`` can be used +alternatively to control the resolve behavior globally. This option +will take precedence over the cache variable. + +Targets that use the :prop_tgt:`DOTNET_SDK` are required to run a +restore before building. Disabling this option may cause the build +to fail in such projects. + +This setting is stored as a cache entry. Default value is ``ON``. + +See also the :prop_tgt:`VS_PACKAGE_REFERENCES` property. diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR.rst index 74db6b1..a19e7e1 100644 --- a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR.rst +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR.rst @@ -9,10 +9,9 @@ The :ref:`Visual Studio Generators` for VS 2010 and above support using a standalone (non-installed) NVIDIA CUDA toolkit. The path may be specified by a field in :variable:`CMAKE_GENERATOR_TOOLSET` of the form ``cuda=C:\path\to\cuda``. The given directory must at least -contain a folder ``.\nvcc`` and must provide Visual Studio integration -files in path ``.\CUDAVisualStudioIntegration\extras\ -visual_studio_integration\MSBuildExtensions\``. One can create a standalone -CUDA toolkit directory by either opening a installer with 7zip or -copying the files that are extracted by the running installer. -The value may be empty if no path to a standalone CUDA Toolkit was -specified. +contain the nvcc compiler in path ``.\bin`` and must provide Visual Studio +integration files in path ``.\extras\visual_studio_integration\ +MSBuildExtensions\``. One can create a standalone CUDA toolkit directory by +either opening a installer with 7zip or copying the files that are extracted +by the running installer. The value may be empty if no path to a standalone +CUDA Toolkit was specified. diff --git a/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER.rst b/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER.rst new file mode 100644 index 0000000..5ad5897 --- /dev/null +++ b/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER.rst @@ -0,0 +1,13 @@ +CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER +------------------------------------ + +.. versionadded:: 3.22 + +Visual Studio target framework identifier. + +In some cases, the :ref:`Visual Studio Generators` may use an explicit value +for the MSBuild ``TargetFrameworkIdentifier`` setting in ``.csproj`` files. +CMake provides the chosen value in this variable. + +See also :variable:`CMAKE_VS_TARGET_FRAMEWORK_VERSION` and +:variable:`CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION`. diff --git a/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION.rst b/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION.rst new file mode 100644 index 0000000..8dcb3a7 --- /dev/null +++ b/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION.rst @@ -0,0 +1,13 @@ +CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION +----------------------------------------- + +.. versionadded:: 3.22 + +Visual Studio target framework targets version. + +In some cases, the :ref:`Visual Studio Generators` may use an explicit value +for the MSBuild ``TargetFrameworkTargetsVersion`` setting in ``.csproj`` files. +CMake provides the chosen value in this variable. + +See also :variable:`CMAKE_VS_TARGET_FRAMEWORK_VERSION` and +:variable:`CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER`. diff --git a/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_VERSION.rst b/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_VERSION.rst new file mode 100644 index 0000000..5489f79 --- /dev/null +++ b/Help/variable/CMAKE_VS_TARGET_FRAMEWORK_VERSION.rst @@ -0,0 +1,17 @@ +CMAKE_VS_TARGET_FRAMEWORK_VERSION +--------------------------------- + +.. versionadded:: 3.22 + +Visual Studio target framework version. + +In some cases, the :ref:`Visual Studio Generators` may use an explicit value +for the MSBuild ``TargetFrameworkVersion`` setting in ``.csproj`` files. +CMake provides the chosen value in this variable. + +See the :variable:`CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION` variable +and :prop_tgt:`DOTNET_TARGET_FRAMEWORK_VERSION` target property to +specify custom ``TargetFrameworkVersion`` values for project targets. + +See also :variable:`CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER` and +:variable:`CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION`. diff --git a/Help/variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE.rst b/Help/variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE.rst new file mode 100644 index 0000000..3a3c847 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE.rst @@ -0,0 +1,15 @@ +CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE +------------------------------------------------ + +.. versionadded:: 3.23 + +Property value for ``GPU Frame Capture`` in the Options section of +the generated Xcode scheme. Example values are `Metal` and +`Disabled`. + +This variable initializes the +:prop_tgt:`XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE` +property on all targets. + +Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property +documentation to see all Xcode schema related properties. diff --git a/Help/variable/CPACK_CUSTOM_INSTALL_VARIABLES.rst b/Help/variable/CPACK_CUSTOM_INSTALL_VARIABLES.rst new file mode 100644 index 0000000..1c070b8 --- /dev/null +++ b/Help/variable/CPACK_CUSTOM_INSTALL_VARIABLES.rst @@ -0,0 +1,44 @@ +CPACK_CUSTOM_INSTALL_VARIABLES +------------------------------ + +.. versionadded:: 3.21 + +CPack variables (set via e.g. ``cpack -D``, ``CPackConfig.cmake`` or +:variable:`CPACK_PROJECT_CONFIG_FILE` scripts) are not directly visible in +installation scripts. Instead, one can pass a list of ``varName=value`` +pairs in the ``CPACK_CUSTOM_INSTALL_VARIABLES`` variable. At install time, +each list item will result in a variable of the specified name (``varName``) +being set to the given ``value``. The ``=`` can be omitted for an empty +``value``. + +``CPACK_CUSTOM_INSTALL_VARIABLES`` allows the packaging installation to be +influenced by the user or driving script at CPack runtime without having to +regenerate the install scripts. + +Example +""""""" + +.. code-block:: cmake + + install(FILES large.txt DESTINATION data) + + install(CODE [[ + if(ENABLE_COMPRESSION) + # "run-compressor" is a fictional tool that produces + # large.txt.xz from large.txt and then removes the input file + execute_process(COMMAND run-compressor $ENV{DESTDIR}${CMAKE_INSTALL_PREFIX}/large.txt) + endif() + ]]) + +With the above example snippet, :manual:`cpack <cpack(1)>` will by default +run the installation script with ``ENABLE_COMPRESSION`` unset, resulting in +a package containing the uncompressed ``large.txt``. This can be overridden +when invoking :manual:`cpack <cpack(1)>` like so: + +.. code-block:: shell + + cpack -D "CPACK_CUSTOM_INSTALL_VARIABLES=ENABLE_COMPRESSION=TRUE" + +The installation script will then run with ``ENABLE_COMPRESSION`` set to +``TRUE``, resulting in a package containing the compressed ``large.txt.xz`` +instead. diff --git a/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst b/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst index 5aeae88..7e7d431 100644 --- a/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst +++ b/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst @@ -5,4 +5,10 @@ When saving a failing test's output, this is the maximum size, in bytes, that will be collected by the :command:`ctest_test` command. Defaults to 307200 (300 KiB). +If a test's output contains the literal string "CTEST_FULL_OUTPUT", +the output will not be truncated and may exceed the maximum size. + .. include:: CTEST_CUSTOM_XXX.txt + +For controlling the output collection of passing tests, see +:variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE`. diff --git a/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst b/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst index 1fbb8c5..64367f9 100644 --- a/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst +++ b/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst @@ -5,4 +5,10 @@ When saving a passing test's output, this is the maximum size, in bytes, that will be collected by the :command:`ctest_test` command. Defaults to 1024 (1 KiB). +If a test's output contains the literal string "CTEST_FULL_OUTPUT", +the output will not be truncated and may exceed the maximum size. + .. include:: CTEST_CUSTOM_XXX.txt + +For controlling the output collection of failing tests, see +:variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE`. diff --git a/Help/variable/CTEST_CUSTOM_TESTS_IGNORE.rst b/Help/variable/CTEST_CUSTOM_TESTS_IGNORE.rst index 57222ca..7b1a4b8 100644 --- a/Help/variable/CTEST_CUSTOM_TESTS_IGNORE.rst +++ b/Help/variable/CTEST_CUSTOM_TESTS_IGNORE.rst @@ -1,7 +1,7 @@ CTEST_CUSTOM_TESTS_IGNORE ------------------------- -A list of regular expressions to use to exclude tests during the +A list of test names to be excluded from the set of tests run by the :command:`ctest_test` command. .. include:: CTEST_CUSTOM_XXX.txt diff --git a/Help/variable/CTEST_SCRIPT_DIRECTORY.rst b/Help/variable/CTEST_SCRIPT_DIRECTORY.rst new file mode 100644 index 0000000..77d4e58 --- /dev/null +++ b/Help/variable/CTEST_SCRIPT_DIRECTORY.rst @@ -0,0 +1,5 @@ +CTEST_SCRIPT_DIRECTORY +---------------------- + +The directory containing the top-level CTest script. +The concept is similar to :variable:`CMAKE_SOURCE_DIR`. diff --git a/Help/variable/CTEST_SUBMIT_INACTIVITY_TIMEOUT.rst b/Help/variable/CTEST_SUBMIT_INACTIVITY_TIMEOUT.rst new file mode 100644 index 0000000..175885a --- /dev/null +++ b/Help/variable/CTEST_SUBMIT_INACTIVITY_TIMEOUT.rst @@ -0,0 +1,7 @@ +CTEST_SUBMIT_INACTIVITY_TIMEOUT +------------------------------- + +.. versionadded:: 3.23 + +Specify the CTest ``SubmitInactivityTimeout`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/EXECUTABLE_OUTPUT_PATH.rst b/Help/variable/EXECUTABLE_OUTPUT_PATH.rst index 26d3e92..245b9eb 100644 --- a/Help/variable/EXECUTABLE_OUTPUT_PATH.rst +++ b/Help/variable/EXECUTABLE_OUTPUT_PATH.rst @@ -3,6 +3,6 @@ EXECUTABLE_OUTPUT_PATH Old executable location variable. -The target property :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` supercedes this +The target property :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` supersedes this variable for a target if it is set. Executable targets are otherwise placed in this directory. diff --git a/Help/variable/GHS-MULTI.rst b/Help/variable/GHS-MULTI.rst deleted file mode 100644 index bb139af..0000000 --- a/Help/variable/GHS-MULTI.rst +++ /dev/null @@ -1,6 +0,0 @@ -GHS-MULTI ---------- - -.. versionadded:: 3.3 - -``True`` when using :generator:`Green Hills MULTI` generator. diff --git a/Help/variable/GHSMULTI.rst b/Help/variable/GHSMULTI.rst new file mode 100644 index 0000000..3daef5d --- /dev/null +++ b/Help/variable/GHSMULTI.rst @@ -0,0 +1,9 @@ +GHSMULTI +-------- + +.. versionadded:: 3.3 + +``1`` when using :generator:`Green Hills MULTI` generator. + +Also, Set to ``1`` when the target system is a Green Hills platform +(i.e. When CMAKE_SYSTEM_NAME is ``GHS-MULTI``). diff --git a/Help/variable/IGNORE_SEARCH_LOCATIONS.txt b/Help/variable/IGNORE_SEARCH_LOCATIONS.txt new file mode 100644 index 0000000..a98f359 --- /dev/null +++ b/Help/variable/IGNORE_SEARCH_LOCATIONS.txt @@ -0,0 +1,4 @@ +Ignoring search locations can be useful in cross-compiling environments where +some system directories contain incompatible but possibly linkable libraries. +For example, on cross-compiled cluster environments, this allows a user to +ignore directories containing libraries meant for the front-end machine. diff --git a/Help/variable/IGNORE_SEARCH_NONSYSTEM.txt b/Help/variable/IGNORE_SEARCH_NONSYSTEM.txt new file mode 100644 index 0000000..a32a189 --- /dev/null +++ b/Help/variable/IGNORE_SEARCH_NONSYSTEM.txt @@ -0,0 +1,2 @@ +By default, |CMAKE_IGNORE_VAR| is empty. It is intended to be set by the +project or the end user. diff --git a/Help/variable/IGNORE_SEARCH_PATH.txt b/Help/variable/IGNORE_SEARCH_PATH.txt new file mode 100644 index 0000000..0811e02 --- /dev/null +++ b/Help/variable/IGNORE_SEARCH_PATH.txt @@ -0,0 +1,19 @@ +:ref:`Semicolon-separated list <CMake Language Lists>` of directories +to be ignored by the various ``find...()`` commands. + +For :command:`find_program`, :command:`find_library`, :command:`find_file`, +and :command:`find_path`, any file found in one of the listed directories +will be ignored. The listed directories do not apply recursively, so any +subdirectories to be ignored must also be explicitly listed. +|CMAKE_IGNORE_VAR| does not affect the search *prefixes* used by these +four commands. To ignore individual paths under a search prefix +(e.g. ``bin``, ``include``, ``lib``, etc.), each path must be listed in +|CMAKE_IGNORE_VAR| as a full absolute path. |CMAKE_IGNORE_PREFIX_VAR| +provides a more appropriate way to ignore a whole search prefix. + +:command:`find_package` is also affected by |CMAKE_IGNORE_VAR|, but only +for *Config mode* searches. Any ``<Name>Config.cmake`` or +``<name>-config.cmake`` file found in one of the specified directories +will be ignored. In addition, any search *prefix* found in |CMAKE_IGNORE_VAR| +will be skipped for backward compatibility reasons, but new code should +prefer to use |CMAKE_IGNORE_PREFIX_VAR| to ignore prefixes instead. diff --git a/Help/variable/IGNORE_SEARCH_PREFIX.txt b/Help/variable/IGNORE_SEARCH_PREFIX.txt new file mode 100644 index 0000000..f5ec3dc --- /dev/null +++ b/Help/variable/IGNORE_SEARCH_PREFIX.txt @@ -0,0 +1,6 @@ +:ref:`Semicolon-separated list <CMake Language Lists>` of search *prefixes* +to be ignored by the :command:`find_program`, :command:`find_library`, +:command:`find_file`, and :command:`find_path` commands. +The prefixes are also ignored by the *Config mode* of the +:command:`find_package` command (*Module mode* is unaffected). +To ignore specific directories instead, see |CMAKE_IGNORE_NONPREFIX_VAR|. diff --git a/Help/variable/IGNORE_SEARCH_SYSTEM.txt b/Help/variable/IGNORE_SEARCH_SYSTEM.txt new file mode 100644 index 0000000..78b285d6 --- /dev/null +++ b/Help/variable/IGNORE_SEARCH_SYSTEM.txt @@ -0,0 +1,5 @@ +|CMAKE_IGNORE_VAR| is populated by CMake as part of its platform +and toolchain setup. Its purpose is to ignore locations containing +incompatible binaries meant for the host rather than the target platform. +The project or end user should not modify this variable, they should use +|CMAKE_IGNORE_NONSYSTEM_VAR| instead. diff --git a/Help/variable/MSVC_TOOLSET_VERSION.rst b/Help/variable/MSVC_TOOLSET_VERSION.rst index c642a9f..59479af 100644 --- a/Help/variable/MSVC_TOOLSET_VERSION.rst +++ b/Help/variable/MSVC_TOOLSET_VERSION.rst @@ -17,6 +17,7 @@ Known toolset version numbers are:: 140 = VS 2015 (14.0) 141 = VS 2017 (15.0) 142 = VS 2019 (16.0) + 143 = VS 2022 (17.0) Compiler versions newer than those known to CMake will be reported as the latest known toolset version. diff --git a/Help/variable/MSVC_VERSION.rst b/Help/variable/MSVC_VERSION.rst index 45df37f..cbb3a3c 100644 --- a/Help/variable/MSVC_VERSION.rst +++ b/Help/variable/MSVC_VERSION.rst @@ -19,6 +19,7 @@ Known version numbers are:: 1900 = VS 14.0 (v140 toolset) 1910-1919 = VS 15.0 (v141 toolset) 1920-1929 = VS 16.0 (v142 toolset) + 1930-1939 = VS 17.0 (v143 toolset) See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` and :variable:`MSVC_TOOLSET_VERSION` variable. diff --git a/Help/variable/PROJECT-NAME_IS_TOP_LEVEL.rst b/Help/variable/PROJECT-NAME_IS_TOP_LEVEL.rst new file mode 100644 index 0000000..6718ecf --- /dev/null +++ b/Help/variable/PROJECT-NAME_IS_TOP_LEVEL.rst @@ -0,0 +1,21 @@ +<PROJECT-NAME>_IS_TOP_LEVEL +--------------------------- + +.. versionadded:: 3.21 + +A boolean variable indicating whether the named project was called in a top +level ``CMakeLists.txt`` file. + +To obtain the value from the most recent call to :command:`project` in +the current directory scope or above, see the +:variable:`PROJECT_IS_TOP_LEVEL` variable. + +The variable value will be true in: + +* the top-level directory of the project +* the top-level directory of an external project added by :module:`ExternalProject` + +The variable value will be false in: + +* a directory added by :command:`add_subdirectory` +* a directory added by :module:`FetchContent` diff --git a/Help/variable/PROJECT_IS_TOP_LEVEL.rst b/Help/variable/PROJECT_IS_TOP_LEVEL.rst new file mode 100644 index 0000000..7e40704 --- /dev/null +++ b/Help/variable/PROJECT_IS_TOP_LEVEL.rst @@ -0,0 +1,32 @@ +PROJECT_IS_TOP_LEVEL +-------------------- + +.. versionadded:: 3.21 + +A boolean variable indicating whether the most recently called +:command:`project` command in the current scope or above was in the top +level ``CMakeLists.txt`` file. + +Some modules should only be included as part of the top level +``CMakeLists.txt`` file to not cause unintended side effects in the build +tree, and this variable can be used to conditionally execute such code. For +example, consider the :module:`CTest` module, which creates targets and +options: + +.. code-block:: cmake + + project(MyProject) + ... + if(PROJECT_IS_TOP_LEVEL) + include(CTest) + endif() + +The variable value will be true in: + +* the top-level directory of the project +* the top-level directory of an external project added by :module:`ExternalProject` + +The variable value will be false in: + +* a directory added by :command:`add_subdirectory` +* a directory added by :module:`FetchContent` |