echo/CMake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Help: Turn items of presets manual page into description list

Browse Source 
It was an ordinal paragraphs (`<p>`) intermixed with blockquote elements.
This commit is contained in:
Alex Turbov 2022-08-13 03:26:02 +04:00
parent e2198fd9dc
commit 2c54cd871a
1 changed files with 0 additions and 154 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

154
Help/manual/cmake-presets.7.rst
View File

@ -40,7 +40,6 @@ The files are a JSON document with an object as the root:
The root object recognizes the following fields:
``version``
A required integer representing the version of the JSON schema.
The supported versions are:
@ -60,31 +59,25 @@ The root object recognizes the following fields:
.. versionadded:: 3.24
``cmakeMinimumRequired``
An optional object representing the minimum version of CMake needed to
build this project. This object consists of the following fields:
``major``
An optional integer representing the major version.
``minor``
An optional integer representing the minor version.
``patch``
An optional integer representing the patch version.
``include``
An optional array of strings representing files to include. If the filenames
are not absolute, they are considered relative to the current file.
This is allowed in preset files specifying version ``4`` or above.
See `Includes`_ for discussion of the constraints on included files.
``vendor``
An optional map containing vendor-specific information. CMake does not
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
@ -93,17 +86,14 @@ The root object recognizes the following fields:
desired by the vendor, though will typically be a map.
``configurePresets``
An optional array of `Configure Preset`_ objects.
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.
``testPresets``
An optional array of `Test Preset`_ objects.
This is allowed in preset files specifying version ``2`` or above.
@ -134,7 +124,6 @@ Each entry of the ``configurePresets`` array is a JSON object
that may contain the following fields:
``name``
A required string representing the machine-friendly name of the preset.
This identifier is used in the :ref:`cmake --preset <CMake Options>` option.
There must not be two configure presets in the union of ``CMakePresets.json``
@ -142,7 +131,6 @@ that may contain the following fields:
However, a configure preset may have the same name as a build or test preset.
``hidden``
An optional boolean specifying whether or not a preset should be hidden.
If a preset is hidden, it cannot be used in the ``--preset=`` argument,
will not show up in the :manual:`CMake GUI <cmake-gui(1)>`, and does not
@ -151,7 +139,6 @@ that may contain the following fields:
other presets to inherit via the ``inherits`` field.
``inherits``
An optional array of strings representing the names of presets to inherit
from. This field can also be a string, which is equivalent to an array
containing one string.
@ -169,12 +156,10 @@ that may contain the following fields:
``CMakeUserPresets.json``.
``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
interpret the contents of this field except to verify that it is a map
if it does exist. However, it should follow the same conventions as the
@ -183,15 +168,12 @@ that may contain the following fields:
when appropriate.
``displayName``
An optional string with a human-friendly name of the preset.
``description``
An optional string with a human-friendly description of the preset.
``generator``
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``). In version ``3``
@ -203,27 +185,22 @@ that may contain the following fields:
in the generator name. Use the ``architecture`` field instead.
``architecture``, ``toolset``
Optional fields representing the platform and toolset, respectively, for
generators that support them. Each may be either a string or an object
with the following fields:
``value``
An optional string representing the value.
``strategy``
An optional string telling CMake how to handle the ``architecture`` or
``toolset`` field. Valid values are:
``"set"``
Set the respective value. This will result in an error for generators
that do not support the respective field.
``"external"``
Do not set the value, even if the generator supports it. This is
useful if, for example, a preset uses the Ninja generator, and an IDE
knows how to set up the Visual C++ environment from the
@ -232,7 +209,6 @@ that may contain the following fields:
before invoking CMake.
``toolchainFile``
An optional string representing the path to the toolchain file.
This field supports `macro expansion`_. If a relative path is specified,
it is calculated relative to the build directory, and if not found,
@ -241,7 +217,6 @@ that may contain the following fields:
specifying version ``3`` or above.
``binaryDir``
An optional string representing the path to the output binary directory.
This field supports `macro expansion`_. If a relative path is specified,
it is calculated relative to the source directory. If ``binaryDir`` is not
@ -250,20 +225,17 @@ that may contain the following fields:
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``
An optional string representing the path to the CMake executable to use
for this preset. This is reserved for use by IDEs, and is not used by
CMake itself. IDEs that use this field should expand any macros in it.
``cacheVariables``
An optional map of cache variables. The key is the variable name (which
may not be an empty string), and the value is either ``null``, a boolean
(which is equivalent to a value of ``"TRUE"`` or ``"FALSE"`` and a type
@ -271,11 +243,9 @@ that may contain the following fields:
supports `macro expansion`_), or an object with the following fields:
``type``
An optional string representing the type of the variable.
``value``
A required string or boolean representing the value of the variable.
A boolean is equivalent to ``"TRUE"`` or ``"FALSE"``. This field
supports `macro expansion`_.
@ -288,7 +258,6 @@ that may contain the following fields:
a value was inherited from another preset.
``environment``
An optional map of environment variables. The key is the variable name
(which may not be an empty string), and the value is either ``null`` or
a string representing the value of the variable. Each variable is set
@ -306,18 +275,15 @@ that may contain the following fields:
a value was inherited from another preset.
``warnings``
An optional object specifying the warnings to enable. The object may
contain the following fields:
``dev``
An optional boolean. Equivalent to passing :option:`-Wdev <cmake -Wdev>`
or :option:`-Wno-dev <cmake -Wno-dev>` on the command line. This may not
be set to ``false`` if ``errors.dev`` is set to ``true``.
``deprecated``
An optional boolean. Equivalent to passing
:option:`-Wdeprecated <cmake -Wdeprecated>` or
:option:`-Wno-deprecated <cmake -Wno-deprecated>` on the command line.
@ -325,36 +291,30 @@ that may contain the following fields:
``true``.
``uninitialized``
An optional boolean. Setting this to ``true`` is equivalent to passing
:option:`--warn-uninitialized <cmake --warn-uninitialized>` on the command
line.
``unusedCli``
An optional boolean. Setting this to ``false`` is equivalent to passing
:option:`--no-warn-unused-cli <cmake --no-warn-unused-cli>` on the command
line.
``systemVars``
An optional boolean. Setting this to ``true`` is equivalent to passing
:option:`--check-system-vars <cmake --check-system-vars>` on the command
line.
``errors``
An optional object specifying the errors to enable. The object may
contain the following fields:
``dev``
An optional boolean. Equivalent to passing :option:`-Werror=dev <cmake -Werror>`
or :option:`-Wno-error=dev <cmake -Werror>` on the command line.
This may not be set to ``true`` if ``warnings.dev`` is set to ``false``.
``deprecated``
An optional boolean. Equivalent to passing
:option:`-Werror=deprecated <cmake -Werror>` or
:option:`-Wno-error=deprecated <cmake -Werror>` on the command line.
@ -362,23 +322,19 @@ that may contain the following fields:
``false``.
``debug``
An optional object specifying debug options. The object may contain the
following fields:
``output``
An optional boolean. Setting this to ``true`` is equivalent to passing
:option:`--debug-output <cmake --debug-output>` on the command line.
``tryCompile``
An optional boolean. Setting this to ``true`` is equivalent to passing
:option:`--debug-trycompile <cmake --debug-trycompile>` on the command
line.
``find``
An optional boolean. Setting this to ``true`` is equivalent to passing
:option:`--debug-find <cmake --debug-find>` on the command line.
@ -389,7 +345,6 @@ Each entry of the ``buildPresets`` array is a JSON object
that may contain the following fields:
``name``
A required string representing the machine-friendly name of the preset.
This identifier is used in the
:ref:`cmake --build --preset <Build Tool Mode>` option.
@ -398,7 +353,6 @@ that may contain the following fields:
However, a build preset may have the same name as a configure or test preset.
``hidden``
An optional boolean specifying whether or not a preset should be hidden.
If a preset is hidden, it cannot be used in the
:option:`--preset <cmake --preset>` argument
@ -407,7 +361,6 @@ that may contain the following fields:
other presets to inherit via the ``inherits`` field.
``inherits``
An optional array of strings representing the names of presets to inherit
from. This field can also be a string, which is equivalent to an array
containing one string.
@ -425,12 +378,10 @@ that may contain the following fields:
``CMakeUserPresets.json``.
``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
interpret the contents of this field except to verify that it is a map
if it does exist. However, it should follow the same conventions as the
@ -439,15 +390,12 @@ that may contain the following fields:
when appropriate.
``displayName``
An optional string with a human-friendly name of the preset.
``description``
An optional string with a human-friendly description of the preset.
``environment``
An optional map of environment variables. The key is the variable name
(which may not be an empty string), and the value is either ``null`` or
a string representing the value of the variable. Each variable is set
@ -478,7 +426,6 @@ that may contain the following fields:
project.
``configurePreset``
An optional string specifying the name of a configure preset to
associate with this build preset. If ``configurePreset`` is not
specified, it must be inherited from the inherits preset (unless this
@ -487,36 +434,30 @@ that may contain the following fields:
configuration did.
``inheritConfigureEnvironment``
An optional boolean that defaults to true. If true, the environment
variables from the associated configure preset are inherited after all
inherited build preset environments, but before environment variables
explicitly specified in this build preset.
``jobs``
An optional integer. Equivalent to passing
:option:`--parallel <cmake --parallel>` or ``-j`` on the command line.
``targets``
An optional string or array of strings. Equivalent to passing
:option:`--target <cmake --target>` or ``-t`` on the command line.
Vendors may ignore the targets property or hide build presets that
explicitly specify targets. This field supports macro expansion.
``configuration``
An optional string. Equivalent to passing :option:`--config <cmake --config>`
on the command line.
``cleanFirst``
An optional bool. If true, equivalent to passing
:option:`--clean-first <cmake --clean-first>` on the command line.
``resolvePackageReferences``
An optional string that specifies the package resolve mode. This is
allowed in preset files specifying version ``4`` or above.
@ -526,16 +467,13 @@ that may contain the following fields:
package references, this option does nothing. Valid values are:
``on``
Causes package references to be resolved before attempting a build.
``off``
Package references will not be resolved. Note that this may cause
errors in some build environments, such as .NET SDK style projects.
``only``
Only resolve package references, but do not perform a build.
.. note::
@ -554,12 +492,10 @@ that may contain the following fields:
done from within a configure preset.
``verbose``
An optional bool. If true, equivalent to passing
:option:`--verbose <cmake --verbose>` on the command line.
``nativeToolOptions``
An optional array of strings. Equivalent to passing options after ``--``
on the command line. The array values support macro expansion.
@ -570,7 +506,6 @@ Each entry of the ``testPresets`` array is a JSON object
that may contain the following fields:
``name``
A required string representing the machine-friendly name of the preset.
This identifier is used in the :option:`ctest --preset` option.
There must not be two test presets in the union of ``CMakePresets.json``
@ -578,7 +513,6 @@ that may contain the following fields:
However, a test preset may have the same name as a configure or build preset.
``hidden``
An optional boolean specifying whether or not a preset should be hidden.
If a preset is hidden, it cannot be used in the
:option:`--preset <ctest --preset>` argument
@ -587,7 +521,6 @@ that may contain the following fields:
other presets to inherit via the ``inherits`` field.
``inherits``
An optional array of strings representing the names of presets to inherit
from. This field can also be a string, which is equivalent to an array
containing one string.
@ -605,12 +538,10 @@ that may contain the following fields:
``CMakeUserPresets.json``.
``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
interpret the contents of this field except to verify that it is a map
if it does exist. However, it should follow the same conventions as the
@ -619,15 +550,12 @@ that may contain the following fields:
when appropriate.
``displayName``
An optional string with a human-friendly name of the preset.
``description``
An optional string with a human-friendly description of the preset.
``environment``
An optional map of environment variables. The key is the variable name
(which may not be an empty string), and the value is either ``null`` or
a string representing the value of the variable. Each variable is set
@ -645,7 +573,6 @@ that may contain the following fields:
even if a value was inherited from another preset.
``configurePreset``
An optional string specifying the name of a configure preset to
associate with this test preset. If ``configurePreset`` is not
specified, it must be inherited from the inherits preset (unless this
@ -654,103 +581,85 @@ that may contain the following fields:
configuration did and build did.
``inheritConfigureEnvironment``
An optional boolean that defaults to true. If true, the environment
variables from the associated configure preset are inherited after all
inherited test preset environments, but before environment variables
explicitly specified in this test preset.
``configuration``
An optional string. Equivalent to passing
:option:`--build-config <ctest --build-config>` on the command line.
``overwriteConfigurationFile``
An optional array of configuration options to overwrite options
specified in the CTest configuration file. Equivalent to passing
:option:`--overwrite <ctest --overwrite>` for each value in the array.
The array values support macro expansion.
``output``
An optional object specifying output options. The object may contain the
following fields.
``shortProgress``
An optional bool. If true, equivalent to passing
:option:`--progress <ctest --progress>` on the command line.
``verbosity``
An optional string specifying verbosity level. Must be one of the
following:
``default``
Equivalent to passing no verbosity flags on the command line.
``verbose``
Equivalent to passing :option:`--verbose <ctest --verbose>` on
the command line.
``extra``
Equivalent to passing :option:`--extra-verbose <ctest --extra-verbose>`
on the command line.
``debug``
An optional bool. If true, equivalent to passing
:option:`--debug <ctest --debug>` on the command line.
``outputOnFailure``
An optional bool. If true, equivalent to passing
:option:`--output-on-failure <ctest --output-on-failure>` on the command
line.
``quiet``
An optional bool. If true, equivalent to passing
:option:`--quiet <ctest --quiet>` on the command line.
``outputLogFile``
An optional string specifying a path to a log file. Equivalent to
passing :option:`--output-log <ctest --output-log>` on the command line.
This field supports macro expansion.
``labelSummary``
An optional bool. If false, equivalent to passing
:option:`--no-label-summary <ctest --no-label-summary>` on the command
line.
``subprojectSummary``
An optional bool. If false, equivalent to passing
:option:`--no-subproject-summary <ctest --no-subproject-summary>`
on the command line.
``maxPassedTestOutputSize``
An optional integer specifying the maximum output for passed tests in
bytes. Equivalent to passing
:option:`--test-output-size-passed <ctest --test-output-size-passed>`
on the command line.
``maxFailedTestOutputSize``
An optional integer specifying the maximum output for failed tests in
bytes. Equivalent to passing
:option:`--test-output-size-failed <ctest --test-output-size-failed>`
on the command line.
``testOutputTruncation``
An optional string specifying the test output truncation mode. Equivalent
to passing
:option:`--test-output-truncation <ctest --test-output-truncation>` on
@ -758,42 +667,34 @@ that may contain the following fields:
``5`` or above.
``maxTestNameWidth``
An optional integer specifying the maximum width of a test name to
output. Equivalent to passing :option:`--max-width <ctest --max-width>`
on the command line.
``filter``
An optional object specifying how to filter the tests to run. The object
may contain the following fields.
``include``
An optional object specifying which tests to include. The object may
contain the following fields.
``name``
An optional string specifying a regex for test names. Equivalent to
passing :option:`--tests-regex <ctest --tests-regex>` on the command
line. This field supports macro expansion. CMake regex syntax is
described under :ref:`string(REGEX) <Regex Specification>`.
``label``
An optional string specifying a regex for test labels. Equivalent to
passing :option:`--label-regex <ctest --label-regex>` on the command
line. This field supports macro expansion.
``useUnion``
An optional bool. Equivalent to passing :option:`--union <ctest --union>`
on the command line.
``index``
An optional object specifying tests to include by test index. The
object may contain the following fields. Can also be an optional
string specifying a file with the command line syntax for
@ -801,99 +702,81 @@ that may contain the following fields:
If specified as a string, this field supports macro expansion.
``start``
An optional integer specifying a test index to start testing at.
``end``
An optional integer specifying a test index to stop testing at.
``stride``
An optional integer specifying the increment.
``specificTests``
An optional array of integers specifying specific test indices to
run.
``exclude``
An optional object specifying which tests to exclude. The object may
contain the following fields.
``name``
An optional string specifying a regex for test names. Equivalent to
passing :option:`--exclude-regex <ctest --exclude-regex>` on the
command line. This field supports macro expansion.
``label``
An optional string specifying a regex for test labels. Equivalent to
passing :option:`--label-exclude <ctest --label-exclude>` on the
command line. This field supports macro expansion.
``fixtures``
An optional object specifying which fixtures to exclude from adding
tests. The object may contain the following fields.
``any``
An optional string specifying a regex for text fixtures to exclude
from adding any tests. Equivalent to
:option:`--fixture-exclude-any <ctest --fixture-exclude-any>` on
the command line. This field supports macro expansion.
``setup``
An optional string specifying a regex for text fixtures to exclude
from adding setup tests. Equivalent to
:option:`--fixture-exclude-setup <ctest --fixture-exclude-setup>`
on the command line. This field supports macro expansion.
``cleanup``
An optional string specifying a regex for text fixtures to exclude
from adding cleanup tests. Equivalent to
:option:`--fixture-exclude-cleanup <ctest --fixture-exclude-cleanup>`
on the command line. This field supports macro expansion.
``execution``
An optional object specifying options for test execution. The object may
contain the following fields.
``stopOnFailure``
An optional bool. If true, equivalent to passing
:option:`--stop-on-failure <ctest --stop-on-failure>` on the command
line.
``enableFailover``
An optional bool. If true, equivalent to passing :option:`-F <ctest -F>`
on the command line.
``jobs``
An optional integer. Equivalent to passing
:option:`--parallel <ctest --parallel>` on the command line.
``resourceSpecFile``
An optional string. Equivalent to passing
:option:`--resource-spec-file <ctest --resource-spec-file>` on
the command line. This field supports macro expansion.
``testLoad``
An optional integer. Equivalent to passing
:option:`--test-load <ctest --test-load>` on the command line.
``showOnly``
An optional string. Equivalent to passing
:option:`--show-only <ctest --show-only>` on the
command line. The string must be one of the following values:
@ -903,13 +786,11 @@ that may contain the following fields:
``json-v1``
``repeat``
An optional object specifying how to repeat tests. Equivalent to
passing :option:`--repeat <ctest --repeat>` on the command line.
The object must have the following fields.
``mode``
A required string. Must be one of the following values:
``until-fail``
@ -919,11 +800,9 @@ that may contain the following fields:
``after-timeout``
``count``
A required integer.
``interactiveDebugging``
An optional bool. If true, equivalent to passing
:option:`--interactive-debug-mode 1 <ctest --interactive-debug-mode>`
on the command line. If false, equivalent to passing
@ -931,32 +810,26 @@ that may contain the following fields:
on the command line.
``scheduleRandom``
An optional bool. If true, equivalent to passing
:option:`--schedule-random <ctest --schedule-random>` on the command
line.
``timeout``
An optional integer. Equivalent to passing
:option:`--timeout <ctest --timeout>` on the command line.
``noTestsAction``
An optional string specifying the behavior if no tests are found. Must
be one of the following values:
``default``
Equivalent to not passing any value on the command line.
``error``
Equivalent to passing :option:`--no-tests=error <ctest --no-tests>`
on the command line.
``ignore``
Equivalent to passing :option:`--no-tests=ignore <ctest --no-tests>`
on the command line.
@ -974,65 +847,53 @@ 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.
@ -1044,17 +905,14 @@ object, it has the following fields:
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
@ -1076,46 +934,37 @@ interpreted as a literal dollar sign.
Recognized macros include:
``${sourceDir}``
Path to the project source directory (i.e. the same as
:variable:`CMAKE_SOURCE_DIR`).
``${sourceParentDir}``
Path to the project source directory's parent directory.
``${sourceDirName}``
The last filename component of ``${sourceDir}``. For example, if
``${sourceDir}`` is ``/path/to/source``, this would be ``source``.
``${presetName}``
Name specified in the preset's ``name`` field.
``${generator}``
Generator specified in the preset's ``generator`` field. For build and
test presets, this will evaluate to the generator specified by
``configurePreset``.
``${hostSystemName}``
The name of the host operating system. Contains the same value as
:variable:`CMAKE_HOST_SYSTEM_NAME`. This is allowed in preset files
specifying version ``3`` or above.
``${fileDir}``
Path to the directory containing the preset file which contains the macro.
This is allowed in preset files specifying version ``4`` or above.
``${dollar}``
A literal dollar sign (``$``).
``${pathListSep}``
Native character for separating lists of paths, such as ``:`` or ``;``.
For example, by setting ``PATH`` to
@ -1126,7 +975,6 @@ Recognized macros include:
This is allowed in preset files specifying version ``5`` or above.
``$env{<variable-name>}``
Environment variable with name ``<variable-name>``. The variable name may
not be an empty string. If the variable is defined in the ``environment``
field, that value is used instead of the value from the parent environment.
@ -1139,7 +987,6 @@ Recognized macros include:
the casing of environment variable names consistent.
``$penv{<variable-name>}``
Similar to ``$env{<variable-name>}``, except that the value only comes from
the parent environment, and never from the ``environment`` field. This
allows you to prepend or append values to existing environment variables.
@ -1149,7 +996,6 @@ Recognized macros include:
references.
``$vendor{<macro-name>}``
An extension point for vendors to insert their own macros. CMake will not
be able to use presets which have a ``$vendor{<macro-name>}`` macro, and
effectively ignores such presets. However, it will still be able to use