diff options
Diffstat (limited to 'Help/manual/cmake.1.rst')
| -rw-r--r-- | Help/manual/cmake.1.rst | 334 |
1 files changed, 5 insertions, 329 deletions
diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index b345db0..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 @@ -1156,7 +832,7 @@ with one of the following options: To view the presets available for a project, use -.. code-block::shell +.. code-block:: shell cmake <source-dir> --list-presets |