Lubuntu/cmake
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

New upstream version 3.29.2

Browse Source
This commit is contained in:
Timo Röhling 2024-04-14 22:45:38 +02:00
parent 2d93009978
commit 3698acc303
2160 changed files with 37258 additions and 14593 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
Auxiliary/cmake-mode.el
View File

@ -258,15 +258,6 @@ Return t unless search stops due to end of buffer."
(forward-line)
t)))
(defun cmake-mark-defun ()
"Mark the current CMake function or macro.
This puts the mark at the end, and point at the beginning."
(interactive)
(cmake-end-of-defun)
(push-mark nil :nomsg :activate)
(cmake-beginning-of-defun))
;------------------------------------------------------------------------------
@ -346,6 +337,10 @@ This puts the mark at the end, and point at the beginning."
(define-derived-mode cmake-mode prog-mode "CMake"
"Major mode for editing CMake source files."
;; Setup jumping to beginning/end of a CMake function/macro.
(set (make-local-variable 'beginning-of-defun-function) #'cmake-beginning-of-defun)
(set (make-local-variable 'end-of-defun-function) #'cmake-end-of-defun)
; Setup font-lock mode.
(set (make-local-variable 'font-lock-defaults) '(cmake-font-lock-keywords))
; Setup indentation function.
@ -356,11 +351,6 @@ This puts the mark at the end, and point at the beginning."
(set (make-local-variable 'syntax-propertize-function) cmake--syntax-propertize-function)
(add-hook 'syntax-propertize-extend-region-functions #'syntax-propertize-multiline nil t))
;; Default cmake-mode key bindings
(define-key cmake-mode-map "\e\C-a" #'cmake-beginning-of-defun)
(define-key cmake-mode-map "\e\C-e" #'cmake-end-of-defun)
(define-key cmake-mode-map "\e\C-h" #'cmake-mark-defun)
; Help mode starts here

2
Auxiliary/vim/indent/cmake.vim
View File

@ -17,6 +17,8 @@ let b:did_indent = 1
setlocal indentexpr=CMakeGetIndent(v:lnum)
setlocal indentkeys+==ENDIF(,ENDFOREACH(,ENDMACRO(,ELSE(,ELSEIF(,ENDWHILE(
let b:undo_indent = "setl inde< indk<"
" Only define the function once.
if exists("*CMakeGetIndent")
finish

13
Auxiliary/vim/syntax/cmake.vim
View File

@ -19,10 +19,10 @@ endif
let s:keepcpo= &cpo
set cpo&vim
syn region cmakeBracketArgument start="\[\z(=\?\|=[0-9]*\)\[" end="\]\z1\]" contains=cmakeTodo,@Spell
syn region cmakeBracketArgument start="\[\z(=*\)\[" end="\]\z1\]" contains=cmakeTodo,@Spell
syn region cmakeComment start="#" end="$" contains=cmakeTodo,@Spell
syn region cmakeBracketComment start="\[\z(=*\)\[" end="\]\z1\]" contains=cmakeTodo,@Spell
syn region cmakeComment start="#\(\[=*\[\)\@!" end="$" contains=cmakeTodo,@Spell
syn region cmakeBracketComment start="#\[\z(=*\)\[" end="\]\z1\]" contains=cmakeTodo,@Spell
syn match cmakeEscaped /\(\\\\\|\\"\|\\n\|\\t\)/ contained
syn region cmakeRegistry start="\[" end="]" contained oneline contains=cmakeTodo,cmakeEscaped
@ -70,6 +70,7 @@ syn keyword cmakeProperty contained
\ ATTACHED_FILES
\ ATTACHED_FILES_ON_FAIL
\ AUTOGEN_BUILD_DIR
\ AUTOGEN_COMMAND_LINE_LENGTH_MAX
\ AUTOGEN_ORIGIN_DEPENDS
\ AUTOGEN_PARALLEL
\ AUTOGEN_SOURCE_GROUP
@ -77,6 +78,7 @@ syn keyword cmakeProperty contained
\ AUTOGEN_TARGETS_FOLDER
\ AUTOGEN_TARGET_DEPENDS
\ AUTOGEN_USE_SYSTEM_INCLUDE
\ AUTOGEN_BETTER_GRAPH_MULTI_CONFIG
\ AUTOMOC
\ AUTOMOC_COMPILER_PREDEFINES
\ AUTOMOC_DEPEND_FILTERS
@ -374,6 +376,7 @@ syn keyword cmakeProperty contained
\ Swift_LANGUAGE_VERSION
\ Swift_MODULE_DIRECTORY
\ Swift_MODULE_NAME
\ Swift_COMPILATION_MODE
\ TARGET_ARCHIVES_MAY_BE_SHARED_LIBS
\ TARGET_MESSAGES
\ TARGET_SUPPORTS_SHARED_LIBS
@ -764,6 +767,8 @@ syn keyword cmakeVariable contained
\ CMAKE_ASM_STANDARD_REQUIRED
\ CMAKE_ASM_SUPPORTED
\ CMAKE_ASM_VISIBILITY_PRESET
\ CMAKE_AUTOGEN_BETTER_GRAPH_MULTI_CONFIG
\ CMAKE_AUTOGEN_COMMAND_LINE_LENGTH_MAX
\ CMAKE_AUTOGEN_ORIGIN_DEPENDS
\ CMAKE_AUTOGEN_PARALLEL
\ CMAKE_AUTOGEN_USE_SYSTEM_INCLUDE
@ -1656,6 +1661,7 @@ syn keyword cmakeVariable contained
\ CMAKE_SKIP_INSTALL_RPATH
\ CMAKE_SKIP_INSTALL_RULES
\ CMAKE_SKIP_RPATH
\ CMAKE_SKIP_TEST_ALL_DEPENDENCY
\ CMAKE_SOURCE_DIR
\ CMAKE_STAGING_PREFIX
\ CMAKE_STATIC_LIBRARY_PREFIX
@ -2760,7 +2766,6 @@ syn keyword cmakeKWcmake_language contained
\ DIRECTORY
\ EVAL
\ FALSE
\ FETCHCONTENT_MAKEAVAILABE_SERIAL
\ FETCHCONTENT_MAKEAVAILABLE_SERIAL
\ FETCHCONTENT_SOURCE_DIR_
\ FETCHCONTENT_TRY_FIND_PACKAGE_MODE

3
CMakeLists.txt
View File

@ -1,7 +1,7 @@
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file Copyright.txt or https://cmake.org/licensing for details.
cmake_minimum_required(VERSION 3.13...3.26 FATAL_ERROR)
cmake_minimum_required(VERSION 3.13...3.27 FATAL_ERROR)
set(CMAKE_USER_MAKE_RULES_OVERRIDE_C ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideC.cmake)
set(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideCXX.cmake)
@ -140,6 +140,7 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
if(CMAKE_SYSTEM_NAME MATCHES "Windows|Darwin|Linux|BSD|DragonFly|CYGWIN|MSYS"
AND NOT (CMAKE_CXX_COMPILER_ID STREQUAL "MSVC" AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 19.16)
AND NOT (CMAKE_CXX_COMPILER_ID STREQUAL "XLClang" AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 16.1)
AND NOT (CMAKE_CXX_COMPILER_ID STREQUAL "LCC" AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 1.23)
)
set(CMake_ENABLE_DEBUGGER 1)
else()

2
CONTRIBUTING.rst
View File

@ -14,7 +14,7 @@ collaboration with a productive community of contributors.
Please post to the ``Development`` category of the `CMake Forum`_ to raise
discussion of development topics.
.. _`Kitware`: http://www.kitware.com/cmake
.. _`Kitware`: https://www.kitware.com/cmake
.. _`CMake Forum`: https://discourse.cmake.org
Patches

2
Copyright.txt
View File

@ -1,5 +1,5 @@
CMake - Cross Platform Makefile Generator
Copyright 2000-2023 Kitware, Inc. and Contributors
Copyright 2000-2024 Kitware, Inc. and Contributors
All rights reserved.
Redistribution and use in source and binary forms, with or without

10
Help/command/add_custom_command.rst
View File

@ -373,6 +373,11 @@ The options are:
:manual:`generator expressions <cmake-generator-expressions(7)>` was also
added.
.. versionadded:: 3.29
The :ref:`Ninja Generators` will now incorporate the dependencies into its
"deps log" database if the file is not listed in ``OUTPUTS`` or
``BYPRODUCTS``.
Using ``DEPFILE`` with generators other than those listed above is an error.
If the ``DEPFILE`` argument is relative, it should be relative to
@ -544,11 +549,14 @@ one of the keywords to make clear the behavior they expect.
lines or custom commands will be omitted for the specific
configuration and no "empty-string-command" will be added.
This allows to add individual build events for every configuration.
This allows adding individual build events for every configuration.
.. versionadded:: 3.21
Support for target-dependent generator expressions.
.. versionadded:: 3.29
The ``<target>`` may be an :ref:`ALIAS target <Alias Targets>`.
Examples: Build Events
^^^^^^^^^^^^^^^^^^^^^^

77
Help/command/add_executable.rst
View File

@ -10,15 +10,28 @@ Add an executable to the project using the specified source files.
Normal Executables
^^^^^^^^^^^^^^^^^^
.. code-block:: cmake
.. signature::
add_executable(<name> <options>... <sources>...)
:target: normal
add_executable(<name> [WIN32] [MACOSX_BUNDLE]
[EXCLUDE_FROM_ALL]
[source1] [source2 ...])
Add an executable target called ``<name>`` to be built from the source
files listed in the command invocation.
Adds an executable target called ``<name>`` to be built from the source
files listed in the command invocation. The
``<name>`` corresponds to the logical target name and must be globally
The options are:
``WIN32``
Set the :prop_tgt:`WIN32_EXECUTABLE` target property automatically.
See documentation of that target property for details.
``MACOSX_BUNDLE``
Set the :prop_tgt:`MACOSX_BUNDLE` target property automatically.
See documentation of that target property for details.
``EXCLUDE_FROM_ALL``
Set the :prop_tgt:`EXCLUDE_FROM_ALL` target property automatically.
See documentation of that target property for details.
The ``<name>`` corresponds to the logical target name and must be globally
unique within a project. The actual file name of the executable built is
constructed based on conventions of the native platform (such as
``<name>.exe`` or just ``<name>``).
@ -39,18 +52,6 @@ command was invoked. See documentation of the
location. See documentation of the :prop_tgt:`OUTPUT_NAME` target property
to change the ``<name>`` part of the final file name.
If ``WIN32`` is given the property :prop_tgt:`WIN32_EXECUTABLE` will be
set on the target created. See documentation of that target property for
details.
If ``MACOSX_BUNDLE`` is given the corresponding property will be set on
the created target. See documentation of the :prop_tgt:`MACOSX_BUNDLE`
target property for details.
If ``EXCLUDE_FROM_ALL`` is given the corresponding property will be set on
the created target. See documentation of the :prop_tgt:`EXCLUDE_FROM_ALL`
target property for details.
See the :manual:`cmake-buildsystem(7)` manual for more on defining
buildsystem properties.
@ -61,17 +62,25 @@ within IDE.
Imported Executables
^^^^^^^^^^^^^^^^^^^^
.. code-block:: cmake
.. signature::
add_executable(<name> IMPORTED [GLOBAL])
:target: IMPORTED
Add an :ref:`IMPORTED executable target <Imported Targets>` to reference
an executable file located outside the project. The target name may be
referenced like any target built within the project, except that by
default it is visible only in the directory in which it is created,
and below.
The options are:
``GLOBAL``
Make the target name globally visible.
No rules are generated to build imported targets, and the :prop_tgt:`IMPORTED`
target property is ``True``. Imported executables are useful for convenient
reference from commands like :command:`add_custom_command`.
An :ref:`IMPORTED executable target <Imported Targets>` references an
executable file located outside the project. No rules are generated to
build it, and the :prop_tgt:`IMPORTED` target property is ``True``. The
target name has scope in the directory in which it is created and below, but
the ``GLOBAL`` option extends visibility. It may be referenced like any
target built within the project. ``IMPORTED`` executables are useful
for convenient reference from commands like :command:`add_custom_command`.
Details about the imported executable are specified by setting properties
whose names begin in ``IMPORTED_``. The most important such property is
:prop_tgt:`IMPORTED_LOCATION` (and its per-configuration version
@ -82,14 +91,14 @@ properties for more information.
Alias Executables
^^^^^^^^^^^^^^^^^
.. code-block:: cmake
.. signature::
add_executable(<name> ALIAS <target>)
:target: ALIAS
Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can
be used to refer to ``<target>`` in subsequent commands. The ``<name>``
does not appear in the generated buildsystem as a make target. The
``<target>`` may not be an ``ALIAS``.
Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can
be used to refer to ``<target>`` in subsequent commands. The ``<name>``
does not appear in the generated buildsystem as a make target. The
``<target>`` may not be an ``ALIAS``.
.. versionadded:: 3.11
An ``ALIAS`` can target a ``GLOBAL`` :ref:`Imported Target <Imported Targets>`

273
Help/command/add_library.rst
View File

@ -10,18 +10,39 @@ Add a library to the project using the specified source files.
Normal Libraries
^^^^^^^^^^^^^^^^
.. code-block:: cmake
.. signature::
add_library(<name> [<type>] [EXCLUDE_FROM_ALL] <sources>...)
:target: normal
add_library(<name> [STATIC | SHARED | MODULE]
[EXCLUDE_FROM_ALL]
[<source>...])
Add a library target called ``<name>`` to be built from the source files
listed in the command invocation.
Adds a library target called ``<name>`` to be built from the source files
listed in the command invocation. The ``<name>``
corresponds to the logical target name and must be globally unique within
a project. The actual file name of the library built is constructed based
on conventions of the native platform (such as ``lib<name>.a`` or
``<name>.lib``).
The optional ``<type>`` specifies the type of library to be created:
``STATIC``
An archive of object files for use when linking other targets.
``SHARED``
A dynamic library that may be linked by other targets and loaded
at runtime.
``MODULE``
A plugin that may not be linked by other targets, but may be
dynamically loaded at runtime using dlopen-like functionality.
If no ``<type>`` is given the default is ``STATIC`` or ``SHARED``
based on the value of the :variable:`BUILD_SHARED_LIBS` variable.
The options are:
``EXCLUDE_FROM_ALL``
Set the :prop_tgt:`EXCLUDE_FROM_ALL` target property automatically.
See documentation of that target property for details.
The ``<name>`` corresponds to the logical target name and must be globally
unique within a project. The actual file name of the library built is
constructed based on conventions of the native platform (such as
``lib<name>.a`` or ``<name>.lib``).
.. versionadded:: 3.1
Source arguments to ``add_library`` may use "generator expressions" with
@ -32,15 +53,8 @@ on conventions of the native platform (such as ``lib<name>.a`` or
The source files can be omitted if they are added later using
:command:`target_sources`.
``STATIC``, ``SHARED``, or ``MODULE`` may be given to specify the type of
library to be created. ``STATIC`` libraries are archives of object files
for use when linking other targets. ``SHARED`` libraries are linked
dynamically and loaded at runtime. ``MODULE`` libraries are plugins that
are not linked into other targets but may be loaded dynamically at runtime
using dlopen-like functionality. If no type is given explicitly the
type is ``STATIC`` or ``SHARED`` based on whether the current value of the
variable :variable:`BUILD_SHARED_LIBS` is ``ON``. For ``SHARED`` and
``MODULE`` libraries the :prop_tgt:`POSITION_INDEPENDENT_CODE` target
For ``SHARED`` and ``MODULE`` libraries the
:prop_tgt:`POSITION_INDEPENDENT_CODE` target
property is set to ``ON`` automatically.
A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK`
target property to create an macOS Framework.
@ -63,10 +77,6 @@ invoked. See documentation of the :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`,
location. See documentation of the :prop_tgt:`OUTPUT_NAME` target
property to change the ``<name>`` part of the final file name.
If ``EXCLUDE_FROM_ALL`` is given the corresponding property will be set on
the created target. See documentation of the :prop_tgt:`EXCLUDE_FROM_ALL`
target property for details.
See the :manual:`cmake-buildsystem(7)` manual for more on defining
buildsystem properties.
@ -77,14 +87,15 @@ within IDE.
Object Libraries
^^^^^^^^^^^^^^^^
.. code-block:: cmake
.. signature::
add_library(<name> OBJECT <sources>...)
:target: OBJECT
add_library(<name> OBJECT [<source>...])
Add an :ref:`Object Library <Object Libraries>` to compile source files
without archiving or linking their object files into a library.
Creates an :ref:`Object Library <Object Libraries>`. An object library
compiles source files but does not archive or link their object files into a
library. Instead other targets created by ``add_library`` or
:command:`add_executable` may reference the objects using an expression of the
Other targets created by ``add_library`` or :command:`add_executable`
may reference the objects using an expression of the
form :genex:`$\<TARGET_OBJECTS:objlib\> <TARGET_OBJECTS>` as a source, where
``objlib`` is the object library name. For example:
@ -109,46 +120,48 @@ consider adding at least one real source file to any target that references
Interface Libraries
^^^^^^^^^^^^^^^^^^^
.. code-block:: cmake
.. signature::
add_library(<name> INTERFACE)
:target: INTERFACE
Creates an :ref:`Interface Library <Interface Libraries>`.
An ``INTERFACE`` library target does not compile sources and does
not produce a library artifact on disk. However, it may have
properties set on it and it may be installed and exported.
Typically, ``INTERFACE_*`` properties are populated on an interface
target using the commands:
Add an :ref:`Interface Library <Interface Libraries>` target that may
specify usage requirements for dependents but does not compile sources
and does not produce a library artifact on disk.
* :command:`set_property`,
* :command:`target_link_libraries(INTERFACE)`,
* :command:`target_link_options(INTERFACE)`,
* :command:`target_include_directories(INTERFACE)`,
* :command:`target_compile_options(INTERFACE)`,
* :command:`target_compile_definitions(INTERFACE)`, and
* :command:`target_sources(INTERFACE)`,
An interface library with no source files is not included as a target
in the generated buildsystem. However, it may have
properties set on it and it may be installed and exported.
Typically, ``INTERFACE_*`` properties are populated on an interface
target using the commands:
and then it is used as an argument to :command:`target_link_libraries`
like any other target.
* :command:`set_property`,
* :command:`target_link_libraries(INTERFACE)`,
* :command:`target_link_options(INTERFACE)`,
* :command:`target_include_directories(INTERFACE)`,
* :command:`target_compile_options(INTERFACE)`,
* :command:`target_compile_definitions(INTERFACE)`, and
* :command:`target_sources(INTERFACE)`,
An interface library created with the above signature has no source files
itself and is not included as a target in the generated buildsystem.
and then it is used as an argument to :command:`target_link_libraries`
like any other target.
.. versionadded:: 3.15
An interface library can have :prop_tgt:`PUBLIC_HEADER` and
:prop_tgt:`PRIVATE_HEADER` properties. The headers specified by those
properties can be installed using the :command:`install(TARGETS)` command.
.. versionadded:: 3.15
An interface library can have :prop_tgt:`PUBLIC_HEADER` and
:prop_tgt:`PRIVATE_HEADER` properties. The headers specified by those
properties can be installed using the :command:`install(TARGETS)` command.
.. versionadded:: 3.19
An interface library target may be created with source files:
.. signature::
add_library(<name> INTERFACE [EXCLUDE_FROM_ALL] <sources>...)
:target: INTERFACE-with-sources
.. code-block:: cmake
.. versionadded:: 3.19
add_library(<name> INTERFACE [<source>...] [EXCLUDE_FROM_ALL])
Source files may be listed directly in the ``add_library`` call or added
later by calls to :command:`target_sources` with the ``PRIVATE`` or
``PUBLIC`` keywords.
Add an :ref:`Interface Library <Interface Libraries>` target with
source files (in addition to usage requirements and properties as
documented by the :command:`above signature <add_library(INTERFACE)>`).
Source files may be listed directly in the ``add_library`` call
or added later by calls to :command:`target_sources` with the
``PRIVATE`` or ``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`
@ -158,92 +171,106 @@ itself and is not included as a target in the generated buildsystem.
but does contain build rules for custom commands created by the
:command:`add_custom_command` command.
.. note::
In most command signatures where the ``INTERFACE`` keyword appears,
the items listed after it only become part of that target's usage
requirements and are not part of the target's own settings. However,
in this signature of ``add_library``, the ``INTERFACE`` keyword refers
to the library type only. Sources listed after it in the ``add_library``
call are ``PRIVATE`` to the interface library and do not appear in its
:prop_tgt:`INTERFACE_SOURCES` target property.
The options are:
``EXCLUDE_FROM_ALL``
Set the :prop_tgt:`EXCLUDE_FROM_ALL` target property automatically.
See documentation of that target property for details.
.. note::
In most command signatures where the ``INTERFACE`` keyword appears,
the items listed after it only become part of that target's usage
requirements and are not part of the target's own settings. However,
in this signature of ``add_library``, the ``INTERFACE`` keyword refers
to the library type only. Sources listed after it in the ``add_library``
call are ``PRIVATE`` to the interface library and do not appear in its
:prop_tgt:`INTERFACE_SOURCES` target property.
.. _`add_library imported libraries`:
Imported Libraries
^^^^^^^^^^^^^^^^^^
.. code-block:: cmake
.. signature::
add_library(<name> <type> IMPORTED [GLOBAL])
:target: IMPORTED
Creates an :ref:`IMPORTED library target <Imported Targets>` called ``<name>``.
No rules are generated to build it, and the :prop_tgt:`IMPORTED` target
property is ``True``. The target name has scope in the directory in which
it is created and below, but the ``GLOBAL`` option extends visibility.
It may be referenced like any target built within the project.
``IMPORTED`` libraries are useful for convenient reference from commands
like :command:`target_link_libraries`. Details about the imported library
are specified by setting properties whose names begin in ``IMPORTED_`` and
``INTERFACE_``.
Add an :ref:`IMPORTED library target <Imported Targets>` called ``<name>``.
The target name may be referenced like any target built within the project,
except that by default it is visible only in the directory in which it is
created, and below.
The ``<type>`` must be one of:
The ``<type>`` must be one of:
``STATIC``, ``SHARED``, ``MODULE``, ``UNKNOWN``
References a library file located outside the project. The
:prop_tgt:`IMPORTED_LOCATION` target property (or its per-configuration
variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) specifies the
location of the main library file on disk:
``STATIC``, ``SHARED``, ``MODULE``, ``UNKNOWN``
References a library file located outside the project. The
:prop_tgt:`IMPORTED_LOCATION` target property (or its per-configuration
variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) specifies the
location of the main library file on disk:
* For a ``SHARED`` library on most non-Windows platforms, the main library
file is the ``.so`` or ``.dylib`` file used by both linkers and dynamic
loaders. If the referenced library file has a ``SONAME`` (or on macOS,
has a ``LC_ID_DYLIB`` starting in ``@rpath/``), the value of that field
should be set in the :prop_tgt:`IMPORTED_SONAME` target property.
If the referenced library file does not have a ``SONAME``, but the
platform supports it, then the :prop_tgt:`IMPORTED_NO_SONAME` target
property should be set.
* For a ``SHARED`` library on most non-Windows platforms, the main library
file is the ``.so`` or ``.dylib`` file used by both linkers and dynamic
loaders. If the referenced library file has a ``SONAME`` (or on macOS,
has a ``LC_ID_DYLIB`` starting in ``@rpath/``), the value of that field
should be set in the :prop_tgt:`IMPORTED_SONAME` target property.
If the referenced library file does not have a ``SONAME``, but the
platform supports it, then the :prop_tgt:`IMPORTED_NO_SONAME` target
property should be set.
* For a ``SHARED`` library on Windows, the :prop_tgt:`IMPORTED_IMPLIB`
target property (or its per-configuration variant
:prop_tgt:`IMPORTED_IMPLIB_<CONFIG>`) specifies the location of the
DLL import library file (``.lib`` or ``.dll.a``) on disk, and the
``IMPORTED_LOCATION`` is the location of the ``.dll`` runtime
library (and is optional, but needed by the :genex:`TARGET_RUNTIME_DLLS`
generator expression).
* For a ``SHARED`` library on Windows, the :prop_tgt:`IMPORTED_IMPLIB`
target property (or its per-configuration variant
:prop_tgt:`IMPORTED_IMPLIB_<CONFIG>`) specifies the location of the
DLL import library file (``.lib`` or ``.dll.a``) on disk, and the
``IMPORTED_LOCATION`` is the location of the ``.dll`` runtime
library (and is optional, but needed by the :genex:`TARGET_RUNTIME_DLLS`
generator expression).
Additional usage requirements may be specified in ``INTERFACE_*`` properties.
Additional usage requirements may be specified in ``INTERFACE_*``
properties.
An ``UNKNOWN`` library type is typically only used in the implementation of
:ref:`Find Modules`. It allows the path to an imported library (often found
using the :command:`find_library` command) to be used without having to know
what type of library it is. This is especially useful on Windows where a
static library and a DLL's import library both have the same file extension.
An ``UNKNOWN`` library type is typically only used in the implementation
of :ref:`Find Modules`. It allows the path to an imported library
(often found using the :command:`find_library` command) to be used
without having to know what type of library it is. This is especially
useful on Windows where a static library and a DLL's import library
both have the same file extension.
``OBJECT``
References a set of object files located outside the project.
The :prop_tgt:`IMPORTED_OBJECTS` target property (or its per-configuration
variant :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`) specifies the locations of
object files on disk.
Additional usage requirements may be specified in ``INTERFACE_*`` properties.
``OBJECT``
References a set of object files located outside the project.
The :prop_tgt:`IMPORTED_OBJECTS` target property (or its per-configuration
variant :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`) specifies the locations of
object files on disk.
Additional usage requirements may be specified in ``INTERFACE_*``
properties.
``INTERFACE``
Does not reference any library or object files on disk, but may
specify usage requirements in ``INTERFACE_*`` properties.
``INTERFACE``
Does not reference any library or object files on disk, but may
specify usage requirements in ``INTERFACE_*`` properties.
See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties
for more information.
The options are:
``GLOBAL``
Make the target name globally visible.
No rules are generated to build imported targets, and the :prop_tgt:`IMPORTED`
target property is ``True``. Imported libraries are useful for convenient
reference from commands like :command:`target_link_libraries`.
Details about the imported library are specified by setting properties whose
names begin in ``IMPORTED_`` and ``INTERFACE_``. See documentation of
such properties for more information.
Alias Libraries
^^^^^^^^^^^^^^^
.. code-block:: cmake
.. signature::
add_library(<name> ALIAS <target>)
:target: ALIAS
Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be
used to refer to ``<target>`` in subsequent commands. The ``<name>`` does
not appear in the generated buildsystem as a make target. The ``<target>``
may not be an ``ALIAS``.
Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be
used to refer to ``<target>`` in subsequent commands. The ``<name>`` does
not appear in the generated buildsystem as a make target. The ``<target>``
may not be an ``ALIAS``.
.. versionadded:: 3.11
An ``ALIAS`` can target a ``GLOBAL`` :ref:`Imported Target <Imported Targets>`

34
Help/command/add_test.rst
View File

@ -27,9 +27,37 @@ directory the test is created in.
``add_test`` options are:
``COMMAND``
Specify the test command-line. If ``<command>`` specifies an executable
target created by :command:`add_executable`, it will automatically be
replaced by the location of the executable created at build time.
Specify the test command-line.
If ``<command>`` specifies an executable target created by
:command:`add_executable`:
* It will automatically be replaced by the location of the executable
created at build time.
* .. versionadded:: 3.3
The target's :prop_tgt:`CROSSCOMPILING_EMULATOR`, if set, will be
used to run the command on the host::
<emulator> <command>
.. versionchanged:: 3.29
The emulator is used only when
:variable:`cross-compiling <CMAKE_CROSSCOMPILING>`.
See policy :policy:`CMP0158`.
* .. versionadded:: 3.29
The target's :prop_tgt:`TEST_LAUNCHER`, if set, will be
used to launch the command::
<launcher> <command>
If the :prop_tgt:`CROSSCOMPILING_EMULATOR` is also set, both are used::
<launcher> <emulator> <command>
The command may be specified using
:manual:`generator expressions <cmake-generator-expressions(7)>`.

2
Help/command/cmake_host_system_information.rst
View File

@ -265,7 +265,7 @@ Example:
.. [#mebibytes] One MiB (mebibyte) is equal to 1024x1024 bytes.
.. _man 5 os-release: https://www.freedesktop.org/software/systemd/man/os-release.html
.. _man 5 os-release: https://www.freedesktop.org/software/systemd/man/latest/os-release.html
.. _various distribution-specific files: http://linuxmafia.com/faq/Admin/release-files.html
.. _Query Windows registry:

25
Help/command/cmake_language.rst
View File

@ -15,6 +15,7 @@ Synopsis
cmake_language(`DEFER`_ <options>... CALL <command> [<arg>...])
cmake_language(`SET_DEPENDENCY_PROVIDER`_ <command> SUPPORTED_METHODS <methods>...)
cmake_language(`GET_MESSAGE_LOG_LEVEL`_ <out-var>)
cmake_language(`EXIT`_ <exit-code>)
Introduction
^^^^^^^^^^^^
@ -317,7 +318,7 @@ be one of the ``<methods>`` that was specified when setting the provider.
implementation as part of its processing, it can do so by including the
``BYPASS_PROVIDER`` keyword as one of the arguments.
``FETCHCONTENT_MAKEAVAILABE_SERIAL``
``FETCHCONTENT_MAKEAVAILABLE_SERIAL``
The ``<method-specific-args>`` will be everything passed to the
:command:`FetchContent_Declare` call that corresponds to the requested
dependency, with the following exceptions:
@ -506,3 +507,25 @@ Getting current message log level
If both the command line option and the variable are set, the command line
option takes precedence. If neither are set, the default logging level
is returned.
Terminating Scripts
^^^^^^^^^^^^^^^^^^^
.. versionadded:: 3.29
.. signature::
cmake_language(EXIT <exit-code>)
Terminate the current :option:`cmake -P` script and exit with ``<exit-code>``.
This command works only in :ref:`script mode <Script Processing Mode>`.
If used outside of that context, it will cause a fatal error.
The ``<exit-code>`` should be non-negative.
If ``<exit-code>`` is negative, then the behavior
is unspecified (e.g., on Windows the error code -1
becomes ``0xffffffff``, and on Linux it becomes 255).
Exit codes above 255 may not be supported by the underlying
shell or platform, and some shells may interpret values
above 125 specially. Therefore, it is advisable to only
specify an ``<exit-code>`` in the range 0 to 125.

140
Help/command/configure_file.rst
View File

@ -1,6 +1,10 @@
configure_file
--------------
.. only:: html
.. contents::
Copy a file to another location and modify its contents.
.. code-block:: cmake
@ -11,11 +15,79 @@ Copy a file to another location and modify its contents.
[COPYONLY] [ESCAPE_QUOTES] [@ONLY]
[NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
Copies an ``<input>`` file to an ``<output>`` file and substitutes
variable values referenced as ``@VAR@``, ``${VAR}``, ``$CACHE{VAR}`` or
``$ENV{VAR}`` in the input file content. Each variable reference will be
replaced with the current value of the variable, or the empty string if
the variable is not defined. Furthermore, input lines of the form
Copies an ``<input>`` file to an ``<output>`` file while performing
`transformations`_ of the input file content.
If the input file is modified the build system will re-run CMake to
re-configure the file and generate the build system again.
The generated file is modified and its timestamp updated on subsequent
cmake runs only if its content is changed.
Options
^^^^^^^
The options are:
``<input>``
Path to the input file. A relative path is treated with respect to
the value of :variable:`CMAKE_CURRENT_SOURCE_DIR`. The input path
must be a file, not a directory.
``<output>``
Path to the output file or directory. A relative path is treated
with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
If the path names an existing directory the output file is placed
in that directory with the same file name as the input file.
If the path contains non-existent directories, they are created.
``NO_SOURCE_PERMISSIONS``
.. versionadded:: 3.19
Do not transfer the permissions of the input file to the output file.
The copied file permissions default to the standard 644 value
(-rw-r--r--).
``USE_SOURCE_PERMISSIONS``
.. versionadded:: 3.20
Transfer the permissions of the input file to the output file.
This is already the default behavior if none of the three permissions-related
keywords are given (``NO_SOURCE_PERMISSIONS``, ``USE_SOURCE_PERMISSIONS``
or ``FILE_PERMISSIONS``). The ``USE_SOURCE_PERMISSIONS`` keyword mostly
serves as a way of making the intended behavior clearer at the call site.
``FILE_PERMISSIONS <permissions>...``
.. versionadded:: 3.20
Ignore the input file's permissions and use the specified ``<permissions>``
for the output file instead.
``COPYONLY``
Copy the file without replacing any variable references or other
content. This option may not be used with ``NEWLINE_STYLE``.
``ESCAPE_QUOTES``
Escape any substituted quotes with backslashes (C-style).
``@ONLY``
Restrict variable replacement to references of the form ``@VAR@``.
This is useful for configuring scripts that use ``${VAR}`` syntax.
``NEWLINE_STYLE <style>``
Specify the newline style for the output file. Specify
``UNIX`` or ``LF`` for ``\n`` newlines, or specify
``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines.
This option may not be used with ``COPYONLY``.
Transformations
^^^^^^^^^^^^^^^
:ref:`Variables <CMake Language Variables>` referenced in the input
file content as ``@VAR@``, ``${VAR}``, ``$CACHE{VAR}``, and
:ref:`environment variables <CMake Language Environment Variables>`
referenced as ``$ENV{VAR}``, will each be replaced with the current value
of the variable, or the empty string if the variable is not defined.
Furthermore, input lines of the form
.. code-block:: c
@ -79,64 +151,6 @@ which may lead to undefined behavior.
# define VAR
# define VAR 1
If the input file is modified the build system will re-run CMake to
re-configure the file and generate the build system again.
The generated file is modified and its timestamp updated on subsequent
cmake runs only if its content is changed.
The arguments are:
``<input>``
Path to the input file. A relative path is treated with respect to
the value of :variable:`CMAKE_CURRENT_SOURCE_DIR`. The input path
must be a file, not a directory.
``<output>``
Path to the output file or directory. A relative path is treated
with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
If the path names an existing directory the output file is placed
in that directory with the same file name as the input file.
If the path contains non-existent directories, they are created.
``NO_SOURCE_PERMISSIONS``
.. versionadded:: 3.19
Do not transfer the permissions of the input file to the output file.
The copied file permissions default to the standard 644 value
(-rw-r--r--).
``USE_SOURCE_PERMISSIONS``
.. versionadded:: 3.20
Transfer the permissions of the input file to the output file.
This is already the default behavior if none of the three permissions-related
keywords are given (``NO_SOURCE_PERMISSIONS``, ``USE_SOURCE_PERMISSIONS``
or ``FILE_PERMISSIONS``). The ``USE_SOURCE_PERMISSIONS`` keyword mostly
serves as a way of making the intended behavior clearer at the call site.
``FILE_PERMISSIONS <permissions>...``
.. versionadded:: 3.20
Ignore the input file's permissions and use the specified ``<permissions>``
for the output file instead.
``COPYONLY``
Copy the file without replacing any variable references or other
content. This option may not be used with ``NEWLINE_STYLE``.
``ESCAPE_QUOTES``
Escape any substituted quotes with backslashes (C-style).
``@ONLY``
Restrict variable replacement to references of the form ``@VAR@``.
This is useful for configuring scripts that use ``${VAR}`` syntax.
``NEWLINE_STYLE <style>``
Specify the newline style for the output file. Specify
``UNIX`` or ``LF`` for ``\n`` newlines, or specify
``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines.
This option may not be used with ``COPYONLY``.
Example
^^^^^^^

79
Help/command/create_test_sourcelist.rst
View File

@ -1,29 +1,62 @@
create_test_sourcelist
----------------------
Create a test driver and source list for building test programs.
Create a test driver program that links together many small tests into a
single executable. This is useful when building static executables with
large libraries to shrink the total required size.
.. code-block:: cmake
.. signature::
create_test_sourcelist(<sourceListName> <driverName> <test>... <options>...)
:target: original
create_test_sourcelist(<sourceListName> <driverName>
<tests> ...
[EXTRA_INCLUDE <include>]
[FUNCTION <function>])
Generate a test driver source file from a list of individual test sources
and provide a combined list of sources that can be built as an executable.
A test driver is a program that links together many small tests into a single
executable. This is useful when building static executables with large
libraries to shrink the total required size. The list of source files needed
to build the test driver will be in ``sourceListName``. ``driverName`` is the
name of the test driver program. The rest of the arguments consist of a list
of test source files and can be semicolon separated. Each test source file
should have a function in it that is the same name as the file with no
extension (``foo.cxx`` should have ``int foo(int, char*[]);``). ``driverName``
will be able to call each of the tests by name on the command line. If
``EXTRA_INCLUDE`` is specified, then the next argument is included into the
generated file. If ``FUNCTION`` is specified, then the next argument is taken
as a function name that is passed pointers to ``argc`` and ``argv``. This can
be used to add extra command line processing to each test. The
``CMAKE_TESTDRIVER_BEFORE_TESTMAIN`` cmake variable can be set to have code
that will be placed directly before calling the test ``main`` function.
``CMAKE_TESTDRIVER_AFTER_TESTMAIN`` can be set to have code that will be
placed directly after the call to the test ``main`` function.
The options are:
``<sourceListName>``
The name of a variable in which to store the list of source files needed
to build the test driver. The list will contain the ``<test>...`` sources
and the generated ``<driverName>`` source.
.. versionchanged:: 3.29
The test driver source is listed by absolute path in the build tree.
Previously it was listed only as ``<driverName>``.
``<driverName>``
Name of the test driver source file to be generated into the build tree.
The source file will contain a ``main()`` program entry point that
dispatches to whatever test is named on the command line.
``<test>...``
Test source files to be added to the driver binary. Each test source
file must have a function in it that is the same name as the file with the
extension removed. For example, a ``foo.cxx`` test source might contain:
.. code-block:: c++
int foo(int argc, char** argv)
``EXTRA_INCLUDE <header>``
Specify a header file to ``#include`` in the generated test driver source.
``FUNCTION <function>``
Specify a function to be called with pointers to ``argc`` and ``argv``.
The function may be provided in the ``EXTRA_INCLUDE`` header:
.. code-block:: c++
void function(int* pargc, char*** pargv)
This can be used to add extra command line processing to each test.
Additionally, some CMake variables affect test driver generation:
.. variable:: CMAKE_TESTDRIVER_BEFORE_TESTMAIN
Code to be placed directly before calling each test's function.
.. variable:: CMAKE_TESTDRIVER_AFTER_TESTMAIN
Code to be placed directly after the call to each test's function.

25
Help/command/ctest_test.rst
View File

@ -13,10 +13,12 @@ Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`.
[INCLUDE <include-regex>]
[EXCLUDE_LABEL <label-exclude-regex>]
[INCLUDE_LABEL <label-include-regex>]
[EXCLUDE_FROM_FILE <filename>]
[INCLUDE_FROM_FILE <filename>]
[EXCLUDE_FIXTURE <regex>]
[EXCLUDE_FIXTURE_SETUP <regex>]
[EXCLUDE_FIXTURE_CLEANUP <regex>]
[PARALLEL_LEVEL <level>]
[PARALLEL_LEVEL [<level>]]
[RESOURCE_SPEC_FILE <file>]
[TEST_LOAD <threshold>]
[SCHEDULE_RANDOM <ON|OFF>]
@ -72,6 +74,16 @@ The options are:
Specify a regular expression matching test labels to include.
Tests not matching this expression are excluded.
``EXCLUDE_FROM_FILE <filename>``
.. versionadded:: 3.29
Do NOT run tests listed with their exact name in the given file.
``INCLUDE_FROM_FILE <filename>``
.. versionadded:: 3.29
Only run the tests listed with their exact name in the given file.
``EXCLUDE_FIXTURE <regex>``
.. versionadded:: 3.7
@ -92,9 +104,14 @@ The options are:
Same as ``EXCLUDE_FIXTURE`` except only matching cleanup tests are excluded.
``PARALLEL_LEVEL <level>``
Specify a positive number representing the number of tests to
be run in parallel.
``PARALLEL_LEVEL [<level>]``
Run tests in parallel, limited to a given level of parallelism.
.. versionadded:: 3.29
The ``<level>`` may be omitted, or ``0``, to let ctest use a default
level of parallelism, or unbounded parallelism, respectively, as
documented by the :option:`ctest --parallel` option.
``RESOURCE_SPEC_FILE <file>``
.. versionadded:: 3.16

36
Help/command/define_property.rst
View File

@ -74,6 +74,42 @@ project via corresponding options to the :command:`get_property` command.
underscore. It is recommended that the property name have a prefix specific
to the project.
Property Redefinition
^^^^^^^^^^^^^^^^^^^^^
Once a property is defined for a particular type of scope, it cannot be
redefined. Attempts to redefine an existing property by calling
:command:`define_property` with the same scope type and property name
will be silently ignored. Defining the same property name for two different
kinds of scope is valid.
:command:`get_property` can be used to determine whether a property is
already defined for a particular kind of scope, and if so, to examine its
definition. For example:
.. code-block:: cmake
# Initial definition
define_property(TARGET PROPERTY MY_NEW_PROP
BRIEF_DOCS "My new custom property"
)
# Later examination
get_property(my_new_prop_exists
TARGET NONE
PROPERTY MY_NEW_PROP
DEFINED
)
if(my_new_prop_exists)
get_property(my_new_prop_docs
TARGET NONE
PROPERTY MY_NEW_PROP
BRIEF_DOCS
)
# ${my_new_prop_docs} is now set to "My new custom property"
endif()
See Also
^^^^^^^^

90
Help/command/export.rst
View File

@ -15,12 +15,13 @@ Synopsis
export(`TARGETS`_ <target>... [...])
export(`EXPORT`_ <export-name> [...])
export(`PACKAGE`_ <PackageName>)
export(`SETUP`_ <export-name> [...])
Exporting Targets
^^^^^^^^^^^^^^^^^
.. _`export(TARGETS)`:
.. _TARGETS:
.. signature::
export(TARGETS <target>... [...])
.. code-block:: cmake
@ -62,7 +63,7 @@ The options are:
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
included, the behavior is unspecified. See the :command:`export(EXPORT)` signature
to automatically export the same targets from the build tree as
:command:`install(EXPORT)` would from an install tree.
@ -102,27 +103,35 @@ that policy is set to OLD for one of the targets.
Exporting Targets matching install(EXPORT)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. _`export(EXPORT)`:
.. _EXPORT:
.. signature::
export(EXPORT <export-name> [...])
.. code-block:: cmake
export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>]
[CXX_MODULES_DIRECTORY <directory>])
[CXX_MODULES_DIRECTORY <directory>] [EXPORT_PACKAGE_DEPENDENCIES])
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
as the :command:`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.
``EXPORT_PACKAGE_DEPENDENCIES``
.. note::
Experimental. Gated by ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES``.
Specify that :command:`find_dependency` calls should be exported. See
:command:`install(EXPORT)` for details on how this works.
Exporting Packages
^^^^^^^^^^^^^^^^^^
.. _`export(PACKAGE)`:
.. _PACKAGE:
.. signature::
export(PACKAGE <PackageName>)
.. code-block:: cmake
@ -149,3 +158,66 @@ 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.
Configuring Exports
^^^^^^^^^^^^^^^^^^^
.. signature::
export(SETUP <export-name> [...])
.. code-block:: cmake
export(SETUP <export-name>
[PACKAGE_DEPENDENCY <dep>
[ENABLED (<bool-true>|<bool-false>|AUTO)]
[EXTRA_ARGS <args>...]
] [...]
[TARGET <target>
[XCFRAMEWORK_LOCATION <location>]
] [...]
)
.. versionadded:: 3.29
Configure the parameters of an export. The arguments are as follows:
``PACKAGE_DEPENDENCY <dep>``
.. note::
Experimental. Gated by ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES``.
Specify a package dependency to configure. This changes how
:command:`find_dependency` calls are written during
:command:`export(EXPORT)` and :command:`install(EXPORT)`. ``<dep>`` is the
name of a package to export. This argument accepts the following additional
arguments:
``ENABLED``
Manually control whether or not the dependency is exported. This accepts
the following values:
``<bool-true>``
Any value that CMake recognizes as "true". Always export the dependency,
even if no exported targets depend on it. This can be used to manually
add :command:`find_dependency` calls to the export.
``<bool-false>``
Any value that CMake recognizes as "false". Never export the dependency,
even if an exported target depends on it.
``AUTO``
Only export the dependency if an exported target depends on it.
``EXTRA_ARGS <args>``
Specify additional arguments to pass to :command:`find_dependency` after
the ``REQUIRED`` argument.
``TARGET <target>``
Specify a target to configure in this export. This argument accepts the
following additional arguments:
``XCFRAMEWORK_LOCATION``
Specify the location of an ``.xcframework`` which contains the library from
this target. If specified, the generated code will check to see if the
``.xcframework`` exists, and if it does, it will use the ``.xcframework``
as its imported location instead of the installed library.

80
Help/command/file.rst
View File

@ -32,14 +32,14 @@ Synopsis
`Writing`_
file({`WRITE`_ | `APPEND`_} <filename> <content>...)
file({`TOUCH`_ | `TOUCH_NOCREATE`_} [<file>...])
file({`TOUCH`_ | `TOUCH_NOCREATE`_} <file>...)
file(`GENERATE`_ OUTPUT <output-file> [...])
file(`CONFIGURE`_ OUTPUT <output-file> CONTENT <content> [...])
`Filesystem`_
file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] [<globbing-expr>...])
file(`MAKE_DIRECTORY`_ [<dir>...])
file({`REMOVE`_ | `REMOVE_RECURSE`_ } [<files>...])
file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] <globbing-expr>...)
file(`MAKE_DIRECTORY`_ <directories>...)
file({`REMOVE`_ | `REMOVE_RECURSE`_ } <files>...)
file(`RENAME`_ <oldname> <newname> [...])
file(`COPY_FILE`_ <oldname> <newname> [...])
file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...])
@ -80,7 +80,7 @@ Reading
(``a`` through ``f``) are in lowercase.
.. signature::
file(STRINGS <filename> <variable> [<options>...])
file(STRINGS <filename> <variable> <options>...)
Parse a list of ASCII strings from ``<filename>`` and store it in
``<variable>``. Binary data in the file are ignored. Carriage return
@ -113,6 +113,11 @@ Reading
Consider only strings that match the given regular expression,
as described under :ref:`string(REGEX) <Regex Specification>`.
.. versionchanged:: 3.29
Capture groups from the last match in the file are stored in
:variable:`CMAKE_MATCH_<n>`, similar to
:command:`string(REGEX MATCHALL)`. See policy :policy:`CMP0159`.
``ENCODING <encoding-type>``
.. versionadded:: 3.1
@ -165,17 +170,17 @@ Reading
[RESOLVED_DEPENDENCIES_VAR <deps_var>]
[UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>]
[CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>]
[EXECUTABLES [<executable_files>...]]
[LIBRARIES [<library_files>...]]
[MODULES [<module_files>...]]
[DIRECTORIES [<directories>...]]
[EXECUTABLES <executable_files>...]
[LIBRARIES <library_files>...]
[MODULES <module_files>...]
[DIRECTORIES <directories>...]
[BUNDLE_EXECUTABLE <bundle_executable_file>]
[PRE_INCLUDE_REGEXES [<regexes>...]]
[PRE_EXCLUDE_REGEXES [<regexes>...]]
[POST_INCLUDE_REGEXES [<regexes>...]]
[POST_EXCLUDE_REGEXES [<regexes>...]]
[POST_INCLUDE_FILES [<files>...]]
[POST_EXCLUDE_FILES [<files>...]]
[PRE_INCLUDE_REGEXES <regexes>...]
[PRE_EXCLUDE_REGEXES <regexes>...]
[POST_INCLUDE_REGEXES <regexes>...]
[POST_EXCLUDE_REGEXES <regexes>...]
[POST_INCLUDE_FILES <files>...]
[POST_EXCLUDE_FILES <files>...]
)
Please note that this sub-command is not intended to be used in project mode.
@ -210,7 +215,7 @@ Reading
of paths that were found for that filename are stored in
``<conflicting_deps_prefix>_<filename>``.
``EXECUTABLES <executable_files>``
``EXECUTABLES <executable_files>...``
List of executable files to read for dependencies. These are executables
that are typically created with :command:`add_executable`, but they do
not have to be created by CMake. On Apple platforms, the paths to these
@ -218,14 +223,14 @@ Reading
resolving the libraries. Specifying any kind of library (``STATIC``,
``MODULE``, or ``SHARED``) here will result in undefined behavior.
``LIBRARIES <library_files>``
``LIBRARIES <library_files>...``
List of library files to read for dependencies. These are libraries that
are typically created with :command:`add_library(SHARED)`, but they do
not have to be created by CMake. Specifying ``STATIC`` libraries,
``MODULE`` libraries, or executables here will result in undefined
behavior.
``MODULES <module_files>``
``MODULES <module_files>...``
List of loadable module files to read for dependencies. These are modules
that are typically created with :command:`add_library(MODULE)`, but they
do not have to be created by CMake. They are typically used by calling
@ -233,7 +238,7 @@ Reading
Specifying ``STATIC`` libraries, ``SHARED`` libraries, or executables
here will result in undefined behavior.
``DIRECTORIES <directories>``
``DIRECTORIES <directories>...``
List of additional directories to search for dependencies. On Linux
platforms, these directories are searched if the dependency is not found
in any of the other usual paths. If it is found in such a directory, a
@ -256,30 +261,30 @@ Reading
The following arguments specify filters for including or excluding libraries
to be resolved. See below for a full description of how they work.
``PRE_INCLUDE_REGEXES <regexes>``
``PRE_INCLUDE_REGEXES <regexes>...``
List of pre-include regexes through which to filter the names of
not-yet-resolved dependencies.
``PRE_EXCLUDE_REGEXES <regexes>``
``PRE_EXCLUDE_REGEXES <regexes>...``
List of pre-exclude regexes through which to filter the names of
not-yet-resolved dependencies.
``POST_INCLUDE_REGEXES <regexes>``
``POST_INCLUDE_REGEXES <regexes>...``
List of post-include regexes through which to filter the names of
resolved dependencies.
``POST_EXCLUDE_REGEXES <regexes>``
``POST_EXCLUDE_REGEXES <regexes>...``
List of post-exclude regexes through which to filter the names of
resolved dependencies.
``POST_INCLUDE_FILES <files>``
``POST_INCLUDE_FILES <files>...``
.. versionadded:: 3.21
List of post-include filenames through which to filter the names of
resolved dependencies. Symlinks are resolved when attempting to match
these filenames.
``POST_EXCLUDE_FILES <files>``
``POST_EXCLUDE_FILES <files>...``
.. versionadded:: 3.21
List of post-exclude filenames through which to filter the names of
@ -486,8 +491,8 @@ Writing
to update the file only when its content changes.
.. signature::
file(TOUCH [<files>...])
file(TOUCH_NOCREATE [<files>...])
file(TOUCH <files>...)
file(TOUCH_NOCREATE <files>...)
.. versionadded:: 3.12
@ -638,10 +643,10 @@ Filesystem
.. signature::
file(GLOB <variable>
[LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
[<globbing-expressions>...])
<globbing-expressions>...)
file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS]
[LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
[<globbing-expressions>...])
<globbing-expressions>...)
Generate a list of files that match the ``<globbing-expressions>`` and
store it into the ``<variable>``. Globbing expressions are similar to
@ -703,13 +708,13 @@ Filesystem
============== ======================================================
.. signature::
file(MAKE_DIRECTORY [<directories>...])
file(MAKE_DIRECTORY <directories>...)
Create the given directories and their parents as needed.
.. signature::
file(REMOVE [<files>...])
file(REMOVE_RECURSE [<files>...])
file(REMOVE <files>...)
file(REMOVE_RECURSE <files>...)
Remove the given files. The ``REMOVE_RECURSE`` mode will remove the given
files and directories, including non-empty directories. No error is emitted
@ -1012,8 +1017,8 @@ Transfer
^^^^^^^^
.. signature::
file(DOWNLOAD <url> [<file>] [<options>...])
file(UPLOAD <file> <url> [<options>...])
file(DOWNLOAD <url> [<file>] <options>...)
file(UPLOAD <file> <url> <options>...)
The ``DOWNLOAD`` subcommand downloads the given ``<url>`` to a local
``<file>``. The ``UPLOAD`` mode uploads a local ``<file>`` to a given
@ -1249,6 +1254,13 @@ Archiving
``LIST_ONLY`` will list the files in the archive rather than extract them.
.. note::
The working directory for this subcommand is the ``DESTINATION`` directory
(provided or computed) except when ``LIST_ONLY`` is specified. Therefore,
outside of script mode, it may be best to provide absolute paths to
``INPUT`` archives as they are unlikely to be extracted where a relative
path works.
.. versionadded:: 3.24
The ``TOUCH`` option gives extracted files a current local
timestamp instead of extracting file timestamps from the archive.

40
Help/command/if.rst
View File

@ -178,6 +178,46 @@ File Operations
False if the given path is an empty string.
.. note::
Prefer ``if(IS_READABLE)`` to check file readability. ``if(EXISTS)``
may be changed in the future to only check file existence.
.. signature:: if(IS_READABLE <path-to-file-or-directory>)
.. versionadded:: 3.29
True if the named file or directory is readable. Behavior
is well-defined only for explicit full paths (a leading ``~/`` is not
expanded as a home directory and is considered a relative path).
Resolves symbolic links, i.e. if the named file or directory is a
symbolic link, returns true if the target of the symbolic link is readable.
False if the given path is an empty string.
.. signature:: if(IS_WRITABLE <path-to-file-or-directory>)
.. versionadded:: 3.29
True if the named file or directory is writable. Behavior
is well-defined only for explicit full paths (a leading ``~/`` is not
expanded as a home directory and is considered a relative path).
Resolves symbolic links, i.e. if the named file or directory is a
symbolic link, returns true if the target of the symbolic link is writable.
False if the given path is an empty string.
.. signature:: if(IS_EXECUTABLE <path-to-file-or-directory>)
.. versionadded:: 3.29
True if the named file or directory is executable. Behavior
is well-defined only for explicit full paths (a leading ``~/`` is not
expanded as a home directory and is considered a relative path).
Resolves symbolic links, i.e. if the named file or directory is a
symbolic link, returns true if the target of the symbolic link is executable.
False if the given path is an empty string.
.. signature:: if(<file1> IS_NEWER_THAN <file2>)
:target: IS_NEWER_THAN

82
Help/command/install.rst
View File

@ -47,23 +47,26 @@ signatures that specify them. The common options are:
``DESTINATION <dir>``
Specify the directory on disk to which a file will be installed.
Arguments can be relative or absolute paths.
``<dir>`` should be a relative path. An absolute path is allowed,
but not recommended.
If a relative path is given it is interpreted relative to the value
When a relative path is given it is interpreted relative to the value
of the :variable:`CMAKE_INSTALL_PREFIX` variable.
The prefix can be relocated at install time using the ``DESTDIR``
mechanism explained in the :variable:`CMAKE_INSTALL_PREFIX` variable
documentation.
If an absolute path (with a leading slash or drive letter) is given
it is used verbatim.
As absolute paths are not supported by :manual:`cpack <cpack(1)>` installer
generators, it is preferable to use relative paths throughout.
As absolute paths do not work with the ``cmake --install`` command's
:option:`--prefix <cmake--install --prefix>` option, or with the
:manual:`cpack <cpack(1)>` installer generators, it is strongly recommended
to use relative paths throughout for best support by package maintainers.
In particular, there is no need to make paths absolute by prepending
:variable:`CMAKE_INSTALL_PREFIX`; this prefix is used by default if
the DESTINATION is a relative path.
If an absolute path (with a leading slash or drive letter) is given
it is used verbatim.
``PERMISSIONS <permission>...``
Specify permissions for installed files. Valid permissions are
``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``, ``GROUP_READ``,
@ -280,8 +283,8 @@ Signatures
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
path that begins with the appropriate :module:`GNUInstallDirs` variable.
projects must specify a ``DESTINATION``, it is strongly recommended that they use
a path that begins with the appropriate relative :module:`GNUInstallDirs` variable.
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
@ -572,8 +575,8 @@ Signatures
``DATA`` instead.
To make packages compliant with distribution filesystem layout policies, if
projects must specify a ``DESTINATION``, it is recommended that they use a
path that begins with the appropriate :module:`GNUInstallDirs` variable.
projects must specify a ``DESTINATION``, it is strongly recommended that they use
a path that begins with the appropriate relative :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 an image to a project-specific documentation
@ -719,8 +722,8 @@ Signatures
``DATA`` instead.
To make packages compliant with distribution filesystem layout policies, if
projects must specify a ``DESTINATION``, it is recommended that they use a
path that begins with the appropriate :module:`GNUInstallDirs` variable.
projects must specify a ``DESTINATION``, it is strongly recommended that they use
a path that begins with the appropriate relative :module:`GNUInstallDirs` variable.
This allows package maintainers to control the install destination by setting
the appropriate cache variables.
@ -784,7 +787,8 @@ Signatures
[CXX_MODULES_DIRECTORY <directory>]
[EXPORT_LINK_INTERFACE_LIBRARIES]
[COMPONENT <component>]
[EXCLUDE_FROM_ALL])
[EXCLUDE_FROM_ALL]
[EXPORT_PACKAGE_DEPENDENCIES])
install(EXPORT_ANDROID_MK <export-name> DESTINATION <dir> [...])
The ``EXPORT`` form generates and installs a CMake file containing code to
@ -848,6 +852,36 @@ Signatures
without this information, none of the C++ modules which are part of the
targets in the export set will support being imported in consuming targets.
``EXPORT_PACKAGE_DEPENDENCIES``
.. note::
Experimental. Gated by ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES``.
Specify that :command:`find_dependency` calls should be exported. If this
argument is specified, CMake examines all targets in the export set and
gathers their ``INTERFACE`` link targets. If any such targets either were
found with :command:`find_package` or have the
:prop_tgt:`EXPORT_FIND_PACKAGE_NAME` property set, and such package
dependency was not disabled by passing ``ENABLED OFF`` to
:command:`export(SETUP)`, then a :command:`find_dependency` call is
written with the target's corresponding package name, a ``REQUIRED``
argument, and any additional arguments specified by the ``EXTRA_ARGS``
argument of :command:`export(SETUP)`. Any package dependencies that were
manually specified by passing ``ENABLED ON`` to :command:`export(SETUP)`
are also added, even if the exported targets don't depend on any targets
from them.
The :command:`find_dependency` calls are written in the following order:
1. Any package dependencies that were listed in :command:`export(SETUP)`
are written in the order they were first specified, regardless of
whether or not they contain ``INTERFACE`` dependencies of the
exported targets.
2. Any package dependencies that contain ``INTERFACE`` link dependencies
of the exported targets and that were never specified in
:command:`export(SETUP)` are written in the order they were first
found.
The ``EXPORT`` form is useful to help outside projects use targets built
and installed by the current project. For example, the code
@ -864,16 +898,6 @@ Signatures
executable from the installation tree using the imported target name
``mp_myexe`` as if the target were built in its own tree.
.. note::
This command supersedes the :command:`install_targets` command and
the :prop_tgt:`PRE_INSTALL_SCRIPT` and :prop_tgt:`POST_INSTALL_SCRIPT`
target properties. It also replaces the ``FILES`` forms of the
:command:`install_files` and :command:`install_programs` commands.
The processing order of these install rules relative to
those generated by :command:`install_targets`,
:command:`install_files`, and :command:`install_programs` commands
is not defined.
.. signature::
install(RUNTIME_DEPENDENCY_SET <set-name> [...])
@ -937,6 +961,16 @@ Signatures
* ``POST_INCLUDE_FILES <file>...``
* ``POST_EXCLUDE_FILES <file>...``
.. note::
This command supersedes the :command:`install_targets` command and
the :prop_tgt:`PRE_INSTALL_SCRIPT` and :prop_tgt:`POST_INSTALL_SCRIPT`
target properties. It also replaces the ``FILES`` forms of the
:command:`install_files` and :command:`install_programs` commands.
The processing order of these install rules relative to
those generated by :command:`install_targets`,
:command:`install_files`, and :command:`install_programs` commands
is not defined.
Examples
^^^^^^^^

12
Help/command/project.rst
View File

@ -123,12 +123,12 @@ The following outlines the steps performed during a ``project()`` call:
* .. versionadded:: 3.15
For every ``project()`` call regardless of the project
name, include the file named by :variable:`CMAKE_PROJECT_INCLUDE_BEFORE`,
if set.
name, include the file(s) and module(s) named by
:variable:`CMAKE_PROJECT_INCLUDE_BEFORE`, if set.
* .. versionadded:: 3.17
If the ``project()`` command specifies ``<PROJECT-NAME>`` as its project
name, include the file named by
name, include the file(s) and module(s) named by
:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`, if set.
* Set the various project-specific variables detailed in the `Synopsis`_
@ -156,11 +156,11 @@ The following outlines the steps performed during a ``project()`` call:
* .. versionadded:: 3.15
For every ``project()`` call regardless of the project
name, include the file named by :variable:`CMAKE_PROJECT_INCLUDE`,
if set.
name, include the file(s) and module(s) named by
:variable:`CMAKE_PROJECT_INCLUDE`, if set.
* If the ``project()`` command specifies ``<PROJECT-NAME>`` as its project
name, include the file named by
name, include the file(s) and module(s) named by
:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, if set.
Usage

2
Help/command/qt_wrap_cpp.rst
View File

@ -8,7 +8,7 @@ qt_wrap_cpp
:module:`FindQt4` module provides the ``qt4_wrap_cpp()`` macro, which
should be used instead for Qt 4 projects. For projects using Qt 5 or
later, use the equivalent macro provided by Qt itself (e.g. Qt 5 provides
``qt5_wrap_cpp()``).
`qt5_wrap_cpp() <https://doc.qt.io/qt-5/qtcore-cmake-qt5-wrap-cpp.html>`_).
Manually create Qt Wrappers.

2
Help/command/return.rst
View File

@ -40,7 +40,7 @@ command. All arguments are ignored unless that policy is set to ``NEW``.
.. code-block:: cmake
:caption: CMakeLists.txt
cmake_version_required(VERSION 3.25)
cmake_minimum_required(VERSION 3.25)
project(example)
set(var1 "top-value")

12
Help/command/try_compile.rst
View File

@ -77,6 +77,7 @@ Try Compiling Source Files
[COMPILE_DEFINITIONS <defs>...]
[LINK_OPTIONS <options>...]
[LINK_LIBRARIES <libs>...]
[LINKER_LANGUAGE <lang>]
[OUTPUT_VARIABLE <var>]
[COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
[<LANG>_STANDARD <std>]
@ -177,6 +178,9 @@ The options for the above signatures are:
If this option is specified, any ``-DLINK_LIBRARIES=...`` value
given to the ``CMAKE_FLAGS`` option will be ignored.
.. versionadded:: 3.29
Alias targets to imported libraries are also supported.
``LINK_OPTIONS <options>...``
.. versionadded:: 3.14
@ -184,6 +188,14 @@ The options for the above signatures are:
set the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property in the generated
project, depending on the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable.
``LINKER_LANGUAGE <lang>``
.. versionadded:: 3.29
Specify the :prop_tgt:`LINKER_LANGUAGE` target property of the generated
project. When using multiple source files with different languages, set
this to the language of the source file containing the program entry point,
e.g., ``main``.
``LOG_DESCRIPTION <text>``
.. versionadded:: 3.26

1
Help/command/try_run.rst
View File

@ -67,6 +67,7 @@ The signature above is recommended for clarity.
[COMPILE_DEFINITIONS <defs>...]
[LINK_OPTIONS <options>...]
[LINK_LIBRARIES <libs>...]
[LINKER_LANGUAGE <lang>]
[COMPILE_OUTPUT_VARIABLE <var>]
[COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
[<LANG>_STANDARD <std>]

34
Help/cpack_gen/deb.rst
View File

@ -69,28 +69,32 @@ List of CPack DEB generator specific variables:
:Mandatory: Yes
:Default: ``<CPACK_PACKAGE_FILE_NAME>[-<component>].deb``
This may be set to ``DEB-DEFAULT`` to allow the CPack DEB generator to generate
package file name by itself in deb format::
This may be set to:
<PackageName>_<VersionNumber>-<DebianRevisionNumber>_<DebianArchitecture>.deb
``DEB-DEFAULT``
Tell CPack to automatically generate the package file name in deb format::
Alternatively provided package file name must end
with either ``.deb`` or ``.ipk`` suffix.
<PackageName>_<VersionNumber>-<DebianRevisionNumber>_<DebianArchitecture>.deb
.. versionadded:: 3.10
``.ipk`` suffix used by OPKG packaging system.
This setting recommended as the preferred behavior, but for backward
compatibility with the CPack DEB generator in CMake prior to version 3.6,
this is not the default. Without this, duplicate names may occur.
Duplicate files get overwritten and it is up to the packager to set
the variables in a manner that will prevent such errors.
.. note::
``<file-name>[.deb]``
Use the given file name.
Preferred setting of this variable is ``DEB-DEFAULT`` but for backward
compatibility with the CPack DEB generator in CMake prior to version 3.6 this
feature is disabled by default.
.. versionchanged:: 3.29
.. note::
The ``.deb`` suffix will be automatically added if the file name does
not end in ``.deb`` or ``.ipk``. Previously the suffix was required.
By using non default filenames duplicate names may occur. Duplicate files
get overwritten and it is up to the packager to set the variables in a
manner that will prevent such errors.
``<file-name>.ipk``
.. versionadded:: 3.10
Use the given file name.
The ``.ipk`` suffix is used by the OPKG packaging system.
.. variable:: CPACK_DEBIAN_PACKAGE_EPOCH

5
Help/cpack_gen/productbuild.rst
View File

@ -91,8 +91,9 @@ macOS using ProductBuild:
.. 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:
installed. When it is set to true (see policy :policy:`CMP0161`), a
``domains`` element of the following form will be added to the
productbuild Distribution XML:
.. code-block:: xml

15
Help/cpack_gen/rpm.rst
View File

@ -84,9 +84,18 @@ List of CPack RPM generator specific variables:
:Default: ``<CPACK_PACKAGE_FILE_NAME>[-<component>].rpm`` with spaces
replaced by '-'
This may be set to ``RPM-DEFAULT`` to allow ``rpmbuild`` tool to generate package
file name by itself.
Alternatively provided package file name must end with ``.rpm`` suffix.
This may be set to:
``RPM-DEFAULT``
Tell ``rpmbuild`` to automatically generate the package file name.
``<file-name>[.rpm]``
Use the given file name.
.. versionchanged:: 3.29
The ``.rpm`` suffix will be automatically added if missing.
Previously the suffix was required.
.. note::

31
Help/cpack_gen/wix.rst
View File

@ -119,7 +119,8 @@ Windows using WiX.
If this variable is set, the specified template will be used to generate
the WiX wxs file. This should be used if further customization of the
output is required.
output is required. The template contents will override the effect of most
``CPACK_WIX_`` variables.
If this variable is not set, the default MSI template included with CMake
will be used.
@ -337,3 +338,31 @@ Windows using WiX.
of the installer. May for example be set to ``x64`` or ``arm64``.
When unspecified, CPack will default to ``x64`` or ``x86``.
.. variable:: CPACK_WIX_INSTALL_SCOPE
.. versionadded:: 3.29
This variable can be optionally set to specify the ``InstallScope``
of the installer:
``perMachine`` (default)
Create an installer that installs for all users and requires
administrative privileges. Start menu entries created by the
installer are visible to all users.
``perUser``
Not yet supported. This is reserved for future use.
``NONE``
Create an installer without any ``InstallScope`` attribute.
.. deprecated:: 3.29
This value is only for compatibility with the inconsistent behavior used
by CPack 3.28 and older. The resulting installer requires administrative
privileges and installs into the system-wide ``ProgramFiles`` directory,
but the start menu entry and uninstaller registration are created only
for the current user.
See https://wixtoolset.org/docs/v3/xsd/wix/package/

8
Help/dev/documentation.rst
View File

@ -13,8 +13,8 @@ The ``Help`` directory contains CMake help manual source files.
They are written using the `reStructuredText`_ markup syntax and
processed by `Sphinx`_ to generate the CMake help manuals.
.. _`reStructuredText`: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
.. _`Sphinx`: http://sphinx-doc.org
.. _`reStructuredText`: https://docutils.sourceforge.net/docs/ref/rst/introduction.html
.. _`Sphinx`: https://sphinx-doc.org
Markup Constructs
-----------------
@ -338,7 +338,7 @@ Document a "variable" object:
The directive requires a single argument, the variable name.
.. _`Sphinx Domain`: http://sphinx-doc.org/domains.html
.. _`Sphinx Domain`: https://sphinx-doc.org/domains.html
.. _`cmake(1)`: https://cmake.org/cmake/help/latest/manual/cmake.1.html
.. _`cmake-env-variables(7)`: https://cmake.org/cmake/help/latest/manual/cmake-env-variables.7.html
.. _`cmake-generator-expressions(7)`: https://cmake.org/cmake/help/latest/manual/cmake-generator-expressions.7.html
@ -520,7 +520,7 @@ Style: Cross-References
Mark up linkable references as links, including repeats.
An alternative, which is used by wikipedia
(`<http://en.wikipedia.org/wiki/WP:REPEATLINK>`_),
(`<https://en.wikipedia.org/wiki/WP:REPEATLINK>`_),
is to link to a reference only once per article. That style is not used
in CMake documentation.

25
Help/dev/experimental.rst
View File

@ -13,3 +13,28 @@ specific values will change over time to reinforce their experimental nature.
When used, a warning will be generated to indicate that an experimental
feature is in use and that the affected behavior in the project is not part of
CMake's stability guarantees.
Export Package Dependencies
===========================
In order to activate support for this experimental feature, set
* variable ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES`` to
* value ``1942b4fa-b2c5-4546-9385-83f254070067``.
This UUID may change in future versions of CMake. Be sure to use the value
documented here by the source tree of the version of CMake with which you are
experimenting.
When activated, this experimental feature provides the following:
* The ``install(EXPORT)`` and ``export(EXPORT)`` commands have experimental
``EXPORT_PACKAGE_DEPENDENCIES`` arguments to generate ``find_dependency``
calls automatically.
* Details of the calls may be configured using the ``export(SETUP)``
command's ``PACKAGE_DEPENDENCY`` argument.
* The package name associated with specific targets may be specified
using the ``CMAKE_EXPORT_FIND_PACKAGE_NAME`` variable and/or
``EXPORT_FIND_PACKAGE_NAME`` target property.

16
Help/dev/maint.rst
View File

@ -8,6 +8,13 @@ See documentation on `CMake Development`_ for more information.
.. contents:: Maintainer Processes:
Governance
==========
CMake has no formal governance body. Maintainers expect one another to
cooperate constructively and make decisions in good faith. In cases of
disagreement, the chief maintainer retains final authority.
Review a Merge Request
======================
@ -332,15 +339,16 @@ Commit with a message such as::
away from setting policies to OLD.
Update the ``cmake_policy`` version range generated by ``install(EXPORT)``
in ``cmExportFileGenerator::GeneratePolicyHeaderCode`` to end at the
in ``cmExportFileGenerator::GeneratePolicyHeaderCode`` and
``install_jar_exports`` in ``javaTargets.cmake.in`` to end at the
previous release. We use one release back since we now know all the
policies added for that version. Commit with a message such as::
export: Increase maximum policy version in exported files to $prev
The files generated by `install(EXPORT)` and `export()` commands
are known to work with policies as of CMake $prev, so enable them
in sufficiently new CMake versions.
The files generated by `install(EXPORT)`, `export()`, and
`install_jar_exports()` commands are known to work with policies
as of CMake $prev, so enable them in sufficiently new CMake versions.
Update the ``cmake_minimum_required`` version range in CMake itself:

2
Help/dev/source.rst
View File

@ -16,7 +16,7 @@ format source code. It automatically runs ``clang-format`` on the set of
source files for which we enforce style. The script also has options to
format only a subset of files, such as those that are locally modified.
.. _`clang-format`: http://clang.llvm.org/docs/ClangFormat.html
.. _`clang-format`: https://clang.llvm.org/docs/ClangFormat.html
.. _`.clang-format`: ../../.clang-format
.. _`Utilities/Scripts/clang-format.bash`: ../../Utilities/Scripts/clang-format.bash

6
Help/dev/try_compile-linker-language.rst Normal file
View File

@ -0,0 +1,6 @@
try_compile-linker-language
---------------------------
* The :command:`try_compile` and :command:`try_run` commands gained a
``LINKER_LANGUAGE`` option to specify the :prop_tgt:`LINKER_LANGUAGE`
target property in the generated test project.

4
Help/envvar/CMAKE_BUILD_PARALLEL_LEVEL.rst
View File

@ -8,6 +8,10 @@ CMAKE_BUILD_PARALLEL_LEVEL
Specifies the maximum number of concurrent processes to use when building
using the ``cmake --build`` command line
:ref:`Build Tool Mode <Build Tool Mode>`.
For example, if ``CMAKE_BUILD_PARALLEL_LEVEL`` is set to 8, the
underlying build tool will execute up to 8 jobs concurrently as if
``cmake --build`` were invoked with the
:option:`--parallel 8 <cmake--build --parallel>` option.
If this variable is defined empty the native build tool's default number is
used.

11
Help/envvar/CMAKE_INSTALL_PREFIX.rst Normal file
View File

@ -0,0 +1,11 @@
CMAKE_INSTALL_PREFIX
--------------------
.. versionadded:: 3.29
.. include:: ENV_VAR.txt
The ``CMAKE_INSTALL_PREFIX`` environment variable specifies a custom default
value for the :variable:`CMAKE_INSTALL_PREFIX` variable in place of the
default values specified by CMake itself. The value specified must be an
absolute path to a directory.

11
Help/envvar/CMAKE_TEST_LAUNCHER.rst Normal file
View File

@ -0,0 +1,11 @@
CMAKE_TEST_LAUNCHER
-------------------
.. versionadded:: 3.29
.. include:: ENV_VAR.txt
The default value for the :variable:`CMAKE_TEST_LAUNCHER` variable when there
is no explicit configuration given on the first run while creating a new
build tree. On later runs in an existing build tree the value persists in
the cache as :variable:`CMAKE_TEST_LAUNCHER`.

19
Help/envvar/CTEST_PARALLEL_LEVEL.rst
View File

@ -3,5 +3,20 @@ CTEST_PARALLEL_LEVEL
.. include:: ENV_VAR.txt
Specify the number of tests for CTest to run in parallel. See :manual:`ctest(1)`
for more information on parallel test execution.
Specify the number of tests for CTest to run in parallel.
For example, if ``CTEST_PARALLEL_LEVEL`` is set to 8, CTest will run
up to 8 tests concurrently as if ``ctest`` were invoked with the
:option:`--parallel 8 <ctest --parallel>` option.
.. versionchanged:: 3.29
The value may be empty, or ``0``, to let ctest use a default level of
parallelism, or unbounded parallelism, respectively, as documented by
the :option:`ctest --parallel` option.
On Windows, environment variables cannot be set to an empty string.
CTest will interpret a whitespace-only string as empty.
In CMake 3.28 and earlier, an empty or ``0`` value was equivalent to ``1``.
See :manual:`ctest(1)` for more information on parallel test execution.

2
Help/guide/tutorial/Adding Generator Expressions.rst
View File

@ -24,7 +24,7 @@ Logical, Informational, and Output expressions.
Logical expressions are used to create conditional output. The basic
expressions are the ``0`` and ``1`` expressions. A ``$<0:...>`` results in the
empty string, and ``<1:...>`` results in the content of ``...``. They can also
empty string, and ``$<1:...>`` results in the content of ``...``. They can also
be nested.
Exercise 1 - Adding Compiler Warning Flags with Generator Expressions

8
Help/guide/tutorial/Adding a Library.rst
View File

@ -145,10 +145,10 @@ Next, the new library target is linked to the executable target using
</details>
Finally we need to specify the library's header file location. Modify
:command:`target_include_directories` to add the ``MathFunctions`` subdirectory
as an include directory so that the ``MathFunctions.h`` header file can be
found.
Finally we need to specify the library's header file location.
Modify the existing :command:`target_include_directories` call
to add the ``MathFunctions`` subdirectory as an include directory
so that the ``MathFunctions.h`` header file can be found.
.. raw:: html

2
Help/guide/tutorial/Step12/CMakeLists.txt
View File

@ -97,7 +97,7 @@ include(CMakePackageConfigHelpers)
# generate the config file that includes the exports
configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in
"${CMAKE_CURRENT_BINARY_DIR}/MathFunctionsConfig.cmake"
INSTALL_DESTINATION "lib/cmake/example"
INSTALL_DESTINATION "lib/cmake/MathFunctions"
NO_SET_AND_CHECK_MACRO
NO_CHECK_REQUIRED_COMPONENTS_MACRO
)

4
Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt
View File

@ -14,9 +14,9 @@ if (USE_MYMATH)
mysqrt.cxx
)
# TODO 7: Link SqrtLibrary to tutorial_compiler_flags
# TODO 6: Link SqrtLibrary to tutorial_compiler_flags
target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
endif()
# TODO 6: Link MathFunctions to tutorial_compiler_flags
# TODO 7: Link MathFunctions to tutorial_compiler_flags

2
Help/manual/CTEST_EXAMPLE_MAKEFILE_JOB_SERVER.make Normal file
View File

@ -0,0 +1,2 @@
test:
+ctest -j 8

1
Help/manual/cmake-compile-features.7.rst
View File

@ -266,6 +266,7 @@ versions specified for each:
* ``PGI``: PGI version 12.10+.
* ``NVHPC``: NVIDIA HPC compilers version 11.0+.
* ``TI``: Texas Instruments compiler.
* ``TIClang``: Texas Instruments Clang-based compilers.
* ``XL``: IBM XL version 10.1+.
CMake is currently aware of the :prop_tgt:`C standards <C_STANDARD>` and

2
Help/manual/cmake-configure-log.7.rst
View File

@ -56,7 +56,7 @@ step finished normally, ends with a ``...`` document marker line:
A new document is appended to the log every time CMake configures
the build tree and logs new events.
The keys of the each document root mapping are:
The keys of each document root mapping are:
``events``
A YAML block sequence of nodes corresponding to events logged during

2
Help/manual/cmake-env-variables.7.rst
View File

@ -50,12 +50,14 @@ Environment Variables that Control the Build
/envvar/CMAKE_GENERATOR_PLATFORM
/envvar/CMAKE_GENERATOR_TOOLSET
/envvar/CMAKE_INSTALL_MODE
/envvar/CMAKE_INSTALL_PREFIX
/envvar/CMAKE_LANG_COMPILER_LAUNCHER
/envvar/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES_EXCLUDE
/envvar/CMAKE_LANG_LINKER_LAUNCHER
/envvar/CMAKE_MSVCIDE_RUN_PATH
/envvar/CMAKE_NO_VERBOSE
/envvar/CMAKE_OSX_ARCHITECTURES
/envvar/CMAKE_TEST_LAUNCHER
/envvar/CMAKE_TOOLCHAIN_FILE
/envvar/DESTDIR
/envvar/LDFLAGS

32
Help/manual/cmake-file-api.7.rst
View File

@ -431,7 +431,7 @@ Version 1 does not exist to avoid confusion with that from
{
"kind": "codemodel",
"version": { "major": 2, "minor": 6 },
"version": { "major": 2, "minor": 7 },
"paths": {
"source": "/path/to/top-level-source-dir",
"build": "/path/to/top-level-build-dir"
@ -998,6 +998,36 @@ with members:
destination is available. The value is an unsigned integer 0-based
index into the ``backtraceGraph`` member's ``nodes`` array.
``launchers``
Optional member that is present on executable targets that have
at least one launcher specified by the project. The value is a
JSON array of entries corresponding to the specified launchers.
Each entry is a JSON object with members:
``command``
A string specifying the path to the launcher on disk, represented
with forward slashes. If the file is inside the top-level source
directory then the path is specified relative to that directory.
``arguments``
Optional member that is present when the launcher command has
arguments preceding the executable to be launched. The value
is a JSON array of strings representing the arguments.
``type``
A string specifying the type of launcher. The value is one of
the following:
``emulator``
An emulator for the target platform when cross-compiling.
See the :prop_tgt:`CROSSCOMPILING_EMULATOR` target property.
``test``
A start program for the execution of tests.
See the :prop_tgt:`TEST_LAUNCHER` target property.
This field was added in codemodel version 2.7.
``link``
Optional member that is present for executables and shared library
targets that link into a runtime binary. The value is a JSON object

23
Help/manual/cmake-generator-expressions.7.rst
View File

@ -1053,6 +1053,10 @@ related to most of the expressions in this sub-section.
``1`` if CMake's compiler id of the C compiler matches any one
of the entries in ``compiler_ids``, otherwise ``0``.
.. versionchanged:: 3.15
Multiple ``compiler_ids`` can be specified.
CMake 3.14 and earlier only accepted a single compiler ID.
.. genex:: $<CXX_COMPILER_ID>
CMake's compiler id of the CXX compiler used.
@ -1063,6 +1067,10 @@ related to most of the expressions in this sub-section.
``1`` if CMake's compiler id of the CXX compiler matches any one
of the entries in ``compiler_ids``, otherwise ``0``.
.. versionchanged:: 3.15
Multiple ``compiler_ids`` can be specified.
CMake 3.14 and earlier only accepted a single compiler ID.
.. genex:: $<CUDA_COMPILER_ID>
.. versionadded:: 3.15
@ -1115,6 +1123,10 @@ related to most of the expressions in this sub-section.
``1`` if CMake's compiler id of the Fortran compiler matches any one
of the entries in ``compiler_ids``, otherwise ``0``.
.. versionchanged:: 3.15
Multiple ``compiler_ids`` can be specified.
CMake 3.14 and earlier only accepted a single compiler ID.
.. genex:: $<HIP_COMPILER_ID>
.. versionadded:: 3.21
@ -2321,10 +2333,13 @@ Export And Install Expressions
Content of the install prefix when the target is exported via
:command:`install(EXPORT)`, or when evaluated in the
:prop_tgt:`INSTALL_NAME_DIR` property, the ``INSTALL_NAME_DIR`` argument of
:command:`install(RUNTIME_DEPENDENCY_SET)`, the code argument of
:command:`install(CODE)`, or the file argument of :command:`install(SCRIPT)`,
and empty otherwise.
:prop_tgt:`INSTALL_NAME_DIR` property or the ``INSTALL_NAME_DIR`` argument of
:command:`install(RUNTIME_DEPENDENCY_SET)`, and empty otherwise.
.. versionchanged:: 3.27
Evaluates to the content of the install prefix
in the code argument of :command:`install(CODE)` or
the file argument of :command:`install(SCRIPT)`.
Multi-level Expression Evaluation
---------------------------------

13
Help/manual/cmake-policies.7.rst
View File

@ -51,6 +51,19 @@ 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.29
=================================
.. toctree::
:maxdepth: 1
CMP0161: CPACK_PRODUCTBUILD_DOMAINS defaults to true. </policy/CMP0161>
CMP0160: More read-only target properties now error when trying to set them. </policy/CMP0160>
CMP0159: file(STRINGS) with REGEX updates CMAKE_MATCH_<n>. </policy/CMP0159>
CMP0158: add_test() honors CMAKE_CROSSCOMPILING_EMULATOR only when cross-compiling. </policy/CMP0158>
CMP0157: Swift compilation mode is selected by an abstraction. </policy/CMP0157>
CMP0156: De-duplicate libraries on link lines based on linker capabilities. </policy/CMP0156>
Policies Introduced by CMake 3.28
=================================

6
Help/manual/cmake-properties.7.rst
View File

@ -129,7 +129,9 @@ Properties on Targets
/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY_CONFIG
/prop_tgt/ARCHIVE_OUTPUT_NAME
/prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG
/prop_tgt/AUTOGEN_BETTER_GRAPH_MULTI_CONFIG
/prop_tgt/AUTOGEN_BUILD_DIR
/prop_tgt/AUTOGEN_COMMAND_LINE_LENGTH_MAX
/prop_tgt/AUTOGEN_ORIGIN_DEPENDS
/prop_tgt/AUTOGEN_PARALLEL
/prop_tgt/AUTOGEN_TARGET_DEPENDS
@ -211,6 +213,7 @@ Properties on Targets
/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD
/prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG
/prop_tgt/EXPORT_COMPILE_COMMANDS
/prop_tgt/EXPORT_FIND_PACKAGE_NAME
/prop_tgt/EXPORT_NAME
/prop_tgt/EXPORT_NO_SYSTEM
/prop_tgt/EXPORT_PROPERTIES
@ -334,6 +337,7 @@ Properties on Targets
/prop_tgt/LINK_SEARCH_START_STATIC
/prop_tgt/LINK_WHAT_YOU_USE
/prop_tgt/LINKER_LANGUAGE
/prop_tgt/LINKER_TYPE
/prop_tgt/LOCATION
/prop_tgt/LOCATION_CONFIG
/prop_tgt/MACHO_COMPATIBILITY_VERSION
@ -389,11 +393,13 @@ Properties on Targets
/prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG
/prop_tgt/STATIC_LIBRARY_OPTIONS
/prop_tgt/SUFFIX
/prop_tgt/Swift_COMPILATION_MODE
/prop_tgt/Swift_DEPENDENCIES_FILE
/prop_tgt/Swift_LANGUAGE_VERSION
/prop_tgt/Swift_MODULE_DIRECTORY
/prop_tgt/Swift_MODULE_NAME
/prop_tgt/SYSTEM
/prop_tgt/TEST_LAUNCHER
/prop_tgt/TYPE
/prop_tgt/UNITY_BUILD
/prop_tgt/UNITY_BUILD_BATCH_SIZE

72
Help/manual/cmake-qt.7.rst
View File

@ -10,34 +10,39 @@ cmake-qt(7)
Introduction
============
CMake can find and use Qt 4 and Qt 5 libraries. The Qt 4 libraries are found
by the :module:`FindQt4` find-module shipped with CMake, whereas the
Qt 5 libraries are found using "Config-file Packages" shipped with Qt 5. See
:manual:`cmake-packages(7)` for more information about CMake packages, and
see `the Qt cmake manual <https://doc.qt.io/qt-5/cmake-manual.html>`_
for your Qt version.
CMake can find and use Qt 4, Qt 5 and Qt 6 libraries. The Qt 4 libraries are
found by the :module:`FindQt4` find-module shipped with CMake, whereas the
Qt 5 and Qt 6 libraries are found using "Config-file Packages" shipped with
Qt 5 and Qt 6. See :manual:`cmake-packages(7)` for more information about CMake
packages, and see `the Qt cmake manual`_ for your Qt version.
Qt 4 and Qt 5 may be used together in the same
.. _`the Qt cmake manual`: https://doc.qt.io/qt-6/cmake-manual.html
Qt 4, Qt 5 and Qt 6 may be used together in the same
:manual:`CMake buildsystem <cmake-buildsystem(7)>`:
.. code-block:: cmake
cmake_minimum_required(VERSION 3.8.0 FATAL_ERROR)
cmake_minimum_required(VERSION 3.16 FATAL_ERROR)
project(Qt4And5)
project(Qt4_5_6)
set(CMAKE_AUTOMOC ON)
find_package(Qt5 COMPONENTS Widgets DBus REQUIRED)
find_package(Qt6 COMPONENTS Widgets DBus REQUIRED)
add_executable(publisher publisher.cpp)
target_link_libraries(publisher Qt5::Widgets Qt5::DBus)
target_link_libraries(publisher Qt6::Widgets Qt6::DBus)
find_package(Qt5 COMPONENTS Gui DBus REQUIRED)
add_executable(subscriber1 subscriber1.cpp)
target_link_libraries(subscriber1 Qt5::Gui Qt5::DBus)
find_package(Qt4 REQUIRED)
add_executable(subscriber subscriber.cpp)
target_link_libraries(subscriber Qt4::QtGui Qt4::QtDBus)
add_executable(subscriber2 subscriber2.cpp)
target_link_libraries(subscriber2 Qt4::QtGui Qt4::QtDBus)
A CMake target may not link to both Qt 4 and Qt 5. A diagnostic is issued if
this is attempted or results from transitive target dependency evaluation.
A CMake target may not link to more than one Qt version. A diagnostic is issued
if this is attempted or results from transitive target dependency evaluation.
Qt Build Tools
==============
@ -46,7 +51,7 @@ Qt relies on some bundled tools for code generation, such as ``moc`` for
meta-object code generation, ``uic`` for widget layout and population,
and ``rcc`` for virtual file system content generation. These tools may be
automatically invoked by :manual:`cmake(1)` if the appropriate conditions
are met. The automatic tool invocation may be used with both Qt 4 and Qt 5.
are met. The automatic tool invocation may be used with Qt version 4 to 6.
.. _`Qt AUTOMOC`:
@ -158,7 +163,7 @@ should be used when running ``uic``:
.. code-block:: cmake
add_library(KI18n klocalizedstring.cpp)
target_link_libraries(KI18n Qt5::Core)
target_link_libraries(KI18n Qt6::Core)
# KI18n uses the tr2i18n() function instead of tr(). That function is
# declared in the klocalizedstring.h header.
@ -213,25 +218,44 @@ overrides options from the :prop_tgt:`AUTORCC_OPTIONS` target property.
Source files can be excluded from :prop_tgt:`AUTORCC` processing by
enabling :prop_sf:`SKIP_AUTORCC` or the broader :prop_sf:`SKIP_AUTOGEN`.
.. _`<ORIGIN>_autogen`:
The ``<ORIGIN>_autogen`` target
===============================
The ``moc`` and ``uic`` tools are executed as part of a synthesized
``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` generated by
CMake. By default that ``<ORIGIN>_autogen`` target inherits the dependencies
:ref:`<ORIGIN>_autogen` :command:`custom target <add_custom_target>` generated by
CMake. By default that :ref:`<ORIGIN>_autogen` target inherits the dependencies
of the ``<ORIGIN>`` target (see :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`).
Target dependencies may be added to the ``<ORIGIN>_autogen`` target by adding
Target dependencies may be added to the :ref:`<ORIGIN>_autogen` target by adding
them to the :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property.
.. note::
If Qt 5.15 or later is used and the generator is either :generator:`Ninja` or
:ref:`Makefile Generators`, see :ref:`<ORIGIN>_autogen_timestamp_deps`.
.. _`<ORIGIN>_autogen_timestamp_deps`:
The ``<ORIGIN>_autogen_timestamp_deps`` target
==============================================
If Qt 5.15 or later is used and the generator is either :generator:`Ninja` or
:ref:`Makefile Generators`, the ``<ORIGIN>_autogen_timestamp_deps`` target is
also created in addition to the :ref:`<ORIGIN>_autogen` target. This target
does not have any sources or commands to execute, but it has dependencies that
were previously inherited by the pre-Qt 5.15 :ref:`<ORIGIN>_autogen` target.
These dependencies will serve as a list of order-only dependencies for the
custom command, without forcing the custom command to re-execute.
Visual Studio Generators
========================
When using the :manual:`Visual Studio generators <cmake-generators(7)>`, CMake
generates a ``PRE_BUILD`` :command:`custom command <add_custom_command>`
instead of the ``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>`
(for :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`).
This isn't always possible though and
an ``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` is used,
instead of the :ref:`<ORIGIN>_autogen`
:command:`custom target <add_custom_target>` (for :prop_tgt:`AUTOMOC` and
:prop_tgt:`AUTOUIC`). This isn't always possible though and an
:ref:`<ORIGIN>_autogen` :command:`custom target <add_custom_target>` is used,
when either
- the ``<ORIGIN>`` target depends on :prop_sf:`GENERATED` files which aren't

100
Help/manual/cmake-variables.7.rst
View File

@ -55,7 +55,6 @@ Variables that Provide Information
/variable/CMAKE_EDIT_COMMAND
/variable/CMAKE_EXECUTABLE_SUFFIX
/variable/CMAKE_EXECUTABLE_SUFFIX_LANG
/variable/CMAKE_EXTRA_GENERATOR
/variable/CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES
/variable/CMAKE_FIND_DEBUG_MODE
/variable/CMAKE_FIND_PACKAGE_NAME
@ -74,6 +73,10 @@ Variables that Provide Information
/variable/CMAKE_JOB_POOLS
/variable/CMAKE_LANG_COMPILER_AR
/variable/CMAKE_LANG_COMPILER_FRONTEND_VARIANT
/variable/CMAKE_LANG_COMPILER_LINKER
/variable/CMAKE_LANG_COMPILER_LINKER_FRONTEND_VARIANT
/variable/CMAKE_LANG_COMPILER_LINKER_ID
/variable/CMAKE_LANG_COMPILER_LINKER_VERSION
/variable/CMAKE_LANG_COMPILER_RANLIB
/variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX
/variable/CMAKE_LINK_LIBRARY_SUFFIX
@ -111,8 +114,10 @@ Variables that Provide Information
/variable/CMAKE_SOURCE_DIR
/variable/CMAKE_STATIC_LIBRARY_PREFIX
/variable/CMAKE_STATIC_LIBRARY_SUFFIX
/variable/CMAKE_Swift_COMPILATION_MODE
/variable/CMAKE_Swift_MODULE_DIRECTORY
/variable/CMAKE_Swift_NUM_THREADS
/variable/CMAKE_TEST_LAUNCHER
/variable/CMAKE_TOOLCHAIN_FILE
/variable/CMAKE_TWEAK_VERSION
/variable/CMAKE_VERBOSE_MAKEFILE
@ -126,6 +131,7 @@ Variables that Provide Information
/variable/CMAKE_VS_PLATFORM_TOOLSET
/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA
/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR
/variable/CMAKE_VS_PLATFORM_TOOLSET_FORTRAN
/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE
/variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION
/variable/CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER
@ -169,8 +175,6 @@ Variables that Change Behavior
/variable/CMAKE_ABSOLUTE_DESTINATION_FILES
/variable/CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY
/variable/CMAKE_APPBUNDLE_PATH
/variable/CMAKE_AUTOMOC_RELAXED_MODE
/variable/CMAKE_BACKWARDS_COMPATIBILITY
/variable/CMAKE_BUILD_TYPE
/variable/CMAKE_CLANG_VFS_OVERLAY
/variable/CMAKE_CODEBLOCKS_COMPILER_ID
@ -198,8 +202,6 @@ Variables that Change Behavior
/variable/CMAKE_FIND_LIBRARY_PREFIXES
/variable/CMAKE_FIND_LIBRARY_SUFFIXES
/variable/CMAKE_FIND_NO_INSTALL_PREFIX
/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY
/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY
/variable/CMAKE_FIND_PACKAGE_PREFER_CONFIG
/variable/CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS
/variable/CMAKE_FIND_PACKAGE_TARGETS_GLOBAL
@ -251,6 +253,7 @@ Variables that Change Behavior
/variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES
/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName
/variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY
/variable/CMAKE_SKIP_TEST_ALL_DEPENDENCY
/variable/CMAKE_STAGING_PREFIX
/variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS
/variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE
@ -336,15 +339,6 @@ Variables that Describe the System
/variable/LINUX
/variable/MINGW
/variable/MSVC
/variable/MSVC10
/variable/MSVC11
/variable/MSVC12
/variable/MSVC14
/variable/MSVC60
/variable/MSVC70
/variable/MSVC71
/variable/MSVC80
/variable/MSVC90
/variable/MSVC_IDE
/variable/MSVC_TOOLSET_VERSION
/variable/MSVC_VERSION
@ -395,6 +389,8 @@ Variables that Control the Build
/variable/CMAKE_APPLE_SILICON_PROCESSOR
/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY
/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG
/variable/CMAKE_AUTOGEN_BETTER_GRAPH_MULTI_CONFIG
/variable/CMAKE_AUTOGEN_COMMAND_LINE_LENGTH_MAX
/variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS
/variable/CMAKE_AUTOGEN_PARALLEL
/variable/CMAKE_AUTOGEN_USE_SYSTEM_INCLUDE
@ -439,6 +435,7 @@ Variables that Control the Build
/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG
/variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT
/variable/CMAKE_EXE_LINKER_FLAGS_INIT
/variable/CMAKE_EXPORT_FIND_PACKAGE_NAME
/variable/CMAKE_FOLDER
/variable/CMAKE_Fortran_FORMAT
/variable/CMAKE_Fortran_MODULE_DIRECTORY
@ -459,7 +456,6 @@ Variables that Control the Build
/variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH
/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION
/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION_CONFIG
/variable/CMAKE_IOS_INSTALL_COMBINED
/variable/CMAKE_LANG_CLANG_TIDY
/variable/CMAKE_LANG_CLANG_TIDY_EXPORT_FIXES_DIR
/variable/CMAKE_LANG_COMPILER_LAUNCHER
@ -474,6 +470,8 @@ Variables that Control the Build
/variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE_SUPPORTED
/variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG
/variable/CMAKE_LANG_LINKER_LAUNCHER
/variable/CMAKE_LANG_USING_LINKER_MODE
/variable/CMAKE_LANG_USING_LINKER_TYPE
/variable/CMAKE_LANG_VISIBILITY_PRESET
/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY
/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG
@ -490,6 +488,7 @@ Variables that Control the Build
/variable/CMAKE_LINK_LIBRARY_USING_FEATURE_SUPPORTED
/variable/CMAKE_LINK_WHAT_YOU_USE
/variable/CMAKE_LINK_WHAT_YOU_USE_CHECK
/variable/CMAKE_LINKER_TYPE
/variable/CMAKE_MACOSX_BUNDLE
/variable/CMAKE_MACOSX_RPATH
/variable/CMAKE_MAP_IMPORTED_CONFIG_CONFIG
@ -534,7 +533,6 @@ Variables that Control the Build
/variable/CMAKE_UNITY_BUILD
/variable/CMAKE_UNITY_BUILD_BATCH_SIZE
/variable/CMAKE_UNITY_BUILD_UNIQUE_ID
/variable/CMAKE_USE_RELATIVE_PATHS
/variable/CMAKE_VERIFY_INTERFACE_HEADER_SETS
/variable/CMAKE_VISIBILITY_INLINES_HIDDEN
/variable/CMAKE_VS_DEBUGGER_COMMAND
@ -571,9 +569,6 @@ Variables for Languages
/variable/CMAKE_C_EXTENSIONS
/variable/CMAKE_C_STANDARD
/variable/CMAKE_C_STANDARD_REQUIRED
/variable/CMAKE_COMPILER_IS_GNUCC
/variable/CMAKE_COMPILER_IS_GNUCXX
/variable/CMAKE_COMPILER_IS_GNUG77
/variable/CMAKE_CUDA_ARCHITECTURES
/variable/CMAKE_CUDA_COMPILE_FEATURES
/variable/CMAKE_CUDA_EXTENSIONS
@ -693,7 +688,6 @@ Variables for CTest
/variable/CTEST_CUSTOM_TESTS_IGNORE
/variable/CTEST_CUSTOM_WARNING_EXCEPTION
/variable/CTEST_CUSTOM_WARNING_MATCH
/variable/CTEST_CVS_CHECKOUT
/variable/CTEST_CVS_COMMAND
/variable/CTEST_CVS_UPDATE_OPTIONS
/variable/CTEST_DROP_LOCATION
@ -722,7 +716,6 @@ Variables for CTest
/variable/CTEST_P4_UPDATE_OPTIONS
/variable/CTEST_RESOURCE_SPEC_FILE
/variable/CTEST_RUN_CURRENT_SCRIPT
/variable/CTEST_SCP_COMMAND
/variable/CTEST_SCRIPT_DIRECTORY
/variable/CTEST_SITE
/variable/CTEST_SOURCE_DIRECTORY
@ -733,7 +726,6 @@ Variables for CTest
/variable/CTEST_SVN_UPDATE_OPTIONS
/variable/CTEST_TEST_LOAD
/variable/CTEST_TEST_TIMEOUT
/variable/CTEST_TRIGGER_SITE
/variable/CTEST_UPDATE_COMMAND
/variable/CTEST_UPDATE_OPTIONS
/variable/CTEST_UPDATE_VERSION_ONLY
@ -786,3 +778,67 @@ are subject to change, and not recommended for use in project code.
/variable/CMAKE_LANG_PLATFORM_ID
/variable/CMAKE_NOT_USING_CONFIG_FLAGS
/variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION
Deprecated Variables that Provide Information
=============================================
.. toctree::
:maxdepth: 1
/variable/CMAKE_EXTRA_GENERATOR
Deprecated Variables that Change Behavior
=========================================
.. toctree::
:maxdepth: 1
/variable/CMAKE_AUTOMOC_RELAXED_MODE
/variable/CMAKE_BACKWARDS_COMPATIBILITY
/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY
/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY
Deprecated Variables that Describe the System
=============================================
.. toctree::
:maxdepth: 1
/variable/MSVC10
/variable/MSVC11
/variable/MSVC12
/variable/MSVC14
/variable/MSVC60
/variable/MSVC70
/variable/MSVC71
/variable/MSVC80
/variable/MSVC90
Deprecated Variables that Control the Build
===========================================
.. toctree::
:maxdepth: 1
/variable/CMAKE_IOS_INSTALL_COMBINED
/variable/CMAKE_USE_RELATIVE_PATHS
Deprecated Variables for Languages
==================================
.. toctree::
:maxdepth: 1
/variable/CMAKE_COMPILER_IS_GNUCC
/variable/CMAKE_COMPILER_IS_GNUCXX
/variable/CMAKE_COMPILER_IS_GNUG77
Deprecated Variables for CTest
==============================
.. toctree::
:maxdepth: 1
/variable/CTEST_CVS_CHECKOUT
/variable/CTEST_SCP_COMMAND
/variable/CTEST_TRIGGER_SITE

5
Help/manual/cmake.1.rst
View File

@ -891,6 +891,10 @@ Available commands are:
``-`` will result in an error. Use ``--`` to indicate the end of options, in
case a file starts with ``-``.
.. versionadded:: 3.29
``cat`` can now print the standard input by passing the ``-`` argument.
.. program:: cmake-E
.. option:: chdir <dir> <cmd> [<arg>...]
@ -1311,6 +1315,7 @@ The following ``cmake -E`` commands are available only on Windows:
Write Windows registry value.
.. _`Find-Package Tool Mode`:
Run the Find-Package Tool
=========================

85
Help/manual/ctest.1.rst
View File

@ -118,17 +118,27 @@ Run Tests
previously interrupted. If no interruption occurred, the ``-F`` option
will have no effect.
.. option:: -j <jobs>, --parallel <jobs>
.. option:: -j [<level>], --parallel [<level>]
Run the tests in parallel using the given number of jobs.
Run tests in parallel, optionally limited to a given level of parallelism.
This option tells CTest to run the tests in parallel using given
number of jobs. This option can also be set by setting the
:envvar:`CTEST_PARALLEL_LEVEL` environment variable.
.. versionadded:: 3.29
The ``<level>`` may be omitted, or ``0``, in which case:
* Under `Job Server Integration`_, parallelism is limited by
available job tokens.
* Otherwise, if the value is omitted, parallelism is limited
by the number of processors, or 2, whichever is larger.
* Otherwise, if the value is ``0``, parallelism is unbounded.
This option may instead be specified by the :envvar:`CTEST_PARALLEL_LEVEL`
environment variable.
This option can be used with the :prop_test:`PROCESSORS` test property.
See `Label and Subproject Summary`_.
See the `Label and Subproject Summary`_.
.. option:: --resource-spec-file <file>
@ -234,6 +244,30 @@ Run Tests
of the test's labels (i.e. the multiple ``-LE`` labels form an ``AND``
relationship). See `Label Matching`_.
.. option:: --tests-from-file <filename>
.. versionadded:: 3.29
Run tests listed in the given file.
This option tells CTest to run tests that are listed in the given file.
The file must contain one exact test name per line.
Lines that do not exactly match any test names are ignored.
This option can be combined with the other options like
``-R``, ``-E``, ``-L`` or ``-LE``.
.. option:: --exclude-from-file <filename>
.. versionadded:: 3.29
Exclude tests listed in the given file.
This option tells CTest to NOT run tests that are listed in the given file.
The file must contain one exact test name per line.
Lines that do not exactly match any test names are ignored.
This option can be combined with the other options like
``-R``, ``-E``, ``-L`` or ``-LE``.
.. option:: -FA <regex>, --fixture-exclude-any <regex>
Exclude fixtures matching ``<regex>`` from automatically adding any tests to
@ -354,6 +388,8 @@ Run Tests
.. option:: --test-dir <dir>
.. versionadded:: 3.20
Specify the directory in which to look for tests, typically a CMake project
build directory. If not specified, the current directory is used.
@ -752,6 +788,16 @@ The available ``<dashboard-options>`` are the following:
This option will submit extra files to the dashboard.
.. option:: --http-header <header>
.. versionadded:: 3.29
Append HTTP header when submitting to the dashboard.
This option will cause CTest to append the specified header
when submitting to the dashboard.
This option may be specified more than once.
.. option:: --http1.0
Submit using `HTTP 1.0`.
@ -1847,6 +1893,31 @@ fixture in their :prop_test:`FIXTURES_REQUIRED`, and a resource spec file may
not be specified with the ``--resource-spec-file`` argument or the
:variable:`CTEST_RESOURCE_SPEC_FILE` variable.
.. _`ctest-job-server-integration`:
Job Server Integration
======================
.. versionadded:: 3.29
On POSIX systems, when running under the context of a `Job Server`_,
CTest shares its job slots. This is independent of the :prop_test:`PROCESSORS`
test property, which still counts against CTest's :option:`-j <ctest -j>`
parallel level. CTest acquires exactly one token from the job server before
running each test, and returns it when the test finishes.
For example, consider the ``Makefile``:
.. literalinclude:: CTEST_EXAMPLE_MAKEFILE_JOB_SERVER.make
:language: make
When invoked via ``make -j 2 test``, ``ctest`` connects to the job server,
acquires a token for each test, and runs at most 2 tests concurrently.
On Windows systems, job server integration is not yet implemented.
.. _`Job Server`: https://www.gnu.org/software/make/manual/html_node/Job-Slots.html
See Also
========

6
Help/policy/CMP0001.rst
View File

@ -14,8 +14,8 @@ and the :command:`cmake_policy` command. However, CMake must still check
``CMAKE_BACKWARDS_COMPATIBILITY`` for projects written for CMake 2.4 and
below.
This policy was introduced in CMake version 2.6.0. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 2.6.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0002.rst
View File

@ -21,8 +21,8 @@ physical name while keeping logical names distinct. Custom targets
must simply have globally unique names (unless one uses the global
property :prop_gbl:`ALLOW_DUPLICATE_CUSTOM_TARGETS` with a Makefiles generator).
This policy was introduced in CMake version 2.6.0. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 2.6.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0003.rst
View File

@ -97,8 +97,8 @@ Note that the warning for this policy will be issued for at most one
target. This avoids flooding users with messages for every target
when setting the policy once will probably fix all targets.
This policy was introduced in CMake version 2.6.0. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 2.6.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0004.rst
View File

@ -19,8 +19,8 @@ policy used when checking the library names is that in effect when the
target is created by an :command:`add_executable` or :command:`add_library`
command.
This policy was introduced in CMake version 2.6.0. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 2.6.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0005.rst
View File

@ -19,8 +19,8 @@ generate correct escapes for all native build tools automatically.
See documentation of the ``COMPILE_DEFINITIONS`` target property for
limitations of the escaping implementation.
This policy was introduced in CMake version 2.6.0. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 2.6.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0006.rst
View File

@ -17,8 +17,8 @@ The ``OLD`` behavior for this policy is to fall back to the
behavior for this policy is to produce an error if a bundle target is installed
without a ``BUNDLE DESTINATION``.
This policy was introduced in CMake version 2.6.0. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 2.6.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0007.rst
View File

@ -10,8 +10,8 @@ and not 4. The ``OLD`` behavior for this policy is to ignore empty list
elements. The ``NEW`` behavior for this policy is to correctly count
empty elements in a list.
This policy was introduced in CMake version 2.6.0. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 2.6.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0008.rst
View File

@ -28,8 +28,8 @@ split the library name from the path and ask the linker to search for
it. The ``NEW`` behavior for this policy is to trust the given path and
pass it directly to the native build tool unchanged.
This policy was introduced in CMake version 2.6.1. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 2.6.1
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0009.rst
View File

@ -14,8 +14,8 @@ policy is to follow the symlinks. The ``NEW`` behavior for this policy is not
to follow the symlinks by default, but only if ``FOLLOW_SYMLINKS`` is given
as an additional argument to the ``FILE`` command.
This policy was introduced in CMake version 2.6.2. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 2.6.2
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0010.rst
View File

@ -13,8 +13,8 @@ The ``NEW`` behavior for this policy is to report an error.
If :policy:`CMP0053` is set to ``NEW``, this policy has no effect
and is treated as always being ``NEW``.
This policy was introduced in CMake version 2.6.3. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 2.6.3
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0011.rst
View File

@ -18,8 +18,8 @@ compatibility. The ``OLD`` behavior for this policy is to imply
The ``NEW`` behavior for this policy is to allow the commands to do
their default cmake_policy ``PUSH`` and ``POP``.
This policy was introduced in CMake version 2.6.3. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 2.6.3
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0012.rst
View File

@ -21,8 +21,8 @@ variables named like numbers and boolean constants. The ``NEW`` behavior
for this policy is to recognize numbers and boolean constants without
dereferencing variables with such names.
This policy was introduced in CMake version 2.8.0. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 2.8.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0013.rst
View File

@ -14,8 +14,8 @@ this policy is to allow duplicate binary directories. The NEW
behavior for this policy is to disallow duplicate binary directories
with an error.
This policy was introduced in CMake version 2.8.0. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 2.8.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0014.rst
View File

@ -10,8 +10,8 @@ treating them as if present but empty. In CMake 2.8.0 and above this
The ``OLD`` behavior for this policy is to silently ignore the problem.
The ``NEW`` behavior for this policy is to report an error.
This policy was introduced in CMake version 2.8.0. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 2.8.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0015.rst
View File

@ -12,8 +12,8 @@ this policy is to use relative paths verbatim in the linker command. The
``NEW`` behavior for this policy is to convert relative paths to absolute
paths by appending the relative path to ``CMAKE_CURRENT_SOURCE_DIR``.
This policy was introduced in CMake version 2.8.1. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 2.8.1
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0016.rst
View File

@ -9,8 +9,8 @@ ignored if it was called with only one argument, and this argument
wasn't a valid target. In CMake 2.8.3 and above it reports an error
in this case.
This policy was introduced in CMake version 2.8.3. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 2.8.3
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0017.rst
View File

@ -14,8 +14,8 @@ precedence over the ones in the CMake module directory. The ``OLD``
behavior is to always prefer files from CMAKE_MODULE_PATH over files
from the CMake modules directory.
This policy was introduced in CMake version 2.8.4. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 2.8.4
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

7
Help/policy/CMP0018.rst
View File

@ -27,9 +27,8 @@ The ``NEW`` behavior for this policy is to ignore
``CMAKE_SHARED_LIBRARY_<Lang>_FLAGS`` whether it is modified or not and
honor the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property.
This policy was introduced in CMake version 2.8.9. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW``
explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 2.8.9
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0019.rst
View File

@ -15,8 +15,8 @@ The ``OLD`` behavior for this policy is to re-evaluate the values for
strict compatibility. The ``NEW`` behavior for this policy is to leave
the values untouched.
This policy was introduced in CMake version 2.8.11. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 2.8.11
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0020.rst
View File

@ -20,8 +20,8 @@ The ``OLD`` behavior for this policy is not to link executables to
The ``NEW`` behavior for this policy is to link executables to ``qtmain.lib``
automatically when they link to QtCore ``IMPORTED`` target.
This policy was introduced in CMake version 2.8.11. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 2.8.11
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0021.rst
View File

@ -14,8 +14,8 @@ in the ``INCLUDE_DIRECTORIES`` target property. The ``NEW`` behavior for this
policy is to issue a ``FATAL_ERROR`` if ``INCLUDE_DIRECTORIES`` contains a
relative path.
This policy was introduced in CMake version 2.8.12. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 2.8.12
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0022.rst
View File

@ -32,8 +32,8 @@ The ``NEW`` behavior for this policy is to use the ``INTERFACE_LINK_LIBRARIES``
property for in-build targets, and ignore the old properties matching
``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?``.
This policy was introduced in CMake version 2.8.12. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 2.8.12
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0023.rst
View File

@ -28,8 +28,8 @@ The ``OLD`` behavior for this policy is to allow keyword and plain
this policy is to not to allow mixing of the keyword and plain
signatures.
This policy was introduced in CMake version 2.8.12. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 2.8.12
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

7
Help/policy/CMP0024.rst
View File

@ -17,9 +17,8 @@ The ``OLD`` behavior for this policy is to allow including the result of
an :command:`export` command. The ``NEW`` behavior for this policy is not to
allow including the result of an :command:`export` command.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW``
explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

8
Help/policy/CMP0025.rst
View File

@ -18,10 +18,10 @@ to the invocation of either command.
The ``OLD`` behavior for this policy is to use compiler id ``Clang``. The
``NEW`` behavior for this policy is to use compiler id ``AppleClang``.
This policy was introduced in CMake version 3.0. 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.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn by default
.. include:: STANDARD_ADVICE.txt
See documentation of the
:variable:`CMAKE_POLICY_WARNING_CMP0025 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
variable to control the warning.

6
Help/policy/CMP0026.rst
View File

@ -22,8 +22,8 @@ The ``OLD`` behavior for this policy is to allow reading the :prop_tgt:`LOCATION
properties from build-targets. The ``NEW`` behavior for this policy is to
not to allow reading the :prop_tgt:`LOCATION` properties from build-targets.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0027.rst
View File

@ -20,8 +20,8 @@ The ``NEW`` behavior of this policy is to report an error if an entry in
the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of a generator-expression
conditionally linked ``IMPORTED`` target does not exist.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0028.rst
View File

@ -20,8 +20,8 @@ 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
double-colons but is not an ``IMPORTED`` target or an ``ALIAS`` target.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0037.rst
View File

@ -27,8 +27,8 @@ reserved names or which do not match the validity pattern.
The ``NEW`` behavior for this policy is to report an error
if an add_* command is used with an invalid target name.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0038.rst
View File

@ -11,8 +11,8 @@ The ``OLD`` behavior for this policy is to ignore targets which list themselves
in their own link implementation. The ``NEW`` behavior for this policy is to
report an error if a target attempts to link to itself.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0039.rst
View File

@ -12,8 +12,8 @@ libraries of utility targets. The ``NEW`` behavior for this policy is to
report an error if an attempt is made to set the link libraries of a
utility target.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

7
Help/policy/CMP0040.rst
View File

@ -13,9 +13,8 @@ for unknown targets. The ``NEW`` behavior for this policy is to report
an error if the target referenced in :command:`add_custom_command` is
unknown or was defined outside the current directory.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior.
Use the :command:`cmake_policy` command to set it to ``OLD`` or
``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0041.rst
View File

@ -20,8 +20,8 @@ contain a generator expression. The ``NEW`` behavior for this policy is to repor
an error if a generator expression appears in another location and the path is
relative.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0042.rst
View File

@ -14,8 +14,8 @@ wanting ``@rpath`` in a target's install name may remove any setting of
the :prop_tgt:`INSTALL_NAME_DIR` and :variable:`CMAKE_INSTALL_NAME_DIR`
variables.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0043.rst
View File

@ -40,8 +40,8 @@ The ``OLD`` behavior for this policy is to consume the content of the suffixed
compilation command. The ``NEW`` behavior for this policy is to ignore the content
of the :prop_tgt:`COMPILE_DEFINITIONS_<CONFIG>` target property .
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0044.rst
View File

@ -14,8 +14,8 @@ with the value in the ``<LANG>_COMPILER_ID`` expression. The ``NEW`` behavior
for this policy is to perform a case-sensitive comparison with the value in
the ``<LANG>_COMPILER_ID`` expression.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

6
Help/policy/CMP0045.rst
View File

@ -12,8 +12,8 @@ variable to a ``-NOTFOUND`` value. The ``NEW`` behavior
for this policy is to issue a ``FATAL_ERROR`` if the command is called with a
non-existent target.
This policy was introduced in CMake version 3.0. CMake version
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

7
Help/policy/CMP0046.rst
View File

@ -11,9 +11,8 @@ dependencies. The ``NEW`` behavior for this policy is to report an error
if non-existent dependencies are listed in the :command:`add_dependencies`
command.
This policy was introduced in CMake version 3.0.
CMake version |release| warns when the policy is not set and uses
``OLD`` behavior. Use the :command:`cmake_policy` command to set it
to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

8
Help/policy/CMP0047.rst
View File

@ -19,10 +19,10 @@ The ``OLD`` behavior for this policy is to use the ``GNU`` compiler id
for the qcc and QCC compiler drivers. The ``NEW`` behavior for this policy
is to use the ``QCC`` compiler id for those drivers.
This policy was introduced in CMake version 3.0. 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.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn by default
.. include:: STANDARD_ADVICE.txt
See documentation of the
:variable:`CMAKE_POLICY_WARNING_CMP0047 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
variable to control the warning.

7
Help/policy/CMP0048.rst
View File

@ -16,9 +16,8 @@ The ``OLD`` behavior for this policy is to leave ``VERSION`` variables untouched
The ``NEW`` behavior for this policy is to set ``VERSION`` as documented by the
:command:`project` command.
This policy was introduced in CMake version 3.0.
CMake version |release| warns when the policy is not set and uses
``OLD`` behavior. Use the :command:`cmake_policy` command to set
it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

7
Help/policy/CMP0049.rst
View File

@ -17,9 +17,8 @@ The ``OLD`` behavior for this policy is to expand such variables when processing
the target sources. The ``NEW`` behavior for this policy is to issue an error
if such variables need to be expanded.
This policy was introduced in CMake version 3.0.
CMake version |release| warns when the policy is not set and uses
``OLD`` behavior. Use the :command:`cmake_policy` command to set
it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

7
Help/policy/CMP0050.rst
View File

@ -12,9 +12,8 @@ The ``OLD`` behavior for this policy is to allow the use of
:command:`add_custom_command` SOURCE signatures. The ``NEW`` behavior for this
policy is to issue an error if such a signature is used.
This policy was introduced in CMake version 3.0.
CMake version |release| warns when the policy is not set and uses
``OLD`` behavior. Use the :command:`cmake_policy` command to set it to ``OLD`` or
``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.0
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

7
Help/policy/CMP0051.rst
View File

@ -20,9 +20,8 @@ expressions from the :prop_tgt:`SOURCES` target property. The ``NEW``
behavior for this policy is to include ``TARGET_OBJECTS`` expressions
in the output.
This policy was introduced in CMake version 3.1.
CMake version |release| warns when the policy is not set and uses
``OLD`` behavior. Use the :command:`cmake_policy` command to set it
to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.1
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

7
Help/policy/CMP0052.rst
View File

@ -21,9 +21,8 @@ The ``OLD`` behavior for this policy is to export the content of the
directory. The ``NEW`` behavior for this
policy is to issue an error if such a directory is used.
This policy was introduced in CMake version 3.1.
CMake version |release| warns when the policy is not set and uses
``OLD`` behavior. Use the :command:`cmake_policy` command to set it
to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.1
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

7
Help/policy/CMP0053.rst
View File

@ -44,9 +44,8 @@ The ``OLD`` behavior for this policy is to honor the legacy behavior for
variable references and escape sequences. The ``NEW`` behavior is to
use the simpler variable expansion and escape sequence evaluation rules.
This policy was introduced in CMake version 3.1.
CMake version |release| warns when the policy is not set and uses
``OLD`` behavior. Use the :command:`cmake_policy` command to set
it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.1
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

7
Help/policy/CMP0054.rst
View File

@ -46,9 +46,8 @@ further dereferenced:
if("E" STREQUAL "")
This policy was introduced in CMake version 3.1.
CMake version |release| warns when the policy is not set and uses
``OLD`` behavior. Use the :command:`cmake_policy` command to set
it to ``OLD`` or ``NEW`` explicitly.
.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.1
.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
.. include:: STANDARD_ADVICE.txt
.. include:: DEPRECATED.txt

Some files were not shown because too many files have changed in this diff Show More