mirror of
https://github.com/Kitware/CMake.git
synced 2025-10-18 17:31:57 +08:00
Help: Add section heading for configure presets in cmake-presets(7)
Cross-reference it from the main `configurePresets` field. This removes an extra layer of indentation and makes the section linkable.
This commit is contained in:
Brad King
@@ -69,221 +69,226 @@ The root object recognizes the following fields:
|
||||
|
||||
``configurePresets``
|
||||
|
||||
An optional array of configure preset objects. Each preset may contain the
|
||||
An optional array of `Configure Preset`_ objects.
|
||||
|
||||
Configure Preset
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
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 ``--preset`` argument. There must not be
|
||||
two presets in the union of ``CMakePresets.json`` and
|
||||
``CMakeUserPresets.json`` in the same directory with the same name.
|
||||
|
||||
``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
|
||||
have to have a valid ``generator`` or ``binaryDir``, even from
|
||||
inheritance. ``hidden`` presets are intended to be used as a base for
|
||||
other presets to inherit via the ``inherits`` field.
|
||||
|
||||
``inherits``
|
||||
|
||||
An optional array of strings representing the names of presets to inherit
|
||||
from. The preset will inherit all of the fields from the ``inherits``
|
||||
presets by default (except ``name``, ``hidden``, ``inherits``,
|
||||
``description``, and ``displayName``), but can override them as
|
||||
desired. If multiple ``inherits`` presets provide conflicting values for
|
||||
the same field, the earlier preset in the ``inherits`` list will be
|
||||
preferred. Presets in ``CMakePresets.json`` may not inherit from presets
|
||||
in ``CMakeUserPresets.json``.
|
||||
|
||||
This field can also be a string, which is equivalent to an array
|
||||
containing one string.
|
||||
|
||||
``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
|
||||
root-level ``vendor`` field. If vendors use their own per-preset
|
||||
``vendor`` field, they should implement inheritance in a sensible manner
|
||||
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``).
|
||||
|
||||
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.
|
||||
|
||||
``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
|
||||
``architecture`` and ``toolset`` fields. In that case, CMake will
|
||||
ignore the field, but the IDE can use them to set up the environment
|
||||
before invoking CMake.
|
||||
|
||||
``binaryDir``
|
||||
|
||||
An optional string representing the path to the output binary directory.
|
||||
This field supports `macro expansion`_. If a relative path is specified,
|
||||
it is calculated relative to the source directory. If ``binaryDir`` is not
|
||||
specified, it must be inherited from the ``inherits`` preset (unless this
|
||||
preset is ``hidden``).
|
||||
|
||||
``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
|
||||
of ``BOOL``), a string representing the value of the variable (which
|
||||
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`_.
|
||||
|
||||
Cache variables are inherited through the ``inherits`` field, and the
|
||||
preset's variables will be the union of its own ``cacheVariables`` and
|
||||
the ``cacheVariables`` from all its parents. If multiple presets in this
|
||||
union define the same variable, the standard rules of ``inherits`` are
|
||||
applied. Setting a variable to ``null`` causes it to not be set, even if
|
||||
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
|
||||
regardless of whether or not a value was given to it by the process's
|
||||
environment. This field supports `macro expansion`_, and environment
|
||||
variables in this map may reference each other, and may be listed in any
|
||||
order, as long as such references do not cause a cycle (for example,
|
||||
if ``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.)
|
||||
|
||||
Environment variables are inherited through the ``inherits`` field, and
|
||||
the preset's environment will be the union of its own ``environment`` and
|
||||
the ``environment`` from all its parents. If multiple presets in this
|
||||
union define the same variable, the standard rules of ``inherits`` are
|
||||
applied. Setting a variable to ``null`` causes it to not be set, even if
|
||||
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 ``-Wdev`` or ``-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 ``-Wdeprecated`` or
|
||||
``-Wno-deprecated`` on the command line. This may not be set to
|
||||
``false`` if ``errors.deprecated`` is set to ``true``.
|
||||
|
||||
``uninitialized``
|
||||
|
||||
An optional boolean. Setting this to ``true`` is equivalent to passing
|
||||
``--warn-uninitialized`` on the command line.
|
||||
|
||||
``unusedCli``
|
||||
|
||||
An optional boolean. Setting this to ``false`` is equivalent to passing
|
||||
``--no-warn-unused-cli`` on the command line.
|
||||
|
||||
``systemVars``
|
||||
|
||||
An optional boolean. Setting this to ``true`` is equivalent to passing
|
||||
``--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 ``-Werror=dev`` or
|
||||
``-Wno-error=dev`` 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 ``-Werror=deprecated`` or
|
||||
``-Wno-error=deprecated`` on the command line. This may not be set to
|
||||
``true`` if ``warnings.deprecated`` is set to ``false``.
|
||||
|
||||
``debug``
|
||||
|
||||
An optional object specifying debug options. The object may contain the
|
||||
following fields:
|
||||
|
||||
``name``
|
||||
``output``
|
||||
|
||||
A required string representing the machine-friendly name of the preset.
|
||||
This identifier is used in the ``--preset`` argument. There must not be
|
||||
two presets in the union of ``CMakePresets.json`` and
|
||||
``CMakeUserPresets.json`` in the same directory with the same name.
|
||||
An optional boolean. Setting this to ``true`` is equivalent to passing
|
||||
``--debug-output`` on the command line.
|
||||
|
||||
``hidden``
|
||||
``tryCompile``
|
||||
|
||||
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
|
||||
have to have a valid ``generator`` or ``binaryDir``, even from
|
||||
inheritance. ``hidden`` presets are intended to be used as a base for
|
||||
other presets to inherit via the ``inherits`` field.
|
||||
An optional boolean. Setting this to ``true`` is equivalent to passing
|
||||
``--debug-trycompile`` on the command line.
|
||||
|
||||
``inherits``
|
||||
``find``
|
||||
|
||||
An optional array of strings representing the names of presets to inherit
|
||||
from. The preset will inherit all of the fields from the ``inherits``
|
||||
presets by default (except ``name``, ``hidden``, ``inherits``,
|
||||
``description``, and ``displayName``), but can override them as
|
||||
desired. If multiple ``inherits`` presets provide conflicting values for
|
||||
the same field, the earlier preset in the ``inherits`` list will be
|
||||
preferred. Presets in ``CMakePresets.json`` may not inherit from presets
|
||||
in ``CMakeUserPresets.json``.
|
||||
|
||||
This field can also be a string, which is equivalent to an array
|
||||
containing one string.
|
||||
|
||||
``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
|
||||
root-level ``vendor`` field. If vendors use their own per-preset
|
||||
``vendor`` field, they should implement inheritance in a sensible manner
|
||||
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``).
|
||||
|
||||
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.
|
||||
|
||||
``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
|
||||
``architecture`` and ``toolset`` fields. In that case, CMake will
|
||||
ignore the field, but the IDE can use them to set up the environment
|
||||
before invoking CMake.
|
||||
|
||||
``binaryDir``
|
||||
|
||||
An optional string representing the path to the output binary directory.
|
||||
This field supports `macro expansion`_. If a relative path is specified,
|
||||
it is calculated relative to the source directory. If ``binaryDir`` is not
|
||||
specified, it must be inherited from the ``inherits`` preset (unless this
|
||||
preset is ``hidden``).
|
||||
|
||||
``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
|
||||
of ``BOOL``), a string representing the value of the variable (which
|
||||
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`_.
|
||||
|
||||
Cache variables are inherited through the ``inherits`` field, and the
|
||||
preset's variables will be the union of its own ``cacheVariables`` and
|
||||
the ``cacheVariables`` from all its parents. If multiple presets in this
|
||||
union define the same variable, the standard rules of ``inherits`` are
|
||||
applied. Setting a variable to ``null`` causes it to not be set, even if
|
||||
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
|
||||
regardless of whether or not a value was given to it by the process's
|
||||
environment. This field supports `macro expansion`_, and environment
|
||||
variables in this map may reference each other, and may be listed in any
|
||||
order, as long as such references do not cause a cycle (for example,
|
||||
if ``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.)
|
||||
|
||||
Environment variables are inherited through the ``inherits`` field, and
|
||||
the preset's environment will be the union of its own ``environment`` and
|
||||
the ``environment`` from all its parents. If multiple presets in this
|
||||
union define the same variable, the standard rules of ``inherits`` are
|
||||
applied. Setting a variable to ``null`` causes it to not be set, even if
|
||||
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 ``-Wdev`` or ``-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 ``-Wdeprecated`` or
|
||||
``-Wno-deprecated`` on the command line. This may not be set to
|
||||
``false`` if ``errors.deprecated`` is set to ``true``.
|
||||
|
||||
``uninitialized``
|
||||
|
||||
An optional boolean. Setting this to ``true`` is equivalent to passing
|
||||
``--warn-uninitialized`` on the command line.
|
||||
|
||||
``unusedCli``
|
||||
|
||||
An optional boolean. Setting this to ``false`` is equivalent to passing
|
||||
``--no-warn-unused-cli`` on the command line.
|
||||
|
||||
``systemVars``
|
||||
|
||||
An optional boolean. Setting this to ``true`` is equivalent to passing
|
||||
``--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 ``-Werror=dev`` or
|
||||
``-Wno-error=dev`` 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 ``-Werror=deprecated`` or
|
||||
``-Wno-error=deprecated`` on the command line. This may not be set to
|
||||
``true`` if ``warnings.deprecated`` is set to ``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
|
||||
``--debug-output`` on the command line.
|
||||
|
||||
``tryCompile``
|
||||
|
||||
An optional boolean. Setting this to ``true`` is equivalent to passing
|
||||
``--debug-trycompile`` on the command line.
|
||||
|
||||
``find``
|
||||
|
||||
An optional boolean. Setting this to ``true`` is equivalent to passing
|
||||
``--debug-find`` on the command line.
|
||||
An optional boolean. Setting this to ``true`` is equivalent to passing
|
||||
``--debug-find`` on the command line.
|
||||
|
||||
Macro Expansion
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
Reference in New Issue
Block a user