diff options
| -rw-r--r-- | Help/guide/user-interaction/index.rst | 2 | ||||
| -rw-r--r-- | Help/index.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-presets.7.rst | 347 | ||||
| -rw-r--r-- | Help/manual/cmake.1.rst | 332 |
4 files changed, 353 insertions, 329 deletions
diff --git a/Help/guide/user-interaction/index.rst b/Help/guide/user-interaction/index.rst index 4bde0be..9e9f2a5 100644 --- a/Help/guide/user-interaction/index.rst +++ b/Help/guide/user-interaction/index.rst @@ -421,7 +421,7 @@ presets can set the build directory, generator, cache variables, environment variables, and other command-line options. All of these options can be overridden by the user. The full details of the ``CMakePresets.json`` format -are listed in the :manual:`cmake(1)` manual. +are listed in the :manual:`cmake-presets(7)` manual. Using presets on the command-line --------------------------------- diff --git a/Help/index.rst b/Help/index.rst index 6d87f71..fdbf847 100644 --- a/Help/index.rst +++ b/Help/index.rst @@ -66,6 +66,7 @@ Reference Manuals /manual/cmake-modules.7 /manual/cmake-packages.7 /manual/cmake-policies.7 + /manual/cmake-presets.7 /manual/cmake-properties.7 /manual/cmake-qt.7 /manual/cmake-server.7 diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst new file mode 100644 index 0000000..2c0aa48 --- /dev/null +++ b/Help/manual/cmake-presets.7.rst @@ -0,0 +1,347 @@ +.. cmake-manual-description: CMakePresets.json + +cmake-presets(7) +**************** + +.. only:: html + + .. contents:: + +Introduction +============ + +One problem that CMake users often face is sharing settings with other people +for common ways to configure a project. This may be done to support CI builds, +or for users who frequently use the same build. CMake supports two files, +``CMakePresets.json`` and ``CMakeUserPresets.json``, that allow users to +specify common configure options and share them with others. + +``CMakePresets.json`` and ``CMakeUserPresets.json`` live in the project's root +directory. They both 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``. + +Format +====== + + 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}``. diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index b8a1b42..5452c79 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -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 |