diff options
Diffstat (limited to 'Help')
129 files changed, 2536 insertions, 472 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 5b63e1c..ee6c1cc 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -170,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/add_custom_command.rst b/Help/command/add_custom_command.rst index b45a079..ec73f9f 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -271,9 +271,47 @@ The options are: ``DEPFILE`` .. versionadded:: 3.7 - Specify a ``.d`` 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. + 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 diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index 1235155..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, 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/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/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/find_package.rst b/Help/command/find_package.rst index 1a79a8a..5acefad 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -363,6 +363,11 @@ 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>`` variables to globally disable various search locations. diff --git a/Help/command/if.rst b/Help/command/if.rst index 5dba13e..4f955db 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -38,21 +38,29 @@ 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 @@ -126,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. diff --git a/Help/command/install.rst b/Help/command/install.rst index 1236f1d..1a9dfd7 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -132,7 +132,7 @@ Installing Targets 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|...]] @@ -204,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 @@ -214,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 @@ -246,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 @@ -338,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 @@ -478,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... @@ -534,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 @@ -547,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 @@ -572,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... @@ -623,10 +656,10 @@ 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 as described under :ref:`string(REGEX) <Regex Specification>` and are applied @@ -795,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 diff --git a/Help/command/list.rst b/Help/command/list.rst index 9b49cb4..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: @@ -150,7 +152,12 @@ For more information on regular expressions look under 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: @@ -186,7 +193,9 @@ to the given variables and then remove the first `N` values from .. 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/set_property.rst b/Help/command/set_property.rst index 555520d..b9b12c4 100644 --- a/Help/command/set_property.rst +++ b/Help/command/set_property.rst @@ -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/string.rst b/Help/command/string.rst index 29ad082..b1ca2cb 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -490,6 +490,9 @@ specifiers: ``%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). @@ -609,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_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/dmg.rst b/Help/cpack_gen/dmg.rst index 1f05618..b4ef5a2 100644 --- a/Help/cpack_gen/dmg.rst +++ b/Help/cpack_gen/dmg.rst @@ -54,6 +54,27 @@ on macOS: 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 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/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/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 4a2a5d9..db92022 100644 --- a/Help/dev/documentation.rst +++ b/Help/dev/documentation.rst @@ -513,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: :: @@ -540,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() @@ -559,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/maint.rst b/Help/dev/maint.rst index 4c2b6a1..53be91f 100644 --- a/Help/dev/maint.rst +++ b/Help/dev/maint.rst @@ -256,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 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 cf65927..74f5d48 100644 --- a/Help/envvar/CUDAHOSTCXX.rst +++ b/Help/envvar/CUDAHOSTCXX.rst @@ -8,9 +8,8 @@ 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. 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/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/Visual Studio 15 2017.rst b/Help/generator/Visual Studio 15 2017.rst index b4d6f6d..912afad 100644 --- a/Help/generator/Visual Studio 15 2017.rst +++ b/Help/generator/Visual Studio 15 2017.rst @@ -17,18 +17,8 @@ Instance Selection .. versionadded:: 3.11 -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. - -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 ^^^^^^^^^^^^^^^^^^ diff --git a/Help/generator/Visual Studio 16 2019.rst b/Help/generator/Visual Studio 16 2019.rst index 72399e0..6cefe6d 100644 --- a/Help/generator/Visual Studio 16 2019.rst +++ b/Help/generator/Visual Studio 16 2019.rst @@ -15,18 +15,8 @@ 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 index b3f49f3..edf9d60 100644 --- a/Help/generator/Visual Studio 17 2022.rst +++ b/Help/generator/Visual Studio 17 2022.rst @@ -15,18 +15,8 @@ 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 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 ``VS170COMNTOOLS`` 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 2022 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/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/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/tutorial/Adding System Introspection.rst b/Help/guide/tutorial/Adding System Introspection.rst index e149110..8db0cb8 100644 --- a/Help/guide/tutorial/Adding System Introspection.rst +++ b/Help/guide/tutorial/Adding System Introspection.rst @@ -9,17 +9,15 @@ 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. +these functions using the :module:`CheckCXXSourceCompiles` module in +``MathFunctions/CMakeLists.txt``. 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 + :name: MathFunctions/CMakeLists.txt-check_cxx_source_compiles :language: cmake :start-after: # to find MathFunctions.h, while we don't. :end-before: # add compile definitions diff --git a/Help/guide/tutorial/Adding a Library.rst b/Help/guide/tutorial/Adding a Library.rst index ed03448..71755be 100644 --- a/Help/guide/tutorial/Adding a Library.rst +++ b/Help/guide/tutorial/Adding a Library.rst @@ -23,8 +23,9 @@ directory: 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: +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 diff --git a/Help/guide/tutorial/Complete/CMakeLists.txt b/Help/guide/tutorial/Complete/CMakeLists.txt index ac1d083..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>>" @@ -88,6 +88,7 @@ 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/Packaging an Installer.rst b/Help/guide/tutorial/Packaging an Installer.rst index 5eb3e3e..0ee5db2 100644 --- a/Help/guide/tutorial/Packaging an Installer.rst +++ b/Help/guide/tutorial/Packaging an Installer.rst @@ -22,8 +22,9 @@ That is all there is to it. We start by including 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. +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 @@ -44,7 +45,11 @@ To specify the generator, use the ``-G`` option. For multi-config builds, use cpack -G ZIP -C Debug -To create a source distribution you would type: +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 diff --git a/Help/guide/tutorial/Step10/CMakeLists.txt b/Help/guide/tutorial/Step10/CMakeLists.txt index dc9a0e8..55dc409 100644 --- a/Help/guide/tutorial/Step10/CMakeLists.txt +++ b/Help/guide/tutorial/Step10/CMakeLists.txt @@ -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/Step11/CMakeLists.txt b/Help/guide/tutorial/Step11/CMakeLists.txt index 10f35ce..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>>" @@ -78,4 +78,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/Step12/CMakeLists.txt b/Help/guide/tutorial/Step12/CMakeLists.txt index 634b84c..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>>" 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/Step6/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt index f64c6ac..42e098a 100644 --- a/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt @@ -7,19 +7,21 @@ target_include_directories(MathFunctions ) # does this system provide the log and exp functions? -include(CheckSymbolExists) -check_symbol_exists(log "math.h" HAVE_LOG) -check_symbol_exists(exp "math.h" HAVE_EXP) -if(NOT (HAVE_LOG AND HAVE_EXP)) - unset(HAVE_LOG CACHE) - unset(HAVE_EXP CACHE) - set(CMAKE_REQUIRED_LIBRARIES "m") - check_symbol_exists(log "math.h" HAVE_LOG) - check_symbol_exists(exp "math.h" HAVE_EXP) - if(HAVE_LOG AND HAVE_EXP) - target_link_libraries(MathFunctions PRIVATE m) - endif() -endif() +include(CheckCXXSourceCompiles) +check_cxx_source_compiles(" + #include <cmath> + int main() { + std::log(1.0); + return 0; + } +" HAVE_LOG) +check_cxx_source_compiles(" + #include <cmath> + int main() { + std::exp(1.0); + return 0; + } +" HAVE_EXP) # add compile definitions if(HAVE_LOG AND HAVE_EXP) diff --git a/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx index 0637063..7eecd26 100644 --- a/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx @@ -12,7 +12,7 @@ double mysqrt(double x) // if we have both log and exp then use them #if defined(HAVE_LOG) && defined(HAVE_EXP) - double result = exp(log(x) * 0.5); + double result = std::exp(std::log(x) * 0.5); std::cout << "Computing sqrt of " << x << " to be " << result << " using log and exp" << std::endl; #else diff --git a/Help/guide/tutorial/Step8/CMakeLists.txt b/Help/guide/tutorial/Step8/CMakeLists.txt index 4ae898f..4c78b94 100644 --- a/Help/guide/tutorial/Step8/CMakeLists.txt +++ b/Help/guide/tutorial/Step8/CMakeLists.txt @@ -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/Step9/CMakeLists.txt b/Help/guide/tutorial/Step9/CMakeLists.txt index 130bc9a..6bae26e 100644 --- a/Help/guide/tutorial/Step9/CMakeLists.txt +++ b/Help/guide/tutorial/Step9/CMakeLists.txt @@ -69,4 +69,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/index.rst b/Help/guide/tutorial/index.rst index 8b20a2d..09553cb 100644 --- a/Help/guide/tutorial/index.rst +++ b/Help/guide/tutorial/index.rst @@ -11,8 +11,9 @@ work together in an example project can be very helpful. Steps ===== -The tutorial documentation and source code for examples can be found in -the ``Help/guide/tutorial`` directory of the CMake source code tree. +.. 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. 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/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 2f43070..f48313a 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -675,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. diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index 67b0f6e..8073511 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -115,6 +115,8 @@ 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 ----------------------------------- diff --git a/Help/manual/cmake-file-api.7.rst b/Help/manual/cmake-file-api.7.rst index 5e22ea9..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" @@ -758,6 +758,15 @@ with members: ``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. @@ -835,6 +844,41 @@ with members: 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, diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index df13dd0..a6d2a05 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -197,6 +197,8 @@ Variable Queries .. 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``. @@ -249,6 +251,8 @@ Variable Queries .. 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. @@ -714,6 +718,8 @@ Variable Queries .. 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. @@ -760,6 +766,8 @@ Variable Queries .. genex:: $<HIP_COMPILER_VERSION> + .. versionadded:: 3.21 + The version of the HIP compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. @@ -1057,10 +1065,10 @@ which is just the string ``tgt``. .. versionadded:: 3.21 List of DLLs that the target depends on at runtime. This is determined by - the locations of all the ``SHARED`` and ``MODULE`` 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. + 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 @@ -1080,9 +1088,9 @@ which is just the string ``tgt``. .. note:: :ref:`Imported Targets` are supported only if they know the location - of their ``.dll`` files. An imported ``SHARED`` or ``MODULE`` library - must have :prop_tgt:`IMPORTED_LOCATION` set to its ``.dll`` file. See - the :ref:`add_library imported libraries <add_library imported libraries>` + 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. diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index 663b18d..034e218 100644 --- a/Help/manual/cmake-generators.7.rst +++ b/Help/manual/cmake-generators.7.rst @@ -102,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-packages.7.rst b/Help/manual/cmake-packages.7.rst index 5c109ff..ed85dc4 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -446,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 3df4f9f..0939a82 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,15 @@ 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 ================================= diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst index 74e9fae..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``, ``2``, and ``3``. + 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 @@ -82,6 +92,26 @@ The root object recognizes the following fields: An optional array of `Test Preset`_ objects. 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,20 @@ 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`` @@ -350,17 +384,21 @@ 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`` @@ -453,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 @@ -487,17 +561,21 @@ 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`` @@ -947,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}`` @@ -974,6 +1053,11 @@ Recognized macros include: :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 bb5dba3..ddb917a 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -191,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 @@ -214,6 +215,11 @@ 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 @@ -239,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 @@ -254,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 @@ -297,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 @@ -425,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 diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 4ed0b2e..4df0237 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -49,6 +49,7 @@ 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 @@ -118,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 @@ -210,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 @@ -220,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 @@ -247,6 +251,7 @@ 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 @@ -262,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 @@ -307,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 @@ -466,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 @@ -578,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 @@ -668,6 +673,7 @@ Variables for CTest /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 @@ -723,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 e23ddd8..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. @@ -449,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. @@ -547,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: @@ -607,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>...]`` @@ -615,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). @@ -625,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. @@ -637,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:: @@ -657,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>...`` @@ -670,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:: @@ -677,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 @@ -723,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 @@ -743,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>...]`` @@ -751,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. @@ -799,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 @@ -810,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 d66c5a9..1e7b077 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -1353,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. diff --git a/Help/manual/presets/example.json b/Help/manual/presets/example.json index b08445a..873c4ad 100644 --- a/Help/manual/presets/example.json +++ b/Help/manual/presets/example.json @@ -1,10 +1,14 @@ { - "version": 3, + "version": 4, "cmakeMinimumRequired": { "major": 3, - "minor": 21, + "minor": 23, "patch": 0 }, + "include": [ + "otherThings.json", + "moreThings.json" + ], "configurePresets": [ { "name": "default", diff --git a/Help/manual/presets/schema.json b/Help/manual/presets/schema.json index 7852550..12f8b5e 100644 --- a/Help/manual/presets/schema.json +++ b/Help/manual/presets/schema.json @@ -42,6 +42,21 @@ "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 } ], "required": [ @@ -412,9 +427,25 @@ "additionalProperties": false } }, + "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 2 and higher.", + "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": { @@ -543,9 +574,44 @@ ] } }, + "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 2 and higher.", + "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" } @@ -609,7 +675,7 @@ }, "testPresetsItemsV3": { "type": "array", - "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 3 and higher.", "items": { "type": "object", "properties": { @@ -934,7 +1000,7 @@ }, "testPresetsV3": { "type": "array", - "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.", + "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" } @@ -1235,6 +1301,13 @@ "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/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/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/CMP0126.rst b/Help/policy/CMP0126.rst index 1b69957..a389512 100644 --- a/Help/policy/CMP0126.rst +++ b/Help/policy/CMP0126.rst @@ -14,6 +14,9 @@ current scope in the following situations: 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, 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_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst index 3a17973..d93a9c1 100644 --- a/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst @@ -35,3 +35,5 @@ The features known to this version of CMake are: .. 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 1a913fb..6846850 100644 --- a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst @@ -46,6 +46,8 @@ but it does not necessarily imply complete conformance to that standard. 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 97da697..7aca9e8 100644 --- a/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst @@ -39,6 +39,8 @@ High level meta features indicating C standard support 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_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/LANGUAGE.rst b/Help/prop_sf/LANGUAGE.rst index a9b5638..92bd227 100644 --- a/Help/prop_sf/LANGUAGE.rst +++ b/Help/prop_sf/LANGUAGE.rst @@ -7,8 +7,8 @@ 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``, ``HIP``, ``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. +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_test/ENVIRONMENT.rst b/Help/prop_test/ENVIRONMENT.rst index 43bcdbe..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 changes from this property do not affect other -tests. +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 index 1e17329..a80651a 100644 --- a/Help/prop_test/ENVIRONMENT_MODIFICATION.rst +++ b/Help/prop_test/ENVIRONMENT_MODIFICATION.rst @@ -7,10 +7,11 @@ 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. -If set to a list 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: +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 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 a3191e8..191f78f 100644 --- a/Help/prop_tgt/CUDA_ARCHITECTURES.rst +++ b/Help/prop_tgt/CUDA_ARCHITECTURES.rst @@ -20,6 +20,20 @@ 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 ^^^^^^^^ 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/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/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/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_STANDARD.rst b/Help/prop_tgt/LANG_STANDARD.rst index bd377ec..c83da01 100644 --- a/Help/prop_tgt/LANG_STANDARD.rst +++ b/Help/prop_tgt/LANG_STANDARD.rst @@ -15,6 +15,13 @@ 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. diff --git a/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst b/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst index 56ecef8..e61125b 100644 --- a/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst +++ b/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst @@ -11,16 +11,22 @@ The variations are: * :prop_tgt:`OBJCXX_STANDARD_REQUIRED` These properties specify whether the value of :prop_tgt:`<LANG>_STANDARD` is a -requirement. When ``OFF`` or unset, the :prop_tgt:`<LANG>_STANDARD` target +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 is not available. +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. -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/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_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/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/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/XCODE_EMBED_type.rst b/Help/prop_tgt/XCODE_EMBED_type.rst index a1af56f..e8383c2 100644 --- a/Help/prop_tgt/XCODE_EMBED_type.rst +++ b/Help/prop_tgt/XCODE_EMBED_type.rst @@ -19,6 +19,12 @@ The supported values for ``<type>`` are: 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. + See also :prop_tgt:`XCODE_EMBED_<type>_PATH`, :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 index 7ec0385..cb449ac 100644 --- a/Help/prop_tgt/XCODE_EMBED_type_CODE_SIGN_ON_COPY.rst +++ b/Help/prop_tgt/XCODE_EMBED_type_CODE_SIGN_ON_COPY.rst @@ -14,5 +14,8 @@ The supported values for ``<type>`` are: ``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 a6f980d..160f765 100644 --- a/Help/prop_tgt/XCODE_EMBED_type_PATH.rst +++ b/Help/prop_tgt/XCODE_EMBED_type_PATH.rst @@ -16,3 +16,6 @@ The supported values for ``<type>`` are: ``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 index 75c8eae..e3a7ced 100644 --- a/Help/prop_tgt/XCODE_EMBED_type_REMOVE_HEADERS_ON_COPY.rst +++ b/Help/prop_tgt/XCODE_EMBED_type_REMOVE_HEADERS_ON_COPY.rst @@ -18,3 +18,6 @@ The supported values for ``<type>`` are: 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.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/index.rst b/Help/release/index.rst index 3d2ed43..ee677a3 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -13,6 +13,7 @@ Releases .. toctree:: :maxdepth: 1 + 3.23 <3.23> 3.22 <3.22> 3.21 <3.21> 3.20 <3.20> 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_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_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_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_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_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_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_ID.rst index 0abedde..cd7d5cd 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_ID.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_ID.rst @@ -28,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) @@ -40,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_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_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_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_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst index 0231668..8c84f91 100644 --- a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -34,6 +34,8 @@ only for the policies that do not warn by default: 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_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_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_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/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_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/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. |