diff options
Diffstat (limited to 'Help/manual')
| -rw-r--r-- | Help/manual/OPTIONS_BUILD.txt | 103 | ||||
| -rw-r--r-- | Help/manual/OPTIONS_HELP.txt | 68 | ||||
| -rw-r--r-- | Help/manual/ccmake.1.rst | 4 | ||||
| -rw-r--r-- | Help/manual/cmake-buildsystem.7.rst | 8 | ||||
| -rw-r--r-- | Help/manual/cmake-commands.7.rst | 2 | ||||
| -rw-r--r-- | Help/manual/cmake-env-variables.7.rst | 2 | ||||
| -rw-r--r-- | Help/manual/cmake-generator-expressions.7.rst | 38 | ||||
| -rw-r--r-- | Help/manual/cmake-generators.7.rst | 16 | ||||
| -rw-r--r-- | Help/manual/cmake-gui.1.rst | 16 | ||||
| -rw-r--r-- | Help/manual/cmake-modules.7.rst | 2 | ||||
| -rw-r--r-- | Help/manual/cmake-policies.7.rst | 10 | ||||
| -rw-r--r-- | Help/manual/cmake-presets.7.rst | 606 | ||||
| -rw-r--r-- | Help/manual/cmake-properties.7.rst | 24 | ||||
| -rw-r--r-- | Help/manual/cmake-toolchains.7.rst | 72 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 48 | ||||
| -rw-r--r-- | Help/manual/cmake.1.rst | 527 | ||||
| -rw-r--r-- | Help/manual/cpack.1.rst | 52 | ||||
| -rw-r--r-- | Help/manual/ctest.1.rst | 465 | ||||
| -rw-r--r-- | Help/manual/presets/example.json | 34 | ||||
| -rw-r--r-- | Help/manual/presets/schema.json | 405 |
20 files changed, 1752 insertions, 750 deletions
diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt index 8e23b77..94adac8 100644 --- a/Help/manual/OPTIONS_BUILD.txt +++ b/Help/manual/OPTIONS_BUILD.txt @@ -1,12 +1,15 @@ -``-S <path-to-source>`` +.. option:: -S <path-to-source> + Path to root directory of the CMake project to build. -``-B <path-to-build>`` +.. option:: -B <path-to-build> + Path to directory which CMake will use as the root of build directory. If the directory doesn't already exist CMake will make it. -``-C <initial-cache>`` +.. option:: -C <initial-cache> + Pre-load a script to populate the cache. When CMake is first run in an empty build tree, it creates a @@ -21,7 +24,8 @@ References to :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR` within the script evaluate to the top-level source and build tree. -``-D <var>:<type>=<value>, -D <var>=<value>`` +.. option:: -D <var>:<type>=<value>, -D <var>=<value> + Create or update a CMake ``CACHE`` entry. When CMake is first run in an empty build tree, it creates a @@ -41,7 +45,27 @@ This option may also be given as a single argument: ``-D<var>:<type>=<value>`` or ``-D<var>=<value>``. -``-U <globbing_expr>`` + It's important to note that the order of ``-C`` and ``-D`` arguments is + significant. They will be carried out in the order they are listed, with the + last argument taking precedence over the previous ones. For example, if you + specify ``-DCMAKE_BUILD_TYPE=Debug``, followed by a ``-C`` argument with a + file that calls: + + .. code-block:: cmake + + set(CMAKE_BUILD_TYPE "Release" CACHE STRING "" FORCE) + + then the ``-C`` argument will take precedence, and ``CMAKE_BUILD_TYPE`` will + be set to ``Release``. However, if the ``-D`` argument comes after the ``-C`` + argument, it will be set to ``Debug``. + + If a ``set(... CACHE ...)`` call in the ``-C`` file does not use ``FORCE``, + and a ``-D`` argument sets the same variable, the ``-D`` argument will take + precedence regardless of order because of the nature of non-``FORCE`` + ``set(... CACHE ...)`` calls. + +.. option:: -U <globbing_expr> + Remove matching entries from CMake ``CACHE``. This option may be used to remove one or more variables from the @@ -51,7 +75,8 @@ Use with care, you can make your ``CMakeCache.txt`` non-working. -``-G <generator-name>`` +.. option:: -G <generator-name> + Specify a build system generator. CMake may support multiple native build systems on certain @@ -62,73 +87,85 @@ If not specified, CMake checks the :envvar:`CMAKE_GENERATOR` environment variable and otherwise falls back to a builtin default selection. -``-T <toolset-spec>`` +.. option:: -T <toolset-spec> + Toolset specification for the generator, if supported. Some CMake generators support a toolset specification to tell the native build system how to choose a compiler. See the :variable:`CMAKE_GENERATOR_TOOLSET` variable for details. -``-A <platform-name>`` +.. option:: -A <platform-name> + Specify platform name if supported by generator. Some CMake generators support a platform name to be given to the native build system to choose a compiler or SDK. See the :variable:`CMAKE_GENERATOR_PLATFORM` variable for details. -``--toolchain <path-to-file>`` +.. option:: --toolchain <path-to-file> + Specify the cross compiling toolchain file, equivalent to setting :variable:`CMAKE_TOOLCHAIN_FILE` variable. -``--install-prefix <directory>`` +.. option:: --install-prefix <directory> + Specify the installation directory, used by the :variable:`CMAKE_INSTALL_PREFIX` variable. Must be an absolute path. -``-Wno-dev`` +.. option:: -Wno-dev + Suppress developer warnings. Suppress warnings that are meant for the author of the ``CMakeLists.txt`` files. By default this will also turn off deprecation warnings. -``-Wdev`` +.. option:: -Wdev + Enable developer warnings. Enable warnings that are meant for the author of the ``CMakeLists.txt`` files. By default this will also turn on deprecation warnings. -``-Werror=dev`` - Make developer warnings errors. - - Make warnings that are meant for the author of the ``CMakeLists.txt`` files - errors. By default this will also turn on deprecated warnings as errors. +.. option:: -Wdeprecated -``-Wno-error=dev`` - Make developer warnings not errors. - - Make warnings that are meant for the author of the ``CMakeLists.txt`` files not - errors. By default this will also turn off deprecated warnings as errors. - -``-Wdeprecated`` Enable deprecated functionality warnings. Enable warnings for usage of deprecated functionality, that are meant for the author of the ``CMakeLists.txt`` files. -``-Wno-deprecated`` +.. option:: -Wno-deprecated + Suppress deprecated functionality warnings. Suppress warnings for usage of deprecated functionality, that are meant for the author of the ``CMakeLists.txt`` files. -``-Werror=deprecated`` - Make deprecated macro and function warnings errors. +.. option:: -Werror=<what> + + Treat CMake warnings as errors. ``<what>`` must be one of the following: + + ``dev`` + Make developer warnings errors. + + Make warnings that are meant for the author of the ``CMakeLists.txt`` files + errors. By default this will also turn on deprecated warnings as errors. + + ``deprecated`` + Make deprecated macro and function warnings errors. + + Make warnings for usage of deprecated macros and functions, that are meant + for the author of the ``CMakeLists.txt`` files, errors. + +.. option:: -Wno-error=<what> - Make warnings for usage of deprecated macros and functions, that are meant - for the author of the ``CMakeLists.txt`` files, errors. + Do not treat CMake warnings as errors. ``<what>`` must be one of the following: -``-Wno-error=deprecated`` - Make deprecated macro and function warnings not errors. + ``dev`` + Make warnings that are meant for the author of the ``CMakeLists.txt`` files not + errors. By default this will also turn off deprecated warnings as errors. - Make warnings for usage of deprecated macros and functions, that are meant - for the author of the ``CMakeLists.txt`` files, not errors. + ``deprecated`` + Make warnings for usage of deprecated macros and functions, that are meant + for the author of the ``CMakeLists.txt`` files, not errors. diff --git a/Help/manual/OPTIONS_HELP.txt b/Help/manual/OPTIONS_HELP.txt index feeca7d..78ee245 100644 --- a/Help/manual/OPTIONS_HELP.txt +++ b/Help/manual/OPTIONS_HELP.txt @@ -1,134 +1,152 @@ -.. |file| replace:: The help is printed to a named <f>ile if given. +.. |file| replace:: The output is printed to a named ``<file>`` if given. + +.. option:: -version [<file>], --version [<file>], /V [<file>] + + Show program name/version banner and exit. + |file| + +.. option:: -h, -H, --help, -help, -usage, /? -``--help,-help,-usage,-h,-H,/?`` Print usage information and exit. Usage describes the basic command line interface and its options. -``--version,-version,/V [<f>]`` - Show program name/version banner and exit. +.. option:: --help-full [<file>] - If a file is specified, the version is written into it. - |file| - -``--help-full [<f>]`` Print all help manuals and exit. All manuals are printed in a human-readable text format. |file| -``--help-manual <man> [<f>]`` +.. option:: --help-manual <man> [<file>] + Print one help manual and exit. The specified manual is printed in a human-readable text format. |file| -``--help-manual-list [<f>]`` +.. option:: --help-manual-list [<file>] + List help manuals available and exit. The list contains all manuals for which help may be obtained by using the ``--help-manual`` option followed by a manual name. |file| -``--help-command <cmd> [<f>]`` +.. option:: --help-command <cmd> [<file>] + Print help for one command and exit. The :manual:`cmake-commands(7)` manual entry for ``<cmd>`` is printed in a human-readable text format. |file| -``--help-command-list [<f>]`` +.. option:: --help-command-list [<file>] + List commands with help available and exit. The list contains all commands for which help may be obtained by using the ``--help-command`` option followed by a command name. |file| -``--help-commands [<f>]`` +.. option:: --help-commands [<file>] + Print cmake-commands manual and exit. The :manual:`cmake-commands(7)` manual is printed in a human-readable text format. |file| -``--help-module <mod> [<f>]`` +.. option:: --help-module <mod> [<file>] + Print help for one module and exit. The :manual:`cmake-modules(7)` manual entry for ``<mod>`` is printed in a human-readable text format. |file| -``--help-module-list [<f>]`` +.. option:: --help-module-list [<file>] + List modules with help available and exit. The list contains all modules for which help may be obtained by using the ``--help-module`` option followed by a module name. |file| -``--help-modules [<f>]`` +.. option:: --help-modules [<file>] + Print cmake-modules manual and exit. The :manual:`cmake-modules(7)` manual is printed in a human-readable text format. |file| -``--help-policy <cmp> [<f>]`` +.. option:: --help-policy <cmp> [<file>] + Print help for one policy and exit. The :manual:`cmake-policies(7)` manual entry for ``<cmp>`` is printed in a human-readable text format. |file| -``--help-policy-list [<f>]`` +.. option:: --help-policy-list [<file>] + List policies with help available and exit. The list contains all policies for which help may be obtained by using the ``--help-policy`` option followed by a policy name. |file| -``--help-policies [<f>]`` +.. option:: --help-policies [<file>] + Print cmake-policies manual and exit. The :manual:`cmake-policies(7)` manual is printed in a human-readable text format. |file| -``--help-property <prop> [<f>]`` +.. option:: --help-property <prop> [<file>] + Print help for one property and exit. The :manual:`cmake-properties(7)` manual entries for ``<prop>`` are printed in a human-readable text format. |file| -``--help-property-list [<f>]`` +.. option:: --help-property-list [<file>] + List properties with help available and exit. The list contains all properties for which help may be obtained by using the ``--help-property`` option followed by a property name. |file| -``--help-properties [<f>]`` +.. option:: --help-properties [<file>] + Print cmake-properties manual and exit. The :manual:`cmake-properties(7)` manual is printed in a human-readable text format. |file| -``--help-variable <var> [<f>]`` +.. option:: --help-variable <var> [<file>] + Print help for one variable and exit. The :manual:`cmake-variables(7)` manual entry for ``<var>`` is printed in a human-readable text format. |file| -``--help-variable-list [<f>]`` +.. option:: --help-variable-list [<file>] + List variables with help available and exit. The list contains all variables for which help may be obtained by using the ``--help-variable`` option followed by a variable name. |file| -``--help-variables [<f>]`` +.. option:: --help-variables [<file>] + Print cmake-variables manual and exit. The :manual:`cmake-variables(7)` manual is printed in a diff --git a/Help/manual/ccmake.1.rst b/Help/manual/ccmake.1.rst index 60d45a3..cd66d51 100644 --- a/Help/manual/ccmake.1.rst +++ b/Help/manual/ccmake.1.rst @@ -8,7 +8,7 @@ Synopsis .. parsed-literal:: - ccmake [<options>] {<path-to-source> | <path-to-existing-build>} + ccmake [<options>] <path-to-source | path-to-existing-build> Description =========== @@ -27,6 +27,8 @@ native tool on their platform. Options ======= +.. program:: ccmake + .. include:: OPTIONS_BUILD.txt .. include:: OPTIONS_HELP.txt diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index bceff2d..b14160c 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -257,7 +257,7 @@ targets in multiple different directories convenient through use of the Transitive Usage Requirements ----------------------------- -The usage requirements of a target can transitively propagate to dependents. +The usage requirements of a target can transitively propagate to the dependents. The :command:`target_link_libraries` command has ``PRIVATE``, ``INTERFACE`` and ``PUBLIC`` keywords to control the propagation. @@ -279,8 +279,10 @@ The :command:`target_link_libraries` command has ``PRIVATE``, # consumer is compiled with -DUSING_ARCHIVE_LIB target_link_libraries(consumer archiveExtras) -Because ``archive`` is a ``PUBLIC`` dependency of ``archiveExtras``, the -usage requirements of it are propagated to ``consumer`` too. Because +Because the ``archive`` is a ``PUBLIC`` dependency of ``archiveExtras``, the +usage requirements of it are propagated to ``consumer`` too. + +Because ``serialization`` is a ``PRIVATE`` dependency of ``archiveExtras``, the usage requirements of it are not propagated to ``consumer``. diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst index 036fa8f..0f35632 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst @@ -15,6 +15,7 @@ These commands are always available. .. toctree:: :maxdepth: 1 + /command/block /command/break /command/cmake_host_system_information /command/cmake_language @@ -26,6 +27,7 @@ These commands are always available. /command/continue /command/else /command/elseif + /command/endblock /command/endforeach /command/endfunction /command/endif diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index 737b22c..50fcf75 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -21,6 +21,8 @@ Environment Variables that Change Behavior :maxdepth: 1 /envvar/CMAKE_PREFIX_PATH + /envvar/SSL_CERT_DIR + /envvar/SSL_CERT_FILE Environment Variables that Control the Build ============================================ diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 7a6188a..69e3f20 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -594,6 +594,10 @@ Configuration Expressions expression when it is evaluated on a property of an :prop_tgt:`IMPORTED` target. + .. versionchanged:: 3.19 + Multiple configurations can be specified for ``cfgs``. + CMake 3.18 and earlier only accepted a single configuration. + .. genex:: $<OUTPUT_CONFIG:...> .. versionadded:: 3.20 @@ -627,9 +631,8 @@ Platform .. genex:: $<PLATFORM_ID:platform_ids> - where ``platform_ids`` is a comma-separated list. ``1`` if CMake's platform id matches any one of the entries in - ``platform_ids``, otherwise ``0``. + comma-separated list ``platform_ids``, otherwise ``0``. See also the :variable:`CMAKE_SYSTEM_NAME` variable. Compiler Version @@ -844,10 +847,15 @@ related to most of the expressions in this sub-section. .. versionadded:: 3.3 - ``1`` when the language used for compilation unit matches any of the entries - in ``languages``, otherwise ``0``. This expression may be used to specify - compile options, compile definitions, and include directories for source - files of a particular language in a target. For example: + .. versionchanged:: 3.15 + Multiple languages can be specified for ``languages``. + CMake 3.14 and earlier only accepted a single language. + + ``1`` when the language used for compilation unit matches any of the + comma-separated entries in ``languages``, otherwise ``0``. This expression + may be used to specify compile options, compile definitions, and include + directories for source files of a particular language in a target. For + example: .. code-block:: cmake @@ -892,8 +900,8 @@ related to most of the expressions in this sub-section. ``1`` when the language used for compilation unit matches ``language`` and CMake's compiler id of the ``language`` compiler matches any one of the - entries in ``compiler_ids``, otherwise ``0``. This expression is a short form - for the combination of ``$<COMPILE_LANGUAGE:language>`` and + comma-separated entries in ``compiler_ids``, otherwise ``0``. This expression + is a short form for the combination of ``$<COMPILE_LANGUAGE:language>`` and ``$<LANG_COMPILER_ID:compiler_ids>``. This expression may be used to specify compile options, compile definitions, and include directories for source files of a particular language and compiler combination in a target. @@ -967,10 +975,10 @@ Linker Language And ID .. versionadded:: 3.18 - ``1`` when the language used for link step matches any of the entries - in ``languages``, otherwise ``0``. This expression may be used to specify - link libraries, link options, link directories and link dependencies of a - particular language in a target. For example: + ``1`` when the language used for link step matches any of the comma-separated + entries in ``languages``, otherwise ``0``. This expression may be used to + specify link libraries, link options, link directories and link dependencies + of a particular language in a target. For example: .. code-block:: cmake @@ -1033,9 +1041,9 @@ Linker Language And ID .. versionadded:: 3.18 ``1`` when the language used for link step matches ``language`` and the - CMake's compiler id of the language linker matches any one of the entries - in ``compiler_ids``, otherwise ``0``. This expression is a short form for the - combination of ``$<LINK_LANGUAGE:language>`` and + CMake's compiler id of the language linker matches any one of the comma-separated + entries in ``compiler_ids``, otherwise ``0``. This expression is a short form + for the combination of ``$<LINK_LANGUAGE:language>`` and ``$<LANG_COMPILER_ID:compiler_ids>``. This expression may be used to specify link libraries, link options, link directories and link dependencies of a particular language and linker combination in a target. For example: diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index 034e218..ed5bbbf 100644 --- a/Help/manual/cmake-generators.7.rst +++ b/Help/manual/cmake-generators.7.rst @@ -18,11 +18,11 @@ as a variant of some of the `Command-Line Build Tool Generators`_ to produce project files for an auxiliary IDE. CMake Generators are platform-specific so each may be available only -on certain platforms. The :manual:`cmake(1)` command-line tool ``--help`` -output lists available generators on the current platform. Use its ``-G`` -option to specify the generator for a new build tree. -The :manual:`cmake-gui(1)` offers interactive selection of a generator -when creating a new build tree. +on certain platforms. The :manual:`cmake(1)` command-line tool +:option:`--help <cmake --help>` output lists available generators on the +current platform. Use its :option:`-G <cmake -G>` option to specify the +generator for a new build tree. The :manual:`cmake-gui(1)` offers +interactive selection of a generator when creating a new build tree. CMake Generators ================ @@ -108,9 +108,9 @@ Extra Generators ================ Some of the `CMake Generators`_ listed in the :manual:`cmake(1)` -command-line tool ``--help`` output may have variants that specify -an extra generator for an auxiliary IDE tool. Such generator -names have the form ``<extra-generator> - <main-generator>``. +command-line tool :option:`--help <cmake --help>` output may have +variants that specify an extra generator for an auxiliary IDE tool. +Such generator names have the form ``<extra-generator> - <main-generator>``. The following extra generators are known to CMake. .. toctree:: diff --git a/Help/manual/cmake-gui.1.rst b/Help/manual/cmake-gui.1.rst index 281986f..dd0eeca 100644 --- a/Help/manual/cmake-gui.1.rst +++ b/Help/manual/cmake-gui.1.rst @@ -9,7 +9,7 @@ Synopsis .. parsed-literal:: cmake-gui [<options>] - cmake-gui [<options>] {<path-to-source> | <path-to-existing-build>} + 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 @@ -29,19 +29,25 @@ native tool on their platform. Options ======= -``-S <path-to-source>`` +.. program:: cmake-gui + +.. option:: -S <path-to-source> + Path to root directory of the CMake project to build. -``-B <path-to-build>`` +.. option:: -B <path-to-build> + Path to directory which CMake will use as the root of build directory. If the directory doesn't already exist CMake will make it. -``--preset=<preset-name>`` +.. option:: --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`` +.. option:: --browse-manual + Open the CMake reference manual in a browser and immediately exit. .. include:: OPTIONS_HELP.txt diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 93beea9..d161a28 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -193,6 +193,7 @@ They are normally called through the :command:`find_package` command. /module/FindOpenGL /module/FindOpenMP /module/FindOpenSceneGraph + /module/FindOpenSP /module/FindOpenSSL /module/FindOpenThreads /module/Findosg @@ -236,6 +237,7 @@ They are normally called through the :command:`find_package` command. /module/FindRuby /module/FindSDL /module/FindSDL_image + /module/FindSDL_gfx /module/FindSDL_mixer /module/FindSDL_net /module/FindSDL_sound diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index f6ab0c7..d6a30ff 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -52,6 +52,16 @@ to determine whether to report an error on use of deprecated macros or functions. +Policies Introduced by CMake 3.25 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0142: The Xcode generator does not append per-config suffixes to library search paths. </policy/CMP0142> + CMP0141: MSVC debug information format flags are selected by an abstraction. </policy/CMP0141> + CMP0140: The return() command checks its arguments. </policy/CMP0140> + Policies Introduced by CMake 3.24 ================================= diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst index a96c704..da699d8 100644 --- a/Help/manual/cmake-presets.7.rst +++ b/Help/manual/cmake-presets.7.rst @@ -10,6 +10,8 @@ cmake-presets(7) Introduction ============ +.. versionadded:: 3.19 + 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 main files, @@ -19,10 +21,10 @@ supports files included with the ``include`` field. ``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 specify project-wide build details, while -``CMakeUserPresets.json`` is meant for developers to specify their own local -build details. +(though at least one must be present if :option:`--preset <cmake --preset>` +is specified). ``CMakePresets.json`` is meant to specify project-wide build +details, while ``CMakeUserPresets.json`` is meant for developers to specify +their own local build details. ``CMakePresets.json`` may be checked into a version control system, and ``CMakeUserPresets.json`` should NOT be checked in. For example, if a @@ -40,7 +42,6 @@ The files are a JSON document with an object as the root: The root object recognizes the following fields: ``version`` - A required integer representing the version of the JSON schema. The supported versions are: @@ -59,32 +60,29 @@ The root object recognizes the following fields: ``5`` .. versionadded:: 3.24 -``cmakeMinimumRequired`` + ``6`` + .. versionadded:: 3.25 +``cmakeMinimumRequired`` An optional object representing the minimum version of CMake needed to build this project. This object consists of the following fields: ``major`` - An optional integer representing the major version. ``minor`` - An optional integer representing the minor version. ``patch`` - An optional integer representing the patch version. ``include`` - An optional array of strings representing files to include. If the filenames are not absolute, they are considered relative to the current file. This is allowed in preset files specifying version ``4`` or above. See `Includes`_ for discussion of the constraints on included files. ``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 @@ -93,20 +91,25 @@ The root object recognizes the following fields: desired by the vendor, though will typically be a map. ``configurePresets`` - An optional array of `Configure Preset`_ objects. This is allowed in preset files specifying version ``1`` or above. ``buildPresets`` - An optional array of `Build Preset`_ objects. This is allowed in preset files specifying version ``2`` or above. ``testPresets`` - An optional array of `Test Preset`_ objects. This is allowed in preset files specifying version ``2`` or above. +``packagePresets`` + An optional array of `Package Preset`_ objects. + This is allowed in preset files specifying version ``6`` or above. + +``workflowPresets`` + An optional array of `Workflow Preset`_ objects. + This is allowed in preset files specifying version ``6`` or above. + Includes ^^^^^^^^ @@ -134,15 +137,14 @@ Each entry of the ``configurePresets`` array is a JSON object that may contain the following fields: ``name`` - A required string representing the machine-friendly name of the preset. This identifier is used in the :ref:`cmake --preset <CMake Options>` option. There must not be two configure presets in the union of ``CMakePresets.json`` and ``CMakeUserPresets.json`` in the same directory with the same name. - However, a configure preset may have the same name as a build or test preset. + However, a configure preset may have the same name as a build, test, + package, or workflow preset. ``hidden`` - An optional boolean specifying whether or not a preset should be hidden. If a preset is hidden, it cannot be used in the ``--preset=`` argument, will not show up in the :manual:`CMake GUI <cmake-gui(1)>`, and does not @@ -151,7 +153,6 @@ that may contain the following fields: other presets to inherit via the ``inherits`` field. ``inherits`` - An optional array of strings representing the names of presets to inherit from. This field can also be a string, which is equivalent to an array containing one string. @@ -160,7 +161,7 @@ that may contain the following fields: presets by default (except ``name``, ``hidden``, ``inherits``, ``description``, and ``displayName``), but can override them as desired. If multiple ``inherits`` presets provide conflicting values for - the same field, the earlier preset in the ``inherits`` list will be + the same field, the earlier preset in the ``inherits`` array will be preferred. A preset can only inherit from another preset that is defined in the @@ -169,12 +170,10 @@ that may contain the following fields: ``CMakeUserPresets.json``. ``condition`` - An optional `Condition`_ object. This is allowed in preset files specifying version ``3`` or above. ``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 @@ -183,47 +182,43 @@ that may contain the following fields: 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``). In version ``3`` or above, this field may be omitted to fall back to regular generator discovery procedure. - 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. + Note that for Visual Studio generators, unlike in the command line + :option:`-G <cmake -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: + :manual:`generators <cmake-generators(7)>` that support them. - ``value`` + See :option:`cmake -A` option for possible values for ``architecture`` + and :option:`cmake -T` for ``toolset``. + + 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 @@ -231,8 +226,10 @@ that may contain the following fields: ignore the field, but the IDE can use them to set up the environment before invoking CMake. -``toolchainFile`` + If no ``strategy`` field is given, or if the field uses the string form + rather than the object form, the behavior is the same as ``"set"``. +``toolchainFile`` An optional string representing the path to the toolchain file. This field supports `macro expansion`_. If a relative path is specified, it is calculated relative to the build directory, and if not found, @@ -241,7 +238,6 @@ that may contain the following fields: specifying version ``3`` or above. ``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 @@ -250,20 +246,17 @@ that may contain the following fields: omitted. ``installDir`` - An optional string representing the path to the installation directory. This field supports `macro expansion`_. If a relative path is specified, it is calculated relative to the source directory. This is allowed in preset files specifying version ``3`` or above. ``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 @@ -271,11 +264,9 @@ that may contain the following fields: 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`_. @@ -288,7 +279,6 @@ that may contain the following fields: 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 @@ -306,73 +296,68 @@ that may contain the following fields: 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``. + An optional boolean. Equivalent to passing :option:`-Wdev <cmake -Wdev>` + or :option:`-Wno-dev <cmake -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``. + An optional boolean. Equivalent to passing + :option:`-Wdeprecated <cmake -Wdeprecated>` or + :option:`-Wno-deprecated <cmake -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. + :option:`--warn-uninitialized <cmake --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. + :option:`--no-warn-unused-cli <cmake --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. + :option:`--check-system-vars <cmake --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``. + An optional boolean. Equivalent to passing :option:`-Werror=dev <cmake -Werror>` + or :option:`-Wno-error=dev <cmake -Werror>` 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``. + An optional boolean. Equivalent to passing + :option:`-Werror=deprecated <cmake -Werror>` or + :option:`-Wno-error=deprecated <cmake -Werror>` 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. + :option:`--debug-output <cmake --debug-output>` on the command line. ``tryCompile`` - An optional boolean. Setting this to ``true`` is equivalent to passing - ``--debug-trycompile`` on the command line. + :option:`--debug-trycompile <cmake --debug-trycompile>` on the command + line. ``find`` - An optional boolean. Setting this to ``true`` is equivalent to passing - ``--debug-find`` on the command line. + :option:`--debug-find <cmake --debug-find>` on the command line. Build Preset ^^^^^^^^^^^^ @@ -381,24 +366,23 @@ Each entry of the ``buildPresets`` array is a JSON object that may contain the following fields: ``name`` - A required string representing the machine-friendly name of the preset. This identifier is used in the :ref:`cmake --build --preset <Build Tool Mode>` option. There must not be two build presets in the union of ``CMakePresets.json`` and ``CMakeUserPresets.json`` in the same directory with the same name. - However, a build preset may have the same name as a configure or test preset. + However, a build preset may have the same name as a configure, test, + package, or workflow preset. ``hidden`` - An optional boolean specifying whether or not a preset should be hidden. - If a preset is hidden, it cannot be used in the ``--preset`` argument + If a preset is hidden, it cannot be used in the + :option:`--preset <cmake --preset>` argument and does not have to have a valid ``configurePreset``, even from inheritance. ``hidden`` presets are intended to be used as a base for other presets to inherit via the ``inherits`` field. ``inherits`` - An optional array of strings representing the names of presets to inherit from. This field can also be a string, which is equivalent to an array containing one string. @@ -407,7 +391,7 @@ that may contain the following fields: ``inherits`` presets by default (except ``name``, ``hidden``, ``inherits``, ``description``, and ``displayName``), but can override them as desired. If multiple ``inherits`` presets provide conflicting - values for the same field, the earlier preset in the ``inherits`` list + values for the same field, the earlier preset in the ``inherits`` array will be preferred. A preset can only inherit from another preset that is defined in the @@ -416,12 +400,10 @@ that may contain the following fields: ``CMakeUserPresets.json``. ``condition`` - An optional `Condition`_ object. This is allowed in preset files specifying version ``3`` or above. ``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 @@ -430,15 +412,12 @@ that may contain the following fields: when appropriate. ``displayName`` - An optional string with a human-friendly name of the preset. ``description`` - An optional string with a human-friendly description of the preset. ``environment`` - An optional map of environment variables. The key is the variable name (which may not be an empty string), and the value is either ``null`` or a string representing the value of the variable. Each variable is set @@ -469,7 +448,6 @@ that may contain the following fields: project. ``configurePreset`` - An optional string specifying the name of a configure preset to associate with this build preset. If ``configurePreset`` is not specified, it must be inherited from the inherits preset (unless this @@ -478,36 +456,30 @@ that may contain the following fields: configuration did. ``inheritConfigureEnvironment`` - An optional boolean that defaults to true. If true, the environment variables from the associated configure preset are inherited after all inherited build preset environments, but before environment variables explicitly specified in this build preset. ``jobs`` - - An optional integer. Equivalent to passing ``--parallel`` or ``-j`` on - the command line. + An optional integer. Equivalent to passing + :option:`--parallel <cmake--build --parallel>` or ``-j`` on the command line. ``targets`` - An optional string or array of strings. Equivalent to passing - ``--target`` or ``-t`` on the command line. Vendors may ignore the - targets property or hide build presets that explicitly specify targets. - This field supports macro expansion. + :option:`--target <cmake--build --target>` or ``-t`` on the command line. + Vendors may ignore the targets property or hide build presets that + explicitly specify targets. This field supports macro expansion. ``configuration`` - - An optional string. Equivalent to passing ``--config`` on the command - line. + An optional string. Equivalent to passing + :option:`--config <cmake--build --config>` on the command line. ``cleanFirst`` - - An optional bool. If true, equivalent to passing ``--clean-first`` on - the command line. + An optional bool. If true, equivalent to passing + :option:`--clean-first <cmake--build --clean-first>` on the command line. ``resolvePackageReferences`` - An optional string that specifies the package resolve mode. This is allowed in preset files specifying version ``4`` or above. @@ -517,24 +489,23 @@ that may contain the following fields: package references, this option does nothing. Valid values are: ``on`` - Causes package references to be resolved before attempting a build. ``off`` - Package references will not be resolved. Note that this may cause errors in some build environments, such as .NET SDK style projects. ``only`` - Only resolve package references, but do not perform a build. .. note:: - The command line parameter ``--resolve-package-references`` will take - priority over this setting. If the command line parameter is not provided - and this setting is not specified, an environment-specific cache variable - will be evaluated to decide, if package restoration should be performed. + The command line parameter + :option:`--resolve-package-references <cmake--build --resolve-package-references>` + will take priority over this setting. If the command line parameter is not + provided and this setting is not specified, an environment-specific cache + variable will be evaluated to decide, if package restoration should be + performed. When using the Visual Studio generator, package references are defined using the :prop_tgt:`VS_PACKAGE_REFERENCES` property. Package references @@ -543,12 +514,10 @@ that may contain the following fields: done from within a configure preset. ``verbose`` - - An optional bool. If true, equivalent to passing ``--verbose`` on the - command line. + An optional bool. If true, equivalent to passing + :option:`--verbose <cmake--build --verbose>` on the command line. ``nativeToolOptions`` - An optional array of strings. Equivalent to passing options after ``--`` on the command line. The array values support macro expansion. @@ -559,23 +528,22 @@ Each entry of the ``testPresets`` array is a JSON object that may contain the following fields: ``name`` - A required string representing the machine-friendly name of the preset. - This identifier is used in the :ref:`ctest --preset <CTest Options>` option. + This identifier is used in the :option:`ctest --preset` option. There must not be two test presets in the union of ``CMakePresets.json`` and ``CMakeUserPresets.json`` in the same directory with the same name. - However, a test preset may have the same name as a configure or build preset. + However, a test preset may have the same name as a configure, build, + package, or workflow preset. ``hidden`` - An optional boolean specifying whether or not a preset should be hidden. - If a preset is hidden, it cannot be used in the ``--preset`` argument + If a preset is hidden, it cannot be used in the + :option:`--preset <ctest --preset>` argument and does not have to have a valid ``configurePreset``, even from inheritance. ``hidden`` presets are intended to be used as a base for other presets to inherit via the ``inherits`` field. ``inherits`` - An optional array of strings representing the names of presets to inherit from. This field can also be a string, which is equivalent to an array containing one string. @@ -584,7 +552,7 @@ that may contain the following fields: ``inherits`` presets by default (except ``name``, ``hidden``, ``inherits``, ``description``, and ``displayName``), but can override them as desired. If multiple ``inherits`` presets provide conflicting - values for the same field, the earlier preset in the ``inherits`` list + values for the same field, the earlier preset in the ``inherits`` array will be preferred. A preset can only inherit from another preset that is defined in the @@ -593,12 +561,10 @@ that may contain the following fields: ``CMakeUserPresets.json``. ``condition`` - An optional `Condition`_ object. This is allowed in preset files specifying version ``3`` or above. ``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 @@ -607,15 +573,12 @@ that may contain the following fields: when appropriate. ``displayName`` - An optional string with a human-friendly name of the preset. ``description`` - An optional string with a human-friendly description of the preset. ``environment`` - An optional map of environment variables. The key is the variable name (which may not be an empty string), and the value is either ``null`` or a string representing the value of the variable. Each variable is set @@ -633,7 +596,6 @@ that may contain the following fields: even if a value was inherited from another preset. ``configurePreset`` - An optional string specifying the name of a configure preset to associate with this test preset. If ``configurePreset`` is not specified, it must be inherited from the inherits preset (unless this @@ -642,233 +604,210 @@ that may contain the following fields: configuration did and build did. ``inheritConfigureEnvironment`` - An optional boolean that defaults to true. If true, the environment variables from the associated configure preset are inherited after all inherited test preset environments, but before environment variables explicitly specified in this test preset. ``configuration`` - - An optional string. Equivalent to passing ``--build-config`` on the - command line. + An optional string. Equivalent to passing + :option:`--build-config <ctest --build-config>` on the command line. ``overwriteConfigurationFile`` - An optional array of configuration options to overwrite options specified in the CTest configuration file. Equivalent to passing - ``--overwrite`` for each value in the array. The array values - support macro expansion. + :option:`--overwrite <ctest --overwrite>` for each value in the array. + The array values support macro expansion. ``output`` - An optional object specifying output options. The object may contain the following fields. ``shortProgress`` - - An optional bool. If true, equivalent to passing ``--progress`` on the - command line. + An optional bool. If true, equivalent to passing + :option:`--progress <ctest --progress>` on the command line. ``verbosity`` - An optional string specifying verbosity level. Must be one of the following: ``default`` - Equivalent to passing no verbosity flags on the command line. ``verbose`` - - Equivalent to passing ``--verbose`` on the command line. + Equivalent to passing :option:`--verbose <ctest --verbose>` on + the command line. ``extra`` - - Equivalent to passing ``--extra-verbose`` on the command line. + Equivalent to passing :option:`--extra-verbose <ctest --extra-verbose>` + on the command line. ``debug`` - - An optional bool. If true, equivalent to passing ``--debug`` on the - command line. + An optional bool. If true, equivalent to passing + :option:`--debug <ctest --debug>` on the command line. ``outputOnFailure`` - An optional bool. If true, equivalent to passing - ``--output-on-failure`` on the command line. + :option:`--output-on-failure <ctest --output-on-failure>` on the command + line. ``quiet`` - - An optional bool. If true, equivalent to passing ``--quiet`` on the - command line. + An optional bool. If true, equivalent to passing + :option:`--quiet <ctest --quiet>` on the command line. ``outputLogFile`` - An optional string specifying a path to a log file. Equivalent to - passing ``--output-log`` on the command line. This field supports - macro expansion. + passing :option:`--output-log <ctest --output-log>` on the command line. + This field supports macro expansion. - ``labelSummary`` + ``outputJUnitFile`` + An optional string specifying a path to a JUnit file. Equivalent to + passing :option:`--output-junit <ctest --output-junit>` on the command line. + This field supports macro expansion. This is allowed in preset files + specifying version ``6`` or above. + ``labelSummary`` An optional bool. If false, equivalent to passing - ``--no-label-summary`` on the command line. + :option:`--no-label-summary <ctest --no-label-summary>` on the command + line. ``subprojectSummary`` - An optional bool. If false, equivalent to passing - ``--no-subproject-summary`` on the command line. + :option:`--no-subproject-summary <ctest --no-subproject-summary>` + on the command line. ``maxPassedTestOutputSize`` - An optional integer specifying the maximum output for passed tests in - bytes. Equivalent to passing ``--test-output-size-passed`` on the - command line. + bytes. Equivalent to passing + :option:`--test-output-size-passed <ctest --test-output-size-passed>` + on the command line. ``maxFailedTestOutputSize`` - An optional integer specifying the maximum output for failed tests in - bytes. Equivalent to passing ``--test-output-size-failed`` on the - command line. + bytes. Equivalent to passing + :option:`--test-output-size-failed <ctest --test-output-size-failed>` + on the command line. ``testOutputTruncation`` - An optional string specifying the test output truncation mode. Equivalent - to passing ``--test-output-truncation`` on the command line." - This is allowed in preset files specifying version ``5`` or above. + to passing + :option:`--test-output-truncation <ctest --test-output-truncation>` on + the command line. This is allowed in preset files specifying version + ``5`` or above. ``maxTestNameWidth`` - An optional integer specifying the maximum width of a test name to - output. Equivalent to passing ``--max-width`` on the command line. + output. Equivalent to passing :option:`--max-width <ctest --max-width>` + on the command line. ``filter`` - An optional object specifying how to filter the tests to run. The object may contain the following fields. ``include`` - An optional object specifying which tests to include. The object may contain the following fields. ``name`` - An optional string specifying a regex for test names. Equivalent to - passing ``--tests-regex`` on the command line. This field supports - macro expansion. CMake regex syntax is described under - :ref:`string(REGEX) <Regex Specification>`. - + passing :option:`--tests-regex <ctest --tests-regex>` on the command + line. This field supports macro expansion. CMake regex syntax is + described under :ref:`string(REGEX) <Regex Specification>`. ``label`` - An optional string specifying a regex for test labels. Equivalent to - passing ``--label-regex`` on the command line. This field supports - macro expansion. + passing :option:`--label-regex <ctest --label-regex>` on the command + line. This field supports macro expansion. ``useUnion`` - - An optional bool. Equivalent to passing ``--union`` on the command - line. + An optional bool. Equivalent to passing :option:`--union <ctest --union>` + on the command line. ``index`` - An optional object specifying tests to include by test index. The object may contain the following fields. Can also be an optional string specifying a file with the command line syntax for - ``--tests-information``. If specified as a string, this field - supports macro expansion. + :option:`--tests-information <ctest --tests-information>`. + If specified as a string, this field supports macro expansion. ``start`` - An optional integer specifying a test index to start testing at. ``end`` - An optional integer specifying a test index to stop testing at. ``stride`` - An optional integer specifying the increment. ``specificTests`` - An optional array of integers specifying specific test indices to run. ``exclude`` - An optional object specifying which tests to exclude. The object may contain the following fields. ``name`` - An optional string specifying a regex for test names. Equivalent to - passing ``--exclude-regex`` on the command line. This field supports - macro expansion. + passing :option:`--exclude-regex <ctest --exclude-regex>` on the + command line. This field supports macro expansion. ``label`` - An optional string specifying a regex for test labels. Equivalent to - passing ``--label-exclude`` on the command line. This field supports - macro expansion. + passing :option:`--label-exclude <ctest --label-exclude>` on the + command line. This field supports macro expansion. ``fixtures`` - An optional object specifying which fixtures to exclude from adding tests. The object may contain the following fields. ``any`` - An optional string specifying a regex for text fixtures to exclude - from adding any tests. Equivalent to ``--fixture-exclude-any`` on + from adding any tests. Equivalent to + :option:`--fixture-exclude-any <ctest --fixture-exclude-any>` on the command line. This field supports macro expansion. ``setup`` - An optional string specifying a regex for text fixtures to exclude - from adding setup tests. Equivalent to ``--fixture-exclude-setup`` + from adding setup tests. Equivalent to + :option:`--fixture-exclude-setup <ctest --fixture-exclude-setup>` on the command line. This field supports macro expansion. ``cleanup`` - An optional string specifying a regex for text fixtures to exclude from adding cleanup tests. Equivalent to - ``--fixture-exclude-cleanup`` on the command line. This field - supports macro expansion. + :option:`--fixture-exclude-cleanup <ctest --fixture-exclude-cleanup>` + on the command line. This field supports macro expansion. ``execution`` - An optional object specifying options for test execution. The object may contain the following fields. ``stopOnFailure`` - - An optional bool. If true, equivalent to passing ``--stop-on-failure`` - on the command line. + An optional bool. If true, equivalent to passing + :option:`--stop-on-failure <ctest --stop-on-failure>` on the command + line. ``enableFailover`` - - An optional bool. If true, equivalent to passing ``-F`` on the command - line. + An optional bool. If true, equivalent to passing :option:`-F <ctest -F>` + on the command line. ``jobs`` - - An optional integer. Equivalent to passing ``--parallel`` on the - command line. + An optional integer. Equivalent to passing + :option:`--parallel <ctest --parallel>` on the command line. ``resourceSpecFile`` - - An optional string. Equivalent to passing ``--resource-spec-file`` on + An optional string. Equivalent to passing + :option:`--resource-spec-file <ctest --resource-spec-file>` on the command line. This field supports macro expansion. ``testLoad`` - - An optional integer. Equivalent to passing ``--test-load`` on the - command line. + An optional integer. Equivalent to passing + :option:`--test-load <ctest --test-load>` on the command line. ``showOnly`` - - An optional string. Equivalent to passing ``--show-only`` on the + An optional string. Equivalent to passing + :option:`--show-only <ctest --show-only>` on the command line. The string must be one of the following values: ``human`` @@ -876,13 +815,11 @@ that may contain the following fields: ``json-v1`` ``repeat`` - An optional object specifying how to repeat tests. Equivalent to - passing ``--repeat`` on the command line. The object must have the - following fields. + passing :option:`--repeat <ctest --repeat>` on the command line. + The object must have the following fields. ``mode`` - A required string. Must be one of the following values: ``until-fail`` @@ -892,42 +829,204 @@ that may contain the following fields: ``after-timeout`` ``count`` - A required integer. ``interactiveDebugging`` - An optional bool. If true, equivalent to passing - ``--interactive-debug-mode 1`` on the command line. If false, - equivalent to passing ``--interactive-debug-mode 0`` on the command - line. + :option:`--interactive-debug-mode 1 <ctest --interactive-debug-mode>` + on the command line. If false, equivalent to passing + :option:`--interactive-debug-mode 0 <ctest --interactive-debug-mode>` + on the command line. ``scheduleRandom`` - - An optional bool. If true, equivalent to passing ``--schedule-random`` - on the command line. + An optional bool. If true, equivalent to passing + :option:`--schedule-random <ctest --schedule-random>` on the command + line. ``timeout`` - - An optional integer. Equivalent to passing ``--timeout`` on the - command line. + An optional integer. Equivalent to passing + :option:`--timeout <ctest --timeout>` on the command line. ``noTestsAction`` - An optional string specifying the behavior if no tests are found. Must be one of the following values: ``default`` - Equivalent to not passing any value on the command line. ``error`` - - Equivalent to passing ``--no-tests=error`` on the command line. + Equivalent to passing :option:`--no-tests=error <ctest --no-tests>` + on the command line. ``ignore`` + Equivalent to passing :option:`--no-tests=ignore <ctest --no-tests>` + on the command line. + +Package Preset +^^^^^^^^^^^^^^ + +Package presets may be used in schema version ``6`` or above. Each entry of +the ``packagePresets`` array is a JSON object that may contain the following +fields: + +``name`` + A required string representing the machine-friendly name of the preset. + This identifier is used in the :option:`cpack --preset` option. + There must not be two package presets in the union of ``CMakePresets.json`` + and ``CMakeUserPresets.json`` in the same directory with the same name. + However, a package preset may have the same name as a configure, build, + test, or workflow preset. + +``hidden`` + An optional boolean specifying whether or not a preset should be hidden. + If a preset is hidden, it cannot be used in the + :option:`--preset <cpack --preset>` argument + and does not have to have a valid ``configurePreset``, even from + inheritance. ``hidden`` presets are intended to be used as a base for + other presets to inherit via the ``inherits`` field. + +``inherits`` + An optional array of strings representing the names of presets to inherit + from. This field can also be a string, which is equivalent to an array + containing one string. + + The preset will inherit all of the fields from the + ``inherits`` presets by default (except ``name``, ``hidden``, + ``inherits``, ``description``, and ``displayName``), but can override + them as desired. If multiple ``inherits`` presets provide conflicting + values for the same field, the earlier preset in the ``inherits`` array + will be preferred. + + A preset can only inherit from another preset that is defined in the + same file or in one of the files it includes (directly or indirectly). + Presets in ``CMakePresets.json`` may not inherit from presets in + ``CMakeUserPresets.json``. + +``condition`` + An optional `Condition`_ object. + +``vendor`` + An optional map containing vendor-specific information. CMake does not + interpret the contents of this field except to verify that it is a map + if it does exist. However, it should follow the same conventions as the + root-level ``vendor`` field. If vendors use their own per-preset + ``vendor`` field, they should implement inheritance in a sensible manner + when appropriate. + +``displayName`` + An optional string with a human-friendly name of the preset. - Equivalent to passing ``--no-tests=ignore`` on the command line. +``description`` + An optional string with a human-friendly description of the preset. + +``environment`` + An optional map of environment variables. The key is the variable name + (which may not be an empty string), and the value is either ``null`` or + a string representing the value of the variable. Each variable is set + regardless of whether or not a value was given to it by the process's + environment. This field supports macro expansion, and environment + variables in this map may reference each other, and may be listed in any + order, as long as such references do not cause a cycle (for example, if + ``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.) + + Environment variables are inherited through the ``inherits`` field, and + the preset's environment will be the union of its own ``environment`` + and the ``environment`` from all its parents. If multiple presets in + this union define the same variable, the standard rules of ``inherits`` + are applied. Setting a variable to ``null`` causes it to not be set, + even if a value was inherited from another preset. + +``configurePreset`` + An optional string specifying the name of a configure preset to + associate with this package preset. If ``configurePreset`` is not + specified, it must be inherited from the inherits preset (unless this + preset is hidden). The build directory is inferred from the configure + preset, so packaging will run in the same ``binaryDir`` that the + configuration did and build did. + +``inheritConfigureEnvironment`` + An optional boolean that defaults to true. If true, the environment + variables from the associated configure preset are inherited after all + inherited package preset environments, but before environment variables + explicitly specified in this package preset. + +``generators`` + An optional array of strings representing generators for CPack to use. + +``configurations`` + An optional array of strings representing build configurations for CPack to + package. + +``variables`` + An optional map of variables to pass to CPack, equivalent to + :option:`-D <cpack -D>` arguments. Each key is the name of a variable, and + the value is the string to assign to that variable. + +``configFile`` + An optional string representing the config file for CPack to use. + +``output`` + An optional object specifying output options. Valid keys are: + + ``debug`` + An optional boolean specifying whether or not to print debug information. + A value of ``true`` is equivalent to passing + :option:`--debug <cpack --debug>` on the command line. + + ``verbose`` + An optional boolean specifying whether or not to print verbosely. A value + of ``true`` is equivalent to passing :option:`--verbose <cpack --verbose>` + on the command line. + +``packageName`` + An optional string representing the package name. + +``packageVersion`` + An optional string representing the package version. + +``packageDirectory`` + An optional string representing the directory in which to place the package. + +``vendorName`` + An optional string representing the vendor name. + +.. _`Workflow Preset`: + +Workflow Preset +^^^^^^^^^^^^^^^ + +Workflow presets may be used in schema version ``6`` or above. Each entry of +the ``workflowPresets`` array is a JSON object that may contain the following +fields: + +``name`` + A required string representing the machine-friendly name of the preset. + This identifier is used in the + :ref:`cmake --workflow --preset <Workflow Mode>` option. There must not be + two workflow presets in the union of ``CMakePresets.json`` and + ``CMakeUserPresets.json`` in the same directory with the same name. However, + a workflow preset may have the same name as a configure, build, test, or + package preset. + +``displayName`` + An optional string with a human-friendly name of the preset. + +``description`` + An optional string with a human-friendly description of the preset. + +``steps`` + A required array of objects describing the steps of the workflow. The first + step must be a configure preset, and all subsequent steps must be non- + configure presets whose ``configurePreset`` field matches the starting + configure preset. Each object may contain the following fields: + + ``type`` + A required string. The first step must be ``configure``. Subsequent steps + must be either ``build``, ``test``, or ``package``. + + ``name`` + A required string representing the name of the configure, build, test, or + package preset to run as this workflow step. Condition ^^^^^^^^^ @@ -943,65 +1042,53 @@ a ``not``, ``anyOf``, or ``allOf`` condition) may not be ``null``. If it is an object, it has the following fields: ``type`` - A required string with one of the following values: ``"const"`` - Indicates that the condition is constant. This is equivalent to using a boolean in place of the object. The condition object will have the following additional fields: ``value`` - A required boolean which provides a constant value for the condition's evaluation. ``"equals"`` ``"notEquals"`` - Indicates that the condition compares two strings to see if they are equal (or not equal). The condition object will have the following additional fields: ``lhs`` - First string to compare. This field supports macro expansion. ``rhs`` - Second string to compare. This field supports macro expansion. ``"inList"`` ``"notInList"`` - Indicates that the condition searches for a string in a list of strings. The condition object will have the following additional fields: ``string`` - A required string to search for. This field supports macro expansion. ``list`` - - A required list of strings to search. This field supports macro + A required array of strings to search. This field supports macro expansion, and uses short-circuit evaluation. ``"matches"`` ``"notMatches"`` - Indicates that the condition searches for a regular expression in a string. The condition object will have the following additional fields: ``string`` - A required string to search. This field supports macro expansion. ``regex`` - A required regular expression to search for. This field supports macro expansion. @@ -1013,17 +1100,14 @@ object, it has the following fields: conditions. The condition object will have the following additional fields: ``conditions`` - A required array of condition objects. These conditions use short-circuit evaluation. ``"not"`` - Indicates that the condition is an inversion of another condition. The condition object will have the following additional fields: ``condition`` - A required condition object. Macro Expansion @@ -1045,46 +1129,37 @@ interpreted as a literal dollar sign. Recognized macros include: ``${sourceDir}`` - Path to the project source directory (i.e. the same as :variable:`CMAKE_SOURCE_DIR`). ``${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. For build and test presets, this will evaluate to the generator specified by ``configurePreset``. ``${hostSystemName}`` - The name of the host operating system. Contains the same value as :variable:`CMAKE_HOST_SYSTEM_NAME`. This is allowed in preset files specifying version ``3`` or above. ``${fileDir}`` - Path to the directory containing the preset file which contains the macro. This is allowed in preset files specifying version ``4`` or above. ``${dollar}`` - A literal dollar sign (``$``). ``${pathListSep}`` - Native character for separating lists of paths, such as ``:`` or ``;``. For example, by setting ``PATH`` to @@ -1095,7 +1170,6 @@ Recognized macros include: This is allowed in preset files specifying version ``5`` or above. ``$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. @@ -1108,7 +1182,6 @@ Recognized macros include: 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. @@ -1118,7 +1191,6 @@ Recognized macros include: 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 diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index d88322c..b17be82 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -90,6 +90,7 @@ Properties on Directories /prop_dir/RULE_LAUNCH_LINK /prop_dir/SOURCE_DIR /prop_dir/SUBDIRECTORIES + /prop_dir/SYSTEM /prop_dir/TESTS /prop_dir/TEST_INCLUDE_FILES /prop_dir/VARIABLES @@ -184,6 +185,16 @@ Properties on Targets /prop_tgt/CUDA_STANDARD /prop_tgt/CUDA_STANDARD_REQUIRED /prop_tgt/CXX_EXTENSIONS + /prop_tgt/CXX_MODULE_DIRS + /prop_tgt/CXX_MODULE_DIRS_NAME + /prop_tgt/CXX_MODULE_HEADER_UNIT_DIRS + /prop_tgt/CXX_MODULE_HEADER_UNIT_DIRS_NAME + /prop_tgt/CXX_MODULE_HEADER_UNIT_SET + /prop_tgt/CXX_MODULE_HEADER_UNIT_SET_NAME + /prop_tgt/CXX_MODULE_HEADER_UNIT_SETS + /prop_tgt/CXX_MODULE_SET + /prop_tgt/CXX_MODULE_SET_NAME + /prop_tgt/CXX_MODULE_SETS /prop_tgt/CXX_STANDARD /prop_tgt/CXX_STANDARD_REQUIRED /prop_tgt/DEBUG_POSTFIX @@ -202,6 +213,7 @@ Properties on Targets /prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG /prop_tgt/EXPORT_COMPILE_COMMANDS /prop_tgt/EXPORT_NAME + /prop_tgt/EXPORT_NO_SYSTEM /prop_tgt/EXPORT_PROPERTIES /prop_tgt/FOLDER /prop_tgt/Fortran_BUILDING_INSTRINSIC_MODULES @@ -262,6 +274,8 @@ Properties on Targets /prop_tgt/INTERFACE_COMPILE_DEFINITIONS /prop_tgt/INTERFACE_COMPILE_FEATURES /prop_tgt/INTERFACE_COMPILE_OPTIONS + /prop_tgt/INTERFACE_CXX_MODULE_HEADER_UNIT_SETS + /prop_tgt/INTERFACE_CXX_MODULE_SETS /prop_tgt/INTERFACE_HEADER_SETS /prop_tgt/INTERFACE_HEADER_SETS_TO_VERIFY /prop_tgt/INTERFACE_INCLUDE_DIRECTORIES @@ -327,6 +341,7 @@ Properties on Targets /prop_tgt/MACOSX_RPATH /prop_tgt/MANUALLY_ADDED_DEPENDENCIES /prop_tgt/MAP_IMPORTED_CONFIG_CONFIG + /prop_tgt/MSVC_DEBUG_INFORMATION_FORMAT /prop_tgt/MSVC_RUNTIME_LIBRARY /prop_tgt/NAME /prop_tgt/NO_SONAME @@ -342,8 +357,8 @@ Properties on Targets /prop_tgt/OSX_ARCHITECTURES_CONFIG /prop_tgt/OUTPUT_NAME /prop_tgt/OUTPUT_NAME_CONFIG - /prop_tgt/PCH_WARN_INVALID /prop_tgt/PCH_INSTANTIATE_TEMPLATES + /prop_tgt/PCH_WARN_INVALID /prop_tgt/PDB_NAME /prop_tgt/PDB_NAME_CONFIG /prop_tgt/PDB_OUTPUT_DIRECTORY @@ -375,6 +390,7 @@ Properties on Targets /prop_tgt/Swift_LANGUAGE_VERSION /prop_tgt/Swift_MODULE_DIRECTORY /prop_tgt/Swift_MODULE_NAME + /prop_tgt/SYSTEM /prop_tgt/TYPE /prop_tgt/UNITY_BUILD /prop_tgt/UNITY_BUILD_BATCH_SIZE @@ -444,13 +460,17 @@ Properties on Targets /prop_tgt/XCODE_SCHEME_ARGUMENTS /prop_tgt/XCODE_SCHEME_DEBUG_AS_ROOT /prop_tgt/XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING - /prop_tgt/XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE /prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER /prop_tgt/XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS /prop_tgt/XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE + /prop_tgt/XCODE_SCHEME_ENABLE_GPU_API_VALIDATION + /prop_tgt/XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE + /prop_tgt/XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION /prop_tgt/XCODE_SCHEME_ENVIRONMENT /prop_tgt/XCODE_SCHEME_EXECUTABLE /prop_tgt/XCODE_SCHEME_GUARD_MALLOC + /prop_tgt/XCODE_SCHEME_LAUNCH_CONFIGURATION + /prop_tgt/XCODE_SCHEME_LAUNCH_MODE /prop_tgt/XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP /prop_tgt/XCODE_SCHEME_MALLOC_GUARD_EDGES /prop_tgt/XCODE_SCHEME_MALLOC_SCRIBBLE diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index e194df0..8a83807 100644 --- a/Help/manual/cmake-toolchains.7.rst +++ b/Help/manual/cmake-toolchains.7.rst @@ -17,6 +17,9 @@ determines the toolchain for host builds based on system introspection and defaults. In cross-compiling scenarios, a toolchain file may be specified with information about compiler and utility paths. +.. versionadded:: 3.19 + One may use :manual:`cmake-presets(7)` to specify toolchain files. + Languages ========= @@ -58,20 +61,24 @@ Variables and Properties ======================== Several variables relate to the language components of a toolchain which are -enabled. :variable:`CMAKE_<LANG>_COMPILER` is the full path to the compiler used -for ``<LANG>``. :variable:`CMAKE_<LANG>_COMPILER_ID` is the identifier used -by CMake for the compiler and :variable:`CMAKE_<LANG>_COMPILER_VERSION` is the -version of the compiler. - -The :variable:`CMAKE_<LANG>_FLAGS` variables and the configuration-specific -equivalents contain flags that will be added to the compile command when -compiling a file of a particular language. - -As the linker is invoked by the compiler driver, CMake needs a way to determine -which compiler to use to invoke the linker. This is calculated by the -:prop_sf:`LANGUAGE` of source files in the target, and in the case of static -libraries, the language of the dependent libraries. The choice CMake makes may -be overridden with the :prop_tgt:`LINKER_LANGUAGE` target property. +enabled: + +:variable:`CMAKE_<LANG>_COMPILER` + The full path to the compiler used for ``<LANG>`` +:variable:`CMAKE_<LANG>_COMPILER_ID` + The compiler identifier used by CMake +:variable:`CMAKE_<LANG>_COMPILER_VERSION` + The version of the compiler. +:variable:`CMAKE_<LANG>_FLAGS` + The variables and the configuration-specific equivalents contain flags that + will be added to the compile command when compiling a file of a particular + language. + +CMake needs a way to determine which compiler to use to invoke the linker. +This is determined by the :prop_sf:`LANGUAGE` property of source files of the +:manual:`target <cmake-buildsystem(7)>`, and in the case of static libraries, +the ``LANGUAGE`` of the dependent libraries. The choice CMake makes may be overridden +with the :prop_tgt:`LINKER_LANGUAGE` target property. Toolchain Features ================== @@ -96,7 +103,8 @@ Cross Compiling =============== If :manual:`cmake(1)` is invoked with the command line parameter -``--toolchain path/to/file`` or ``-DCMAKE_TOOLCHAIN_FILE=path/to/file``, the +:option:`--toolchain path/to/file <cmake --toolchain>` or +:option:`-DCMAKE_TOOLCHAIN_FILE=path/to/file <cmake -D>`, the file will be loaded early to set values for the compilers. The :variable:`CMAKE_CROSSCOMPILING` variable is set to true when CMake is cross-compiling. @@ -132,24 +140,24 @@ as: set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY) set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY) -The :variable:`CMAKE_SYSTEM_NAME` is the CMake-identifier of the target platform -to build for. - -The :variable:`CMAKE_SYSTEM_PROCESSOR` is the CMake-identifier of the target architecture -to build for. +Where: -The :variable:`CMAKE_SYSROOT` is optional, and may be specified if a sysroot -is available. - -The :variable:`CMAKE_STAGING_PREFIX` is also optional. It may be used to specify -a path on the host to install to. The :variable:`CMAKE_INSTALL_PREFIX` is always -the runtime installation location, even when cross-compiling. - -The :variable:`CMAKE_<LANG>_COMPILER` variables may be set to full paths, or to -names of compilers to search for in standard locations. For toolchains that -do not support linking binaries without custom flags or scripts one may set -the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable to ``STATIC_LIBRARY`` -to tell CMake not to try to link executables during its checks. +:variable:`CMAKE_SYSTEM_NAME` + is the CMake-identifier of the target platform to build for. +:variable:`CMAKE_SYSTEM_PROCESSOR` + is the CMake-identifier of the target architecture. +:variable:`CMAKE_SYSROOT` + is optional, and may be specified if a sysroot is available. +:variable:`CMAKE_STAGING_PREFIX` + is also optional. It may be used to specify a path on the host to install to. + The :variable:`CMAKE_INSTALL_PREFIX` is always the runtime installation + location, even when cross-compiling. +:variable:`CMAKE_<LANG>_COMPILER` + variable may be set to full paths, or to names of compilers to search for + in standard locations. For toolchains that do not support linking binaries + without custom flags or scripts one may set the + :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable to ``STATIC_LIBRARY`` to + tell CMake not to try to link executables during its checks. CMake ``find_*`` commands will look in the sysroot, and the :variable:`CMAKE_FIND_ROOT_PATH` entries by default in all cases, as well as looking in the host system root prefix. diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 7c8a7fa..cd46615 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -128,9 +128,9 @@ Variables that Provide Information /variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR /variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE /variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION - /variable/CMAKE_VS_TARGET_FRAMEWORK_VERSION /variable/CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER /variable/CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION + /variable/CMAKE_VS_TARGET_FRAMEWORK_VERSION /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM /variable/CMAKE_XCODE_BUILD_SYSTEM @@ -207,9 +207,9 @@ Variables that Change Behavior /variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE /variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM /variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH - /variable/CMAKE_FIND_USE_INSTALL_PREFIX /variable/CMAKE_FIND_USE_CMAKE_PATH /variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH + /variable/CMAKE_FIND_USE_INSTALL_PREFIX /variable/CMAKE_FIND_USE_PACKAGE_REGISTRY /variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH /variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH @@ -228,12 +228,12 @@ Variables that Change Behavior /variable/CMAKE_LIBRARY_PATH /variable/CMAKE_LINK_DIRECTORIES_BEFORE /variable/CMAKE_LINK_LIBRARIES_ONLY_TARGETS - /variable/CMAKE_MFC_FLAG /variable/CMAKE_MAXIMUM_RECURSION_DEPTH /variable/CMAKE_MESSAGE_CONTEXT /variable/CMAKE_MESSAGE_CONTEXT_SHOW /variable/CMAKE_MESSAGE_INDENT /variable/CMAKE_MESSAGE_LOG_LEVEL + /variable/CMAKE_MFC_FLAG /variable/CMAKE_MODULE_PATH /variable/CMAKE_POLICY_DEFAULT_CMPNNNN /variable/CMAKE_POLICY_WARNING_CMPNNNN @@ -272,12 +272,16 @@ Variables that Change Behavior /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN /variable/CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING - /variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE /variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE + /variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_API_VALIDATION + /variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE + /variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION /variable/CMAKE_XCODE_SCHEME_ENVIRONMENT /variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC + /variable/CMAKE_XCODE_SCHEME_LAUNCH_CONFIGURATION + /variable/CMAKE_XCODE_SCHEME_LAUNCH_MODE /variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP /variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES /variable/CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE @@ -300,10 +304,13 @@ Variables that Describe the System /variable/ANDROID /variable/APPLE /variable/BORLAND + /variable/BSD /variable/CMAKE_ANDROID_NDK_VERSION /variable/CMAKE_CL_64 /variable/CMAKE_COMPILER_2005 /variable/CMAKE_HOST_APPLE + /variable/CMAKE_HOST_BSD + /variable/CMAKE_HOST_LINUX /variable/CMAKE_HOST_SOLARIS /variable/CMAKE_HOST_SYSTEM /variable/CMAKE_HOST_SYSTEM_NAME @@ -321,6 +328,7 @@ Variables that Describe the System /variable/CYGWIN /variable/GHSMULTI /variable/IOS + /variable/LINUX /variable/MINGW /variable/MSVC /variable/MSVC10 @@ -412,19 +420,19 @@ Variables that Control the Build /variable/CMAKE_DEBUG_POSTFIX /variable/CMAKE_DEFAULT_BUILD_TYPE /variable/CMAKE_DEFAULT_CONFIGS - /variable/CMAKE_DISABLE_PRECOMPILE_HEADERS /variable/CMAKE_DEPENDS_USE_COMPILER + /variable/CMAKE_DISABLE_PRECOMPILE_HEADERS /variable/CMAKE_ENABLE_EXPORTS /variable/CMAKE_EXE_LINKER_FLAGS /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_EXE_LINKER_FLAGS_INIT /variable/CMAKE_FOLDER - /variable/CMAKE_FRAMEWORK - /variable/CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG /variable/CMAKE_Fortran_FORMAT /variable/CMAKE_Fortran_MODULE_DIRECTORY /variable/CMAKE_Fortran_PREPROCESS + /variable/CMAKE_FRAMEWORK + /variable/CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_CONFIG /variable/CMAKE_GHS_NO_SOURCE_GROUP_FILE /variable/CMAKE_GLOBAL_AUTOGEN_TARGET /variable/CMAKE_GLOBAL_AUTOGEN_TARGET_NAME @@ -445,14 +453,14 @@ Variables that Control the Build /variable/CMAKE_LANG_CPPCHECK /variable/CMAKE_LANG_CPPLINT /variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE - /variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE - /variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE_SUPPORTED - /variable/CMAKE_LANG_LINKER_LAUNCHER /variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE /variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE_SUPPORTED /variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LANG_LINK_LIBRARY_FLAG + /variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE + /variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE_SUPPORTED /variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG + /variable/CMAKE_LANG_LINKER_LAUNCHER /variable/CMAKE_LANG_VISIBILITY_PRESET /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG @@ -475,8 +483,9 @@ Variables that Control the Build /variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG /variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_MODULE_LINKER_FLAGS_INIT - /variable/CMAKE_MSVCIDE_RUN_PATH + /variable/CMAKE_MSVC_DEBUG_INFORMATION_FORMAT /variable/CMAKE_MSVC_RUNTIME_LIBRARY + /variable/CMAKE_MSVCIDE_RUN_PATH /variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX /variable/CMAKE_NO_BUILTIN_CHRPATH /variable/CMAKE_NO_SYSTEM_FROM_IMPORTED @@ -484,8 +493,8 @@ Variables that Control the Build /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_PCH_WARN_INVALID /variable/CMAKE_PDB_OUTPUT_DIRECTORY /variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_PLATFORM_NO_VERSIONED_SONAME @@ -502,6 +511,7 @@ Variables that Control the Build /variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG /variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_STATIC_LINKER_FLAGS_INIT + /variable/CMAKE_TASKING_TOOLSET /variable/CMAKE_TRY_COMPILE_CONFIGURATION /variable/CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES /variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES @@ -538,6 +548,10 @@ Variables for Languages .. toctree:: :maxdepth: 1 + /variable/CMAKE_C_COMPILE_FEATURES + /variable/CMAKE_C_EXTENSIONS + /variable/CMAKE_C_STANDARD + /variable/CMAKE_C_STANDARD_REQUIRED /variable/CMAKE_COMPILER_IS_GNUCC /variable/CMAKE_COMPILER_IS_GNUCXX /variable/CMAKE_COMPILER_IS_GNUG77 @@ -552,10 +566,6 @@ Variables for Languages /variable/CMAKE_CXX_EXTENSIONS /variable/CMAKE_CXX_STANDARD /variable/CMAKE_CXX_STANDARD_REQUIRED - /variable/CMAKE_C_COMPILE_FEATURES - /variable/CMAKE_C_EXTENSIONS - /variable/CMAKE_C_STANDARD - /variable/CMAKE_C_STANDARD_REQUIRED /variable/CMAKE_Fortran_MODDIR_DEFAULT /variable/CMAKE_Fortran_MODDIR_FLAG /variable/CMAKE_Fortran_MODOUT_FLAG @@ -573,6 +583,7 @@ Variables for Languages /variable/CMAKE_LANG_ARCHIVE_CREATE /variable/CMAKE_LANG_ARCHIVE_FINISH /variable/CMAKE_LANG_BYTE_ORDER + /variable/CMAKE_LANG_COMPILE_OBJECT /variable/CMAKE_LANG_COMPILER /variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN /variable/CMAKE_LANG_COMPILER_ID @@ -580,7 +591,6 @@ Variables for Languages /variable/CMAKE_LANG_COMPILER_PREDEFINES_COMMAND /variable/CMAKE_LANG_COMPILER_TARGET /variable/CMAKE_LANG_COMPILER_VERSION - /variable/CMAKE_LANG_COMPILE_OBJECT /variable/CMAKE_LANG_CREATE_SHARED_LIBRARY /variable/CMAKE_LANG_CREATE_SHARED_MODULE /variable/CMAKE_LANG_CREATE_STATIC_LIBRARY @@ -653,12 +663,12 @@ Variables for CTest /variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS /variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS /variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE - /variable/CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION /variable/CTEST_CUSTOM_MEMCHECK_IGNORE /variable/CTEST_CUSTOM_POST_MEMCHECK /variable/CTEST_CUSTOM_POST_TEST /variable/CTEST_CUSTOM_PRE_MEMCHECK /variable/CTEST_CUSTOM_PRE_TEST + /variable/CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION /variable/CTEST_CUSTOM_TESTS_IGNORE /variable/CTEST_CUSTOM_WARNING_EXCEPTION /variable/CTEST_CUSTOM_WARNING_MATCH @@ -694,9 +704,9 @@ Variables for CTest /variable/CTEST_SCP_COMMAND /variable/CTEST_SCRIPT_DIRECTORY /variable/CTEST_SITE + /variable/CTEST_SOURCE_DIRECTORY /variable/CTEST_SUBMIT_INACTIVITY_TIMEOUT /variable/CTEST_SUBMIT_URL - /variable/CTEST_SOURCE_DIRECTORY /variable/CTEST_SVN_COMMAND /variable/CTEST_SVN_OPTIONS /variable/CTEST_SVN_UPDATE_OPTIONS diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 38105dd..35bd05f 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -9,8 +9,7 @@ Synopsis .. parsed-literal:: `Generate a Project Buildsystem`_ - cmake [<options>] <path-to-source> - cmake [<options>] <path-to-existing-build> + cmake [<options>] <path-to-source | path-to-existing-build> cmake [<options>] -S <path-to-source> -B <path-to-build> `Build a Project`_ @@ -23,7 +22,7 @@ Synopsis cmake --open <dir> `Run a Script`_ - cmake [{-D <var>=<value>}...] -P <cmake-script-file> + cmake [-D <var>=<value>]... -P <cmake-script-file> `Run a Command-Line Tool`_ cmake -E <command> [<options>] @@ -31,6 +30,9 @@ Synopsis `Run the Find-Package Tool`_ cmake --find-package [<options>] + `Run a Workflow Preset`_ + cmake --workflow [<options>] + `View Help`_ cmake --help[-<topic>] @@ -96,9 +98,10 @@ Build Tree Generator This chooses the kind of buildsystem to generate. See the :manual:`cmake-generators(7)` manual for documentation of all generators. - Run ``cmake --help`` to see a list of generators available locally. - Optionally use the ``-G`` option below to specify a generator, or simply - accept the default CMake chooses for the current platform. + Run :option:`cmake --help` to see a list of generators available locally. + Optionally use the :option:`-G <cmake -G>` option below to specify a + generator, or simply accept the default CMake chooses for the current + platform. When using one of the :ref:`Command-Line Build Tool Generators` CMake expects that the environment needed by the compiler toolchain @@ -139,6 +142,9 @@ source and build trees and generate a buildsystem: $ cmake . ``cmake [<options>] -S <path-to-source> -B <path-to-build>`` + + .. versionadded:: 3.13 + Uses ``<path-to-build>`` as the build tree and ``<path-to-source>`` as the source tree. The specified paths may be absolute or relative to the current working directory. The source tree must contain a @@ -152,11 +158,11 @@ source and build trees and generate a buildsystem: In all cases the ``<options>`` may be zero or more of the `Options`_ below. The above styles for specifying the source and build trees may be mixed. -Paths specified with ``-S`` or ``-B`` are always classified as source or -build trees, respectively. Paths specified with plain arguments are -classified based on their content and the types of paths given earlier. -If only one type of path is given, the current working directory (cwd) -is used for the other. For example: +Paths specified with :option:`-S <cmake -S>` or :option:`-B <cmake -B>` +are always classified as source or build trees, respectively. Paths +specified with plain arguments are classified based on their content +and the types of paths given earlier. If only one type of path is given, +the current working directory (cwd) is used for the other. For example: ============================== ============ =========== Command Line Source Dir Build Dir @@ -195,51 +201,60 @@ automatically choosing and invoking the appropriate native build tool. Options ------- +.. program:: cmake + .. include:: OPTIONS_BUILD.txt -``--fresh`` +.. option:: --fresh + .. versionadded:: 3.24 Perform a fresh configuration of the build tree. This removes any existing ``CMakeCache.txt`` file and associated ``CMakeFiles/`` directory, and recreates them from scratch. -``-L[A][H]`` +.. option:: -L[A][H] + List non-advanced cached variables. List ``CACHE`` variables will run CMake and list all the variables from the CMake ``CACHE`` that are not marked as ``INTERNAL`` or :prop_cache:`ADVANCED`. This will effectively display current CMake settings, which can then be - changed with ``-D`` option. Changing some of the variables may result - in more variables being created. If ``A`` is specified, then it will - display also advanced variables. If ``H`` is specified, it will also + changed with :option:`-D <cmake -D>` option. Changing some of the variables + may result in more variables being created. If ``A`` is specified, then it + will display also advanced variables. If ``H`` is specified, it will also display help for each variable. -``-N`` +.. option:: -N + View mode only. Only load the cache. Do not actually run configure and generate steps. -``--graphviz=[file]`` +.. option:: --graphviz=<file> + Generate graphviz of dependencies, see :module:`CMakeGraphVizOptions` for more. Generate a graphviz input file that will contain all the library and executable dependencies in the project. See the documentation for :module:`CMakeGraphVizOptions` for more details. -``--system-information [file]`` +.. option:: --system-information [file] + Dump information about this system. Dump a wide range of information about the current system. If run from the top of a binary tree for a CMake project it will dump additional information such as the cache, log files etc. -``--log-level=<ERROR|WARNING|NOTICE|STATUS|VERBOSE|DEBUG|TRACE>`` - Set the log level. +.. option:: --log-level=<level> + + Set the log ``<level>``. The :command:`message` command will only output messages of the specified - log level or higher. The default log level is ``STATUS``. + log level or higher. The valid log levels are ``ERROR``, ``WARNING``, + ``NOTICE``, ``STATUS`` (default), ``VERBOSE``, ``DEBUG``, or ``TRACE``. To make a log level persist between CMake runs, set :variable:`CMAKE_MESSAGE_LOG_LEVEL` as a cache variable instead. @@ -249,7 +264,12 @@ Options For backward compatibility reasons, ``--loglevel`` is also accepted as a synonym for this option. -``--log-context`` + .. versionadded:: 3.25 + See the :command:`cmake_language` command for a way to + :ref:`query the current message logging level <query_message_log_level>`. + +.. option:: --log-context + Enable the :command:`message` command outputting context attached to each message. @@ -259,24 +279,36 @@ Options When this command line option is given, :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` is ignored. -``--debug-trycompile`` - Do not delete the :command:`try_compile` build tree. - Only useful on one :command:`try_compile` at a time. +.. option:: --debug-trycompile + + Do not delete the files and directories created for + :command:`try_compile` / :command:`try_run` calls. + This is useful in debugging failed checks. + + Note that some uses of :command:`try_compile` may use the same build tree, + which will limit the usefulness of this option if a project executes more + than one :command:`try_compile`. For example, such uses may change results + as artifacts from a previous try-compile may cause a different test to either + pass or fail incorrectly. This option is best used only when debugging. + + (With respect to the preceding, the :command:`try_run` command + is effectively a :command:`try_compile`. Any combination of the two + is subject to the potential issues described.) - Do not delete the files and directories created for :command:`try_compile` - calls. This is useful in debugging failed try_compiles. It may - however change the results of the try-compiles as old junk from a - previous try-compile may cause a different test to either pass or - fail incorrectly. This option is best used for one try-compile at a - time, and only when debugging. + .. versionadded:: 3.25 + + When this option is enabled, every try-compile check prints a log + message reporting the directory in which the check is performed. + +.. option:: --debug-output -``--debug-output`` Put cmake in a debug mode. Print extra information during the cmake run like stack traces with :command:`message(SEND_ERROR)` calls. -``--debug-find`` +.. option:: --debug-find + Put cmake find commands in a debug mode. Print extra find call information during the cmake run to standard @@ -284,32 +316,39 @@ Options See also the :variable:`CMAKE_FIND_DEBUG_MODE` variable for debugging a more local part of the project. -``--debug-find-pkg=<pkg>[,...]`` +.. option:: --debug-find-pkg=<pkg>[,...] + Put cmake find commands in a debug mode when running under calls to :command:`find_package(\<pkg\>) <find_package>`, where ``<pkg>`` is an entry in the given comma-separated list of case-sensitive package names. - Like ``--debug-find``, but limiting scope to the specified packages. + Like :option:`--debug-find <cmake --debug-find>`, but limiting scope + to the specified packages. + +.. option:: --debug-find-var=<var>[,...] -``--debug-find-var=<var>[,...]`` Put cmake find commands in a debug mode when called with ``<var>`` as the result variable, where ``<var>`` is an entry in the given comma-separated list. - Like ``--debug-find``, but limiting scope to the specified variable names. + Like :option:`--debug-find <cmake --debug-find>`, but limiting scope + to the specified variable names. + +.. option:: --trace -``--trace`` Put cmake in trace mode. Print a trace of all calls made and from where. -``--trace-expand`` +.. option:: --trace-expand + Put cmake in trace mode. - Like ``--trace``, but with variables expanded. + Like :option:`--trace <cmake --trace>`, but with variables expanded. + +.. option:: --trace-format=<format> -``--trace-format=<format>`` Put cmake in trace mode and sets the trace output format. ``<format>`` can be one of the following values. @@ -395,46 +434,57 @@ Options Indicates the version of the JSON format. The version has a major and minor components following semantic version conventions. -``--trace-source=<file>`` +.. option:: --trace-source=<file> + Put cmake in trace mode, but output only lines of a specified file. Multiple options are allowed. -``--trace-redirect=<file>`` +.. option:: --trace-redirect=<file> + Put cmake in trace mode and redirect trace output to a file instead of stderr. -``--warn-uninitialized`` +.. option:: --warn-uninitialized + Warn about uninitialized values. Print a warning when an uninitialized variable is used. -``--warn-unused-vars`` +.. option:: --warn-unused-vars + 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`` +.. option:: --no-warn-unused-cli + Don't warn about command line options. Don't find variables that are declared on the command line, but not used. -``--check-system-vars`` +.. option:: --check-system-vars + Find problems with variable usage in system files. Normally, unused and uninitialized variables are searched for only in :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR`. This flag tells CMake to warn about other files as well. -``--compile-no-warning-as-error`` +.. option:: --compile-no-warning-as-error + Ignore target property :prop_tgt:`COMPILE_WARNING_AS_ERROR` and variable :variable:`CMAKE_COMPILE_WARNING_AS_ERROR`, preventing warnings from being treated as errors on compile. -``--profiling-output=<path>`` - Used in conjunction with ``--profiling-format`` to output to a given path. +.. option:: --profiling-output=<path> + + Used in conjunction with + :option:`--profiling-format <cmake --profiling-format>` to output to a + given path. + +.. option:: --profiling-format=<file> -``--profiling-format=<file>`` Enable the output of profiling data of CMake script in the given format. This can aid performance analysis of CMake scripts executed. Third party @@ -445,7 +495,8 @@ Options about:tracing tab of Google Chrome or using a plugin for a tool like Trace Compass. -``--preset <preset>``, ``--preset=<preset>`` +.. option:: --preset <preset>, --preset=<preset> + Reads a :manual:`preset <cmake-presets(7)>` from ``<path-to-source>/CMakePresets.json`` and ``<path-to-source>/CMakeUserPresets.json``. The preset may specify the @@ -461,15 +512,20 @@ Options a variable called ``MYVAR`` to ``1``, but the user sets it to ``2`` with a ``-D`` argument, the value ``2`` is preferred. -``--list-presets, --list-presets=<[configure | build | test | all]>`` - Lists the available presets. If no option is specified only configure presets - will be listed. The current working directory must contain CMake preset files. +.. option:: --list-presets[=<type>] + + Lists the available presets of the specified ``<type>``. Valid values for + ``<type>`` are ``configure``, ``build``, ``test``, ``package``, or ``all``. + If ``<type>`` is omitted, ``configure`` is assumed. The current working + directory must contain CMake preset files. .. _`Build Tool Mode`: Build a Project =============== +.. program:: cmake + CMake provides a command-line signature to build an already-generated project binary tree: @@ -481,21 +537,29 @@ project binary tree: This abstracts a native build tool's command-line interface with the following options: -``--build <dir>`` +.. option:: --build <dir> + Project binary directory to be built. This is required (unless a preset is specified) and must be first. -``--preset <preset>``, ``--preset=<preset>`` +.. program:: cmake--build + +.. option:: --preset <preset>, --preset=<preset> + Use a build preset to specify build options. The project binary directory is inferred from the ``configurePreset`` key. The current working directory must contain CMake preset files. See :manual:`preset <cmake-presets(7)>` for more details. -``--list-presets`` +.. option:: --list-presets + Lists the available build presets. The current working directory must contain CMake preset files. -``--parallel [<jobs>], -j [<jobs>]`` +.. option:: -j [<jobs>], --parallel [<jobs>] + + .. versionadded:: 3.12 + The maximum number of concurrent processes to use when building. If ``<jobs>`` is omitted the native build tool's default number is used. @@ -505,24 +569,29 @@ following options: Some native build tools always build in parallel. The use of ``<jobs>`` value of ``1`` can be used to limit to a single job. -``--target <tgt>..., -t <tgt>...`` +.. option:: -t <tgt>..., --target <tgt>... + Build ``<tgt>`` instead of the default target. Multiple targets may be given, separated by spaces. -``--config <cfg>`` +.. option:: --config <cfg> + For multi-configuration tools, choose configuration ``<cfg>``. -``--clean-first`` +.. option:: --clean-first + Build target ``clean`` first, then build. - (To clean only, use ``--target clean``.) + (To clean only, use :option:`--target clean <cmake--build --target>`.) + +.. option:: --resolve-package-references=<value> -``--resolve-package-references=<on|off|only>`` .. versionadded:: 3.23 Resolve remote package references from external package managers (e.g. NuGet) - before build. When set to ``on`` (default), packages will be restored before - building a target. When set to ``only``, the packages will be restored, but no - build will be performed. When set to ``off``, no packages will be restored. + before build. When ``<value>`` is set to ``on`` (default), packages will be + restored before building a target. When ``<value>`` is set to ``only``, the + packages will be restored, but no build will be performed. When + ``<value>`` is set to ``off``, no packages will be restored. If the target does not define any package references, this option does nothing. @@ -539,10 +608,12 @@ following options: are restored using NuGet. It can be disabled by setting the ``CMAKE_VS_NUGET_PACKAGE_RESTORE`` variable to ``OFF``. -``--use-stderr`` +.. option:: --use-stderr + Ignored. Behavior is default in CMake >= 3.0. -``--verbose, -v`` +.. option:: -v, --verbose + Enable verbose output - if supported - including the build commands to be executed. @@ -550,14 +621,17 @@ following options: :variable:`CMAKE_VERBOSE_MAKEFILE` cached variable is set. -``--`` +.. option:: -- + Pass remaining options to the native tool. -Run ``cmake --build`` with no options for quick help. +Run :option:`cmake --build` with no options for quick help. Install a Project ================= +.. program:: cmake + CMake provides a command-line signature to install an already-generated project binary tree: @@ -569,34 +643,45 @@ This may be used after building a project to run installation without using the generated build system or the native build tool. The options are: -``--install <dir>`` +.. option:: --install <dir> + Project binary directory to install. This is required and must be first. -``--config <cfg>`` +.. program:: cmake--install + +.. option:: --config <cfg> + For multi-configuration generators, choose configuration ``<cfg>``. -``--component <comp>`` +.. option:: --component <comp> + Component-based install. Only install component ``<comp>``. -``--default-directory-permissions <permissions>`` +.. option:: --default-directory-permissions <permissions> + Default directory install permissions. Permissions in format ``<u=rwx,g=rx,o=rx>``. -``--prefix <prefix>`` +.. option:: --prefix <prefix> + Override the installation prefix, :variable:`CMAKE_INSTALL_PREFIX`. -``--strip`` +.. option:: --strip + Strip before installing. -``-v, --verbose`` +.. option:: -v, --verbose + Enable verbose output. This option can be omitted if :envvar:`VERBOSE` environment variable is set. -Run ``cmake --install`` with no options for quick help. +Run :option:`cmake --install` with no options for quick help. Open a Project ============== +.. program:: cmake + .. code-block:: shell cmake --open <dir> @@ -610,14 +695,26 @@ supported by some generators. Run a Script ============ +.. program:: cmake + .. code-block:: shell - cmake [{-D <var>=<value>}...] -P <cmake-script-file> [-- <unparsed-options>...] + cmake [-D <var>=<value>]... -P <cmake-script-file> [-- <unparsed-options>...] + +.. program:: cmake-P + +.. option:: -D <var>=<value> -Process the given cmake file as a script written in the CMake -language. No configure or generate step is performed and the cache -is not modified. If variables are defined using ``-D``, this must be -done before the ``-P`` argument. + Define a variable for script mode. + +.. program:: cmake + +.. option:: -P <cmake-script-file> + + Process the given cmake file as a script written in the CMake + language. No configure or generate step is performed and the cache + is not modified. If variables are defined using ``-D``, this must be + done before the ``-P`` argument. Any options after ``--`` are not parsed by CMake, but they are still included in the set of :variable:`CMAKE_ARGV<n> <CMAKE_ARGV0>` variables passed to the @@ -629,16 +726,24 @@ script (including the ``--`` itself). Run a Command-Line Tool ======================= +.. program:: cmake + CMake provides builtin command-line tools through the signature .. code-block:: shell cmake -E <command> [<options>] -Run ``cmake -E`` or ``cmake -E help`` for a summary of commands. +.. option:: -E [help] + + Run ``cmake -E`` or ``cmake -E help`` for a summary of commands. + +.. program:: cmake-E + Available commands are: -``capabilities`` +.. option:: capabilities + .. versionadded:: 3.7 Report cmake capabilities in JSON format. The output is a JSON object @@ -648,7 +753,7 @@ Available commands are: A JSON object with version information. Keys are: ``string`` - The full version string as displayed by cmake ``--version``. + The full version string as displayed by cmake :option:`--version <cmake --version>`. ``major`` The major version number in integer form. ``minor`` @@ -675,7 +780,8 @@ Available commands are: Optional member that may be present when the generator supports platform specification via :variable:`CMAKE_GENERATOR_PLATFORM` - (``-A ...``). The value is a list of platforms known to be supported. + (:option:`-A ... <cmake -A>`). The value is a list of platforms known to + be supported. ``extraGenerators`` A list of strings with all the extra generators compatible with the generator. @@ -700,30 +806,52 @@ Available commands are: ``true`` if cmake supports server-mode and ``false`` otherwise. Always false since CMake 3.20. -``cat [--] <files>...`` + ``tls`` + .. versionadded:: 3.25 + + ``true`` if TLS support is enabled and ``false`` otherwise. + +.. option:: cat [--] <files>... + .. versionadded:: 3.18 Concatenate files and print on the standard output. - .. versionadded:: 3.24 + .. program:: cmake-E_cat + + .. option:: -- + + .. versionadded:: 3.24 + Added support for the double dash argument ``--``. This basic implementation of ``cat`` does not support any options, so using a option starting with ``-`` will result in an error. Use ``--`` to indicate the end of options, in case a file starts with ``-``. -``chdir <dir> <cmd> [<arg>...]`` +.. program:: cmake-E + +.. option:: chdir <dir> <cmd> [<arg>...] + Change the current working directory and run a command. -``compare_files [--ignore-eol] <file1> <file2>`` +.. option:: 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``. In case of invalid arguments, it returns 2. - .. versionadded:: 3.14 - The ``--ignore-eol`` option implies line-wise comparison and ignores - LF/CRLF differences. + .. program:: cmake-E_compare_files + + .. option:: --ignore-eol + + .. versionadded:: 3.14 + + The option implies line-wise comparison and ignores LF/CRLF differences. + +.. program:: cmake-E + +.. option:: copy <file>... <destination> -``copy <file>... <destination>`` Copy files to ``<destination>`` (either file or directory). If multiple files are specified, the ``<destination>`` must be directory and it must exist. Wildcards are not supported. @@ -733,7 +861,8 @@ Available commands are: .. versionadded:: 3.5 Support for multiple input files. -``copy_directory <dir>... <destination>`` +.. option:: copy_directory <dir>... <destination> + Copy content of ``<dir>...`` directories to ``<destination>`` directory. If ``<destination>`` directory does not exist it will be created. ``copy_directory`` does follow symlinks. @@ -745,7 +874,8 @@ Available commands are: The command now fails when the source directory does not exist. Previously it succeeded by creating an empty destination directory. -``copy_if_different <file>... <destination>`` +.. option:: copy_if_different <file>... <destination> + Copy files to ``<destination>`` (either file or directory) if they have changed. If multiple files are specified, the ``<destination>`` must be @@ -755,7 +885,8 @@ Available commands are: .. versionadded:: 3.5 Support for multiple input files. -``create_symlink <old> <new>`` +.. option:: create_symlink <old> <new> + Create a symbolic link ``<new>`` naming ``<old>``. .. versionadded:: 3.13 @@ -764,7 +895,8 @@ Available commands are: .. note:: Path to where ``<new>`` symbolic link will be created has to exist beforehand. -``create_hardlink <old> <new>`` +.. option:: create_hardlink <old> <new> + .. versionadded:: 3.19 Create a hard link ``<new>`` naming ``<old>``. @@ -773,31 +905,65 @@ Available commands are: Path to where ``<new>`` hard link will be created has to exist beforehand. ``<old>`` has to exist beforehand. -``echo [<string>...]`` +.. option:: echo [<string>...] + Displays arguments as text. -``echo_append [<string>...]`` +.. option:: echo_append [<string>...] + Displays arguments as text but no new line. -``env [--unset=NAME ...] [NAME=VALUE ...] [--] <command> [<arg>...]`` +.. option:: env [<options>] [--] <command> [<arg>...] + .. versionadded:: 3.1 - Run command in a modified environment. + Run command in a modified environment. Options are: + + .. program:: cmake-E_env + + .. option:: NAME=VALUE + + Replaces the current value of ``NAME`` with ``VALUE``. + + .. option:: --unset=NAME + + Unsets the current value of ``NAME``. + + .. option:: --modify ENVIRONMENT_MODIFICATION + + .. versionadded:: 3.25 + + Apply a single :prop_test:`ENVIRONMENT_MODIFICATION` operation to the + modified environment. + + The ``NAME=VALUE`` and ``--unset=NAME`` options are equivalent to + ``--modify NAME=set:VALUE`` and ``--modify NAME=unset:``, respectively. + Note that ``--modify NAME=reset:`` resets ``NAME`` to the value it had + when ``cmake`` launched (or unsets it), not to the most recent + ``NAME=VALUE`` option. + + .. option:: -- + + .. versionadded:: 3.24 - .. versionadded:: 3.24 Added support for the double dash argument ``--``. Use ``--`` to stop interpreting options/environment variables and treat the next argument as the command, even if it start with ``-`` or contains a ``=``. -``environment`` +.. program:: cmake-E + +.. option:: environment + Display the current environment variables. -``false`` +.. option:: false + .. versionadded:: 3.16 Do nothing, with an exit code of 1. -``make_directory <dir>...`` +.. option:: make_directory <dir>... + Create ``<dir>`` directories. If necessary, create parent directories too. If a directory already exists it will be silently ignored. @@ -805,13 +971,15 @@ Available commands are: .. versionadded:: 3.5 Support for multiple input directories. -``md5sum <file>...`` +.. option:: md5sum <file>... + Create MD5 checksum of files in ``md5sum`` compatible format:: 351abe79cd3800b38cdfb25d45015a15 file1.txt 052f86c15bbde68af55c7f7b340ab639 file2.txt -``sha1sum <file>...`` +.. option:: sha1sum <file>... + .. versionadded:: 3.10 Create SHA1 checksum of files in ``sha1sum`` compatible format:: @@ -819,7 +987,8 @@ Available commands are: 4bb7932a29e6f73c97bb9272f2bdc393122f86e0 file1.txt 1df4c8f318665f9a5f2ed38f55adadb7ef9f559c file2.txt -``sha224sum <file>...`` +.. option:: sha224sum <file>... + .. versionadded:: 3.10 Create SHA224 checksum of files in ``sha224sum`` compatible format:: @@ -827,7 +996,8 @@ Available commands are: b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930 file1.txt 6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24 file2.txt -``sha256sum <file>...`` +.. option:: sha256sum <file>... + .. versionadded:: 3.10 Create SHA256 checksum of files in ``sha256sum`` compatible format:: @@ -835,7 +1005,8 @@ Available commands are: 76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc file1.txt 15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea file2.txt -``sha384sum <file>...`` +.. option:: sha384sum <file>... + .. versionadded:: 3.10 Create SHA384 checksum of files in ``sha384sum`` compatible format:: @@ -843,7 +1014,8 @@ Available commands are: acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434 file1.txt 668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d file2.txt -``sha512sum <file>...`` +.. option:: sha512sum <file>... + .. versionadded:: 3.10 Create SHA512 checksum of files in ``sha512sum`` compatible format:: @@ -851,7 +1023,8 @@ Available commands are: 2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89 file1.txt 7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d file2.txt -``remove [-f] <file>...`` +.. option:: remove [-f] <file>... + .. deprecated:: 3.17 Remove the file(s). The planned behavior was that if any of the @@ -864,7 +1037,8 @@ Available commands are: The implementation was buggy and always returned 0. It cannot be fixed without breaking backwards compatibility. Use ``rm`` instead. -``remove_directory <dir>...`` +.. option:: remove_directory <dir>... + .. deprecated:: 3.17 Remove ``<dir>`` directories and their contents. If a directory does @@ -877,11 +1051,13 @@ Available commands are: .. versionadded:: 3.16 If ``<dir>`` is a symlink to a directory, just the symlink will be removed. -``rename <oldname> <newname>`` +.. option:: rename <oldname> <newname> + Rename a file or directory (on one volume). If file with the ``<newname>`` name already exists, then it will be silently replaced. -``rm [-rRf] [--] <file|dir>...`` +.. option:: rm [-rRf] [--] <file|dir>... + .. versionadded:: 3.17 Remove the files ``<file>`` or directories ``<dir>``. @@ -892,22 +1068,29 @@ Available commands are: situations instead. Use ``--`` to stop interpreting options and treat all remaining arguments as paths, even if they start with ``-``. -``server`` +.. option:: server + Launch :manual:`cmake-server(7)` mode. -``sleep <number>...`` +.. option:: sleep <number>... + .. versionadded:: 3.0 Sleep for given number of seconds. -``tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]`` +.. option:: tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...] + Create or extract a tar or zip archive. Options are: - ``c`` + .. program:: cmake-E_tar + + .. option:: c + Create a new archive containing the specified files. If used, the ``<pathname>...`` argument is mandatory. - ``x`` + .. option:: x + Extract to disk from the archive. .. versionadded:: 3.15 @@ -916,33 +1099,40 @@ Available commands are: When extracting selected files or directories, you must provide their exact names including the path, as printed by list (``-t``). - ``t`` + .. option:: t + List archive contents. .. versionadded:: 3.15 The ``<pathname>...`` argument could be used to list only selected files or directories. - ``v`` + .. option:: v + Produce verbose output. - ``z`` + .. option:: z + Compress the resulting archive with gzip. - ``j`` + .. option:: j + Compress the resulting archive with bzip2. - ``J`` + .. option:: J + .. versionadded:: 3.1 Compress the resulting archive with XZ. - ``--zstd`` + .. option:: --zstd + .. versionadded:: 3.15 Compress the resulting archive with Zstandard. - ``--files-from=<file>`` + .. option:: --files-from=<file> + .. versionadded:: 3.1 Read file names from the given file, one per line. @@ -950,25 +1140,29 @@ Available commands are: except for ``--add-file=<name>`` to add files whose names start in ``-``. - ``--format=<format>`` + .. option:: --format=<format> + .. versionadded:: 3.3 Specify the format of the archive to be created. Supported formats are: ``7zip``, ``gnutar``, ``pax``, ``paxr`` (restricted pax, default), and ``zip``. - ``--mtime=<date>`` + .. option:: --mtime=<date> + .. versionadded:: 3.1 Specify modification time recorded in tarball entries. - ``--touch`` + .. option:: --touch + .. versionadded:: 3.24 Use current local timestamp instead of extracting file timestamps from the archive. - ``--`` + .. option:: -- + .. versionadded:: 3.1 Stop interpreting options and treat all remaining arguments @@ -983,7 +1177,10 @@ Available commands are: ``tar`` tool. The command now also parses all flags, and if an invalid flag was provided, a warning is issued. -``time <command> [<args>...]`` +.. program:: cmake-E + +.. option:: time <command> [<args>...] + Run command and display elapsed time. .. versionadded:: 3.5 @@ -991,15 +1188,18 @@ Available commands are: through to the child process. This may break scripts that worked around the bug with their own extra quoting or escaping. -``touch <file>...`` +.. option:: touch <file>... + Creates ``<file>`` if file do not exist. If ``<file>`` exists, it is changing ``<file>`` access and modification times. -``touch_nocreate <file>...`` +.. option:: touch_nocreate <file>... + Touch a file if it exists but do not create it. If a file does not exist it will be silently ignored. -``true`` +.. option:: true + .. versionadded:: 3.16 Do nothing, with an exit code of 0. @@ -1009,28 +1209,34 @@ Windows-specific Command-Line Tools The following ``cmake -E`` commands are available only on Windows: -``delete_regv <key>`` +.. option:: delete_regv <key> + Delete Windows registry value. -``env_vs8_wince <sdkname>`` +.. option:: env_vs8_wince <sdkname> + .. versionadded:: 3.2 Displays a batch file which sets the environment for the provided Windows CE SDK installed in VS2005. -``env_vs9_wince <sdkname>`` +.. option:: env_vs9_wince <sdkname> + .. versionadded:: 3.2 Displays a batch file which sets the environment for the provided Windows CE SDK installed in VS2008. -``write_regv <key> <value>`` +.. option:: write_regv <key> <value> + Write Windows registry value. Run the Find-Package Tool ========================= +.. program:: cmake--find-package + CMake provides a pkg-config like helper for Makefile-based projects: .. code-block:: shell @@ -1046,10 +1252,45 @@ autoconf-based projects (via ``share/aclocal/cmake.m4``). This mode is not well-supported due to some technical limitations. It is kept for compatibility but should not be used in new projects. +.. _`Workflow Mode`: + +Run a Workflow Preset +===================== + +.. program:: cmake + +:manual:`CMake Presets <cmake-presets(7)>` provides a way to execute multiple +build steps in order: + +.. code-block:: shell + + cmake --workflow [<options>] + +The options are: + +.. option:: --workflow + + Select a :ref:`Workflow Preset` using one of the following options. + +.. program:: cmake--workflow + +.. option:: --preset <preset>, --preset=<preset> + + Use a workflow preset to specify a workflow. The project binary directory + is inferred from the initial configure preset. The current working directory + must contain CMake preset files. + See :manual:`preset <cmake-presets(7)>` for more details. + +.. option:: --list-presets + + Lists the available workflow presets. The current working directory must + contain CMake preset files. View Help ========= +.. program:: cmake + To print selected pages from the CMake documentation, use .. code-block:: shell diff --git a/Help/manual/cpack.1.rst b/Help/manual/cpack.1.rst index 395cd41..3f26d72 100644 --- a/Help/manual/cpack.1.rst +++ b/Help/manual/cpack.1.rst @@ -26,12 +26,12 @@ All supported generators are specified in the :manual:`cpack-generators <cpack-generators(7)>` manual. The command ``cpack --help`` prints a list of generators supported for the target platform. Which of them are to be used can be selected through the :variable:`CPACK_GENERATOR` variable -or through the command-line option ``-G``. +or through the command-line option :option:`-G <cpack -G>`. The **cpack** program is steered by a configuration file written in the :manual:`CMake language <cmake-language(7)>`. Unless chosen differently -through the command-line option ``--config``, the file ``CPackConfig.cmake`` -in the current directory is used. +through the command-line option :option:`--config <cpack --config>`, the +file ``CPackConfig.cmake`` in the current directory is used. In the standard CMake workflow, the file ``CPackConfig.cmake`` is generated by the :manual:`cmake <cmake(1)>` executable, provided the :module:`CPack` @@ -40,7 +40,10 @@ module is included by the project's ``CMakeLists.txt`` file. Options ======= -``-G <generators>`` +.. program:: cpack + +.. option:: -G <generators> + ``<generators>`` is a :ref:`semicolon-separated list <CMake Language Lists>` of generator names. ``cpack`` will iterate through this list and produce package(s) in that generator's format according to the details provided in @@ -48,7 +51,8 @@ Options the :variable:`CPACK_GENERATOR` variable determines the default set of generators that will be used. -``-C <configs>`` +.. option:: -C <configs> + Specify the project configuration(s) to be packaged (e.g. ``Debug``, ``Release``, etc.), where ``<configs>`` is a :ref:`semicolon-separated list <CMake Language Lists>`. @@ -58,36 +62,44 @@ Options The user is responsible for ensuring that the configuration(s) listed have already been built before invoking ``cpack``. -``-D <var>=<value>`` +.. option:: -D <var>=<value> + Set a CPack variable. This will override any value set for ``<var>`` in the input file read by ``cpack``. -``--config <configFile>`` +.. option:: --config <configFile> + Specify the configuration file read by ``cpack`` to provide the packaging details. By default, ``CPackConfig.cmake`` in the current directory will be used. -``--verbose, -V`` +.. option:: -V, --verbose + Run ``cpack`` with verbose output. This can be used to show more details from the package generation tools and is suitable for project developers. -``--debug`` +.. option:: --debug + Run ``cpack`` with debug output. This option is intended mainly for the developers of ``cpack`` itself and is not normally needed by project developers. -``--trace`` +.. option:: --trace + Put the underlying cmake scripts in trace mode. -``--trace-expand`` +.. option:: --trace-expand + Put the underlying cmake scripts in expanded trace mode. -``-P <packageName>`` +.. option:: -P <packageName> + Override/define the value of the :variable:`CPACK_PACKAGE_NAME` variable used for packaging. Any value set for this variable in the ``CPackConfig.cmake`` file will then be ignored. -``-R <packageVersion>`` +.. option:: -R <packageVersion> + Override/define the value of the :variable:`CPACK_PACKAGE_VERSION` variable used for packaging. It will override a value set in the ``CPackConfig.cmake`` file or one automatically computed from @@ -95,16 +107,26 @@ Options :variable:`CPACK_PACKAGE_VERSION_MINOR` and :variable:`CPACK_PACKAGE_VERSION_PATCH`. -``-B <packageDirectory>`` +.. option:: -B <packageDirectory> + Override/define :variable:`CPACK_PACKAGE_DIRECTORY`, which controls the directory where CPack will perform its packaging work. The resultant package(s) will be created at this location by default and a ``_CPack_Packages`` subdirectory will also be created below this directory to use as a working area during package creation. -``--vendor <vendorName>`` +.. option:: --vendor <vendorName> + Override/define :variable:`CPACK_PACKAGE_VENDOR`. +.. option:: --preset <presetName> + + Use a preset from :manual:`cmake-presets(7)`. + +.. option:: --list-presets + + List presets from :manual:`cmake-presets(7)`. + .. include:: OPTIONS_HELP.txt See Also diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 06f0d4e..3497a9f 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -10,12 +10,24 @@ Synopsis .. parsed-literal:: - ctest [<options>] - ctest --build-and-test <path-to-source> <path-to-build> - --build-generator <generator> [<options>...] - [--build-options <opts>...] [--test-command <command> [<args>...]] - ctest {-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>} - [-- <dashboard-options>...] + `Run Tests`_ + ctest [<options>] + + `Build and Test Mode`_ + ctest --build-and-test <path-to-source> <path-to-build> + --build-generator <generator> [<options>...] + [--build-options <opts>...] + [--test-command <command> [<args>...]] + + `Dashboard Client`_ + ctest -D <dashboard> [-- <dashboard-options>...] + ctest -M <model> -T <action> [-- <dashboard-options>...] + ctest -S <script> [-- <dashboard-options>...] + ctest -SP <script> [-- <dashboard-options>...] + + `View Help`_ + ctest --help[-<topic>] + Description =========== @@ -25,22 +37,27 @@ CMake-generated build trees created for projects that use the :command:`enable_testing` and :command:`add_test` commands have testing support. This program will run the tests and report results. -.. _`CTest Options`: +.. _`Run Tests`: -Options -======= +Run Tests +========= + +.. program:: ctest + +.. option:: --preset <preset>, --preset=<preset> -``--preset <preset>``, ``--preset=<preset>`` Use a test preset to specify test options. The project binary directory is inferred from the ``configurePreset`` key. The current working directory must contain CMake preset files. See :manual:`preset <cmake-presets(7)>` for more details. -``--list-presets`` +.. option:: --list-presets + Lists the available test presets. The current working directory must contain CMake preset files. -``-C <cfg>, --build-config <cfg>`` +.. option:: -C <cfg>, --build-config <cfg> + Choose configuration to test. Some CMake-generated build trees can have multiple build @@ -48,7 +65,8 @@ Options which one should be tested. Example configurations are ``Debug`` and ``Release``. -``--progress`` +.. option:: --progress + Enable short progress output from tests. When the output of **ctest** is being sent directly to a terminal, the @@ -61,40 +79,47 @@ Options This option can also be enabled by setting the environment variable :envvar:`CTEST_PROGRESS_OUTPUT`. -``-V,--verbose`` +.. option:: -V, --verbose + Enable verbose output from tests. Test output is normally suppressed and only summary information is displayed. This option will show all test output. -``-VV,--extra-verbose`` +.. option:: -VV, --extra-verbose + Enable more verbose output from tests. Test output is normally suppressed and only summary information is displayed. This option will show even more test output. -``--debug`` +.. option:: --debug + Displaying more verbose internals of CTest. This feature will result in a large number of output that is mostly useful for debugging dashboard problems. -``--output-on-failure`` +.. option:: --output-on-failure + Output anything outputted by the test program if the test should fail. This option can also be enabled by setting the :envvar:`CTEST_OUTPUT_ON_FAILURE` environment variable -``--stop-on-failure`` +.. option:: --stop-on-failure + Stop running the tests when the first failure happens. -``-F`` +.. option:: -F + Enable failover. This option allows CTest to resume a test set execution that was previously interrupted. If no interruption occurred, the ``-F`` option will have no effect. -``-j <jobs>, --parallel <jobs>`` +.. option:: -j <jobs>, --parallel <jobs> + Run the tests in parallel using the given number of jobs. This option tells CTest to run the tests in parallel using given @@ -105,7 +130,8 @@ Options See `Label and Subproject Summary`_. -``--resource-spec-file <file>`` +.. option:: --resource-spec-file <file> + Run CTest with :ref:`resource allocation <ctest-resource-allocation>` enabled, using the :ref:`resource specification file <ctest-resource-specification-file>` @@ -114,40 +140,54 @@ Options When ``ctest`` is run as a `Dashboard Client`_ this sets the ``ResourceSpecFile`` option of the `CTest Test Step`_. -``--test-load <level>`` - While running tests in parallel (e.g. with ``-j``), try not to start - tests when they may cause the CPU load to pass above a given threshold. +.. option:: --test-load <level> + + While running tests in parallel (e.g. with :option:`-j <ctest -j>`), try + not to start tests when they may cause the CPU load to pass above a given + threshold. When ``ctest`` is run as a `Dashboard Client`_ this sets the ``TestLoad`` option of the `CTest Test Step`_. -``-Q,--quiet`` +.. option:: -Q, --quiet + Make CTest quiet. This option will suppress all the output. The output log file will - still be generated if the ``--output-log`` is specified. Options such - as ``--verbose``, ``--extra-verbose``, and ``--debug`` are ignored + still be generated if the :option:`--output-log <ctest --output-log>` is + specified. Options such as :option:`--verbose <ctest --verbose>`, + :option:`--extra-verbose <ctest --extra-verbose>`, and + :option:`--debug <ctest --debug>` are ignored if ``--quiet`` is specified. -``-O <file>, --output-log <file>`` +.. option:: -O <file>, --output-log <file> + Output to log file. This option tells CTest to write all its output to a ``<file>`` log file. -``--output-junit <file>`` +.. option:: --output-junit <file> + + .. versionadded:: 3.21 + Write test results in JUnit format. This option tells CTest to write test results to ``<file>`` in JUnit XML format. If ``<file>`` already exists, it will be overwritten. If using the - ``-S`` option to run a dashboard script, use the ``OUTPUT_JUNIT`` keyword - with the :command:`ctest_test` command instead. + :option:`-S <ctest -S>` option to run a dashboard script, use the + ``OUTPUT_JUNIT`` keyword with the :command:`ctest_test` command instead. + +.. option:: -N, --show-only[=<format>] -``-N,--show-only[=<format>]`` Disable actual execution of tests. This option tells CTest to list the tests that would be run but not - actually run them. Useful in conjunction with the ``-R`` and ``-E`` - options. + actually run them. Useful in conjunction with the :option:`-R <ctest -R>` + and :option:`-E <ctest -E>` options. + + .. versionadded:: 3.14 + + The ``--show-only`` option accepts a ``<format>`` value. ``<format>`` can be one of the following values. @@ -159,7 +199,8 @@ Options Dump the test information in JSON format. See `Show as JSON Object Model`_. -``-L <regex>, --label-regex <regex>`` +.. option:: -L <regex>, --label-regex <regex> + Run tests with labels matching regular expression as described under :ref:`string(REGEX) <Regex Specification>`. @@ -169,19 +210,22 @@ Options of the test's labels (i.e. the multiple ``-L`` labels form an ``AND`` relationship). See `Label Matching`_. -``-R <regex>, --tests-regex <regex>`` +.. option:: -R <regex>, --tests-regex <regex> + Run tests matching regular expression. This option tells CTest to run only the tests whose names match the given regular expression. -``-E <regex>, --exclude-regex <regex>`` +.. option:: -E <regex>, --exclude-regex <regex> + Exclude tests matching regular expression. This option tells CTest to NOT run the tests whose names match the given regular expression. -``-LE <regex>, --label-exclude <regex>`` +.. option:: -LE <regex>, --label-exclude <regex> + Exclude tests with labels matching regular expression. This option tells CTest to NOT run the tests whose labels match the @@ -190,7 +234,8 @@ Options of the test's labels (i.e. the multiple ``-LE`` labels form an ``AND`` relationship). See `Label Matching`_. -``-FA <regex>, --fixture-exclude-any <regex>`` +.. option:: -FA <regex>, --fixture-exclude-any <regex> + Exclude fixtures matching ``<regex>`` from automatically adding any tests to the test set. @@ -201,72 +246,18 @@ Options including test dependencies and skipping tests that have fixture setup tests that fail. -``-FS <regex>, --fixture-exclude-setup <regex>`` - Same as ``-FA`` except only matching setup tests are excluded. - -``-FC <regex>, --fixture-exclude-cleanup <regex>`` - Same as ``-FA`` except only matching cleanup tests are excluded. - -``-D <dashboard>, --dashboard <dashboard>`` - Execute dashboard test. - - This option tells CTest to act as a CDash client and perform a - dashboard test. All tests are ``<Mode><Test>``, where ``<Mode>`` can be - ``Experimental``, ``Nightly``, and ``Continuous``, and ``<Test>`` can be - ``Start``, ``Update``, ``Configure``, ``Build``, ``Test``, - ``Coverage``, and ``Submit``. - - See `Dashboard Client`_. - -``-D <var>:<type>=<value>`` - Define a variable for script mode. - - Pass in variable values on the command line. Use in conjunction - with ``-S`` to pass variable values to a dashboard script. Parsing ``-D`` - arguments as variable values is only attempted if the value - following ``-D`` does not match any of the known dashboard types. - -``-M <model>, --test-model <model>`` - Sets the model for a dashboard. - - This option tells CTest to act as a CDash client where the ``<model>`` - can be ``Experimental``, ``Nightly``, and ``Continuous``. - Combining ``-M`` and ``-T`` is similar to ``-D``. +.. option:: -FS <regex>, --fixture-exclude-setup <regex> - See `Dashboard Client`_. + Same as :option:`-FA <ctest -FA>` except only matching setup tests are + excluded. -``-T <action>, --test-action <action>`` - Sets the dashboard action to perform. - - This option tells CTest to act as a CDash client and perform some - action such as ``start``, ``build``, ``test`` etc. See - `Dashboard Client Steps`_ for the full list of actions. - Combining ``-M`` and ``-T`` is similar to ``-D``. +.. option:: -FC <regex>, --fixture-exclude-cleanup <regex> - See `Dashboard Client`_. + Same as :option:`-FA <ctest -FA>` except only matching cleanup tests are + excluded. -``-S <script>, --script <script>`` - Execute a dashboard for a configuration. +.. option:: -I [Start,End,Stride,test#,test#|Test file], --tests-information - This option tells CTest to load in a configuration script which sets - a number of parameters such as the binary and source directories. - Then CTest will do what is required to create and run a dashboard. - This option basically sets up a dashboard and then runs ``ctest -D`` - with the appropriate options. - - See `Dashboard Client`_. - -``-SP <script>, --script-new-process <script>`` - Execute a dashboard for a configuration. - - This option does the same operations as ``-S`` but it will do them in a - separate process. This is primarily useful in cases where the - script may modify the environment and you do not want the modified - environment to impact other ``-S`` scripts. - - See `Dashboard Client`_. - -``-I [Start,End,Stride,test#,test#|Test file], --tests-information`` Run a specific number of tests by number. This option causes CTest to run tests starting at number ``Start``, @@ -275,23 +266,29 @@ Options ``End``, or ``Stride`` can be empty. Optionally a file can be given that contains the same syntax as the command line. -``-U, --union`` - Take the Union of ``-I`` and ``-R``. +.. option:: -U, --union + + Take the Union of :option:`-I <ctest -I>` and :option:`-R <ctest -R>`. + + When both :option:`-R <ctest -R>` and :option:`-I <ctest -I>` are specified + by default the intersection of tests are run. By specifying ``-U`` the union + of tests is run instead. - When both ``-R`` and ``-I`` are specified by default the intersection of - tests are run. By specifying ``-U`` the union of tests is run instead. +.. option:: --rerun-failed -``--rerun-failed`` Run only the tests that failed previously. This option tells CTest to perform only the tests that failed during its previous run. When this option is specified, CTest ignores all - other options intended to modify the list of tests to run (``-L``, ``-R``, - ``-E``, ``-LE``, ``-I``, etc). In the event that CTest runs and no tests - fail, subsequent calls to CTest with the ``--rerun-failed`` option will run - the set of tests that most recently failed (if any). + other options intended to modify the list of tests to run ( + :option:`-L <ctest -L>`, :option:`-R <ctest -R>`, :option:`-E <ctest -E>`, + :option:`-LE <ctest -LE>`, :option:`-I <ctest -I>`, etc). In the event that + CTest runs and no tests fail, subsequent calls to CTest with the + ``--rerun-failed`` option will run the set of tests that most recently + failed (if any). + +.. option:: --repeat <mode>:<n> -``--repeat <mode>:<n>`` Run tests repeatedly based on the given ``<mode>`` up to ``<n>`` times. The modes are: @@ -310,17 +307,20 @@ Options This is useful in tolerating sporadic timeouts in test cases on busy machines. -``--repeat-until-fail <n>`` - Equivalent to ``--repeat until-fail:<n>``. +.. option:: --repeat-until-fail <n> + + Equivalent to :option:`--repeat until-fail:\<n\> <ctest --repeat>`. + +.. option:: --max-width <width> -``--max-width <width>`` Set the max width for a test name to output. Set the maximum width for each test name to show in the output. This allows the user to widen the output to avoid clipping the test name which can be very annoying. -``--interactive-debug-mode [0|1]`` +.. option:: --interactive-debug-mode [0|1] + Set the interactive mode to ``0`` or ``1``. This option causes CTest to run tests in either an interactive mode @@ -332,7 +332,8 @@ Options popup windows to appear. Now, due to CTest's use of ``libuv`` to launch test processes, all system debug popup windows are always blocked. -``--no-label-summary`` +.. option:: --no-label-summary + Disable timing summary information for labels. This option tells CTest not to print summary information for each @@ -341,7 +342,8 @@ Options See `Label and Subproject Summary`_. -``--no-subproject-summary`` +.. option:: --no-subproject-summary + Disable timing summary information for subprojects. This option tells CTest not to print summary information for each @@ -350,79 +352,95 @@ Options See `Label and Subproject Summary`_. -``--build-and-test`` -See `Build and Test Mode`_. +.. option:: --test-dir <dir> + + Specify the directory in which to look for tests. -``--test-dir <dir>`` -Specify the directory in which to look for tests. +.. option:: --test-output-size-passed <size> -``--test-output-size-passed <size>`` .. versionadded:: 3.4 Limit the output for passed tests to ``<size>`` bytes. -``--test-output-size-failed <size>`` +.. option:: --test-output-size-failed <size> + .. versionadded:: 3.4 Limit the output for failed tests to ``<size>`` bytes. -``--test-output-truncation <mode>`` +.. option:: --test-output-truncation <mode> + .. versionadded:: 3.24 Truncate ``tail`` (default), ``middle`` or ``head`` of test output once maximum output size is reached. -``--overwrite`` +.. option:: --overwrite + Overwrite CTest configuration option. By default CTest uses configuration options from configuration file. This option will overwrite the configuration option. -``--force-new-ctest-process`` +.. option:: --force-new-ctest-process + Run child CTest instances as new processes. By default CTest will run child CTest instances within the same process. If this behavior is not desired, this argument will enforce new processes for child CTest processes. -``--schedule-random`` +.. option:: --schedule-random + Use a random order for scheduling tests. This option will run the tests in a random order. It is commonly used to detect implicit dependencies in a test suite. -``--submit-index`` +.. option:: --submit-index + Legacy option for old Dart2 dashboard server feature. Do not use. -``--timeout <seconds>`` +.. option:: --timeout <seconds> + Set the default test timeout. This option effectively sets a timeout on all tests that do not already have a timeout set on them via the :prop_test:`TIMEOUT` property. -``--stop-time <time>`` +.. option:: --stop-time <time> + Set a time at which all tests should stop running. Set a real time of day at which all tests should timeout. Example: ``7:00:00 -0400``. Any time format understood by the curl date parser is accepted. Local time is assumed if no timezone is specified. -``--print-labels`` +.. option:: --print-labels + Print all available test labels. This option will not run any tests, it will simply print the list of all labels associated with the test set. -``--no-tests=<[error|ignore]>`` - Regard no tests found either as error or ignore it. +.. option:: --no-tests=<action> + + Regard no tests found either as error (when ``<action>`` is set to + ``error``) or ignore it (when ``<action>`` is set to ``ignore``). If no tests were found, the default behavior of CTest is to always log an error message but to return an error code in script mode only. This option unifies the behavior of CTest by either returning an error code if no tests were found or by ignoring it. +View Help +========= + +To print version details or selected pages from the CMake documentation, +use one of the following options: + .. include:: OPTIONS_HELP.txt .. _`Label Matching`: @@ -435,17 +453,17 @@ or excluded from a test run by filtering on the labels. Each individual filter is a regular expression applied to the labels attached to a test. -When ``-L`` is used, in order for a test to be included in a +When :option:`-L <ctest -L>` is used, in order for a test to be included in a test run, each regular expression must match at least one -label. Using more than one ``-L`` option means "match **all** +label. Using more than one :option:`-L <ctest -L>` option means "match **all** of these". -The ``-LE`` option works just like ``-L``, but excludes tests -rather than including them. A test is excluded if each regular -expression matches at least one label. +The :option:`-LE <ctest -LE>` option works just like :option:`-L <ctest -L>`, +but excludes tests rather than including them. A test is excluded if each +regular expression matches at least one label. -If a test has no labels attached to it, then ``-L`` will never -include that test, and ``-LE`` will never exclude that test. +If a test has no labels attached to it, then :option:`-L <ctest -L>` will never +include that test, and :option:`-LE <ctest -LE>` will never exclude that test. As an example of tests with labels, consider five tests, with the following labels: @@ -532,62 +550,85 @@ be provided to use ``--build-and-test``. If ``--test-command`` is specified then that will be run after the build is complete. Other options that affect this mode include: -``--build-target`` - Specify a specific target to build. +.. option:: --build-and-test - If left out the ``all`` target is built. + Switch into the build and test mode. + +.. option:: --build-target + + Specify a specific target to build. The option can be given multiple times + with different targets, in which case each target is built in turn. + A clean will be done before building each target unless the + :option:`--build-noclean` option is given. + + If no ``--build-target`` is specified, the ``all`` target is built. + +.. option:: --build-nocmake -``--build-nocmake`` Run the build without running cmake first. Skip the cmake step. -``--build-run-dir`` +.. option:: --build-run-dir + Specify directory to run programs from. Directory where programs will be after it has been compiled. -``--build-two-config`` +.. option:: --build-two-config + Run CMake twice. -``--build-exe-dir`` +.. option:: --build-exe-dir + Specify the directory for the executable. -``--build-generator`` +.. option:: --build-generator + Specify the generator to use. See the :manual:`cmake-generators(7)` manual. -``--build-generator-platform`` +.. option:: --build-generator-platform + Specify the generator-specific platform. -``--build-generator-toolset`` +.. option:: --build-generator-toolset + Specify the generator-specific toolset. -``--build-project`` +.. option:: --build-project + Specify the name of the project to build. -``--build-makeprogram`` +.. option:: --build-makeprogram + Specify the explicit make program to be used by CMake when configuring and building the project. Only applicable for Make and Ninja based generators. -``--build-noclean`` +.. option:: --build-noclean + Skip the make clean step. -``--build-config-sample`` +.. option:: --build-config-sample + A sample executable to use to determine the configuration that should be used. e.g. ``Debug``, ``Release`` etc. -``--build-options`` +.. option:: --build-options + Additional options for configuring the build (i.e. for CMake, not for the build tool). Note that if this is specified, the ``--build-options`` keyword and its arguments must be the last option given on the command line, with the possible exception of ``--test-command``. -``--test-command`` - The command to run as the test step with the ``--build-and-test`` option. +.. option:: --test-command + + The command to run as the test step with the + :option:`--build-and-test <ctest --build-and-test>` option. All arguments following this keyword will be assumed to be part of the test command line, so it must be the last option given. -``--test-timeout`` +.. option:: --test-timeout + The time limit in seconds .. _`Dashboard Client`: @@ -600,12 +641,80 @@ application. As a dashboard client, CTest performs a sequence of steps to configure, build, and test software, and then submits the results to a `CDash`_ server. The command-line signature used to submit to `CDash`_ is:: - ctest (-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>) - [-- <dashboard-options>...] + ctest -D <dashboard> [-- <dashboard-options>...] + ctest -M <model> -T <action> [-- <dashboard-options>...] + ctest -S <script> [-- <dashboard-options>...] + ctest -SP <script> [-- <dashboard-options>...] Options for Dashboard Client include: -``--group <group>`` +.. option:: -D <dashboard>, --dashboard <dashboard> + + Execute dashboard test. + + This option tells CTest to act as a CDash client and perform a + dashboard test. All tests are ``<Mode><Test>``, where ``<Mode>`` can be + ``Experimental``, ``Nightly``, and ``Continuous``, and ``<Test>`` can be + ``Start``, ``Update``, ``Configure``, ``Build``, ``Test``, + ``Coverage``, and ``Submit``. + + If ``<dashboard>`` is not one of the recognized ``<Mode><Test>`` values, + this will be treated as a variable definition instead (see the + :ref:`dashboard-options <Dashboard Options>` further below). + +.. option:: -M <model>, --test-model <model> + + Sets the model for a dashboard. + + This option tells CTest to act as a CDash client where the ``<model>`` + can be ``Experimental``, ``Nightly``, and ``Continuous``. + Combining ``-M`` and :option:`-T <ctest -T>` is similar to + :option:`-D <ctest -D>`. + +.. option:: -T <action>, --test-action <action> + + Sets the dashboard action to perform. + + This option tells CTest to act as a CDash client and perform some + action such as ``start``, ``build``, ``test`` etc. See + `Dashboard Client Steps`_ for the full list of actions. + Combining :option:`-M <ctest -M>` and ``-T`` is similar to + :option:`-D <ctest -D>`. + +.. option:: -S <script>, --script <script> + + Execute a dashboard for a configuration. + + This option tells CTest to load in a configuration script which sets + a number of parameters such as the binary and source directories. + Then CTest will do what is required to create and run a dashboard. + This option basically sets up a dashboard and then runs :option:`ctest -D` + with the appropriate options. + +.. option:: -SP <script>, --script-new-process <script> + + Execute a dashboard for a configuration. + + This option does the same operations as :option:`-S <ctest -S>` but it + will do them in a separate process. This is primarily useful in cases + where the script may modify the environment and you do not want the modified + environment to impact other :option:`-S <ctest -S>` scripts. + +.. _`Dashboard Options`: + +The available ``<dashboard-options>`` are the following: + +.. option:: -D <var>:<type>=<value> + + Define a variable for script mode. + + Pass in variable values on the command line. Use in conjunction + with :option:`-S <ctest -S>` to pass variable values to a dashboard script. + Parsing ``-D`` arguments as variable values is only attempted if the value + following ``-D`` does not match any of the known dashboard types. + +.. option:: --group <group> + Specify what group you'd like to submit results to Submit dashboard to specified group instead of default one. By @@ -616,29 +725,34 @@ Options for Dashboard Client include: This replaces the deprecated option ``--track``. Despite the name change its behavior is unchanged. -``-A <file>, --add-notes <file>`` +.. option:: -A <file>, --add-notes <file> + Add a notes file with submission. This option tells CTest to include a notes file when submitting dashboard. -``--tomorrow-tag`` +.. option:: --tomorrow-tag + ``Nightly`` or ``Experimental`` starts with next day tag. This is useful if the build will not finish in one day. -``--extra-submit <file>[;<file>]`` +.. option:: --extra-submit <file>[;<file>] + Submit extra files to the dashboard. This option will submit extra files to the dashboard. -``--http1.0`` +.. option:: --http1.0 + Submit using `HTTP 1.0`. This option will force CTest to use `HTTP 1.0` to submit files to the dashboard, instead of `HTTP 1.1`. -``--no-compress-output`` +.. option:: --no-compress-output + Do not compress test output when submitting. This flag will turn off automatic compression of test output. Use @@ -722,7 +836,7 @@ Run the ``ctest`` command with the current working directory set to the build tree and use one of these signatures:: ctest -D <mode>[<step>] - ctest -M <mode> [ -T <step> ]... + ctest -M <mode> [-T <step>]... The ``<mode>`` must be one of the above `Dashboard Client Modes`_, and each ``<step>`` must be one of the above `Dashboard Client Steps`_. @@ -1027,9 +1141,9 @@ Configuration settings include: ``DefaultCTestConfigurationType`` When the build system to be launched allows build-time selection of the configuration (e.g. ``Debug``, ``Release``), this specifies - the default configuration to be built when no ``-C`` option is - given to the ``ctest`` command. The value will be substituted into - the value of ``MakeCommand`` to replace the literal string + the default configuration to be built when no :option:`-C <ctest -C>` + option is given to the ``ctest`` command. The value will be substituted + into the value of ``MakeCommand`` to replace the literal string ``${CTEST_CONFIGURATION_TYPE}`` if it appears. * `CTest Script`_ variable: :variable:`CTEST_CONFIGURATION_TYPE` @@ -1101,8 +1215,9 @@ Configuration settings include: See `Label and Subproject Summary`_. ``TestLoad`` - While running tests in parallel (e.g. with ``-j``), try not to start - tests when they may cause the CPU load to pass above a given threshold. + While running tests in parallel (e.g. with :option:`-j <ctest -j>`), + try not to start tests when they may cause the CPU load to pass above + a given threshold. * `CTest Script`_ variable: :variable:`CTEST_TEST_LOAD` * :module:`CTest` module variable: ``CTEST_TEST_LOAD`` @@ -1382,6 +1497,8 @@ Configuration settings include: Show as JSON Object Model ========================= +.. versionadded:: 3.14 + When the ``--show-only=json-v1`` command line option is given, the test information is output in JSON format. Version 1.0 of the JSON object model is defined as follows: @@ -1518,12 +1635,12 @@ Resource Specification File --------------------------- The resource specification file is a JSON file which is passed to CTest, either -on the :manual:`ctest(1)` command line as ``--resource-spec-file``, or as the +on the command line as :option:`ctest --resource-spec-file`, or as the ``RESOURCE_SPEC_FILE`` argument of :command:`ctest_test`. If a dashboard script is used and ``RESOURCE_SPEC_FILE`` is not specified, the value of :variable:`CTEST_RESOURCE_SPEC_FILE` in the dashboard script is used instead. -If ``--resource-spec-file``, ``RESOURCE_SPEC_FILE``, and -:variable:`CTEST_RESOURCE_SPEC_FILE` in the dashboard script are not specified, +If :option:`--resource-spec-file <ctest --resource-spec-file>`, ``RESOURCE_SPEC_FILE``, +and :variable:`CTEST_RESOURCE_SPEC_FILE` in the dashboard script are not specified, the value of :variable:`CTEST_RESOURCE_SPEC_FILE` in the CMake build is used instead. If none of these are specified, no resource spec file is used. diff --git a/Help/manual/presets/example.json b/Help/manual/presets/example.json index be5c791..696ab47 100644 --- a/Help/manual/presets/example.json +++ b/Help/manual/presets/example.json @@ -1,5 +1,5 @@ { - "version": 5, + "version": 6, "cmakeMinimumRequired": { "major": 3, "minor": 23, @@ -66,6 +66,38 @@ "execution": {"noTestsAction": "error", "stopOnFailure": true} } ], + "packagePresets": [ + { + "name": "default", + "configurePreset": "default", + "generators": [ + "TGZ" + ] + } + ], + "workflowPresets": [ + { + "name": "default", + "steps": [ + { + "type": "configure", + "name": "default" + }, + { + "type": "build", + "name": "default" + }, + { + "type": "test", + "name": "default" + }, + { + "type": "package", + "name": "default" + } + ] + } + ], "vendor": { "example.com/ExampleIDE/1.0": { "autoFormat": false diff --git a/Help/manual/presets/schema.json b/Help/manual/presets/schema.json index c96405c..348116b 100644 --- a/Help/manual/presets/schema.json +++ b/Help/manual/presets/schema.json @@ -72,6 +72,23 @@ "include": { "$ref": "#/definitions/include"} }, "additionalProperties": false + }, + { + "properties": { + "version": { + "const": 6, + "description": "A required integer representing the version of the JSON schema." + }, + "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, + "vendor": { "$ref": "#/definitions/vendor" }, + "configurePresets": { "$ref": "#/definitions/configurePresetsV3"}, + "buildPresets": { "$ref": "#/definitions/buildPresetsV4"}, + "testPresets": { "$ref": "#/definitions/testPresetsV6"}, + "packagePresets": { "$ref": "#/definitions/packagePresetsV6"}, + "workflowPresets": { "$ref": "#/definitions/workflowPresetsV6" }, + "include": { "$ref": "#/definitions/include"} + }, + "additionalProperties": false } ], "required": [ @@ -476,12 +493,12 @@ "properties": { "name": { "type": "string", - "description": "A required string representing the machine-friendly name of the preset. This identifier is used in the --preset argument. There must not be two presets (configure, build, or test) in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", + "description": "A required string representing the machine-friendly name of the preset. This identifier is used in the --preset argument. There must not be two presets (configure, build, test, package, or workflow) in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", "minLength": 1 }, "hidden": { "type": "boolean", - "description": "An optional boolean specifying whether or not a preset should be hidden. If a preset is hidden, it cannot be used in the --preset argument, will not show up in the CMake GUI, and does not have to have a valid configurePreset, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." + "description": "An optional boolean specifying whether or not a preset should be hidden. If a preset is hidden, it cannot be used in the --preset argument and does not have to have a valid configurePreset, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." }, "inherits": { "anyOf": [ @@ -688,6 +705,25 @@ "additionalProperties": false } }, + "testPresetsItemsV6": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 6 and higher.", + "items": { + "type": "object", + "properties": { + "output": { + "type": "object", + "description": "An optional object specifying output options.", + "properties": { + "outputJUnitFile": { + "type": "string", + "description": "An optional string specifying a path to a JUnit file. Equivalent to passing --output-junit on the command line." + } + } + } + } + } + }, "testPresetsItemsV5": { "type": "array", "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 5 and higher.", @@ -728,12 +764,12 @@ "properties": { "name": { "type": "string", - "description": "A required string representing the machine-friendly name of the preset. This identifier is used in the --preset argument. There must not be two presets (configure, build, or test) in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", + "description": "A required string representing the machine-friendly name of the preset. This identifier is used in the --preset argument. There must not be two presets (configure, build, test, package, or workflow) in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", "minLength": 1 }, "hidden": { "type": "boolean", - "description": "An optional boolean specifying whether or not a preset should be hidden. If a preset is hidden, it cannot be used in the --preset argument, will not show up in the CMake GUI, and does not have to have a valid configurePreset, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." + "description": "An optional boolean specifying whether or not a preset should be hidden. If a preset is hidden, it cannot be used in the --preset argument and does not have to have a valid configurePreset, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." }, "inherits": { "anyOf": [ @@ -1034,6 +1070,58 @@ ] } }, + "testPresetsV6": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 6 and higher.", + "allOf": [ + { "$ref": "#/definitions/testPresetsItemsV2" }, + { "$ref": "#/definitions/testPresetsItemsV3" }, + { "$ref": "#/definitions/testPresetsItemsV5" }, + { "$ref": "#/definitions/testPresetsItemsV6" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "configuration": {}, + "overwriteConfigurationFile": {}, + "output": { + "type": "object", + "properties": { + "shortProgress": {}, + "verbosity": {}, + "debug": {}, + "outputOnFailure": {}, + "quiet": {}, + "outputLogFile": {}, + "outputJUnitFile": {}, + "labelSummary": {}, + "subprojectSummary": {}, + "maxPassedTestOutputSize": {}, + "maxFailedTestOutputSize": {}, + "maxTestNameWidth": {}, + "testOutputTruncation": {} + }, + "additionalProperties": false + }, + "filter": {}, + "execution": {}, + "condition": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, "testPresetsV5": { "type": "array", "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 5 and higher.", @@ -1056,7 +1144,24 @@ "environment": {}, "configuration": {}, "overwriteConfigurationFile": {}, - "output": {}, + "output": { + "type": "object", + "properties": { + "shortProgress": {}, + "verbosity": {}, + "debug": {}, + "outputOnFailure": {}, + "quiet": {}, + "outputLogFile": {}, + "labelSummary": {}, + "subprojectSummary": {}, + "maxPassedTestOutputSize": {}, + "maxFailedTestOutputSize": {}, + "maxTestNameWidth": {}, + "testOutputTruncation": {} + }, + "additionalProperties": false + }, "filter": {}, "execution": {}, "condition": {} @@ -1088,7 +1193,23 @@ "environment": {}, "configuration": {}, "overwriteConfigurationFile": {}, - "output": {}, + "output": { + "type": "object", + "properties": { + "shortProgress": {}, + "verbosity": {}, + "debug": {}, + "outputOnFailure": {}, + "quiet": {}, + "outputLogFile": {}, + "labelSummary": {}, + "subprojectSummary": {}, + "maxPassedTestOutputSize": {}, + "maxFailedTestOutputSize": {}, + "maxTestNameWidth": {} + }, + "additionalProperties": false + }, "filter": {}, "execution": {}, "condition": {} @@ -1119,7 +1240,23 @@ "environment": {}, "configuration": {}, "overwriteConfigurationFile": {}, - "output": {}, + "output": { + "type": "object", + "properties": { + "shortProgress": {}, + "verbosity": {}, + "debug": {}, + "outputOnFailure": {}, + "quiet": {}, + "outputLogFile": {}, + "labelSummary": {}, + "subprojectSummary": {}, + "maxPassedTestOutputSize": {}, + "maxFailedTestOutputSize": {}, + "maxTestNameWidth": {} + }, + "additionalProperties": false + }, "filter": {}, "execution": {} }, @@ -1129,6 +1266,260 @@ "additionalProperties": false } }, + "packagePresetsItemsV6": { + "type": "array", + "description": "An optional array of package preset objects. Used to specify arguments to cpack. Available in version 6 and higher.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "A required string representing the machine-friendly name of the preset. This identifier is used in the --preset argument. There must not be two presets (configure, build, test, package, or workflow) in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", + "minLength": 1 + }, + "hidden": { + "type": "boolean", + "description": "An optional boolean specifying whether or not a preset should be hidden. If a preset is hidden, it cannot be used in the --preset argument and does not have to have a valid configurePreset, even from inheritance. Hidden presets are intended to be used as a base for other presets to inherit via the inherits field." + }, + "inherits": { + "anyOf": [ + { + "type": "string", + "description": "An optional string representing the name of the package preset to inherit from.", + "minLength": 1 + }, + { + "type": "array", + "description": "An optional array of strings representing the names of package presets to inherit from. The preset will inherit all of the fields from the inherits presets by default (except name, hidden, inherits, description, and displayName), but can override them as desired. If multiple inherits presets provide conflicting values for the same field, the earlier preset in the inherits list will be preferred. Presets in CMakePresets.json must not inherit from presets in CMakeUserPresets.json.", + "items": { + "type": "string", + "description": "An optional string representing the name of the preset to inherit from.", + "minLength": 1 + } + } + ] + }, + "configurePreset": { + "type": "string", + "description": "An optional string specifying the name of a configure preset to associate with this package preset. If configurePreset is not specified, it must be inherited from the inherits preset (unless this preset is hidden). The build tree directory is inferred from the configure preset.", + "minLength": 1 + }, + "vendor": { + "type": "object", + "description": "An optional map containing vendor-specific information. CMake does not interpret the contents of this field except to verify that it is a map if it does exist. However, it should follow the same conventions as the root-level vendor field. If vendors use their own per-preset vendor field, they should implement inheritance in a sensible manner when appropriate.", + "properties": {} + }, + "displayName": { + "type": "string", + "description": "An optional string with a human-friendly name of the preset." + }, + "description": { + "type": "string", + "description": "An optional string with a human-friendly description of the preset." + }, + "inheritConfigureEnvironment": { + "type": "boolean", + "description": "An optional boolean that defaults to true. If true, the environment variables from the associated configure preset are inherited after all inherited package preset environments, but before environment variables explicitly specified in this package preset." + }, + "environment": { + "type": "object", + "description": "An optional map of environment variables. The key is the variable name (which must not be an empty string). Each variable is set regardless of whether or not a value was given to it by the process's environment. This field supports macro expansion, and environment variables in this map may reference each other, and may be listed in any order, as long as such references do not cause a cycle (for example,if ENV_1 is $env{ENV_2}, ENV_2 may not be $env{ENV_1}.) Environment variables are inherited through the inherits field, and the preset's environment will be the union of its own environment and the environment from all its parents. If multiple presets in this union define the same variable, the standard rules of inherits are applied. Setting a variable to null causes it to not be set, even if a value was inherited from another preset.", + "properties": {}, + "additionalProperties": { + "anyOf": [ + { + "type": "null", + "description": "Setting a variable to null causes it to not be set, even if a value was inherited from another preset." + }, + { + "type": "string", + "description": "A string representing the value of the variable." + } + ] + }, + "propertyNames": { + "pattern": "^.+$" + } + }, + "condition": { "$ref": "#/definitions/topCondition" }, + "generators": { + "type": "array", + "description": "An optional list of strings representing generators for CPack to use.", + "items": { + "type": "string", + "description": "An optional string representing the name of the CPack generator to use." + } + }, + "configurations": { + "type": "array", + "description": "An optional list of strings representing build configurations for CPack to package.", + "items": { + "type": "string", + "description": "An optional string representing the name of the configuration to use." + } + }, + "variables": { + "type": "object", + "description": "An optional map of variables to pass to CPack, equivalent to -D arguments. Each key is the name of a variable, and the value is the string to assign to that variable.", + "items": { + "type": "string", + "description": "An optional string representing the value of the variable." + } + }, + "configFile": { + "type": "string", + "description": "An optional string representing the config file for CPack to use." + }, + "output": { + "type": "object", + "description": "An optional object specifying output options.", + "properties": { + "debug": { + "type": "boolean", + "description": "An optional boolean specifying whether or not to print debug information. A value of true is equivalent to passing --debug on the command line." + }, + "verbose": { + "type": "boolean", + "description": "An optional boolean specifying whether or not to print verbosely. A value of true is equivalent to passing --verbose on the command line." + } + }, + "additionalProperties": false + }, + "packageName": { + "type": "string", + "description": "An optional string representing the package name." + }, + "packageVersion": { + "type": "string", + "description": "An optional string representing the package version." + }, + "packageDirectory": { + "type": "string", + "description": "An optional string representing the directory in which to place the package." + }, + "vendorName": { + "type": "string", + "description": "An optional string representing the vendor name." + } + }, + "required": [ + "name" + ] + } + }, + "packagePresetsV6": { + "type": "array", + "description": "An optional array of package preset objects. Used to specify arguments to cpack. Available in version 6 and higher.", + "allOf": [ + { "$ref": "#/definitions/packagePresetsItemsV6" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "condition": {}, + "generators": {}, + "configurations": {}, + "variables": {}, + "configFile": {}, + "output": {}, + "packageName": {}, + "packageVersion": {}, + "packageDirectory": {}, + "vendorName": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, + "workflowPresetsItemsV6": { + "type": "array", + "description": "An optional array of workflow preset objects. Used to execute configure, build, test, and package presets in order. Available in version 6 and higher.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "A required string representing the machine-friendly name of the preset. This identifier is used in the --preset argument. There must not be two presets (configure, build, test, package, or workflow) in the union of CMakePresets.json and CMakeUserPresets.json in the same directory with the same name.", + "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.", + "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." + }, + "steps": { + "type": "array", + "description": "A required array of objects describing the steps of the workflow. The first step must be a configure preset, and all subsequent steps must be non-configure presets whose configurePreset field matches the starting configure preset.", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string. The first step must be configure. Subsequent steps must be either build, test, or package.", + "enum": ["configure", "build", "test", "package"] + }, + "name": { + "type": "string", + "description": "A required string representing the name of the configure, build, test, or package preset to run as this workflow step.", + "minLength": 1 + } + }, + "required": [ + "type", + "name" + ], + "additionalProperties": false + } + } + }, + "required": [ + "name", + "steps" + ], + "additionalProperties": false + } + }, + "workflowPresetsV6": { + "type": "array", + "description": "An optional array of workflow preset objects. Used to execute configure, build, test, and package presets in order. Available in version 6 and higher.", + "allOf": [ + { "$ref": "#/definitions/workflowPresetsItemsV6" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "steps": {} + }, + "required": [ + "name", + "steps" + ], + "additionalProperties": false + } + }, "condition": { "anyOf": [ { |