summaryrefslogtreecommitdiffstats
path: root/Help/manual
diff options
context:
space:
mode:
Diffstat (limited to 'Help/manual')
-rw-r--r--Help/manual/OPTIONS_BUILD.txt8
-rw-r--r--Help/manual/cmake-compile-features.7.rst1
-rw-r--r--Help/manual/cmake-developer.7.rst18
-rw-r--r--Help/manual/cmake-file-api.7.rst265
-rw-r--r--Help/manual/cmake-generator-expressions.7.rst23
-rw-r--r--Help/manual/cmake-policies.7.rst9
-rw-r--r--Help/manual/cmake-presets.7.rst140
-rw-r--r--Help/manual/cmake-properties.7.rst1
-rw-r--r--Help/manual/cmake-toolchains.7.rst4
-rw-r--r--Help/manual/cmake-variables.7.rst2
-rw-r--r--Help/manual/ctest.1.rst50
-rw-r--r--Help/manual/presets/example.json13
-rw-r--r--Help/manual/presets/schema.json498
13 files changed, 978 insertions, 54 deletions
diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt
index 0947e41..c4f83f7 100644
--- a/Help/manual/OPTIONS_BUILD.txt
+++ b/Help/manual/OPTIONS_BUILD.txt
@@ -76,6 +76,14 @@
native build system to choose a compiler or SDK. See the
:variable:`CMAKE_GENERATOR_PLATFORM` variable for details.
+``--toolchain <path-to-file>``
+ Specify the cross compiling toolchain file, equivalant to setting
+ :variable:`CMAKE_TOOLCHAIN_FILE` variable.
+
+``--install-prefix <directory>``
+ Specify the installation directory, used by the
+ :variable:`CMAKE_INSTALL_PREFIX` variable. Must be an absolute path.
+
``-Wno-dev``
Suppress developer warnings.
diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst
index 0d15ddf..56d16c0 100644
--- a/Help/manual/cmake-compile-features.7.rst
+++ b/Help/manual/cmake-compile-features.7.rst
@@ -359,6 +359,7 @@ following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the
versions specified for each:
* ``Cray``: Cray Compiler Environment version 8.1+.
+* ``Fujitsu``: Fujitsu HPC compiler 4.0+.
* ``PGI``: PGI version 12.10+.
* ``NVHPC``: NVIDIA HPC compilers version 11.0+.
* ``TI``: Texas Instruments compiler.
diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst
index af9a8ab..fe146de 100644
--- a/Help/manual/cmake-developer.7.rst
+++ b/Help/manual/cmake-developer.7.rst
@@ -350,6 +350,24 @@ look.
PATHS ${PC_Foo_LIBRARY_DIRS}
)
+Alternatively, if the library is available with multiple configurations, you can
+use :module:`SelectLibraryConfigurations` to automatically set the
+``Foo_LIBRARY`` variable instead:
+
+.. code-block:: cmake
+
+ find_library(Foo_LIBRARY_RELEASE
+ NAMES foo
+ PATHS ${PC_Foo_LIBRARY_DIRS}/Release
+ )
+ find_library(Foo_LIBRARY_DEBUG
+ NAMES foo
+ PATHS ${PC_Foo_LIBRARY_DIRS}/Debug
+ )
+
+ include(SelectLibraryConfigurations)
+ select_library_configurations(Foo)
+
If you have a good way of getting the version (from a header file, for
example), you can use that information to set ``Foo_VERSION`` (although
note that find modules have traditionally used ``Foo_VERSION_STRING``,
diff --git a/Help/manual/cmake-file-api.7.rst b/Help/manual/cmake-file-api.7.rst
index 89739b7..cbc3d6d 100644
--- a/Help/manual/cmake-file-api.7.rst
+++ b/Help/manual/cmake-file-api.7.rst
@@ -443,7 +443,8 @@ Version 1 does not exist to avoid confusion with that from
"hasInstallRule": true,
"minimumCMakeVersion": {
"string": "3.14"
- }
+ },
+ "jsonFile": "<file>"
},
{
"source": "sub",
@@ -453,7 +454,8 @@ Version 1 does not exist to avoid confusion with that from
"targetIndexes": [ 1 ],
"minimumCMakeVersion": {
"string": "3.14"
- }
+ },
+ "jsonFile": "<file>"
}
],
"projects": [
@@ -569,6 +571,13 @@ The members specific to ``codemodel`` objects are:
:command:`install` rules, i.e. whether a ``make install``
or equivalent rule is available.
+ ``jsonFile``
+ A JSON string specifying a path relative to the codemodel file
+ to another JSON file containing a
+ `"codemodel" version 2 "directory" object`_.
+
+ This field was added in codemodel version 2.3.
+
``projects``
A JSON array of entries corresponding to the top-level project
and sub-projects defined in the build system. Each (sub-)project
@@ -633,6 +642,182 @@ The members specific to ``codemodel`` objects are:
to another JSON file containing a
`"codemodel" version 2 "target" object`_.
+"codemodel" version 2 "directory" object
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A codemodel "directory" object is referenced by a `"codemodel" version 2`_
+object's ``directories`` array. Each "directory" object is a JSON object
+with members:
+
+``paths``
+ A JSON object containing members:
+
+ ``source``
+ A string specifying the path to the source directory, represented
+ with forward slashes. If the directory is inside the top-level
+ source directory then the path is specified relative to that
+ directory (with ``.`` for the top-level source directory itself).
+ Otherwise the path is absolute.
+
+ ``build``
+ A string specifying the path to the build directory, represented
+ with forward slashes. If the directory is inside the top-level
+ build directory then the path is specified relative to that
+ directory (with ``.`` for the top-level build directory itself).
+ Otherwise the path is absolute.
+
+``installers``
+ A JSON array of entries corresponding to :command:`install` rules.
+ Each entry is a JSON object containing members:
+
+ ``component``
+ A string specifying the component selected by the corresponding
+ :command:`install` command invocation.
+
+ ``destination``
+ Optional member that is present for specific ``type`` values below.
+ The value is a string specifying the install destination path.
+ The path may be absolute or relative to the install prefix.
+
+ ``paths``
+ Optional member that is present for specific ``type`` values below.
+ The value is a JSON array of entries corresponding to the paths
+ (files or directories) to be installed. Each entry is one of:
+
+ * A string specifying the path from which a file or directory
+ is to be installed. The portion of the path not preceded by
+ a ``/`` also specifies the path (name) to which the file
+ or directory is to be installed under the destination.
+
+ * A JSON object with members:
+
+ ``from``
+ A string specifying the path from which a file or directory
+ is to be installed.
+
+ ``to``
+ A string specifying the path to which the file or directory
+ is to be installed under the destination.
+
+ In both cases the paths are represented with forward slashes. If
+ the "from" path is inside the top-level directory documented by the
+ corresponding ``type`` value, then the path is specified relative
+ to that directory. Otherwise the path is absolute.
+
+ ``type``
+ A string specifying the type of installation rule. The value is one
+ of the following, with some variants providing additional members:
+
+ ``file``
+ An :command:`install(FILES)` or :command:`install(PROGRAMS)` call.
+ The ``destination`` and ``paths`` members are populated, with paths
+ under the top-level *source* directory expressed relative to it.
+ The ``isOptional`` member may exist.
+ This type has no additional members.
+
+ ``directory``
+ An :command:`install(DIRECTORY)` call.
+ The ``destination`` and ``paths`` members are populated, with paths
+ under the top-level *source* directory expressed relative to it.
+ The ``isOptional`` member may exist.
+ This type has no additional members.
+
+ ``target``
+ An :command:`install(TARGETS)` call.
+ The ``destination`` and ``paths`` members are populated, with paths
+ under the top-level *build* directory expressed relative to it.
+ The ``isOptional`` member may exist.
+ This type has additional members ``targetId``, ``targetIndex``,
+ ``targetIsImportLibrary``, and ``targetInstallNamelink``.
+
+ ``export``
+ An :command:`install(EXPORT)` call.
+ The ``destination`` and ``paths`` members are populated, with paths
+ under the top-level *build* directory expressed relative to it.
+ The ``paths`` entries refer to files generated automatically by
+ CMake for installation, and their actual values are considered
+ private implementation details.
+ This type has additional members ``exportName`` and ``exportTargets``.
+
+ ``script``
+ An :command:`install(SCRIPT)` call.
+ This type has additional member ``scriptFile``.
+
+ ``code``
+ An :command:`install(CODE)` call.
+ This type has no additional members.
+
+ ``isExcludeFromAll``
+ Optional member that is present with boolean value ``true`` when
+ :command:`install` is called with the ``EXCLUDE_FROM_ALL`` option.
+
+ ``isOptional``
+ Optional member that is present with boolean value ``true`` when
+ :command:`install` is called with the ``OPTIONAL`` option.
+ This is allowed when ``type`` is ``file``, ``directory``, or ``target``.
+
+ ``targetId``
+ Optional member that is present when ``type`` is ``target``.
+ The value is a string uniquely identifying the target to be installed.
+ This matches the ``id`` member of the target in the main
+ "codemodel" object's ``targets`` array.
+
+ ``targetIndex``
+ Optional member that is present when ``type`` is ``target``.
+ The value is an unsigned integer 0-based index into the main "codemodel"
+ object's ``targets`` array for the target to be installed.
+
+ ``targetIsImportLibrary``
+ Optional member that is present when ``type`` is ``target`` and
+ the installer is for a Windows DLL import library file or for an
+ AIX linker import file. If present, it has boolean value ``true``.
+
+ ``targetInstallNamelink``
+ Optional member that is present when ``type`` is ``target`` and
+ the installer corresponds to a target that may use symbolic links
+ to implement the :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION`
+ target properties.
+ The value is a string indicating how the installer is supposed to
+ handle the symlinks: ``skip`` means the installer should skip the
+ symlinks and install only the real file, and ``only`` means the
+ installer should install only the symlinks and not the real file.
+ In all cases the ``paths`` member lists what it actually installs.
+
+ ``exportName``
+ Optional member that is present when ``type`` is ``export``.
+ The value is a string specifying the name of the export.
+
+ ``exportTargets``
+ Optional member that is present when ``type`` is ``export``.
+ The value is a JSON array of entries corresponding to the targets
+ included in the export. Each entry is a JSON object with members:
+
+ ``id``
+ A string uniquely identifying the target. This matches
+ the ``id`` member of the target in the main "codemodel"
+ object's ``targets`` array.
+
+ ``index``
+ An unsigned integer 0-based index into the main "codemodel"
+ object's ``targets`` array for the target.
+
+ ``scriptFile``
+ Optional member that is present when ``type`` is ``script``.
+ The value is a string specifying the path to the script file on disk,
+ represented with forward slashes. If the file is inside the top-level
+ source directory then the path is specified relative to that directory.
+ Otherwise the path is absolute.
+
+ ``backtrace``
+ Optional member that is present when a CMake language backtrace to
+ the :command:`install` or other command invocation that added this
+ installer is available. The value is an unsigned integer 0-based
+ index into the ``backtraceGraph`` member's ``nodes`` array.
+
+``backtraceGraph``
+ A `"codemodel" version 2 "backtrace graph"`_ whose nodes are referenced
+ from ``backtrace`` members elsewhere in this "directory" object.
+
"codemodel" version 2 "target" object
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -964,40 +1149,48 @@ with members:
with forward slashes.
``backtraceGraph``
- A JSON object describing the graph of backtraces whose nodes are
- referenced from ``backtrace`` members elsewhere. The members are:
-
- ``nodes``
- A JSON array listing nodes in the backtrace graph. Each entry
- is a JSON object with members:
-
- ``file``
- An unsigned integer 0-based index into the backtrace ``files`` array.
-
- ``line``
- An optional member present when the node represents a line within
- the file. The value is an unsigned integer 1-based line number.
-
- ``command``
- An optional member present when the node represents a command
- invocation within the file. The value is an unsigned integer
- 0-based index into the backtrace ``commands`` array.
-
- ``parent``
- An optional member present when the node is not the bottom of
- the call stack. The value is an unsigned integer 0-based index
- of another entry in the backtrace ``nodes`` array.
-
- ``commands``
- A JSON array listing command names referenced by backtrace nodes.
- Each entry is a string specifying a command name.
-
- ``files``
- A JSON array listing CMake language files referenced by backtrace nodes.
- Each entry is a string specifying the path to a file, represented
- with forward slashes. If the file is inside the top-level source
- directory then the path is specified relative to that directory.
- Otherwise the path is absolute.
+ A `"codemodel" version 2 "backtrace graph"`_ whose nodes are referenced
+ from ``backtrace`` members elsewhere in this "target" object.
+
+"codemodel" version 2 "backtrace graph"
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``backtraceGraph`` member of a `"codemodel" version 2 "directory" object`_,
+or `"codemodel" version 2 "target" object`_ is a JSON object describing a
+graph of backtraces. Its nodes are referenced from ``backtrace`` members
+elsewhere in the containing object. The backtrace graph object members are:
+
+``nodes``
+ A JSON array listing nodes in the backtrace graph. Each entry
+ is a JSON object with members:
+
+ ``file``
+ An unsigned integer 0-based index into the backtrace ``files`` array.
+
+ ``line``
+ An optional member present when the node represents a line within
+ the file. The value is an unsigned integer 1-based line number.
+
+ ``command``
+ An optional member present when the node represents a command
+ invocation within the file. The value is an unsigned integer
+ 0-based index into the backtrace ``commands`` array.
+
+ ``parent``
+ An optional member present when the node is not the bottom of
+ the call stack. The value is an unsigned integer 0-based index
+ of another entry in the backtrace ``nodes`` array.
+
+``commands``
+ A JSON array listing command names referenced by backtrace nodes.
+ Each entry is a string specifying a command name.
+
+``files``
+ A JSON array listing CMake language files referenced by backtrace nodes.
+ Each entry is a string specifying the path to a file, represented
+ with forward slashes. If the file is inside the top-level source
+ directory then the path is specified relative to that directory.
+ Otherwise the path is absolute.
Object Kind "cache"
-------------------
diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst
index 7bc490f..775067a 100644
--- a/Help/manual/cmake-generator-expressions.7.rst
+++ b/Help/manual/cmake-generator-expressions.7.rst
@@ -940,6 +940,29 @@ which is just the string ``tgt``.
:ref:`Target Usage Requirements` this is the consuming target rather
than the target specifying the requirement.
+.. genex:: $<TARGET_RUNTIME_DLLS:tgt>
+
+ List of DLLs that the target depends on at runtime. This is determined by
+ the locations of all the ``SHARED`` and ``MODULE`` targets in the target's
+ transitive dependencies. Using this generator expression on targets other
+ than executables, ``SHARED`` libraries, and ``MODULE`` libraries is an error.
+ On non-DLL platforms, it evaluates to an empty string.
+
+ This generator expression can be used to copy all of the DLLs that a target
+ depends on into its output directory in a ``POST_BUILD`` custom command. For
+ example:
+
+ .. code-block:: cmake
+
+ find_package(foo REQUIRED)
+
+ add_executable(exe main.c)
+ target_link_libraries(exe PRIVATE foo::foo foo::bar)
+ add_custom_command(TARGET exe POST_BUILD
+ COMMAND ${CMAKE_COMMAND} -E copy $<TARGET_RUNTIME_DLLS:exe> $<TARGET_FILE_DIR:exe>
+ COMMAND_EXPAND_LISTS
+ )
+
.. genex:: $<INSTALL_PREFIX>
Content of the install prefix when the target is exported via
diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index bd6b2f0..5dfa894 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -51,6 +51,15 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used
to determine whether to report an error on use of deprecated macros or
functions.
+Policies Introduced by CMake 3.21
+=================================
+
+.. toctree::
+ :maxdepth: 1
+
+ CMP0122: UseSWIG use standard library name conventions for csharp language. </policy/CMP0122>
+ CMP0121: The list command detects invalid indicies. </policy/CMP0121>
+
Policies Introduced by CMake 3.20
=================================
diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst
index 467818d..3714004 100644
--- a/Help/manual/cmake-presets.7.rst
+++ b/Help/manual/cmake-presets.7.rst
@@ -39,7 +39,7 @@ The root object recognizes the following fields:
``version``
A required integer representing the version of the JSON schema.
- The supported versions are ``1`` and ``2``.
+ The supported versions are ``1``, ``2``, and ``3``.
``cmakeMinimumRequired``
@@ -70,17 +70,17 @@ The root object recognizes the following fields:
``configurePresets``
An optional array of `Configure Preset`_ objects.
- This is allowed in preset files specifying version 1 or above.
+ This is allowed in preset files specifying version ``1`` or above.
``buildPresets``
An optional array of `Build Preset`_ objects.
- This is allowed in preset files specifying version 2 or above.
+ This is allowed in preset files specifying version ``2`` or above.
``testPresets``
An optional array of `Test Preset`_ objects.
- This is allowed in preset files specifying version 2 or above.
+ This is allowed in preset files specifying version ``2`` or above.
Configure Preset
^^^^^^^^^^^^^^^^
@@ -119,6 +119,11 @@ that may contain the following fields:
This field can also be a string, which is equivalent to an array
containing one string.
+``condition``
+
+ An optional `Condition`_ object. This is allowed in preset files specifying
+ version ``3`` or above.
+
``vendor``
An optional map containing vendor-specific information. CMake does not
@@ -140,7 +145,9 @@ that may contain the following fields:
An optional string representing the generator to use for the preset. If
``generator`` is not specified, it must be inherited from the
- ``inherits`` preset (unless this preset is ``hidden``).
+ ``inherits`` preset (unless this preset is ``hidden``). In version ``3``
+ or above, this field may be omitted to fall back to regular generator
+ discovery procedure.
Note that for Visual Studio generators, unlike in the command line ``-G``
argument, you cannot include the platform name in the generator name. Use
@@ -181,7 +188,15 @@ that may contain the following fields:
This field supports `macro expansion`_. If a relative path is specified,
it is calculated relative to the source directory. If ``binaryDir`` is not
specified, it must be inherited from the ``inherits`` preset (unless this
- preset is ``hidden``).
+ preset is ``hidden``). In version ``3`` or above, this field may be
+ omitted.
+
+``installDir``
+
+ An optional string representing the path to the installation directory.
+ This field supports `macro expansion`_. If a relative path is specified,
+ it is calculated relative to the source directory. This is allowed in
+ preset files specifying version ``3`` or above.
``cmakeExecutable``
@@ -338,6 +353,11 @@ that may contain the following fields:
This field can also be a string, which is equivalent to an array
containing one string.
+``condition``
+
+ An optional `Condition`_ object. This is allowed in preset files specifying
+ version ``3`` or above.
+
``vendor``
An optional map containing vendor-specific information. CMake does not
@@ -457,6 +477,11 @@ that may contain the following fields:
This field can also be a string, which is equivalent to an array
containing one string.
+``condition``
+
+ An optional `Condition`_ object. This is allowed in preset files specifying
+ version ``3`` or above.
+
``vendor``
An optional map containing vendor-specific information. CMake does not
@@ -782,6 +807,103 @@ that may contain the following fields:
Equivalent to passing ``--no-tests=ignore`` on the command line.
+Condition
+^^^^^^^^^
+
+The ``condition`` field of a preset, allowed in preset files specifying version
+``3`` or above, is used to determine whether or not the preset is enabled. For
+example, this can be used to disable a preset on platforms other than Windows.
+``condition`` may be either a boolean, ``null``, or an object. If it is a
+boolean, the boolean indicates whether the preset is enabled or disabled. If it
+is ``null``, the preset is enabled, but the ``null`` condition is not inherited
+by any presets that may inherit from the preset. Sub-conditions (for example in
+a ``not``, ``anyOf``, or ``allOf`` condition) may not be ``null``. If it is an
+object, it has the following fields:
+
+``type``
+
+ A required string with one of the following values:
+
+ ``"const"``
+
+ Indicates that the condition is constant. This is equivalent to using a
+ boolean in place of the object. The condition object will have the
+ following additional fields:
+
+ ``value``
+
+ A required boolean which provides a constant value for the condition's
+ evaluation.
+
+ ``"equals"``
+
+ ``"notEquals"``
+
+ Indicates that the condition compares two strings to see if they are equal
+ (or not equal). The condition object will have the following additional
+ fields:
+
+ ``lhs``
+
+ First string to compare. This field supports macro expansion.
+
+ ``rhs``
+
+ Second string to compare. This field supports macro expansion.
+
+ ``"inList"``
+
+ ``"notInList"``
+
+ Indicates that the condition searches for a string in a list of strings.
+ The condition object will have the following additional fields:
+
+ ``string``
+
+ A required string to search for. This field supports macro expansion.
+
+ ``list``
+
+ A required list of strings to search. This field supports macro
+ expansion, and uses short-circuit evaluation.
+
+ ``"matches"``
+
+ ``"notMatches"``
+
+ Indicates that the condition searches for a regular expression in a string.
+ The condition object will have the following additional fields:
+
+ ``string``
+
+ A required string to search. This field supports macro expansion.
+
+ ``regex``
+
+ A required regular expression to search for. This field supports macro
+ expansion.
+
+ ``"anyOf"``
+
+ ``"allOf"``
+
+ Indicates that the condition is an aggregation of zero or more nested
+ conditions. The condition object will have the following additional fields:
+
+ ``conditions``
+
+ A required array of condition objects. These conditions use short-circuit
+ evaluation.
+
+ ``"not"``
+
+ Indicates that the condition is an inversion of another condition. The
+ condition object will have the following additional fields:
+
+ ``condition``
+
+ A required condition object.
+
Macro Expansion
^^^^^^^^^^^^^^^
@@ -823,6 +945,12 @@ Recognized macros include:
test presets, this will evaluate to the generator specified by
``configurePreset``.
+``${hostSystemName}``
+
+ The name of the host operating system. Contains the same value as
+ :variable:`CMAKE_HOST_SYSTEM_NAME`. This is allowed in preset files
+ specifying version ``3`` or above.
+
``${dollar}``
A literal dollar sign (``$``).
diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index af170da..60a4028 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -21,6 +21,7 @@ Properties of Global Scope
/prop_gbl/AUTOMOC_SOURCE_GROUP
/prop_gbl/AUTOMOC_TARGETS_FOLDER
/prop_gbl/AUTORCC_SOURCE_GROUP
+ /prop_gbl/AUTOUIC_SOURCE_GROUP
/prop_gbl/CMAKE_C_KNOWN_FEATURES
/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES
/prop_gbl/CMAKE_CXX_KNOWN_FEATURES
diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst
index 1ededee..a941310 100644
--- a/Help/manual/cmake-toolchains.7.rst
+++ b/Help/manual/cmake-toolchains.7.rst
@@ -96,8 +96,8 @@ Cross Compiling
===============
If :manual:`cmake(1)` is invoked with the command line parameter
-``-DCMAKE_TOOLCHAIN_FILE=path/to/file``, the file will be loaded early to set
-values for the compilers.
+``--toolchain path/to/file`` or ``-DCMAKE_TOOLCHAIN_FILE=path/to/file``, the
+file will be loaded early to set values for the compilers.
The :variable:`CMAKE_CROSSCOMPILING` variable is set to true when CMake is
cross-compiling.
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 4317dd4..37ef053 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -130,6 +130,7 @@ Variables that Provide Information
/variable/PROJECT-NAME_BINARY_DIR
/variable/PROJECT-NAME_DESCRIPTION
/variable/PROJECT-NAME_HOMEPAGE_URL
+ /variable/PROJECT-NAME_IS_TOP_LEVEL
/variable/PROJECT-NAME_SOURCE_DIR
/variable/PROJECT-NAME_VERSION
/variable/PROJECT-NAME_VERSION_MAJOR
@@ -139,6 +140,7 @@ Variables that Provide Information
/variable/PROJECT_BINARY_DIR
/variable/PROJECT_DESCRIPTION
/variable/PROJECT_HOMEPAGE_URL
+ /variable/PROJECT_IS_TOP_LEVEL
/variable/PROJECT_NAME
/variable/PROJECT_SOURCE_DIR
/variable/PROJECT_VERSION
diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst
index 175359d..68409e1 100644
--- a/Help/manual/ctest.1.rst
+++ b/Help/manual/ctest.1.rst
@@ -155,7 +155,10 @@ Options
Run tests with labels matching regular expression.
This option tells CTest to run only the tests whose labels match the
- given regular expression.
+ given regular expression. When more than one ``-L`` option is given,
+ a test will only be run if each regular expression matches at least one
+ of the test's labels (i.e. the multiple ``-L`` labels form an ``AND``
+ relationship). See `Label Matching`_.
``-R <regex>, --tests-regex <regex>``
Run tests matching regular expression.
@@ -173,7 +176,10 @@ Options
Exclude tests with labels matching regular expression.
This option tells CTest to NOT run the tests whose labels match the
- given regular expression.
+ given regular expression. When more than one ``-LE`` option is given,
+ a test will only be excluded if each regular expression matches at least one
+ of the test's labels (i.e. the multiple ``-LE`` labels form an ``AND``
+ relationship). See `Label Matching`_.
``-FA <regex>, --fixture-exclude-any <regex>``
Exclude fixtures matching ``<regex>`` from automatically adding any tests to
@@ -398,6 +404,46 @@ Specify the directory in which to look for tests.
.. include:: OPTIONS_HELP.txt
+.. _`Label Matching`:
+
+Label Matching
+==============
+
+Tests may have labels attached to them. Tests may be included
+or excluded from a test run by filtering on the labels.
+Each individual filter is a regular expression applied to
+the labels attached to a test.
+
+When ``-L`` is used, in order for a test to be included in a
+test run, each regular expression must match at least one
+label. Using more than one ``-L`` option means "match **all**
+of these".
+
+The ``-LE`` option works just like ``-L``, but excludes tests
+rather than including them. A test is excluded if each regular
+expression matches at least one label.
+
+If a test has no labels attached to it, then ``-L`` will never
+include that test, and ``-LE`` will never exclude that test.
+As an example of tests with labels, consider five tests,
+with the following labels:
+
+* *test1* has labels *tuesday* and *production*
+* *test2* has labels *tuesday* and *test*
+* *test3* has labels *wednesday* and *production*
+* *test4* has label *wednesday*
+* *test5* has labels *friday* and *test*
+
+Running ``ctest`` with ``-L tuesday -L test`` will select *test2*, which has
+both labels. Running CTest with ``-L test`` will select *test2* and
+*test5*, because both of them have a label that matches that regular
+expression.
+
+Because the matching works with regular expressions, take note that
+running CTest with ``-L es`` will match all five tests.
+To select the *tuesday* and *wednesday* tests together, use a single
+regular expression that matches either of them, like ``-L "tue|wed"``.
+
.. _`Label and Subproject Summary`:
Label and Subproject Summary
diff --git a/Help/manual/presets/example.json b/Help/manual/presets/example.json
index dfc2910..346f342 100644
--- a/Help/manual/presets/example.json
+++ b/Help/manual/presets/example.json
@@ -1,5 +1,5 @@
{
- "version": 2,
+ "version": 3,
"cmakeMinimumRequired": {
"major": 3,
"minor": 20,
@@ -35,6 +35,17 @@
"displayName": "Ninja Multi-Config",
"description": "Default build using Ninja Multi-Config generator",
"generator": "Ninja Multi-Config"
+ },
+ {
+ "name": "windows-only",
+ "inherits": "default",
+ "displayName": "Windows-only configuration",
+ "description": "This build is only available on Windows",
+ "condition": {
+ "type": "equals",
+ "lhs": "${hostSystemName}",
+ "rhs": "Windows"
+ }
}
],
"buildPresets": [
diff --git a/Help/manual/presets/schema.json b/Help/manual/presets/schema.json
index f8faf3d..e066362 100644
--- a/Help/manual/presets/schema.json
+++ b/Help/manual/presets/schema.json
@@ -11,7 +11,7 @@
},
"cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"},
"vendor": { "$ref": "#/definitions/vendor" },
- "configurePresets": { "$ref": "#/definitions/configurePresets"}
+ "configurePresets": { "$ref": "#/definitions/configurePresetsV1"}
},
"additionalProperties": false
},
@@ -23,9 +23,23 @@
},
"cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"},
"vendor": { "$ref": "#/definitions/vendor" },
- "configurePresets": { "$ref": "#/definitions/configurePresets"},
- "buildPresets": { "$ref": "#/definitions/buildPresets"},
- "testPresets": { "$ref": "#/definitions/testPresets"}
+ "configurePresets": { "$ref": "#/definitions/configurePresetsV1"},
+ "buildPresets": { "$ref": "#/definitions/buildPresetsV2"},
+ "testPresets": { "$ref": "#/definitions/testPresetsV2"}
+ },
+ "additionalProperties": false
+ },
+ {
+ "properties": {
+ "version": {
+ "const": 3,
+ "description": "A required integer representing the version of the JSON schema."
+ },
+ "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"},
+ "vendor": { "$ref": "#/definitions/vendor" },
+ "configurePresets": { "$ref": "#/definitions/configurePresetsV3"},
+ "buildPresets": { "$ref": "#/definitions/buildPresetsV3"},
+ "testPresets": { "$ref": "#/definitions/testPresetsV3"}
},
"additionalProperties": false
}
@@ -58,7 +72,30 @@
"description": "An optional map containing vendor-specific information. CMake does not interpret the contents of this field except to verify that it is a map if it does exist. However, the keys should be a vendor-specific domain name followed by a /-separated path. For example, the Example IDE 1.0 could use example.com/ExampleIDE/1.0. The value of each field can be anything desired by the vendor, though will typically be a map.",
"properties": {}
},
- "configurePresets": {
+ "configurePresetsItemsV3": {
+ "type": "array",
+ "description": "A configure preset object.",
+ "items": {
+ "type": "object",
+ "description": "A configure preset object.",
+ "properties": {
+ "binaryDir": {
+ "type": "string",
+ "description": "An optional string representing the path to the output binary directory. This field supports macro expansion. If a relative path is specified, it is calculated relative to the source directory. If binaryDir is not specified, the path is calculated using regular methods."
+ },
+ "generator": {
+ "type": "string",
+ "description": "An optional string representing the generator to use for the preset. If generator is not specified, the normal generator discovery procedure is used. Note that for Visual Studio generators, unlike in the command line -G argument, you cannot include the platform name in the generator name. Use the architecture field instead."
+ },
+ "installDir": {
+ "type": "string",
+ "description": "An optional string representing the path to the output binary directory. This field supports macro expansion. If a relative path is specified, it is calculated relative to the source directory. If binaryDir is not specified, it must be inherited from the inherits preset (unless this preset is hidden)."
+ },
+ "condition": { "$ref": "#/definitions/topCondition" }
+ }
+ }
+ },
+ "configurePresetsItemsV1": {
"type": "array",
"description": "An optional array of configure preset objects.",
"items": {
@@ -302,6 +339,67 @@
},
"additionalProperties": false
}
+ }
+ }
+ },
+ "configurePresetsV3": {
+ "type": "array",
+ "description": "An optional array of configure preset objects.",
+ "allOf": [
+ { "$ref": "#/definitions/configurePresetsItemsV1" },
+ { "$ref": "#/definitions/configurePresetsItemsV3" }
+ ],
+ "items": {
+ "properties": {
+ "name": {},
+ "hidden": {},
+ "inherits": {},
+ "vendor": {},
+ "displayName": {},
+ "description": {},
+ "generator": {},
+ "architecture": {},
+ "toolset": {},
+ "binaryDir": {},
+ "installDir": {},
+ "cmakeExecutable": {},
+ "cacheVariables": {},
+ "environment": {},
+ "warnings": {},
+ "errors": {},
+ "debug": {},
+ "condition": {}
+ },
+ "required": [
+ "name"
+ ],
+ "additionalProperties": false
+ }
+ },
+ "configurePresetsV1": {
+ "type": "array",
+ "description": "An optional array of configure preset objects.",
+ "allOf": [
+ { "$ref": "#/definitions/configurePresetsItemsV1" }
+ ],
+ "items": {
+ "properties": {
+ "name": {},
+ "hidden": {},
+ "inherits": {},
+ "vendor": {},
+ "displayName": {},
+ "description": {},
+ "generator": {},
+ "architecture": {},
+ "toolset": {},
+ "binaryDir": {},
+ "cmakeExecutable": {},
+ "cacheVariables": {},
+ "environment": {},
+ "warnings": {},
+ "errors": {},
+ "debug": {}
},
"required": [
"name"
@@ -309,7 +407,17 @@
"additionalProperties": false
}
},
- "buildPresets": {
+ "buildPresetsItemsV3": {
+ "type": "array",
+ "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "condition": { "$ref": "#/definitions/topCondition" }
+ }
+ }
+ },
+ "buildPresetsItemsV2": {
"type": "array",
"description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.",
"items": {
@@ -427,11 +535,84 @@
},
"required": [
"name"
+ ]
+ }
+ },
+ "buildPresetsV3": {
+ "type": "array",
+ "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.",
+ "allOf": [
+ { "$ref": "#/definitions/buildPresetsItemsV3" },
+ { "$ref": "#/definitions/buildPresetsItemsV2" }
+ ],
+ "items": {
+ "type": "object",
+ "properties": {
+ "name": {},
+ "hidden": {},
+ "inherits": {},
+ "configurePreset": {},
+ "vendor": {},
+ "displayName": {},
+ "description": {},
+ "inheritConfigureEnvironment": {},
+ "environment": {},
+ "jobs": {},
+ "targets": {},
+ "configuration": {},
+ "cleanFirst": {},
+ "verbose": {},
+ "nativeToolOptions": {},
+ "condition": {}
+ },
+ "required": [
+ "name"
+ ],
+ "additionalProperties": false
+ }
+ },
+ "buildPresetsV2": {
+ "type": "array",
+ "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.",
+ "allOf": [
+ { "$ref": "#/definitions/buildPresetsItemsV2" }
+ ],
+ "items": {
+ "type": "object",
+ "properties": {
+ "name": {},
+ "hidden": {},
+ "inherits": {},
+ "configurePreset": {},
+ "vendor": {},
+ "displayName": {},
+ "description": {},
+ "inheritConfigureEnvironment": {},
+ "environment": {},
+ "jobs": {},
+ "targets": {},
+ "configuration": {},
+ "cleanFirst": {},
+ "verbose": {},
+ "nativeToolOptions": {}
+ },
+ "required": [
+ "name"
],
"additionalProperties": false
}
},
- "testPresets": {
+ "testPresetsItemsV3": {
+ "type": "array",
+ "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "condition": { "$ref": "#/definitions/topCondition" }
+ }
+ }
+ },
+ "testPresetsItemsV2": {
"type": "array",
"description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.",
"items": {
@@ -743,9 +924,312 @@
},
"required": [
"name"
+ ]
+ }
+ },
+ "testPresetsV3": {
+ "type": "array",
+ "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.",
+ "allOf": [
+ { "$ref": "#/definitions/testPresetsItemsV2" },
+ { "$ref": "#/definitions/testPresetsItemsV3" }
+ ],
+ "items": {
+ "type": "object",
+ "properties": {
+ "name": {},
+ "hidden": {},
+ "inherits": {},
+ "configurePreset": {},
+ "vendor": {},
+ "displayName": {},
+ "description": {},
+ "inheritConfigureEnvironment": {},
+ "environment": {},
+ "configuration": {},
+ "overwriteConfigurationFile": {},
+ "output": {},
+ "filter": {},
+ "execution": {},
+ "condition": {}
+ },
+ "required": [
+ "name"
+ ],
+ "additionalProperties": false
+ }
+ },
+ "testPresetsV2": {
+ "type": "array",
+ "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.",
+ "allOf": [
+ { "$ref": "#/definitions/testPresetsItemsV2" }
+ ],
+ "items": {
+ "type": "object",
+ "properties": {
+ "name": {},
+ "hidden": {},
+ "inherits": {},
+ "configurePreset": {},
+ "vendor": {},
+ "displayName": {},
+ "description": {},
+ "inheritConfigureEnvironment": {},
+ "environment": {},
+ "configuration": {},
+ "overwriteConfigurationFile": {},
+ "output": {},
+ "filter": {},
+ "execution": {}
+ },
+ "required": [
+ "name"
],
"additionalProperties": false
}
+ },
+ "condition": {
+ "anyOf": [
+ {
+ "type": "boolean",
+ "description": "A boolean which provides a constant value for the condition's evaluation."
+ },
+ {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "description": "A required string specifying the type of the condition.",
+ "const": "const"
+ },
+ "value": {
+ "type": "boolean",
+ "description": "A required boolean which provides a constant value for the condition's evaluation."
+ }
+ },
+ "required": [
+ "type",
+ "value"
+ ],
+ "additionalProperties": false
+ },
+ {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "description": "A required string specifying the type of the condition.",
+ "const": "equals"
+ },
+ "lhs": {
+ "type": "string",
+ "description": "First string to compare. This field supports macro expansion."
+ },
+ "rhs": {
+ "type": "string",
+ "description": "Second string to compare. This field supports macro expansion."
+ }
+ },
+ "required": [
+ "type",
+ "lhs",
+ "rhs"
+ ],
+ "additionalProperties": false
+ },
+ {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "description": "A required string specifying the type of the condition.",
+ "const": "notEquals"
+ },
+ "lhs": {
+ "type": "string",
+ "description": "First string to compare. This field supports macro expansion."
+ },
+ "rhs": {
+ "type": "string",
+ "description": "Second string to compare. This field supports macro expansion."
+ }
+ },
+ "required": [
+ "type",
+ "lhs",
+ "rhs"
+ ],
+ "additionalProperties": false
+ },
+ {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "description": "A required string specifying the type of the condition.",
+ "const": "inList"
+ },
+ "string": {
+ "type": "string",
+ "description": "A required string to search for. This field supports macro expansion."
+ },
+ "list": {
+ "type": "array",
+ "description": "A required list of strings to search. This field supports macro expansion, and uses short-circuit evaluation.",
+ "items": {
+ "type": "string"
+ }
+ }
+ },
+ "required": [
+ "type",
+ "string",
+ "list"
+ ],
+ "additionalProperties": false
+ },
+ {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "description": "A required string specifying the type of the condition.",
+ "const": "notInList"
+ },
+ "string": {
+ "type": "string",
+ "description": "A required string to search for. This field supports macro expansion."
+ },
+ "list": {
+ "type": "array",
+ "description": "A required list of strings to search. This field supports macro expansion, and uses short-circuit evaluation.",
+ "items": {
+ "type": "string"
+ }
+ }
+ },
+ "required": [
+ "type",
+ "string",
+ "list"
+ ],
+ "additionalProperties": false
+ },
+ {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "description": "A required string specifying the type of the condition.",
+ "const": "matches"
+ },
+ "string": {
+ "type": "string",
+ "description": "A required string to search. This field supports macro expansion."
+ },
+ "regex": {
+ "type": "string",
+ "description": "A required regular expression to search for. This field supports macro expansion."
+ }
+ },
+ "required": [
+ "type",
+ "string",
+ "regex"
+ ],
+ "additionalProperties": false
+ },
+ {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "description": "A required string specifying the type of the condition.",
+ "const": "notMatches"
+ },
+ "string": {
+ "type": "string",
+ "description": "A required string to search. This field supports macro expansion."
+ },
+ "regex": {
+ "type": "string",
+ "description": "A required regular expression to search for. This field supports macro expansion."
+ }
+ },
+ "required": [
+ "type",
+ "string",
+ "regex"
+ ],
+ "additionalProperties": false
+ },
+ {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "description": "A required string specifying the type of the condition.",
+ "const": "anyOf"
+ },
+ "conditions": {
+ "type": "array",
+ "description": "A required array of condition objects. These conditions use short-circuit evaluation.",
+ "items": { "$ref": "#/definitions/condition" }
+ }
+ },
+ "required": [
+ "type",
+ "conditions"
+ ],
+ "additionalProperties": false
+ },
+ {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "description": "A required string specifying the type of the condition.",
+ "const": "allOf"
+ },
+ "conditions": {
+ "type": "array",
+ "description": "A required array of condition objects. These conditions use short-circuit evaluation.",
+ "items": { "$ref": "#/definitions/condition" }
+ }
+ },
+ "required": [
+ "type",
+ "conditions"
+ ],
+ "additionalProperties": false
+ },
+ {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "description": "A required string specifying the type of the condition.",
+ "const": "not"
+ },
+ "condition": { "$ref": "#/definitions/condition" }
+ },
+ "required": [
+ "type",
+ "condition"
+ ],
+ "additionalProperties": false
+ }
+ ]
+ },
+ "topCondition": {
+ "anyOf": [
+ { "$ref": "#/definitions/condition" },
+ {
+ "type": "null",
+ "description": "Null indicates that the condition always evaluates to true and is not inherited."
+ }
+ ]
}
}
}
generated by cgit v0.12 at 2025-01-08 04:10:25 (GMT)