|
|
@@ -150,21 +150,14 @@ source and build trees and generate a buildsystem:
|
|
|
$ cmake -S src -B build
|
|
|
|
|
|
``cmake [<options>] -S <path-to-source> --preset=<preset-name>``
|
|
|
- Uses ``<path-to-source>`` as the source tree and reads a preset from
|
|
|
+ Uses ``<path-to-source>`` as the source tree and reads a
|
|
|
+ :manual:`preset <cmake-presets(7)>` from
|
|
|
``<path-to-source>/CMakePresets.json`` and
|
|
|
``<path-to-source>/CMakeUserPresets.json``. The preset specifies the
|
|
|
generator and the build directory, and optionally a list of variables and
|
|
|
other arguments to pass to CMake. The :manual:`CMake GUI <cmake-gui(1)>` can
|
|
|
- also recognize ``CMakePresets.json`` and ``CMakeUserPresets.json`` files.
|
|
|
-
|
|
|
- ``CMakePresets.json`` and ``CMakeUserPresets.json`` have exactly the same
|
|
|
- format, and both are optional (though at least one must be present if
|
|
|
- ``--preset`` is specified.) ``CMakePresets.json`` is meant to save
|
|
|
- project-wide builds, while ``CMakeUserPresets.json`` is meant for developers
|
|
|
- to save their own local builds. ``CMakePresets.json`` may be checked into a
|
|
|
- version control system, and ``CMakeUserPresets.json`` should NOT be checked
|
|
|
- in. For example, if a project is using Git, ``CMakePresets.json`` may be
|
|
|
- tracked, and ``CMakeUserPresets.json`` should be added to the ``.gitignore``.
|
|
|
+ also recognize ``CMakePresets.json`` and ``CMakeUserPresets.json`` files. For
|
|
|
+ full details on these files, see :manual:`cmake-presets(7)`.
|
|
|
|
|
|
The presets are read before all other command line options. The options
|
|
|
specified by the preset (variables, generator, etc.) can all be overridden by
|
|
|
@@ -172,323 +165,6 @@ source and build trees and generate a buildsystem:
|
|
|
a variable called ``MYVAR`` to ``1``, but the user sets it to ``2`` with a
|
|
|
``-D`` argument, the value ``2`` is preferred.
|
|
|
|
|
|
- The files are a JSON document with an object as the root:
|
|
|
-
|
|
|
- .. literalinclude:: presets/example.json
|
|
|
- :language: json
|
|
|
-
|
|
|
- The root object recognizes the following fields:
|
|
|
-
|
|
|
- ``version``
|
|
|
-
|
|
|
- A required integer representing the version of the JSON schema. Currently,
|
|
|
- the only supported version is 1.
|
|
|
-
|
|
|
- ``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.
|
|
|
-
|
|
|
- ``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
|
|
|
- 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. For example:
|
|
|
-
|
|
|
- .. code-block:: json
|
|
|
-
|
|
|
- {
|
|
|
- "version": 1,
|
|
|
- "vendor": {
|
|
|
- "example.com/ExampleIDE/1.0": {
|
|
|
- "autoFormat": true
|
|
|
- }
|
|
|
- },
|
|
|
- "configurePresets": []
|
|
|
- }
|
|
|
-
|
|
|
- ``configurePresets``
|
|
|
-
|
|
|
- An optional array of configure preset objects. Each preset 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 ``longDescription``), 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``
|
|
|
-
|
|
|
- An optional string representing the platform name to use for Visual
|
|
|
- Studio generators.
|
|
|
-
|
|
|
- ``toolset``
|
|
|
-
|
|
|
- An optional string representing the toolset name to use for Visual Studio
|
|
|
- generators.
|
|
|
-
|
|
|
- ``cmakeGeneratorConfig``
|
|
|
-
|
|
|
- An optional string telling CMake how to handle the ``architecture`` and
|
|
|
- ``toolset`` fields. Valid values are:
|
|
|
-
|
|
|
- ``"default"``
|
|
|
-
|
|
|
- Set the platform and toolset using the ``architecture`` and ``toolset``
|
|
|
- fields respectively. On non-Visual Studio generators, this will result
|
|
|
- in an error if ``architecture`` or ``toolset`` are set.
|
|
|
-
|
|
|
- ``"ignore"``
|
|
|
-
|
|
|
- Do not set the platform or toolset at all, even on Visual Studio
|
|
|
- generators. 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 ``architecture`` and ``toolset``, 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 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 representing the value of the variable. 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 warnings. 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.
|
|
|
-
|
|
|
- ``unusedVars``
|
|
|
-
|
|
|
- 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 errors. 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``.
|
|
|
-
|
|
|
- As mentioned above, some fields support macro expansion. Macros are
|
|
|
- recognized in the form ``$<macro-namespace>{<macro-name>}``. All macros are
|
|
|
- evaluated in the context of the preset being used, even if the macro is in a
|
|
|
- field that was inherited from another preset. For example, if the ``Base``
|
|
|
- preset sets variable ``PRESET_NAME`` to ``${presetName}``, and the
|
|
|
- ``Derived`` preset inherits from ``Base``, ``PRESET_NAME`` will be set to
|
|
|
- ``Derived``.
|
|
|
-
|
|
|
- It is an error to not put a closing brace at the end of a macro name. For
|
|
|
- example, ``${sourceDir`` is invalid. A dollar sign (``$``) followed by
|
|
|
- anything other than a left curly brace (``{``) with a possible namespace is
|
|
|
- interpreted as a literal dollar sign.
|
|
|
-
|
|
|
- Recognized macros include:
|
|
|
-
|
|
|
- ``${sourceDir}``
|
|
|
-
|
|
|
- Path to the project source directory.
|
|
|
-
|
|
|
- ``${sourceParentDir}``
|
|
|
-
|
|
|
- Path to the project source directory's parent directory.
|
|
|
-
|
|
|
- ``${presetName}``
|
|
|
-
|
|
|
- Name specified in the preset's ``name`` field.
|
|
|
-
|
|
|
- ``${generator}``
|
|
|
-
|
|
|
- Generator specified in the preset's ``generator`` field.
|
|
|
-
|
|
|
- ``${dollar}``
|
|
|
-
|
|
|
- A literal dollar sign (``$``).
|
|
|
-
|
|
|
- ``$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.
|
|
|
- If the environment variable is not defined, this evaluates as an empty
|
|
|
- string.
|
|
|
-
|
|
|
- Note that while Windows environment variable names are case-insensitive,
|
|
|
- variable names within a preset are still case-sensitive. This may lead to
|
|
|
- unexpected results when using inconsistent casing. For best results, keep
|
|
|
- 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.
|
|
|
- For example, setting ``PATH`` to ``/path/to/ninja/bin:$penv{PATH}`` will
|
|
|
- prepend ``/path/to/ninja/bin`` to the ``PATH`` environment variable. This
|
|
|
- is needed because ``$env{<variable-name>}`` does not allow circular
|
|
|
- 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
|
|
|
- other presets from the same file.
|
|
|
-
|
|
|
- CMake does not make any attempt to interpret ``$vendor{<macro-name>}``
|
|
|
- macros. However, to avoid name collisions, IDE vendors should prefix
|
|
|
- ``<macro-name>`` with a very short (preferably <= 4 characters) vendor
|
|
|
- identifier prefix, followed by a ``.``, followed by the macro name. For
|
|
|
- example, the Example IDE could have ``$vendor{xide.ideInstallDir}``.
|
|
|
-
|
|
|
In all cases the ``<options>`` may be zero or more of the `Options`_ below.
|
|
|
|
|
|
After generating a buildsystem one may use the corresponding native
|
Kyle Edwards