diff options
Diffstat (limited to 'Help/manual')
| -rw-r--r-- | Help/manual/VS-Choose-Arch.png | bin | 11130 -> 0 bytes | |||
| -rw-r--r-- | Help/manual/cmake-buildsystem.7.rst | 62 | ||||
| -rw-r--r-- | Help/manual/cmake-commands.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-compile-features.7.rst | 2 | ||||
| -rw-r--r-- | Help/manual/cmake-env-variables.7.rst | 2 | ||||
| -rw-r--r-- | Help/manual/cmake-file-api.7.rst | 25 | ||||
| -rw-r--r-- | Help/manual/cmake-generator-expressions.7.rst | 53 | ||||
| -rw-r--r-- | Help/manual/cmake-generators.7.rst | 2 | ||||
| -rw-r--r-- | Help/manual/cmake-gui.1.rst | 8 | ||||
| -rw-r--r-- | Help/manual/cmake-modules.7.rst | 3 | ||||
| -rw-r--r-- | Help/manual/cmake-policies.7.rst | 22 | ||||
| -rw-r--r-- | Help/manual/cmake-presets.7.rst | 368 | ||||
| -rw-r--r-- | Help/manual/cmake-properties.7.rst | 5 | ||||
| -rw-r--r-- | Help/manual/cmake-server.7.rst | 741 | ||||
| -rw-r--r-- | Help/manual/cmake-toolchains.7.rst | 10 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 13 | ||||
| -rw-r--r-- | Help/manual/cmake.1.rst | 49 | ||||
| -rw-r--r-- | Help/manual/ctest.1.rst | 16 | ||||
| -rw-r--r-- | Help/manual/presets/example.json | 45 | ||||
| -rw-r--r-- | Help/manual/presets/schema.json | 292 |
20 files changed, 935 insertions, 784 deletions
diff --git a/Help/manual/VS-Choose-Arch.png b/Help/manual/VS-Choose-Arch.png Binary files differdeleted file mode 100644 index 816b0f4..0000000 --- a/Help/manual/VS-Choose-Arch.png +++ /dev/null diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index d8142a2..7008383 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -96,6 +96,9 @@ Apple Frameworks A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK` target property to create an macOS or iOS Framework Bundle. +A library with the ``FRAMEWORK`` target property should also set the +:prop_tgt:`FRAMEWORK_VERSION` target property. This property is typically +set to the value of "A" by macOS conventions. The ``MACOSX_FRAMEWORK_IDENTIFIER`` sets ``CFBundleIdentifier`` key and it uniquely identifies the bundle. @@ -104,7 +107,7 @@ and it uniquely identifies the bundle. add_library(MyFramework SHARED MyFramework.cpp) set_target_properties(MyFramework PROPERTIES FRAMEWORK TRUE - FRAMEWORK_VERSION A + FRAMEWORK_VERSION A # Version "A" is macOS convention MACOSX_FRAMEWORK_IDENTIFIER org.cmake.MyFramework ) @@ -115,7 +118,10 @@ Object Libraries The ``OBJECT`` library type defines a non-archival collection of object files resulting from compiling the given source files. The object files collection -may be used as source inputs to other targets: +may be used as source inputs to other targets by using the syntax +``$<TARGET_OBJECTS:name>``. This is a +:manual:`generator expression <cmake-generator-expressions(7)>` that can be +used to supply the ``OBJECT`` library content to other targets: .. code-block:: cmake @@ -373,8 +379,12 @@ position-independent-code, so a diagnostic is issued. The ``lib1`` and ``lib2`` requirements are not "compatible". One of them requires that consumers are built as position-independent-code, while the other requires that consumers are not built as position-independent-code. -Because ``exe2`` links to both and they are in conflict, a diagnostic is -issued. +Because ``exe2`` links to both and they are in conflict, a CMake error message +is issued:: + + CMake Error: The INTERFACE_POSITION_INDEPENDENT_CODE property of "lib2" does + not agree with the value of POSITION_INDEPENDENT_CODE already determined + for "exe2". To be "compatible", the :prop_tgt:`POSITION_INDEPENDENT_CODE` property, if set must be either the same, in a boolean sense, as the @@ -732,7 +742,7 @@ As the value of the :prop_tgt:`POSITION_INDEPENDENT_CODE` property of the ``exe1`` target is dependent on the linked libraries (``lib3``), and the edge of linking ``exe1`` is determined by the same :prop_tgt:`POSITION_INDEPENDENT_CODE` property, the dependency graph above -contains a cycle. :manual:`cmake(1)` issues a diagnostic in this case. +contains a cycle. :manual:`cmake(1)` issues an error message. .. _`Output Artifacts`: @@ -922,8 +932,8 @@ property from it: Interface Libraries ------------------- -An ``INTERFACE`` target has no :prop_tgt:`LOCATION` and is mutable, but is -otherwise similar to an :prop_tgt:`IMPORTED` target. +An ``INTERFACE`` library target does not compile sources and does not +produce a library artifact on disk, so it has no :prop_tgt:`LOCATION`. It may specify usage requirements such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, @@ -937,11 +947,22 @@ Only the ``INTERFACE`` modes of the :command:`target_include_directories`, :command:`target_sources`, and :command:`target_link_libraries` commands may be used with ``INTERFACE`` libraries. +Since CMake 3.19, an ``INTERFACE`` library target may optionally contain +source files. An interface library that contains source files will be +included as a build target in the generated buildsystem. It does not +compile sources, but may contain custom commands to generate other sources. +Additionally, IDEs will show the source files as part of the target for +interactive reading and editing. + A primary use-case for ``INTERFACE`` libraries is header-only libraries. .. code-block:: cmake - add_library(Eigen INTERFACE) + add_library(Eigen INTERFACE + src/eigen.h + src/vector.h + src/matrix.h + ) target_include_directories(Eigen INTERFACE $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src> $<INSTALL_INTERFACE:include/Eigen> @@ -975,25 +996,17 @@ This way, the build specification of ``exe1`` is expressed entirely as linked targets, and the complexity of compiler-specific flags is encapsulated in an ``INTERFACE`` library target. -The properties permitted to be set on or read from an ``INTERFACE`` library -are: - -* Properties matching ``INTERFACE_*`` -* Built-in properties matching ``COMPATIBLE_INTERFACE_*`` -* ``EXPORT_NAME`` -* ``EXPORT_PROPERTIES`` -* ``IMPORTED`` -* ``MANUALLY_ADDED_DEPENDENCIES`` -* ``NAME`` -* Properties matching ``IMPORTED_LIBNAME_*`` -* Properties matching ``MAP_IMPORTED_CONFIG_*`` - ``INTERFACE`` libraries may be installed and exported. Any content they refer to must be installed separately: .. code-block:: cmake - add_library(Eigen INTERFACE) + set(Eigen_headers + src/eigen.h + src/vector.h + src/matrix.h + ) + add_library(Eigen INTERFACE ${Eigen_headers}) target_include_directories(Eigen INTERFACE $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src> $<INSTALL_INTERFACE:include/Eigen> @@ -1003,9 +1016,6 @@ to must be installed separately: install(EXPORT eigenExport NAMESPACE Upstream:: DESTINATION lib/cmake/Eigen ) - install(FILES - ${CMAKE_CURRENT_SOURCE_DIR}/src/eigen.h - ${CMAKE_CURRENT_SOURCE_DIR}/src/vector.h - ${CMAKE_CURRENT_SOURCE_DIR}/src/matrix.h + install(FILES ${Eigen_headers} DESTINATION include/Eigen ) diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst index 0aa4f75..036fa8f 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst @@ -20,6 +20,7 @@ These commands are always available. /command/cmake_language /command/cmake_minimum_required /command/cmake_parse_arguments + /command/cmake_path /command/cmake_policy /command/configure_file /command/continue diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index 05dc038..690d293 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -358,6 +358,7 @@ versions specified for each: * ``Cray``: Cray Compiler Environment version 8.1+. * ``PGI``: PGI version 12.10+. +* ``TI``: Texas Instruments compiler. * ``XL``: IBM XL version 10.1+. CMake is currently aware of the :prop_tgt:`C standards <C_STANDARD>` and @@ -366,7 +367,6 @@ following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: * all compilers and versions listed above with only meta-features for C++. -* ``TI``: Texas Instruments compiler. CMake is currently aware of the :prop_tgt:`CUDA standards <CUDA_STANDARD>` and their associated meta-features (e.g. ``cuda_std_11``) available from the diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index ce1e360..13e0d39 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -63,6 +63,8 @@ Environment Variables for Languages /envvar/CXXFLAGS /envvar/FC /envvar/FFLAGS + /envvar/ISPC + /envvar/ISPCFLAGS /envvar/OBJC /envvar/OBJCXX /envvar/RC diff --git a/Help/manual/cmake-file-api.7.rst b/Help/manual/cmake-file-api.7.rst index cc50952..6876e1c 100644 --- a/Help/manual/cmake-file-api.7.rst +++ b/Help/manual/cmake-file-api.7.rst @@ -425,7 +425,7 @@ Version 1 does not exist to avoid confusion with that from { "kind": "codemodel", - "version": { "major": 2, "minor": 1 }, + "version": { "major": 2, "minor": 2 }, "paths": { "source": "/path/to/top-level-source-dir", "build": "/path/to/top-level-build-dir" @@ -650,7 +650,8 @@ with members: ``type`` A string specifying the type of the target. The value is one of ``EXECUTABLE``, ``STATIC_LIBRARY``, ``SHARED_LIBRARY``, - ``MODULE_LIBRARY``, ``OBJECT_LIBRARY``, or ``UTILITY``. + ``MODULE_LIBRARY``, ``OBJECT_LIBRARY``, ``INTERFACE_LIBRARY``, + or ``UTILITY``. ``backtrace`` Optional member that is present when a CMake language backtrace to @@ -869,6 +870,26 @@ with members: A string specifying the language (e.g. ``C``, ``CXX``, ``Fortran``) of the toolchain is used to compile the source file. + ``languageStandard`` + Optional member that is present when the language standard is set + explicitly (e.g. via :prop_tgt:`CXX_STANDARD`) or implicitly by + compile features. Each entry is a JSON object with two members: + + ``backtraces`` + Optional member that is present when a CMake language backtrace to + the ``<LANG>_STANDARD`` setting is available. If the language + standard was set implicitly by compile features those are used as + the backtrace(s). It's possible for multiple compile features to + require the same language standard so there could be multiple + backtraces. The value is a JSON array with each entry being an + unsigned integer 0-based index into the ``backtraceGraph`` + member's ``nodes`` array. + + ``standard`` + String representing the language standard. + + This field was added in codemodel version 2.2. + ``compileCommandFragments`` Optional member that is present when fragments of the compiler command line invocation are available. The value is a JSON array of entries diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 124da44..ff9d1bf 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -105,10 +105,11 @@ Variable Queries ``$<TARGET_EXISTS:target>`` ``1`` if ``target`` exists, else ``0``. -``$<CONFIG:cfg>`` - ``1`` if config is ``cfg``, else ``0``. This is a case-insensitive comparison. - The mapping in :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by - this expression when it is evaluated on a property on an :prop_tgt:`IMPORTED` +``$<CONFIG:cfgs>`` + ``1`` if config is any one of the entries in ``cfgs``, else ``0``. This is a + case-insensitive comparison. The mapping in + :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by this + expression when it is evaluated on a property on an :prop_tgt:`IMPORTED` target. ``$<PLATFORM_ID:platform_ids>`` where ``platform_ids`` is a comma-separated list. @@ -145,6 +146,11 @@ Variable Queries ``1`` if the CMake's compiler id of the Fortran compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<ISPC_COMPILER_ID:compiler_ids>`` + where ``compiler_ids`` is a comma-separated list. + ``1`` if the CMake's compiler id of the ISPC compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. ``$<C_COMPILER_VERSION:version>`` ``1`` if the version of the C compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. @@ -163,6 +169,9 @@ Variable Queries ``$<Fortran_COMPILER_VERSION:version>`` ``1`` if the version of the Fortran compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<ISPC_COMPILER_VERSION:version>`` + ``1`` if the version of the ISPC compiler matches ``version``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. ``$<TARGET_POLICY:policy>`` ``1`` if the ``policy`` was NEW when the 'head' target was created, else ``0``. If the ``policy`` was not set, the warning message for the policy @@ -542,6 +551,9 @@ Variable Queries ``$<Fortran_COMPILER_ID>`` The CMake's compiler id of the Fortran compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<ISPC_COMPILER_ID>`` + The CMake's compiler id of the ISPC compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. ``$<C_COMPILER_VERSION>`` The version of the C compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. @@ -560,6 +572,9 @@ Variable Queries ``$<Fortran_COMPILER_VERSION>`` The version of the Fortran compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<ISPC_COMPILER_VERSION>`` + The version of the ISPC compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. ``$<COMPILE_LANGUAGE>`` The compile language of source files when evaluating compile options. See :ref:`the related boolean expression @@ -595,6 +610,9 @@ which is just the string ``tgt``. ``$<TARGET_NAME_IF_EXISTS:tgt>`` The target name ``tgt`` if the target exists, an empty string otherwise. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. ``$<TARGET_FILE:tgt>`` Full path to the ``tgt`` binary file. ``$<TARGET_FILE_BASE_NAME:tgt>`` @@ -632,6 +650,9 @@ which is just the string ``tgt``. The ``tgt`` filename. ``$<TARGET_FILE_DIR:tgt>`` Directory of the ``tgt`` binary file. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_LINKER_FILE:tgt>`` File used when linking to the ``tgt`` target. This will usually be the library that ``tgt`` represents (``.a``, ``.lib``, ``.so``), @@ -673,14 +694,26 @@ which is just the string ``tgt``. expression is evaluated on. ``$<TARGET_LINKER_FILE_NAME:tgt>`` Name of file used to link target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_LINKER_FILE_DIR:tgt>`` Directory of file used to link target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_SONAME_FILE:tgt>`` File with soname (``.so.3``) where ``tgt`` is the name of a target. ``$<TARGET_SONAME_FILE_NAME:tgt>`` Name of file with soname (``.so.3``). + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_SONAME_FILE_DIR:tgt>`` Directory of with soname (``.so.3``). + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_PDB_FILE:tgt>`` Full path to the linker generated program database file (.pdb) where ``tgt`` is the name of a target. @@ -706,17 +739,29 @@ which is just the string ``tgt``. expression is evaluated on. ``$<TARGET_PDB_FILE_NAME:tgt>`` Name of the linker generated program database file (.pdb). + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_PDB_FILE_DIR:tgt>`` Directory of the linker generated program database file (.pdb). + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_BUNDLE_DIR:tgt>`` Full path to the bundle directory (``my.app``, ``my.framework``, or ``my.bundle``) where ``tgt`` is the name of a target. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_BUNDLE_CONTENT_DIR:tgt>`` Full path to the bundle content directory where ``tgt`` is the name of a target. For the macOS SDK it leads to ``my.app/Contents``, ``my.framework``, or ``my.bundle/Contents``. For all other SDKs (e.g. iOS) it leads to ``my.app``, ``my.framework``, or ``my.bundle`` due to the flat bundle structure. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_PROPERTY:tgt,prop>`` Value of the property ``prop`` on the target ``tgt``. diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index 6f88c0a..8ca2bf6 100644 --- a/Help/manual/cmake-generators.7.rst +++ b/Help/manual/cmake-generators.7.rst @@ -52,6 +52,8 @@ Makefile Generators /generator/Unix Makefiles /generator/Watcom WMake +.. _`Ninja Generators`: + Ninja Generators ^^^^^^^^^^^^^^^^ diff --git a/Help/manual/cmake-gui.1.rst b/Help/manual/cmake-gui.1.rst index ff8311b..281986f 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>] --browse-manual Description =========== @@ -36,6 +37,13 @@ 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 + :manual:`presets <cmake-presets(7)>` files, if it has them. + +``--browse-manual`` + Open the CMake reference manual in a browser and immediately exit. + .. include:: OPTIONS_HELP.txt See Also diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 50131e8..14af149 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -45,6 +45,9 @@ These modules are loaded using the :command:`include` command. /module/CheckOBJCXXSourceRuns /module/CheckPIESupported /module/CheckPrototypeDefinition + /module/CheckCompilerFlag + /module/CheckSourceCompiles + /module/CheckSourceRuns /module/CheckStructHasMember /module/CheckSymbolExists /module/CheckTypeSize diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index e98038a..0116674 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,28 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used to determine whether to report an error on use of deprecated macros or functions. +Policies Introduced by CMake 3.20 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0116: Ninja generators transform DEPFILEs from add_custom_command(). </policy/CMP0116> + CMP0115: Source file extensions must be explicit. </policy/CMP0115> + +Policies Introduced by CMake 3.19 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0114: ExternalProject step targets fully adopt their steps. </policy/CMP0114> + CMP0113: Makefile generators do not repeat custom commands from target dependencies. </policy/CMP0113> + CMP0112: Target file component generator expressions do not add target dependencies. </policy/CMP0112> + CMP0111: An imported target missing its location property fails during generation. </policy/CMP0111> + CMP0110: add_test() supports arbitrary characters in test names. </policy/CMP0110> + CMP0109: find_program() requires permission to execute but not to read. </policy/CMP0109> + Policies Introduced by CMake 3.18 ================================= diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst new file mode 100644 index 0000000..62c4b7c --- /dev/null +++ b/Help/manual/cmake-presets.7.rst @@ -0,0 +1,368 @@ +.. 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. + + ``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`` + ``toolset`` + + Optional fields representing the platform and toolset, respectively, for + generators that support them. Each may be either a string or an object + with the following fields: + + ``value`` + + An optional string representing the value. + + ``strategy`` + + An optional string telling CMake how to handle the ``architecture`` or + ``toolset`` field. Valid values are: + + ``"set"`` + + Set the respective value. This will result in an error for generators + that do not support the respective field. + + ``"external"`` + + Do not set the value, even if the generator supports it. 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 the field, 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 boolean + (which is equivalent to a value of ``"TRUE"`` or ``"FALSE"`` and a type + of ``BOOL``), 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 or boolean representing the value of the variable. + A boolean is equivalent to ``"TRUE"`` or ``"FALSE"``. 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 the warnings to enable. 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. + + ``unusedCli`` + + 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 the errors to enable. 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``. + + ``debug`` + + An optional object specifying debug options. The object may contain the + following fields: + + ``output`` + + An optional boolean. Setting this to ``true`` is equivalent to passing + ``--debug-output`` on the command line. + + ``tryCompile`` + + An optional boolean. Setting this to ``true`` is equivalent to passing + ``--debug-trycompile`` on the command line. + + ``find`` + + An optional boolean. Setting this to ``true`` is equivalent to passing + ``--debug-find`` on the command line. + + 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. + + ``${sourceDirName}`` + + The last filename component of ``${sourceDir}``. For example, if + ``${sourceDir}`` is ``/path/to/source``, this would be ``source``. + + ``${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}``. + +Schema +====== + +:download:`This file </manual/presets/schema.json>` provides a machine-readable +JSON schema for the ``CMakePresets.json`` format. diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 30b2a05..cb9579e 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -258,6 +258,8 @@ Properties on Targets /prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG /prop_tgt/INTERPROCEDURAL_OPTIMIZATION /prop_tgt/IOS_INSTALL_COMBINED + /prop_tgt/ISPC_HEADER_DIRECTORY + /prop_tgt/ISPC_INSTRUCTION_SETS /prop_tgt/JOB_POOL_COMPILE /prop_tgt/JOB_POOL_LINK /prop_tgt/JOB_POOL_PRECOMPILE_HEADER @@ -307,11 +309,13 @@ Properties on Targets /prop_tgt/OBJCXX_EXTENSIONS /prop_tgt/OBJCXX_STANDARD /prop_tgt/OBJCXX_STANDARD_REQUIRED + /prop_tgt/OPTIMIZE_DEPENDENCIES /prop_tgt/OSX_ARCHITECTURES_CONFIG /prop_tgt/OSX_ARCHITECTURES /prop_tgt/OUTPUT_NAME_CONFIG /prop_tgt/OUTPUT_NAME /prop_tgt/PCH_WARN_INVALID + /prop_tgt/PCH_INSTANTIATE_TEMPLATES /prop_tgt/PDB_NAME_CONFIG /prop_tgt/PDB_NAME /prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG @@ -394,6 +398,7 @@ Properties on Targets /prop_tgt/XCODE_ATTRIBUTE_an-attribute /prop_tgt/XCODE_EXPLICIT_FILE_TYPE /prop_tgt/XCODE_GENERATE_SCHEME + /prop_tgt/XCODE_LINK_BUILD_PHASE_MODE /prop_tgt/XCODE_PRODUCT_TYPE /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN diff --git a/Help/manual/cmake-server.7.rst b/Help/manual/cmake-server.7.rst index 8f10b9f..6c8d0f4 100644 --- a/Help/manual/cmake-server.7.rst +++ b/Help/manual/cmake-server.7.rst @@ -3,742 +3,5 @@ cmake-server(7) *************** -.. only:: html - - .. contents:: - -.. deprecated:: 3.15 - - This will be removed from a future version of CMake. - Clients should use the :manual:`cmake-file-api(7)` instead. - -Introduction -============ - -:manual:`cmake(1)` is capable of providing semantic information about -CMake code it executes to generate a buildsystem. If executed with -the ``-E server`` command line options, it starts in a long running mode -and allows a client to request the available information via a JSON protocol. - -The protocol is designed to be useful to IDEs, refactoring tools, and -other tools which have a need to understand the buildsystem in entirety. - -A single :manual:`cmake-buildsystem(7)` may describe buildsystem contents -and build properties which differ based on -:manual:`generation-time context <cmake-generator-expressions(7)>` -including: - -* The Platform (eg, Windows, APPLE, Linux). -* The build configuration (eg, Debug, Release, Coverage). -* The Compiler (eg, MSVC, GCC, Clang) and compiler version. -* The language of the source files compiled. -* Available compile features (eg CXX variadic templates). -* CMake policies. - -The protocol aims to provide information to tooling to satisfy several -needs: - -#. Provide a complete and easily parsed source of all information relevant - to the tooling as it relates to the source code. There should be no need - for tooling to parse generated buildsystems to access include directories - or compile definitions for example. -#. Semantic information about the CMake buildsystem itself. -#. Provide a stable interface for reading the information in the CMake cache. -#. Information for determining when cmake needs to be re-run as a result of - file changes. - - -Operation -========= - -Start :manual:`cmake(1)` in the server command mode, supplying the path to -the build directory to process:: - - cmake -E server (--debug|--pipe=<NAMED_PIPE>) - -The server will communicate using stdin/stdout (with the ``--debug`` parameter) -or using a named pipe (with the ``--pipe=<NAMED_PIPE>`` parameter). Note -that "named pipe" refers to a local domain socket on Unix and to a named pipe -on Windows. - -When connecting to the server (via named pipe or by starting it in ``--debug`` -mode), the server will reply with a hello message:: - - [== "CMake Server" ==[ - {"supportedProtocolVersions":[{"major":1,"minor":0}],"type":"hello"} - ]== "CMake Server" ==] - -Messages sent to and from the process are wrapped in magic strings:: - - [== "CMake Server" ==[ - { - ... some JSON message ... - } - ]== "CMake Server" ==] - -The server is now ready to accept further requests via the named pipe -or stdin. - - -Debugging -========= - -CMake server mode can be asked to provide statistics on execution times, etc. -or to dump a copy of the response into a file. This is done passing a "debug" -JSON object as a child of the request. - -The debug object supports the "showStats" key, which takes a boolean and makes -the server mode return a "zzzDebug" object with stats as part of its response. -"dumpToFile" takes a string value and will cause the cmake server to copy -the response into the given filename. - -This is a response from the cmake server with "showStats" set to true:: - - [== "CMake Server" ==[ - { - "cookie":"", - "errorMessage":"Waiting for type \"handshake\".", - "inReplyTo":"unknown", - "type":"error", - "zzzDebug": { - "dumpFile":"/tmp/error.txt", - "jsonSerialization":0.011016, - "size":111, - "totalTime":0.025995 - } - } - ]== "CMake Server" ==] - -The server has made a copy of this response into the file /tmp/error.txt and -took 0.011 seconds to turn the JSON response into a string, and it took 0.025 -seconds to process the request in total. The reply has a size of 111 bytes. - - -Protocol API -============ - - -General Message Layout ----------------------- - -All messages need to have a "type" value, which identifies the type of -message that is passed back or forth. E.g. the initial message sent by the -server is of type "hello". Messages without a type will generate an response -of type "error". - -All requests sent to the server may contain a "cookie" value. This value -will he handed back unchanged in all responses triggered by the request. - -All responses will contain a value "inReplyTo", which may be empty in -case of parse errors, but will contain the type of the request message -in all other cases. - - -Type "reply" -^^^^^^^^^^^^ - -This type is used by the server to reply to requests. - -The message may -- depending on the type of the original request -- -contain values. - -Example:: - - [== "CMake Server" ==[ - {"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"} - ]== "CMake Server" ==] - - -Type "error" -^^^^^^^^^^^^ - -This type is used to return an error condition to the client. It will -contain an "errorMessage". - -Example:: - - [== "CMake Server" ==[ - {"cookie":"","errorMessage":"Protocol version not supported.","inReplyTo":"handshake","type":"error"} - ]== "CMake Server" ==] - - -Type "progress" -^^^^^^^^^^^^^^^ - -When the server is busy for a long time, it is polite to send back replies of -type "progress" to the client. These will contain a "progressMessage" with a -string describing the action currently taking place as well as -"progressMinimum", "progressMaximum" and "progressCurrent" with integer values -describing the range of progress. - -Messages of type "progress" will be followed by more "progress" messages or with -a message of type "reply" or "error" that complete the request. - -"progress" messages may not be emitted after the "reply" or "error" message for -the request that triggered the responses was delivered. - - -Type "message" -^^^^^^^^^^^^^^ - -A message is triggered when the server processes a request and produces some -form of output that should be displayed to the user. A Message has a "message" -with the actual text to display as well as a "title" with a suggested dialog -box title. - -Example:: - - [== "CMake Server" ==[ - {"cookie":"","message":"Something happened.","title":"Title Text","inReplyTo":"handshake","type":"message"} - ]== "CMake Server" ==] - - -Type "signal" -^^^^^^^^^^^^^ - -The server can send signals when it detects changes in the system state. Signals -are of type "signal", have an empty "cookie" and "inReplyTo" field and always -have a "name" set to show which signal was sent. - - -Specific Signals ----------------- - -The cmake server may sent signals with the following names: - -"dirty" Signal -^^^^^^^^^^^^^^ - -The "dirty" signal is sent whenever the server determines that the configuration -of the project is no longer up-to-date. This happens when any of the files that have -an influence on the build system is changed. - -The "dirty" signal may look like this:: - - [== "CMake Server" ==[ - { - "cookie":"", - "inReplyTo":"", - "name":"dirty", - "type":"signal"} - ]== "CMake Server" ==] - - -"fileChange" Signal -^^^^^^^^^^^^^^^^^^^ - -The "fileChange" signal is sent whenever a watched file is changed. It contains -the "path" that has changed and a list of "properties" with the kind of change -that was detected. Possible changes are "change" and "rename". - -The "fileChange" signal looks like this:: - - [== "CMake Server" ==[ - { - "cookie":"", - "inReplyTo":"", - "name":"fileChange", - "path":"/absolute/CMakeLists.txt", - "properties":["change"], - "type":"signal"} - ]== "CMake Server" ==] - - -Specific Message Types ----------------------- - - -Type "hello" -^^^^^^^^^^^^ - -The initial message send by the cmake server on startup is of type "hello". -This is the only message ever sent by the server that is not of type "reply", -"progress" or "error". - -It will contain "supportedProtocolVersions" with an array of server protocol -versions supported by the cmake server. These are JSON objects with "major" and -"minor" keys containing non-negative integer values. Some versions may be marked -as experimental. These will contain the "isExperimental" key set to true. Enabling -these requires a special command line argument when starting the cmake server mode. - -Within a "major" version all "minor" versions are fully backwards compatible. -New "minor" versions may introduce functionality in such a way that existing -clients of the same "major" version will continue to work, provided they -ignore keys in the output that they do not know about. - -Example:: - - [== "CMake Server" ==[ - {"supportedProtocolVersions":[{"major":0,"minor":1}],"type":"hello"} - ]== "CMake Server" ==] - - -Type "handshake" -^^^^^^^^^^^^^^^^ - -The first request that the client may send to the server is of type "handshake". - -This request needs to pass one of the "supportedProtocolVersions" of the "hello" -type response received earlier back to the server in the "protocolVersion" field. -Giving the "major" version of the requested protocol version will make the server -use the latest minor version of that protocol. Use this if you do not explicitly -need to depend on a specific minor version. - -Protocol version 1.0 requires the following attributes to be set: - - * "sourceDirectory" with a path to the sources - * "buildDirectory" with a path to the build directory - * "generator" with the generator name - * "extraGenerator" (optional!) with the extra generator to be used - * "platform" with the generator platform (if supported by the generator) - * "toolset" with the generator toolset (if supported by the generator) - -Protocol version 1.2 makes all but the build directory optional, provided -there is a valid cache in the build directory that contains all the other -information already. - -Example:: - - [== "CMake Server" ==[ - {"cookie":"zimtstern","type":"handshake","protocolVersion":{"major":0}, - "sourceDirectory":"/home/code/cmake", "buildDirectory":"/tmp/testbuild", - "generator":"Ninja"} - ]== "CMake Server" ==] - -which will result in a response type "reply":: - - [== "CMake Server" ==[ - {"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"} - ]== "CMake Server" ==] - -indicating that the server is ready for action. - - -Type "globalSettings" -^^^^^^^^^^^^^^^^^^^^^ - -This request can be sent after the initial handshake. It will return a -JSON structure with information on cmake state. - -Example:: - - [== "CMake Server" ==[ - {"type":"globalSettings"} - ]== "CMake Server" ==] - -which will result in a response type "reply":: - - [== "CMake Server" ==[ - { - "buildDirectory": "/tmp/test-build", - "capabilities": { - "generators": [ - { - "extraGenerators": [], - "name": "Watcom WMake", - "platformSupport": false, - "toolsetSupport": false - }, - <...> - ], - "serverMode": false, - "version": { - "isDirty": false, - "major": 3, - "minor": 6, - "patch": 20160830, - "string": "3.6.20160830-gd6abad", - "suffix": "gd6abad" - } - }, - "checkSystemVars": false, - "cookie": "", - "extraGenerator": "", - "generator": "Ninja", - "debugOutput": false, - "inReplyTo": "globalSettings", - "sourceDirectory": "/home/code/cmake", - "trace": false, - "traceExpand": false, - "type": "reply", - "warnUninitialized": false, - "warnUnused": false, - "warnUnusedCli": true - } - ]== "CMake Server" ==] - - -Type "setGlobalSettings" -^^^^^^^^^^^^^^^^^^^^^^^^ - -This request can be sent to change the global settings attributes. Unknown -attributes are going to be ignored. Read-only attributes reported by -"globalSettings" are all capabilities, buildDirectory, generator, -extraGenerator and sourceDirectory. Any attempt to set these will be ignored, -too. - -All other settings will be changed. - -The server will respond with an empty reply message or an error. - -Example:: - - [== "CMake Server" ==[ - {"type":"setGlobalSettings","debugOutput":true} - ]== "CMake Server" ==] - -CMake will reply to this with:: - - [== "CMake Server" ==[ - {"inReplyTo":"setGlobalSettings","type":"reply"} - ]== "CMake Server" ==] - - -Type "configure" -^^^^^^^^^^^^^^^^ - -This request will configure a project for build. - -To configure a build directory already containing cmake files, it is enough to -set "buildDirectory" via "setGlobalSettings". To create a fresh build directory -you also need to set "currentGenerator" and "sourceDirectory" via "setGlobalSettings" -in addition to "buildDirectory". - -You may a list of strings to "configure" via the "cacheArguments" key. These -strings will be interpreted similar to command line arguments related to -cache handling that are passed to the cmake command line client. - -Example:: - - [== "CMake Server" ==[ - {"type":"configure", "cacheArguments":["-Dsomething=else"]} - ]== "CMake Server" ==] - -CMake will reply like this (after reporting progress for some time):: - - [== "CMake Server" ==[ - {"cookie":"","inReplyTo":"configure","type":"reply"} - ]== "CMake Server" ==] - - -Type "compute" -^^^^^^^^^^^^^^ - -This request will generate build system files in the build directory and -is only available after a project was successfully "configure"d. - -Example:: - - [== "CMake Server" ==[ - {"type":"compute"} - ]== "CMake Server" ==] - -CMake will reply (after reporting progress information):: - - [== "CMake Server" ==[ - {"cookie":"","inReplyTo":"compute","type":"reply"} - ]== "CMake Server" ==] - - -Type "codemodel" -^^^^^^^^^^^^^^^^ - -The "codemodel" request can be used after a project was "compute"d successfully. - -It will list the complete project structure as it is known to cmake. - -The reply will contain a key "configurations", which will contain a list of -configuration objects. Configuration objects are used to destinquish between -different configurations the build directory might have enabled. While most -generators only support one configuration, others might support several. - -Each configuration object can have the following keys: - -"name" - contains the name of the configuration. The name may be empty. -"projects" - contains a list of project objects, one for each build project. - -Project objects define one (sub-)project defined in the cmake build system. - -Each project object can have the following keys: - -"name" - contains the (sub-)projects name. -"minimumCMakeVersion" - contains the minimum cmake version allowed for this project, null if the - project doesn't specify one. -"hasInstallRule" - true if the project contains any install rules, false otherwise. -"sourceDirectory" - contains the current source directory -"buildDirectory" - contains the current build directory. -"targets" - contains a list of build system target objects. - -Target objects define individual build targets for a certain configuration. - -Each target object can have the following keys: - -"name" - contains the name of the target. -"type" - defines the type of build of the target. Possible values are - "STATIC_LIBRARY", "MODULE_LIBRARY", "SHARED_LIBRARY", "OBJECT_LIBRARY", - "EXECUTABLE", "UTILITY" and "INTERFACE_LIBRARY". -"fullName" - contains the full name of the build result (incl. extensions, etc.). -"sourceDirectory" - contains the current source directory. -"buildDirectory" - contains the current build directory. -"isGeneratorProvided" - true if the target is auto-created by a generator, false otherwise -"hasInstallRule" - true if the target contains any install rules, false otherwise. -"installPaths" - full path to the destination directories defined by target install rules. -"artifacts" - with a list of build artifacts. The list is sorted with the most - important artifacts first (e.g. a .DLL file is listed before a - .PDB file on windows). -"linkerLanguage" - contains the language of the linker used to produce the artifact. -"linkLibraries" - with a list of libraries to link to. This value is encoded in the - system's native shell format. -"linkFlags" - with a list of flags to pass to the linker. This value is encoded in - the system's native shell format. -"linkLanguageFlags" - with the flags for a compiler using the linkerLanguage. This value is - encoded in the system's native shell format. -"frameworkPath" - with the framework path (on Apple computers). This value is encoded - in the system's native shell format. -"linkPath" - with the link path. This value is encoded in the system's native shell - format. -"sysroot" - with the sysroot path. -"fileGroups" - contains the source files making up the target. - -FileGroups are used to group sources using similar settings together. - -Each fileGroup object may contain the following keys: - -"language" - contains the programming language used by all files in the group. -"compileFlags" - with a string containing all the flags passed to the compiler - when building any of the files in this group. This value is encoded in - the system's native shell format. -"includePath" - with a list of include paths. Each include path is an object - containing a "path" with the actual include path and "isSystem" with a bool - value informing whether this is a normal include or a system include. This - value is encoded in the system's native shell format. -"defines" - with a list of defines in the form "SOMEVALUE" or "SOMEVALUE=42". This - value is encoded in the system's native shell format. -"sources" - with a list of source files. - -All file paths in the fileGroup are either absolute or relative to the -sourceDirectory of the target. - -Example:: - - [== "CMake Server" ==[ - {"type":"codemodel"} - ]== "CMake Server" ==] - -CMake will reply:: - - [== "CMake Server" ==[ - { - "configurations": [ - { - "name": "", - "projects": [ - { - "buildDirectory": "/tmp/build/Source/CursesDialog/form", - "name": "CMAKE_FORM", - "sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form", - "targets": [ - { - "artifacts": [ "/tmp/build/Source/CursesDialog/form/libcmForm.a" ], - "buildDirectory": "/tmp/build/Source/CursesDialog/form", - "fileGroups": [ - { - "compileFlags": " -std=gnu11", - "defines": [ "CURL_STATICLIB", "LIBARCHIVE_STATIC" ], - "includePath": [ { "path": "/tmp/build/Utilities" }, <...> ], - "isGenerated": false, - "language": "C", - "sources": [ "fld_arg.c", <...> ] - } - ], - "fullName": "libcmForm.a", - "linkerLanguage": "C", - "name": "cmForm", - "sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form", - "type": "STATIC_LIBRARY" - } - ] - }, - <...> - ] - } - ], - "cookie": "", - "inReplyTo": "codemodel", - "type": "reply" - } - ]== "CMake Server" ==] - - -Type "ctestInfo" -^^^^^^^^^^^^^^^^ - -The "ctestInfo" request can be used after a project was "compute"d successfully. - -It will list the complete project test structure as it is known to cmake. - -The reply will contain a key "configurations", which will contain a list of -configuration objects. Configuration objects are used to destinquish between -different configurations the build directory might have enabled. While most -generators only support one configuration, others might support several. - -Each configuration object can have the following keys: - -"name" - contains the name of the configuration. The name may be empty. -"projects" - contains a list of project objects, one for each build project. - -Project objects define one (sub-)project defined in the cmake build system. - -Each project object can have the following keys: - -"name" - contains the (sub-)projects name. -"ctestInfo" - contains a list of test objects. - -Each test object can have the following keys: - -"ctestName" - contains the name of the test. -"ctestCommand" - contains the test command. -"properties" - contains a list of test property objects. - -Each test property object can have the following keys: - -"key" - contains the test property key. -"value" - contains the test property value. - - -Type "cmakeInputs" -^^^^^^^^^^^^^^^^^^ - -The "cmakeInputs" requests will report files used by CMake as part -of the build system itself. - -This request is only available after a project was successfully -"configure"d. - -Example:: - - [== "CMake Server" ==[ - {"type":"cmakeInputs"} - ]== "CMake Server" ==] - -CMake will reply with the following information:: - - [== "CMake Server" ==[ - {"buildFiles": - [ - {"isCMake":true,"isTemporary":false,"sources":["/usr/lib/cmake/...", ... ]}, - {"isCMake":false,"isTemporary":false,"sources":["CMakeLists.txt", ...]}, - {"isCMake":false,"isTemporary":true,"sources":["/tmp/build/CMakeFiles/...", ...]} - ], - "cmakeRootDirectory":"/usr/lib/cmake", - "sourceDirectory":"/home/code/src/cmake", - "cookie":"", - "inReplyTo":"cmakeInputs", - "type":"reply" - } - ]== "CMake Server" ==] - -All file names are either relative to the top level source directory or -absolute. - -The list of files which "isCMake" set to true are part of the cmake installation. - -The list of files witch "isTemporary" set to true are part of the build directory -and will not survive the build directory getting cleaned out. - - -Type "cache" -^^^^^^^^^^^^ - -The "cache" request will list the cached configuration values. - -Example:: - - [== "CMake Server" ==[ - {"type":"cache"} - ]== "CMake Server" ==] - -CMake will respond with the following output:: - - [== "CMake Server" ==[ - { - "cookie":"","inReplyTo":"cache","type":"reply", - "cache": - [ - { - "key":"SOMEVALUE", - "properties": - { - "ADVANCED":"1", - "HELPSTRING":"This is not helpful" - } - "type":"STRING", - "value":"TEST"} - ] - } - ]== "CMake Server" ==] - -The output can be limited to a list of keys by passing an array of key names -to the "keys" optional field of the "cache" request. - - -Type "fileSystemWatchers" -^^^^^^^^^^^^^^^^^^^^^^^^^ - -The server can watch the filesystem for changes. The "fileSystemWatchers" -command will report on the files and directories watched. - -Example:: - - [== "CMake Server" ==[ - {"type":"fileSystemWatchers"} - ]== "CMake Server" ==] - -CMake will respond with the following output:: - - [== "CMake Server" ==[ - { - "cookie":"","inReplyTo":"fileSystemWatchers","type":"reply", - "watchedFiles": [ "/absolute/path" ], - "watchedDirectories": [ "/absolute" ] - } - ]== "CMake Server" ==] +The :manual:`cmake(1)` server mode has been removed since CMake 3.20. +Clients should use the :manual:`cmake-file-api(7)` instead. diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index e8badd4..88cddf6 100644 --- a/Help/manual/cmake-toolchains.7.rst +++ b/Help/manual/cmake-toolchains.7.rst @@ -312,8 +312,9 @@ is specific to the Android development environment to be used. For :ref:`Visual Studio Generators`, CMake expects :ref:`NVIDIA Nsight Tegra Visual Studio Edition <Cross Compiling for Android with NVIDIA Nsight Tegra -Visual Studio Edition>` to be installed. See that section for further -configuration details. +Visual Studio Edition>` or the :ref:`Visual Studio tools for Android +<Cross Compiling for Android with the NDK>` to be installed. See those sections +for further configuration details. For :ref:`Makefile Generators` and the :generator:`Ninja` generator, CMake expects one of these environments: @@ -363,8 +364,9 @@ CMake uses the following steps to select one of the environments: Cross Compiling for Android with the NDK ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -A toolchain file may configure :ref:`Makefile Generators` or the -:generator:`Ninja` generator to target Android for cross-compiling. +A toolchain file may configure :ref:`Makefile Generators`, +:ref:`Ninja Generators`, or :ref:`Visual Studio Generators` to target +Android for cross-compiling. Configure use of an Android NDK with the following variables: diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 4ce8365..f0c9d99 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -124,7 +124,8 @@ Variables that Provide Information /variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE /variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION - /variable/CMAKE_XCODE_GENERATE_SCHEME + /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM + /variable/CMAKE_XCODE_BUILD_SYSTEM /variable/CMAKE_XCODE_PLATFORM_TOOLSET /variable/PROJECT-NAME_BINARY_DIR /variable/PROJECT-NAME_DESCRIPTION @@ -158,6 +159,7 @@ Variables that Change Behavior /variable/CMAKE_AUTOMOC_RELAXED_MODE /variable/CMAKE_BACKWARDS_COMPATIBILITY /variable/CMAKE_BUILD_TYPE + /variable/CMAKE_CLANG_VFS_OVERLAY /variable/CMAKE_CODEBLOCKS_COMPILER_ID /variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES /variable/CMAKE_CODELITE_USE_TARGETS @@ -244,7 +246,9 @@ Variables that Change Behavior /variable/CMAKE_USER_MAKE_RULES_OVERRIDE /variable/CMAKE_WARN_DEPRECATED /variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION + /variable/CMAKE_XCODE_GENERATE_SCHEME /variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY + /variable/CMAKE_XCODE_LINK_BUILD_PHASE_MODE /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN /variable/CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING @@ -332,6 +336,7 @@ Variables that Control the Build /variable/CMAKE_ANDROID_ARM_MODE /variable/CMAKE_ANDROID_ARM_NEON /variable/CMAKE_ANDROID_ASSETS_DIRECTORIES + /variable/CMAKE_ANDROID_EXCEPTIONS /variable/CMAKE_ANDROID_GUI /variable/CMAKE_ANDROID_JAR_DEPENDENCIES /variable/CMAKE_ANDROID_JAR_DIRECTORIES @@ -345,6 +350,7 @@ Variables that Control the Build /variable/CMAKE_ANDROID_PROCESS_MAX /variable/CMAKE_ANDROID_PROGUARD /variable/CMAKE_ANDROID_PROGUARD_CONFIG_PATH + /variable/CMAKE_ANDROID_RTTI /variable/CMAKE_ANDROID_SECURE_PROPS_PATH /variable/CMAKE_ANDROID_SKIP_ANT_STEP /variable/CMAKE_ANDROID_STANDALONE_TOOLCHAIN @@ -436,10 +442,12 @@ Variables that Control the Build /variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX /variable/CMAKE_NO_BUILTIN_CHRPATH /variable/CMAKE_NO_SYSTEM_FROM_IMPORTED + /variable/CMAKE_OPTIMIZE_DEPENDENCIES /variable/CMAKE_OSX_ARCHITECTURES /variable/CMAKE_OSX_DEPLOYMENT_TARGET /variable/CMAKE_OSX_SYSROOT /variable/CMAKE_PCH_WARN_INVALID + /variable/CMAKE_PCH_INSTANTIATE_TEMPLATES /variable/CMAKE_PDB_OUTPUT_DIRECTORY /variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_POSITION_INDEPENDENT_CODE @@ -507,12 +515,15 @@ Variables for Languages /variable/CMAKE_Fortran_MODDIR_DEFAULT /variable/CMAKE_Fortran_MODDIR_FLAG /variable/CMAKE_Fortran_MODOUT_FLAG + /variable/CMAKE_ISPC_HEADER_DIRECTORY + /variable/CMAKE_ISPC_INSTRUCTION_SETS /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_MACHINE /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_PREFIX /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_SUFFIX /variable/CMAKE_LANG_ARCHIVE_APPEND /variable/CMAKE_LANG_ARCHIVE_CREATE /variable/CMAKE_LANG_ARCHIVE_FINISH + /variable/CMAKE_LANG_BYTE_ORDER /variable/CMAKE_LANG_COMPILER /variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN /variable/CMAKE_LANG_COMPILER_ID diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 9becfc6..7efe0cd 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -295,6 +295,11 @@ Options ``line`` The line in ``file`` of the function call. + ``defer`` + Optional member that is present when the function call was deferred + by :command:`cmake_language(DEFER)`. If present, its value is a + string containing the deferred call ``<id>``. + ``cmd`` The name of the function that was called. @@ -317,7 +322,7 @@ Options { "version": { "major": 1, - "minor": 0 + "minor": 1 } } @@ -341,9 +346,9 @@ Options Print a warning when an uninitialized variable is used. ``--warn-unused-vars`` - Warn about unused variables. - - Find variables that are declared or set, but not used. + Does nothing. In CMake versions 3.2 and below this enabled warnings about + unused variables. In CMake versions 3.3 through 3.18 the option was broken. + In CMake 3.19 and above the option has been removed. ``--no-warn-unused-cli`` Don't warn about command line options. @@ -359,7 +364,7 @@ Options This flag tells CMake to warn about other files as well. ``--profiling-output=<path>`` - Used in conjuction with ``--profiling-format`` to output to a given path. + Used in conjunction with ``--profiling-format`` to output to a given path. ``--profiling-format=<file>`` Enable the output of profiling data of CMake script in the given format. @@ -372,6 +377,21 @@ Options about:tracing tab of Google Chrome or using a plugin for a tool like Trace Compass. +``--preset=<preset>`` + 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. 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 + 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. + .. _`Build Tool Mode`: Build a Project @@ -450,6 +470,9 @@ The options are: ``--component <comp>`` Component-based install. Only install component ``<comp>``. +``--default-directory-permissions <permissions>`` + Default directory install permissions. Permissions in format ``<u=rwx,g=rx,o=rx>``. + ``--prefix <prefix>`` Override the installation prefix, :variable:`CMAKE_INSTALL_PREFIX`. @@ -557,6 +580,7 @@ Available commands are: ``serverMode`` ``true`` if cmake supports server-mode and ``false`` otherwise. + Always false since CMake 3.20. ``cat <files>...`` Concatenate files and print on the standard output. @@ -566,7 +590,8 @@ Available commands are: ``compare_files [--ignore-eol] <file1> <file2>`` Check if ``<file1>`` is same as ``<file2>``. If files are the same, - then returns ``0``, if not it returns ``1``. The ``--ignore-eol`` option + then returns ``0``, if not it returns ``1``. In case of invalid + arguments, it returns 2. The ``--ignore-eol`` option implies line-wise comparison and ignores LF/CRLF differences. ``copy <file>... <destination>`` @@ -594,6 +619,13 @@ Available commands are: .. note:: Path to where ``<new>`` symbolic link will be created has to exist beforehand. +``create_hardlink <old> <new>`` + Create a hard link ``<new>`` naming ``<old>``. + + .. note:: + Path to where ``<new>`` hard link will be created has to exist beforehand. + ``<old>`` has to exist beforehand. + ``echo [<string>...]`` Displays arguments as text. @@ -797,6 +829,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/manual/ctest.1.rst b/Help/manual/ctest.1.rst index d3ab75a..e947232 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -1142,6 +1142,20 @@ Additional configuration settings include: * `CTest Script`_ variable: none * :module:`CTest` module variable: ``DRMEMORY_COMMAND_OPTIONS`` +``CudaMemcheckCommand`` + Specify a ``MemoryCheckCommand`` that is known to be a command-line + compatible with cuda-memcheck or compute-sanitizer. + + * `CTest Script`_ variable: none + * :module:`CTest` module variable: ``CUDA_MEMCHECK_COMMAND`` + +``CudaMemcheckCommandOptions`` + Specify command-line options to the ``CudaMemcheckCommand`` tool. + They will be placed prior to the test command line. + + * `CTest Script`_ variable: none + * :module:`CTest` module variable: ``CUDA_MEMCHECK_COMMAND_OPTIONS`` + .. _`CTest Submit Step`: CTest Submit Step @@ -1333,7 +1347,7 @@ Resource Allocation =================== CTest provides a mechanism for tests to specify the resources that they need -in a fine-grained way, and for users to specify the resources availiable on +in a fine-grained way, and for users to specify the resources available on the running machine. This allows CTest to internally keep track of which resources are in use and which are free, scheduling tests in a way that prevents them from trying to claim resources that are not available. diff --git a/Help/manual/presets/example.json b/Help/manual/presets/example.json new file mode 100644 index 0000000..d3b6f4a --- /dev/null +++ b/Help/manual/presets/example.json @@ -0,0 +1,45 @@ +{ + "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": { + "FIRST_CACHE_VARIABLE": { + "type": "BOOL", + "value": "OFF" + }, + "SECOND_CACHE_VARIABLE": "ON" + }, + "environment": { + "MY_ENVIRONMENT_VARIABLE": "Test", + "PATH": "$env{HOME}/ninja/bin:$penv{PATH}" + }, + "vendor": { + "example.com/ExampleIDE/1.0": { + "autoFormat": true + } + } + }, + { + "name": "ninja-multi", + "inherits": "default", + "displayName": "Ninja Multi-Config", + "description": "Default build using Ninja Multi-Config generator", + "generator": "Ninja Multi-Config" + } + ], + "vendor": { + "example.com/ExampleIDE/1.0": { + "autoFormat": false + } + } +} diff --git a/Help/manual/presets/schema.json b/Help/manual/presets/schema.json new file mode 100644 index 0000000..57b063e --- /dev/null +++ b/Help/manual/presets/schema.json @@ -0,0 +1,292 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "description": "The presets specify the generator and the build directory, and optionally a list of variables and other arguments to pass to CMake.", + "properties": { + "version": { + "type": "integer", + "description": "A required integer representing the version of the JSON schema. Currently, the only supported version is 1.", + "minimum": 1, + "maximum": 1 + }, + "cmakeMinimumRequired": { + "type": "object", + "description": "An optional object representing the minimum version of CMake needed to build this project.", + "properties": { + "major": { + "type": "integer", + "description": "An optional integer representing the major version." + }, + "minor": { + "type": "integer", + "description": "An optional integer representing the minor version." + }, + "patch": { + "type": "integer", + "description": "An optional integer representing the patch version." + } + }, + "additionalProperties": false + }, + "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, 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.", + "properties": {} + }, + "configurePresets": { + "type": "array", + "description": "An optional array of configure preset objects.", + "items": { + "type": "object", + "description": "A configure preset 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 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 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": { + "anyOf": [ + { + "type": "string", + "description": "An optional string representing the name of the preset to inherit from.", + "minLength": 1 + }, + { + "type": "array", + "description": "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.", + "items": { + "type": "string", + "description": "An optional string representing the name of the preset to inherit from.", + "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." + }, + "generator": { + "type": "string", + "description": "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": { + "anyOf": [ + { + "type": "string", + "description": "An optional string representing the platform for generators that support it." + }, + { + "type": "object", + "description": "An optional object representing the platform for generators that support it.", + "properties": { + "value": { + "type": "string", + "description": "An optional string representing the value." + }, + "strategy": { + "type": "string", + "description": "An optional string telling CMake how to handle the field. Valid values are: \"set\" Set the respective value. This will result in an error for generators that do not support the respective field. \"external\" Do not set the value, even if the generator supports it. 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 the field, but the IDE can use them to set up the environment before invoking CMake.", + "enum": [ + "set", + "external" + ] + } + }, + "additionalProperties": false + } + ] + }, + "toolset": { + "anyOf": [ + { + "type": "string", + "description": "An optional string representing the toolset for generators that support it." + }, + { + "type": "object", + "description": "An optional object representing the toolset for generators that support it.", + "properties": { + "value": { + "type": "string", + "description": "An optional string representing the value." + }, + "strategy": { + "type": "string", + "description": "An optional string telling CMake how to handle the field. Valid values are: \"set\" Set the respective value. This will result in an error for generators that do not support the respective field. \"external\" Do not set the value, even if the generator supports it. 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 the field, but the IDE can use them to set up the environment before invoking CMake.", + "enum": [ + "set", + "external" + ] + } + }, + "additionalProperties": false + } + ] + }, + "binaryDir": { + "type": "string", + "description": "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": { + "type": "string", + "description": "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": { + "type": "object", + "description": "An optional map of cache variables. The key is the variable name (which must not be an empty string). 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.", + "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": "boolean", + "description": "A boolean representing the value of the variable. Equivalent to \"TRUE\" or \"FALSE\"." + }, + { + "type": "string", + "description": "A string representing the value of the variable (which supports macro expansion)." + }, + { + "type": "object", + "description": "An object representing the type and value of the variable.", + "properties": { + "type": { + "type": "string", + "description": "An optional string representing the type of the variable. It should be BOOL, FILEPATH, PATH, STRING, or INTERNAL." + }, + "value": { + "anyOf": [ + { + "type": "boolean", + "description": "A required boolean representing the value of the variable. Equivalent to \"TRUE\" or \"FALSE\"." + }, + { + "type": "string", + "description": "A required string representing the value of the variable. This field supports macro expansion." + } + ] + } + }, + "required": [ + "value" + ], + "additionalProperties": false + } + ] + }, + "propertyNames": { + "pattern": "^.+$" + } + }, + "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": "^.+$" + } + }, + "warnings": { + "type": "object", + "description": "An optional object specifying warnings.", + "properties": { + "dev": { + "type": "boolean", + "description": "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": { + "type": "boolean", + "description": "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": { + "type": "boolean", + "description": "An optional boolean. Setting this to true is equivalent to passing --warn-uninitialized on the command line." + }, + "unusedCli": { + "type": "boolean", + "description": "An optional boolean. Setting this to false is equivalent to passing --no-warn-unused-cli on the command line." + }, + "systemVars": { + "type": "boolean", + "description": "An optional boolean. Setting this to true is equivalent to passing --check-system-vars on the command line." + } + }, + "additionalProperties": false + }, + "errors": { + "type": "object", + "description": "An optional object specifying errors.", + "properties": { + "dev": { + "type": "boolean", + "description": "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": { + "type": "boolean", + "description": "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." + } + }, + "additionalProperties": false + }, + "debug": { + "type": "object", + "description": "An optional object specifying debug options.", + "properties": { + "output": { + "type": "boolean", + "description": "An optional boolean. Setting this to true is equivalent to passing --debug-output on the command line." + }, + "tryCompile": { + "type": "boolean", + "description": "An optional boolean. Setting this to true is equivalent to passing --debug-trycompile on the command line." + }, + "find": { + "type": "boolean", + "description": "An optional boolean. Setting this to true is equivalent to passing --debug-find on the command line." + } + }, + "additionalProperties": false + } + }, + "required": [ + "name" + ], + "additionalProperties": false + } + } + }, + "required": [ + "version" + ], + "additionalProperties": false +} |
