diff options
author | Brad King <brad.king@kitware.com> | 2020-10-06 14:49:44 +0000 |
---|---|---|
committer | Kitware Robot <kwrobot@kitware.com> | 2020-10-06 10:49:59 -0400 |
commit | 8c4c658ab062f2920448a02fe3a5d42fe3d48876 (patch) | |
tree | 97656d990c21802ec181b9269d63500bb461437c /Help | |
parent | a12da6fb5ece6baf3b4540d8204b8b29dde92538 (diff) | |
parent | 6f8fdc686c0e0710a9c1981c66359a205cc127dd (diff) | |
download | cmake-8c4c658ab062f2920448a02fe3a5d42fe3d48876.tar.gz |
Merge topic 'cmake-presets'
6f8fdc686c .gitignore: Add CMakeUserPresets.json
1d25760198 Help: Add presets documentation and release notes
a4382f72d7 CMake GUI: Add presets functionality
8617479061 CMake: Add presets functionality
06128cf949 Presets: Add cmCMakePresetsFile class
5a36542086 Refactor: Add allowArch parameter to cmake::CreateGlobalGenerator()
3059e6aed7 cmJSONHelpers: Add new Bind() function
8682d1b7b2 CMake GUI Tests: Increase default sleep time
Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Michael Hirsch, Ph.D. <michael@scivision.dev>
Merge-request: !5169
Diffstat (limited to 'Help')
-rw-r--r-- | Help/manual/cmake-gui.1.rst | 5 | ||||
-rw-r--r-- | Help/manual/cmake.1.rst | 368 | ||||
-rw-r--r-- | Help/release/dev/cmake-presets.rst | 5 |
3 files changed, 378 insertions, 0 deletions
diff --git a/Help/manual/cmake-gui.1.rst b/Help/manual/cmake-gui.1.rst index ff8311bbed..d9c8ed7e39 100644 --- a/Help/manual/cmake-gui.1.rst +++ b/Help/manual/cmake-gui.1.rst @@ -11,6 +11,7 @@ Synopsis cmake-gui [<options>] cmake-gui [<options>] {<path-to-source> | <path-to-existing-build>} cmake-gui [<options>] -S <path-to-source> -B <path-to-build> + cmake-gui [<options>] -S <path-to-source> --preset=<preset-name> Description =========== @@ -36,6 +37,10 @@ Options If the directory doesn't already exist CMake will make it. +``--preset=<preset-name>`` + Name of the preset to use from the project's ``CMakePresets.json`` file, if it + has one. + .. include:: OPTIONS_HELP.txt See Also diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 9850116093..764f61e309 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -12,6 +12,7 @@ Synopsis cmake [<options>] <path-to-source> cmake [<options>] <path-to-existing-build> cmake [<options>] -S <path-to-source> -B <path-to-build> + cmake [<options>] -S <path-to-source> --preset=<preset-name> `Build a Project`_ cmake --build <dir> [<options>] [-- <build-tool-options>] @@ -148,6 +149,368 @@ 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 + ``<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``. + + The presets are read before all other command line options. The options + specified by the preset (variables, generator, etc.) can all be overridden by + manually specifying them on the command line. For example, if the preset sets + 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: + + .. code-block:: json + + { + "version": 1, + "cmakeMinimumRequired": { + "major": 3, + "minor": 19, + "patch": 0 + }, + "configurePresets": [ + { + "name": "default", + "displayName": "Default Config", + "description": "Default build using Ninja generator", + "generator": "Ninja", + "binaryDir": "${sourceDir}/build/default", + "cacheVariables": [ + { + "name": "MY_CACHE_VARIABLE", + "type": "BOOL", + "value": "OFF" + } + ] + } + ] + } + + 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, 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, + 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>``. 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 @@ -813,6 +1176,11 @@ with one of the following options: .. include:: OPTIONS_HELP.txt +To view the presets available for a project, use + +.. code-block::shell + + cmake <source-dir> --list-presets See Also ======== diff --git a/Help/release/dev/cmake-presets.rst b/Help/release/dev/cmake-presets.rst new file mode 100644 index 0000000000..a901f10935 --- /dev/null +++ b/Help/release/dev/cmake-presets.rst @@ -0,0 +1,5 @@ +cmake-presets +------------- + +* :manual:`cmake(1)` and :manual:`cmake-gui(1)` now recognize + ``CMakePresets.json`` and ``CMakeUserPresets.json`` files. |