diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/manual/cmake-presets.7.rst | 140 | ||||
| -rw-r--r-- | Help/manual/cmake.1.rst | 6 | ||||
| -rw-r--r-- | Help/manual/cpack.1.rst | 8 | ||||
| -rw-r--r-- | Help/manual/presets/schema.json | 200 | ||||
| -rw-r--r-- | Help/release/dev/cmake-presets-package.rst | 5 |
5 files changed, 349 insertions, 10 deletions
diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst index 16cd54e..35dac76 100644 --- a/Help/manual/cmake-presets.7.rst +++ b/Help/manual/cmake-presets.7.rst @@ -58,6 +58,9 @@ The root object recognizes the following fields: ``5`` .. versionadded:: 3.24 + ``6`` + .. versionadded:: 3.25 + ``cmakeMinimumRequired`` An optional object representing the minimum version of CMake needed to build this project. This object consists of the following fields: @@ -128,7 +131,8 @@ that may contain the following fields: 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`` and ``CMakeUserPresets.json`` in the same directory with the same name. - However, a configure preset may have the same name as a build or test preset. + However, a configure preset may have the same name as a build, test, or + package preset. ``hidden`` An optional boolean specifying whether or not a preset should be hidden. @@ -350,7 +354,8 @@ that may contain the following fields: :ref:`cmake --build --preset <Build Tool Mode>` option. There must not be two build presets in the union of ``CMakePresets.json`` and ``CMakeUserPresets.json`` in the same directory with the same name. - However, a build preset may have the same name as a configure or test preset. + However, a build preset may have the same name as a configure, test, or + package preset. ``hidden`` An optional boolean specifying whether or not a preset should be hidden. @@ -510,7 +515,8 @@ that may contain the following fields: This identifier is used in the :option:`ctest --preset` option. There must not be two test presets in the union of ``CMakePresets.json`` and ``CMakeUserPresets.json`` in the same directory with the same name. - However, a test preset may have the same name as a configure or build preset. + However, a test preset may have the same name as a configure, build, or + package preset. ``hidden`` An optional boolean specifying whether or not a preset should be hidden. @@ -833,6 +839,134 @@ that may contain the following fields: Equivalent to passing :option:`--no-tests=ignore <ctest --no-tests>` on the command line. +Package Preset +^^^^^^^^^^^^^^ + +Package presets may be used in schema version ``6`` or above. Each entry of +the ``packagePresets`` 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:`cpack --preset` option. + There must not be two package presets in the union of ``CMakePresets.json`` + and ``CMakeUserPresets.json`` in the same directory with the same name. + However, a package preset may have the same name as a configure, 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 + :option:`--preset <cpack --preset>` argument + and does not have to have a valid ``configurePreset``, 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. This field can also be a string, which is equivalent to an array + containing one string. + + 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. + + A preset can only inherit from another preset that is defined in the + same file or in one of the files it includes (directly or indirectly). + Presets in ``CMakePresets.json`` may not inherit from presets in + ``CMakeUserPresets.json``. + +``condition`` + An optional `Condition`_ object. + +``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. + +``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. + +``configurePreset`` + An optional string specifying the name of a configure preset to + associate with this package preset. If ``configurePreset`` is not + specified, it must be inherited from the inherits preset (unless this + preset is hidden). The build directory is inferred from the configure + preset, so packaging will run in the same ``binaryDir`` that the + 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 package preset environments, but before environment variables + explicitly specified in this package preset. + +``generators`` + An optional list of strings representing generators for CPack to use. + +``configurations`` + An optional list of strings representing build configurations for CPack to + package. + +``variables`` + An optional map of variables to pass to CPack, equivalent to + :option:`-D <cpack -D>` arguments. Each key is the name of a variable, and + the value is the string to assign to that variable. + +``configFile`` + An optional string representing the config file for CPack to use. + +``output`` + An optional object specifying output options. Valid keys are: + + ``debug`` + An optional boolean specifying whether or not to print debug information. + A value of ``true`` is equivalent to passing + :option:`--debug <cpack --debug>` on the command line. + + ``verbose`` + An optional boolean specifying whether or not to print verbosely. A value + of ``true`` is equivalent to passing :option:`--verbose <cpack --verbose>` + on the command line. + +``packageName`` + An optional string representing the package name. + +``packageVersion`` + An optional string representing the package version. + +``packageDirectory`` + An optional string representing the directory in which to place the package. + +``vendorName`` + An optional string representing the vendor name. + Condition ^^^^^^^^^ diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 8cec9d4..a3e9fd0 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -500,9 +500,9 @@ Options .. option:: --list-presets[=<type>] Lists the available presets of the specified ``<type>``. Valid values for - ``<type>`` are ``configure``, ``build``, ``test``, or ``all``. If ``<type>`` - is omitted, ``configure`` is assumed. The current working directory must - contain CMake preset files. + ``<type>`` are ``configure``, ``build``, ``test``, ``package``, or ``all``. + If ``<type>`` is omitted, ``configure`` is assumed. The current working + directory must contain CMake preset files. .. _`Build Tool Mode`: diff --git a/Help/manual/cpack.1.rst b/Help/manual/cpack.1.rst index a95df8b..3f26d72 100644 --- a/Help/manual/cpack.1.rst +++ b/Help/manual/cpack.1.rst @@ -119,6 +119,14 @@ Options Override/define :variable:`CPACK_PACKAGE_VENDOR`. +.. option:: --preset <presetName> + + Use a preset from :manual:`cmake-presets(7)`. + +.. option:: --list-presets + + List presets from :manual:`cmake-presets(7)`. + .. include:: OPTIONS_HELP.txt See Also diff --git a/Help/manual/presets/schema.json b/Help/manual/presets/schema.json index c96405c..f3a7532 100644 --- a/Help/manual/presets/schema.json +++ b/Help/manual/presets/schema.json @@ -72,6 +72,22 @@ "include": { "$ref": "#/definitions/include"} }, "additionalProperties": false + }, + { + "properties": { + "version": { + "const": 6, + "description": "A required integer representing the version of the JSON schema." + }, + "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, + "vendor": { "$ref": "#/definitions/vendor" }, + "configurePresets": { "$ref": "#/definitions/configurePresetsV3"}, + "buildPresets": { "$ref": "#/definitions/buildPresetsV4"}, + "testPresets": { "$ref": "#/definitions/testPresetsV5"}, + "packagePresets": { "$ref": "#/definitions/packagePresetsV6"}, + "include": { "$ref": "#/definitions/include"} + }, + "additionalProperties": false } ], "required": [ @@ -476,12 +492,12 @@ "properties": { "name": { "type": "string", - "description": "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 (configure, build, or test) in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", + "description": "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 (configure, build, test, or package) in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", "minLength": 1 }, "hidden": { "type": "boolean", - "description": "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 CMake GUI, and does not have to have a valid configurePreset, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." + "description": "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 and does not have to have a valid configurePreset, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." }, "inherits": { "anyOf": [ @@ -728,12 +744,12 @@ "properties": { "name": { "type": "string", - "description": "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 (configure, build, or test) in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", + "description": "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 (configure, build, test, or package) in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", "minLength": 1 }, "hidden": { "type": "boolean", - "description": "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 CMake GUI, and does not have to have a valid configurePreset, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." + "description": "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 and does not have to have a valid configurePreset, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." }, "inherits": { "anyOf": [ @@ -1129,6 +1145,182 @@ "additionalProperties": false } }, + "packagePresetsItemsV6": { + "type": "array", + "description": "An optional array of package preset objects. Used to specify arguments to cpack. Available in version 6 and higher.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "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 (configure, build, test, or package) in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", + "minLength": 1 + }, + "hidden": { + "type": "boolean", + "description": "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 and does not have to have a valid configurePreset, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." + }, + "inherits": { + "anyOf": [ + { + "type": "string", + "description": "An optional string representing the name of the package preset to inherit from.", + "minLength": 1 + }, + { + "type": "array", + "description": "An optional array of strings representing the names of package 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 must not inherit from presets in CMakeUserPresets.json.", + "items": { + "type": "string", + "description": "An optional string representing the name of the preset to inherit from.", + "minLength": 1 + } + } + ] + }, + "configurePreset": { + "type": "string", + "description": "An optional string specifying the name of a configure preset to associate with this package preset. If configurePreset is not specified, it must be inherited from the inherits preset (unless this preset is hidden). The build tree directory is inferred from the configure preset.", + "minLength": 1 + }, + "vendor": { + "type": "object", + "description": "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.", + "properties": {} + }, + "displayName": { + "type": "string", + "description": "An optional string with a human-friendly name of the preset." + }, + "description": { + "type": "string", + "description": "An optional string with a human-friendly description of the preset." + }, + "inheritConfigureEnvironment": { + "type": "boolean", + "description": "An optional boolean that defaults to true. If true, the environment variables from the associated configure preset are inherited after all inherited package preset environments, but before environment variables explicitly specified in this package preset." + }, + "environment": { + "type": "object", + "description": "An optional map of environment variables. The key is the variable name (which must not be an empty string). 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.", + "properties": {}, + "additionalProperties": { + "anyOf": [ + { + "type": "null", + "description": "Setting a variable to null causes it to not be set, even if a value was inherited from another preset." + }, + { + "type": "string", + "description": "A string representing the value of the variable." + } + ] + }, + "propertyNames": { + "pattern": "^.+$" + } + }, + "condition": { "$ref": "#/definitions/topCondition" }, + "generators": { + "type": "array", + "description": "An optional list of strings representing generators for CPack to use.", + "items": { + "type": "string", + "description": "An optional string representing the name of the CPack generator to use." + } + }, + "configurations": { + "type": "array", + "description": "An optional list of strings representing build configurations for CPack to package.", + "items": { + "type": "string", + "description": "An optional string representing the name of the configuration to use." + } + }, + "variables": { + "type": "object", + "description": "An optional map of variables to pass to CPack, equivalent to -D arguments. Each key is the name of a variable, and the value is the string to assign to that variable.", + "items": { + "type": "string", + "description": "An optional string representing the value of the variable." + } + }, + "configFile": { + "type": "string", + "description": "An optional string representing the config file for CPack to use." + }, + "output": { + "type": "object", + "description": "An optional object specifying output options.", + "properties": { + "debug": { + "type": "boolean", + "description": "An optional boolean specifying whether or not to print debug information. A value of true is equivalent to passing --debug on the command line." + }, + "verbose": { + "type": "boolean", + "description": "An optional boolean specifying whether or not to print verbosely. A value of true is equivalent to passing --verbose on the command line." + } + }, + "additionalProperties": false + }, + "packageName": { + "type": "string", + "description": "An optional string representing the package name." + }, + "packageVersion": { + "type": "string", + "description": "An optional string representing the package version." + }, + "packageDirectory": { + "type": "string", + "description": "An optional string representing the directory in which to place the package." + }, + "vendorName": { + "type": "string", + "description": "An optional string representing the vendor name." + } + }, + "required": [ + "name" + ] + } + }, + "packagePresetsV6": { + "type": "array", + "description": "An optional array of package preset objects. Used to specify arguments to cpack. Available in version 6 and higher.", + "allOf": [ + { "$ref": "#/definitions/packagePresetsItemsV6" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "condition": {}, + "generators": {}, + "configurations": {}, + "variables": {}, + "configFile": {}, + "output": {}, + "packageName": {}, + "packageVersion": {}, + "packageDirectory": {}, + "vendorName": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, "condition": { "anyOf": [ { diff --git a/Help/release/dev/cmake-presets-package.rst b/Help/release/dev/cmake-presets-package.rst new file mode 100644 index 0000000..8f7ea6b --- /dev/null +++ b/Help/release/dev/cmake-presets-package.rst @@ -0,0 +1,5 @@ +cmake-presets-package +--------------------- + +* The :manual:`cmake-presets(7)` schema version has been bumped to ``6``. +* The :manual:`cmake-presets(7)` format now supports a ``packagePresets`` field. |