diff options
Diffstat (limited to 'Help/manual')
| -rw-r--r-- | Help/manual/OPTIONS_BUILD.txt | 8 | ||||
| -rw-r--r-- | Help/manual/cmake-buildsystem.7.rst | 157 | ||||
| -rw-r--r-- | Help/manual/cmake-compile-features.7.rst | 16 | ||||
| -rw-r--r-- | Help/manual/cmake-developer.7.rst | 18 | ||||
| -rw-r--r-- | Help/manual/cmake-env-variables.7.rst | 7 | ||||
| -rw-r--r-- | Help/manual/cmake-file-api.7.rst | 333 | ||||
| -rw-r--r-- | Help/manual/cmake-generator-expressions.7.rst | 181 | ||||
| -rw-r--r-- | Help/manual/cmake-generators.7.rst | 3 | ||||
| -rw-r--r-- | Help/manual/cmake-language.7.rst | 42 | ||||
| -rw-r--r-- | Help/manual/cmake-modules.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-packages.7.rst | 8 | ||||
| -rw-r--r-- | Help/manual/cmake-policies.7.rst | 31 | ||||
| -rw-r--r-- | Help/manual/cmake-presets.7.rst | 301 | ||||
| -rw-r--r-- | Help/manual/cmake-properties.7.rst | 24 | ||||
| -rw-r--r-- | Help/manual/cmake-toolchains.7.rst | 4 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 38 | ||||
| -rw-r--r-- | Help/manual/cmake.1.rst | 202 | ||||
| -rw-r--r-- | Help/manual/ctest.1.rst | 88 | ||||
| -rw-r--r-- | Help/manual/presets/example.json | 19 | ||||
| -rw-r--r-- | Help/manual/presets/schema.json | 582 |
20 files changed, 1902 insertions, 161 deletions
diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt index 0947e41..8e23b77 100644 --- a/Help/manual/OPTIONS_BUILD.txt +++ b/Help/manual/OPTIONS_BUILD.txt @@ -76,6 +76,14 @@ native build system to choose a compiler or SDK. See the :variable:`CMAKE_GENERATOR_PLATFORM` variable for details. +``--toolchain <path-to-file>`` + Specify the cross compiling toolchain file, equivalent to setting + :variable:`CMAKE_TOOLCHAIN_FILE` variable. + +``--install-prefix <directory>`` + Specify the installation directory, used by the + :variable:`CMAKE_INSTALL_PREFIX` variable. Must be an absolute path. + ``-Wno-dev`` Suppress developer warnings. diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 7008383..f48313a 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -21,9 +21,9 @@ Binary Targets Executables and libraries are defined using the :command:`add_executable` and :command:`add_library` commands. The resulting binary files have -appropriate :prop_tgt:`PREFIX`, :prop_tgt:`SUFFIX` and extensions for the platform targeted. -Dependencies between binary targets are expressed using the -:command:`target_link_libraries` command: +appropriate :prop_tgt:`PREFIX`, :prop_tgt:`SUFFIX` and extensions for the +platform targeted. Dependencies between binary targets are expressed using +the :command:`target_link_libraries` command: .. code-block:: cmake @@ -530,38 +530,6 @@ the calculated "compatible" value of a property may be read with the In this case, the ``exe1`` source files will be compiled with ``-DCONTAINER_SIZE=200``. -Configuration determined build specifications may be conveniently set using -the ``CONFIG`` generator expression. - -.. code-block:: cmake - - target_compile_definitions(exe1 PRIVATE - $<$<CONFIG:Debug>:DEBUG_BUILD> - ) - -The ``CONFIG`` parameter is compared case-insensitively with the configuration -being built. In the presence of :prop_tgt:`IMPORTED` targets, the content of -:prop_tgt:`MAP_IMPORTED_CONFIG_DEBUG <MAP_IMPORTED_CONFIG_<CONFIG>>` is also -accounted for by this expression. - -Some buildsystems generated by :manual:`cmake(1)` have a predetermined -build-configuration set in the :variable:`CMAKE_BUILD_TYPE` variable. The -buildsystem for the IDEs such as Visual Studio and Xcode are generated -independent of the build-configuration, and the actual build configuration -is not known until build-time. Therefore, code such as - -.. code-block:: cmake - - string(TOLOWER ${CMAKE_BUILD_TYPE} _type) - if (_type STREQUAL debug) - target_compile_definitions(exe1 PRIVATE DEBUG_BUILD) - endif() - -may appear to work for :ref:`Makefile Generators` and :generator:`Ninja` -generators, but is not portable to IDE generators. Additionally, -the :prop_tgt:`IMPORTED` configuration-mappings are not accounted for -with code like this, so it should be avoided. - The unary ``TARGET_PROPERTY`` generator expression and the ``TARGET_POLICY`` generator expression are evaluated with the consuming target context. This means that a usage requirement specification may be evaluated differently based @@ -707,7 +675,9 @@ listed in the :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` of the dependency. This can result in omission of compiler warnings for headers found in those directories. This behavior for :ref:`imported targets` may be controlled by setting the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target -property on the *consumers* of imported targets. +property on the *consumers* of imported targets, or by setting the +:prop_tgt:`IMPORTED_NO_SYSTEM` target property on the imported targets +themselves. If a binary target is linked transitively to a macOS :prop_tgt:`FRAMEWORK`, the ``Headers`` directory of the framework is also treated as a usage requirement. @@ -840,6 +810,121 @@ target at a time. The commands :command:`add_compile_definitions`, a similar function, but operate at directory scope instead of target scope for convenience. +.. _`Build Configurations`: + +Build Configurations +==================== + +Configurations determine specifications for a certain type of build, such +as ``Release`` or ``Debug``. The way this is specified depends on the type +of :manual:`generator <cmake-generators(7)>` being used. For single +configuration generators like :ref:`Makefile Generators` and +:generator:`Ninja`, the configuration is specified at configure time by the +:variable:`CMAKE_BUILD_TYPE` variable. For multi-configuration generators +like :ref:`Visual Studio <Visual Studio Generators>`, :generator:`Xcode`, and +:generator:`Ninja Multi-Config`, the configuration is chosen by the user at +build time and :variable:`CMAKE_BUILD_TYPE` is ignored. In the +multi-configuration case, the set of *available* configurations is specified +at configure time by the :variable:`CMAKE_CONFIGURATION_TYPES` variable, +but the actual configuration used cannot be known until the build stage. +This difference is often misunderstood, leading to problematic code like the +following: + +.. code-block:: cmake + + # WARNING: This is wrong for multi-config generators because they don't use + # and typically don't even set CMAKE_BUILD_TYPE + string(TOLOWER ${CMAKE_BUILD_TYPE} build_type) + if (build_type STREQUAL debug) + target_compile_definitions(exe1 PRIVATE DEBUG_BUILD) + endif() + +:manual:`Generator expressions <cmake-generator-expressions(7)>` should be +used instead to handle configuration-specific logic correctly, regardless of +the generator used. For example: + +.. code-block:: cmake + + # Works correctly for both single and multi-config generators + target_compile_definitions(exe1 PRIVATE + $<$<CONFIG:Debug>:DEBUG_BUILD> + ) + +In the presence of :prop_tgt:`IMPORTED` targets, the content of +:prop_tgt:`MAP_IMPORTED_CONFIG_DEBUG <MAP_IMPORTED_CONFIG_<CONFIG>>` is also +accounted for by the above ``$<CONFIG:Debug>`` expression. + + +Case Sensitivity +---------------- + +:variable:`CMAKE_BUILD_TYPE` and :variable:`CMAKE_CONFIGURATION_TYPES` are +just like other variables in that any string comparisons made with their +values will be case-sensitive. The ``$<CONFIG>`` generator expression also +preserves the casing of the configuration as set by the user or CMake defaults. +For example: + +.. code-block:: cmake + + # NOTE: Don't use these patterns, they are for illustration purposes only. + + set(CMAKE_BUILD_TYPE Debug) + if(CMAKE_BUILD_TYPE STREQUAL DEBUG) + # ... will never get here, "Debug" != "DEBUG" + endif() + add_custom_target(print_config ALL + # Prints "Config is Debug" in this single-config case + COMMAND ${CMAKE_COMMAND} -E echo "Config is $<CONFIG>" + VERBATIM + ) + + set(CMAKE_CONFIGURATION_TYPES Debug Release) + if(DEBUG IN_LIST CMAKE_CONFIGURATION_TYPES) + # ... will never get here, "Debug" != "DEBUG" + endif() + +In contrast, CMake treats the configuration type case-insensitively when +using it internally in places that modify behavior based on the configuration. +For example, the ``$<CONFIG:Debug>`` generator expression will evaluate to 1 +for a configuration of not only ``Debug``, but also ``DEBUG``, ``debug`` or +even ``DeBuG``. Therefore, you can specify configuration types in +:variable:`CMAKE_BUILD_TYPE` and :variable:`CMAKE_CONFIGURATION_TYPES` with +any mixture of upper and lowercase, although there are strong conventions +(see the next section). If you must test the value in string comparisons, +always convert the value to upper or lowercase first and adjust the test +accordingly. + +Default And Custom Configurations +--------------------------------- + +By default, CMake defines a number of standard configurations: + +* ``Debug`` +* ``Release`` +* ``RelWithDebInfo`` +* ``MinSizeRel`` + +In multi-config generators, the :variable:`CMAKE_CONFIGURATION_TYPES` variable +will be populated with (potentially a subset of) the above list by default, +unless overridden by the project or user. The actual configuration used is +selected by the user at build time. + +For single-config generators, the configuration is specified with the +:variable:`CMAKE_BUILD_TYPE` variable at configure time and cannot be changed +at build time. The default value will often be none of the above standard +configurations and will instead be an empty string. A common misunderstanding +is that this is the same as ``Debug``, but that is not the case. Users should +always explicitly specify the build type instead to avoid this common problem. + +The above standard configuration types provide reasonable behavior on most +platforms, but they can be extended to provide other types. Each configuration +defines a set of compiler and linker flag variables for the language in use. +These variables follow the convention :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`, +where ``<CONFIG>`` is always the uppercase configuration name. When defining +a custom configuration type, make sure these variables are set appropriately, +typically as cache variables. + + Pseudo Targets ============== diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index 2c2b04c..8073511 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -115,16 +115,17 @@ of at-least C++ 11 (or C++ 14, C++ 17, ...), adding flags such as ``-std=gnu++11`` if necessary. This applies to sources within ``mylib`` as well as any dependents (that may include headers from ``mylib``). +.. include:: ../prop_gbl/CMAKE_LANG_STD_FLAGS.txt + Availability of Compiler Extensions ----------------------------------- -Because the :prop_tgt:`CXX_EXTENSIONS` target property is ``ON`` by default, -CMake uses extended variants of language dialects by default, such as -``-std=gnu++11`` instead of ``-std=c++11``. That target property may be -set to ``OFF`` to use the non-extended variant of the dialect flag. Note -that because most compilers enable extensions by default, this could -expose cross-platform bugs in user code or in the headers of third-party -dependencies. +The :prop_tgt:`<LANG>_EXTENSIONS` target property defaults to the compiler's +default (see :variable:`CMAKE_<LANG>_EXTENSIONS_DEFAULT`). Note that because +most compilers enable extensions by default, this may expose portability bugs +in user code or in the headers of third-party dependencies. + +:prop_tgt:`<LANG>_EXTENSIONS` used to default to ``ON``. See :policy:`CMP0128`. Optional Compile Features ========================= @@ -261,6 +262,7 @@ following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: * ``Cray``: Cray Compiler Environment version 8.1+. +* ``Fujitsu``: Fujitsu HPC compiler 4.0+. * ``PGI``: PGI version 12.10+. * ``NVHPC``: NVIDIA HPC compilers version 11.0+. * ``TI``: Texas Instruments compiler. diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index af9a8ab..fe146de 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -350,6 +350,24 @@ look. PATHS ${PC_Foo_LIBRARY_DIRS} ) +Alternatively, if the library is available with multiple configurations, you can +use :module:`SelectLibraryConfigurations` to automatically set the +``Foo_LIBRARY`` variable instead: + +.. code-block:: cmake + + find_library(Foo_LIBRARY_RELEASE + NAMES foo + PATHS ${PC_Foo_LIBRARY_DIRS}/Release + ) + find_library(Foo_LIBRARY_DEBUG + NAMES foo + PATHS ${PC_Foo_LIBRARY_DIRS}/Debug + ) + + include(SelectLibraryConfigurations) + select_library_configurations(Foo) + If you have a good way of getting the version (from a header file, for example), you can use that information to set ``Foo_VERSION`` (although note that find modules have traditionally used ``Foo_VERSION_STRING``, diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index bc1fa1d..0799fdd 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -30,16 +30,21 @@ Environment Variables that Control the Build /envvar/CMAKE_APPLE_SILICON_PROCESSOR /envvar/CMAKE_BUILD_PARALLEL_LEVEL + /envvar/CMAKE_BUILD_TYPE + /envvar/CMAKE_CONFIGURATION_TYPES /envvar/CMAKE_CONFIG_TYPE /envvar/CMAKE_EXPORT_COMPILE_COMMANDS /envvar/CMAKE_GENERATOR /envvar/CMAKE_GENERATOR_INSTANCE /envvar/CMAKE_GENERATOR_PLATFORM /envvar/CMAKE_GENERATOR_TOOLSET + /envvar/CMAKE_INSTALL_MODE /envvar/CMAKE_LANG_COMPILER_LAUNCHER + /envvar/CMAKE_LANG_LINKER_LAUNCHER /envvar/CMAKE_MSVCIDE_RUN_PATH /envvar/CMAKE_NO_VERBOSE /envvar/CMAKE_OSX_ARCHITECTURES + /envvar/CMAKE_TOOLCHAIN_FILE /envvar/DESTDIR /envvar/LDFLAGS /envvar/MACOSX_DEPLOYMENT_TARGET @@ -65,6 +70,8 @@ Environment Variables for Languages /envvar/CXXFLAGS /envvar/FC /envvar/FFLAGS + /envvar/HIPCXX + /envvar/HIPFLAGS /envvar/ISPC /envvar/ISPCFLAGS /envvar/OBJC diff --git a/Help/manual/cmake-file-api.7.rst b/Help/manual/cmake-file-api.7.rst index 89739b7..4b8ac65 100644 --- a/Help/manual/cmake-file-api.7.rst +++ b/Help/manual/cmake-file-api.7.rst @@ -425,7 +425,7 @@ Version 1 does not exist to avoid confusion with that from { "kind": "codemodel", - "version": { "major": 2, "minor": 2 }, + "version": { "major": 2, "minor": 4 }, "paths": { "source": "/path/to/top-level-source-dir", "build": "/path/to/top-level-build-dir" @@ -443,7 +443,8 @@ Version 1 does not exist to avoid confusion with that from "hasInstallRule": true, "minimumCMakeVersion": { "string": "3.14" - } + }, + "jsonFile": "<file>" }, { "source": "sub", @@ -453,7 +454,8 @@ Version 1 does not exist to avoid confusion with that from "targetIndexes": [ 1 ], "minimumCMakeVersion": { "string": "3.14" - } + }, + "jsonFile": "<file>" } ], "projects": [ @@ -569,6 +571,13 @@ The members specific to ``codemodel`` objects are: :command:`install` rules, i.e. whether a ``make install`` or equivalent rule is available. + ``jsonFile`` + A JSON string specifying a path relative to the codemodel file + to another JSON file containing a + `"codemodel" version 2 "directory" object`_. + + This field was added in codemodel version 2.3. + ``projects`` A JSON array of entries corresponding to the top-level project and sub-projects defined in the build system. Each (sub-)project @@ -633,6 +642,260 @@ The members specific to ``codemodel`` objects are: to another JSON file containing a `"codemodel" version 2 "target" object`_. +"codemodel" version 2 "directory" object +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A codemodel "directory" object is referenced by a `"codemodel" version 2`_ +object's ``directories`` array. Each "directory" object is a JSON object +with members: + +``paths`` + A JSON object containing members: + + ``source`` + A string specifying the path to the source directory, represented + with forward slashes. If the directory is inside the top-level + source directory then the path is specified relative to that + directory (with ``.`` for the top-level source directory itself). + Otherwise the path is absolute. + + ``build`` + A string specifying the path to the build directory, represented + with forward slashes. If the directory is inside the top-level + build directory then the path is specified relative to that + directory (with ``.`` for the top-level build directory itself). + Otherwise the path is absolute. + +``installers`` + A JSON array of entries corresponding to :command:`install` rules. + Each entry is a JSON object containing members: + + ``component`` + A string specifying the component selected by the corresponding + :command:`install` command invocation. + + ``destination`` + Optional member that is present for specific ``type`` values below. + The value is a string specifying the install destination path. + The path may be absolute or relative to the install prefix. + + ``paths`` + Optional member that is present for specific ``type`` values below. + The value is a JSON array of entries corresponding to the paths + (files or directories) to be installed. Each entry is one of: + + * A string specifying the path from which a file or directory + is to be installed. The portion of the path not preceded by + a ``/`` also specifies the path (name) to which the file + or directory is to be installed under the destination. + + * A JSON object with members: + + ``from`` + A string specifying the path from which a file or directory + is to be installed. + + ``to`` + A string specifying the path to which the file or directory + is to be installed under the destination. + + In both cases the paths are represented with forward slashes. If + the "from" path is inside the top-level directory documented by the + corresponding ``type`` value, then the path is specified relative + to that directory. Otherwise the path is absolute. + + ``type`` + A string specifying the type of installation rule. The value is one + of the following, with some variants providing additional members: + + ``file`` + An :command:`install(FILES)` or :command:`install(PROGRAMS)` call. + The ``destination`` and ``paths`` members are populated, with paths + under the top-level *source* directory expressed relative to it. + The ``isOptional`` member may exist. + This type has no additional members. + + ``directory`` + An :command:`install(DIRECTORY)` call. + The ``destination`` and ``paths`` members are populated, with paths + under the top-level *source* directory expressed relative to it. + The ``isOptional`` member may exist. + This type has no additional members. + + ``target`` + An :command:`install(TARGETS)` call. + The ``destination`` and ``paths`` members are populated, with paths + under the top-level *build* directory expressed relative to it. + The ``isOptional`` member may exist. + This type has additional members ``targetId``, ``targetIndex``, + ``targetIsImportLibrary``, and ``targetInstallNamelink``. + + ``export`` + An :command:`install(EXPORT)` call. + The ``destination`` and ``paths`` members are populated, with paths + under the top-level *build* directory expressed relative to it. + The ``paths`` entries refer to files generated automatically by + CMake for installation, and their actual values are considered + private implementation details. + This type has additional members ``exportName`` and ``exportTargets``. + + ``script`` + An :command:`install(SCRIPT)` call. + This type has additional member ``scriptFile``. + + ``code`` + An :command:`install(CODE)` call. + This type has no additional members. + + ``importedRuntimeArtifacts`` + An :command:`install(IMPORTED_RUNTIME_ARTIFACTS)` call. + The ``destination`` member is populated. The ``isOptional`` member may + exist. This type has no additional members. + + ``runtimeDependencySet`` + An :command:`install(RUNTIME_DEPENDENCY_SET)` call or an + :command:`install(TARGETS)` call with ``RUNTIME_DEPENDENCIES``. The + ``destination`` member is populated. This type has additional members + ``runtimeDependencySetName`` and ``runtimeDependencySetType``. + + ``fileSet`` + An :command:`install(TARGETS)` call with ``FILE_SET``. + The ``destination`` and ``paths`` members are populated. + The ``isOptional`` member may exist. + This type has additional members ``fileSetName``, ``fileSetType``, + ``fileSetDirectories``, and ``fileSetTarget``. + + This type was added in codemodel version 2.4. + + ``isExcludeFromAll`` + Optional member that is present with boolean value ``true`` when + :command:`install` is called with the ``EXCLUDE_FROM_ALL`` option. + + ``isForAllComponents`` + Optional member that is present with boolean value ``true`` when + :command:`install(SCRIPT|CODE)` is called with the + ``ALL_COMPONENTS`` option. + + ``isOptional`` + Optional member that is present with boolean value ``true`` when + :command:`install` is called with the ``OPTIONAL`` option. + This is allowed when ``type`` is ``file``, ``directory``, or ``target``. + + ``targetId`` + Optional member that is present when ``type`` is ``target``. + The value is a string uniquely identifying the target to be installed. + This matches the ``id`` member of the target in the main + "codemodel" object's ``targets`` array. + + ``targetIndex`` + Optional member that is present when ``type`` is ``target``. + The value is an unsigned integer 0-based index into the main "codemodel" + object's ``targets`` array for the target to be installed. + + ``targetIsImportLibrary`` + Optional member that is present when ``type`` is ``target`` and + the installer is for a Windows DLL import library file or for an + AIX linker import file. If present, it has boolean value ``true``. + + ``targetInstallNamelink`` + Optional member that is present when ``type`` is ``target`` and + the installer corresponds to a target that may use symbolic links + to implement the :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` + target properties. + The value is a string indicating how the installer is supposed to + handle the symlinks: ``skip`` means the installer should skip the + symlinks and install only the real file, and ``only`` means the + installer should install only the symlinks and not the real file. + In all cases the ``paths`` member lists what it actually installs. + + ``exportName`` + Optional member that is present when ``type`` is ``export``. + The value is a string specifying the name of the export. + + ``exportTargets`` + Optional member that is present when ``type`` is ``export``. + The value is a JSON array of entries corresponding to the targets + included in the export. Each entry is a JSON object with members: + + ``id`` + A string uniquely identifying the target. This matches + the ``id`` member of the target in the main "codemodel" + object's ``targets`` array. + + ``index`` + An unsigned integer 0-based index into the main "codemodel" + object's ``targets`` array for the target. + + ``runtimeDependencySetName`` + Optional member that is present when ``type`` is ``runtimeDependencySet`` + and the installer was created by an + :command:`install(RUNTIME_DEPENDENCY_SET)` call. The value is a string + specifying the name of the runtime dependency set that was installed. + + ``runtimeDependencySetType`` + Optional member that is present when ``type`` is ``runtimeDependencySet``. + The value is a string with one of the following values: + + ``library`` + Indicates that this installer installs dependencies that are not macOS + frameworks. + + ``framework`` + Indicates that this installer installs dependencies that are macOS + frameworks. + + ``fileSetName`` + Optional member that is present when ``type`` is ``fileSet``. The value is + a string with the name of the file set. + + This field was added in codemodel version 2.4. + + ``fileSetType`` + Optional member that is present when ``type`` is ``fileSet``. The value is + a string with the type of the file set. + + This field was added in codemodel version 2.4. + + ``fileSetDirectories`` + Optional member that is present when ``type`` is ``fileSet``. The value + is a list of strings with the file set's base directories (determined by + genex-evaluation of :prop_tgt:`HEADER_DIRS` or + :prop_tgt:`HEADER_DIRS_<NAME>`). + + This field was added in codemodel version 2.4. + + ``fileSetTarget`` + Optional member that is present when ``type`` is ``fileSet``. The value + is a JSON object with members: + + ``id`` + A string uniquely identifying the target. This matches + the ``id`` member of the target in the main "codemodel" + object's ``targets`` array. + + ``index`` + An unsigned integer 0-based index into the main "codemodel" + object's ``targets`` array for the target. + + This field was added in codemodel version 2.4. + + ``scriptFile`` + Optional member that is present when ``type`` is ``script``. + The value is a string specifying the path to the script file on disk, + represented with forward slashes. If the file is inside the top-level + source directory then the path is specified relative to that directory. + Otherwise the path is absolute. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to + the :command:`install` or other command invocation that added this + installer is available. The value is an unsigned integer 0-based + index into the ``backtraceGraph`` member's ``nodes`` array. + +``backtraceGraph`` + A `"codemodel" version 2 "backtrace graph"`_ whose nodes are referenced + from ``backtrace`` members elsewhere in this "directory" object. + "codemodel" version 2 "target" object ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -964,40 +1227,48 @@ with members: with forward slashes. ``backtraceGraph`` - A JSON object describing the graph of backtraces whose nodes are - referenced from ``backtrace`` members elsewhere. The members are: + A `"codemodel" version 2 "backtrace graph"`_ whose nodes are referenced + from ``backtrace`` members elsewhere in this "target" object. - ``nodes`` - A JSON array listing nodes in the backtrace graph. Each entry - is a JSON object with members: +"codemodel" version 2 "backtrace graph" +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - ``file`` - An unsigned integer 0-based index into the backtrace ``files`` array. +The ``backtraceGraph`` member of a `"codemodel" version 2 "directory" object`_, +or `"codemodel" version 2 "target" object`_ is a JSON object describing a +graph of backtraces. Its nodes are referenced from ``backtrace`` members +elsewhere in the containing object. The backtrace graph object members are: - ``line`` - An optional member present when the node represents a line within - the file. The value is an unsigned integer 1-based line number. +``nodes`` + A JSON array listing nodes in the backtrace graph. Each entry + is a JSON object with members: - ``command`` - An optional member present when the node represents a command - invocation within the file. The value is an unsigned integer - 0-based index into the backtrace ``commands`` array. + ``file`` + An unsigned integer 0-based index into the backtrace ``files`` array. - ``parent`` - An optional member present when the node is not the bottom of - the call stack. The value is an unsigned integer 0-based index - of another entry in the backtrace ``nodes`` array. + ``line`` + An optional member present when the node represents a line within + the file. The value is an unsigned integer 1-based line number. - ``commands`` - A JSON array listing command names referenced by backtrace nodes. - Each entry is a string specifying a command name. + ``command`` + An optional member present when the node represents a command + invocation within the file. The value is an unsigned integer + 0-based index into the backtrace ``commands`` array. - ``files`` - A JSON array listing CMake language files referenced by backtrace nodes. - Each entry is a string specifying the path to a file, represented - with forward slashes. If the file is inside the top-level source - directory then the path is specified relative to that directory. - Otherwise the path is absolute. + ``parent`` + An optional member present when the node is not the bottom of + the call stack. The value is an unsigned integer 0-based index + of another entry in the backtrace ``nodes`` array. + +``commands`` + A JSON array listing command names referenced by backtrace nodes. + Each entry is a string specifying a command name. + +``files`` + A JSON array listing CMake language files referenced by backtrace nodes. + Each entry is a string specifying the path to a file, represented + with forward slashes. If the file is inside the top-level source + directory then the path is specified relative to that directory. + Otherwise the path is absolute. Object Kind "cache" ------------------- @@ -1244,7 +1515,7 @@ The members specific to ``toolchains`` objects are: ``language`` A JSON string specifying the toolchain language, like C or CXX. Language - names are the same as langauge names that can be passed to the + names are the same as language names that can be passed to the :command:`project` command. Because CMake only supports a single toolchain per language, this field can be used as a key. diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 7bc490f..a6d2a05 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -94,6 +94,8 @@ String Comparisons .. genex:: $<IN_LIST:string,list> + .. versionadded:: 3.12 + ``1`` if ``string`` is member of the semicolon-separated ``list``, else ``0``. Uses case-sensitive comparisons. @@ -111,10 +113,14 @@ String Comparisons .. genex:: $<VERSION_LESS_EQUAL:v1,v2> + .. versionadded:: 3.7 + ``1`` if ``v1`` is a version less than or equal to ``v2``, else ``0``. .. genex:: $<VERSION_GREATER_EQUAL:v1,v2> + .. versionadded:: 3.7 + ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``. Variable Queries @@ -122,12 +128,14 @@ Variable Queries .. genex:: $<TARGET_EXISTS:target> + .. versionadded:: 3.12 + ``1`` if ``target`` exists, else ``0``. .. genex:: $<CONFIG:cfgs> - ``1`` if config is any one of the entries in ``cfgs``, else ``0``. This is a - case-insensitive comparison. The mapping in + ``1`` if config is any one of the entries in comma-separated list + ``cfgs``, else ``0``. This is a case-insensitive comparison. The mapping in :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by this expression when it is evaluated on a property on an :prop_tgt:`IMPORTED` target. @@ -155,6 +163,8 @@ Variable Queries .. genex:: $<CUDA_COMPILER_ID:compiler_ids> + .. versionadded:: 3.15 + where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the CUDA compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. @@ -162,6 +172,8 @@ Variable Queries .. genex:: $<OBJC_COMPILER_ID:compiler_ids> + .. versionadded:: 3.16 + where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the Objective-C compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. @@ -169,6 +181,8 @@ Variable Queries .. genex:: $<OBJCXX_COMPILER_ID:compiler_ids> + .. versionadded:: 3.16 + where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the Objective-C++ compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. @@ -181,8 +195,19 @@ Variable Queries of the entries in ``compiler_ids``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +.. genex:: $<HIP_COMPILER_ID:compiler_ids> + + .. versionadded:: 3.21 + + where ``compiler_ids`` is a comma-separated list. + ``1`` if the CMake's compiler id of the HIP compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. + .. genex:: $<ISPC_COMPILER_ID:compiler_ids> + .. versionadded:: 3.19 + where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the ISPC compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. @@ -200,16 +225,22 @@ Variable Queries .. genex:: $<CUDA_COMPILER_VERSION:version> + .. versionadded:: 3.15 + ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<OBJC_COMPILER_VERSION:version> + .. versionadded:: 3.16 + ``1`` if the version of the OBJC compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<OBJCXX_COMPILER_VERSION:version> + .. versionadded:: 3.16 + ``1`` if the version of the OBJCXX compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. @@ -218,8 +249,17 @@ Variable Queries ``1`` if the version of the Fortran compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +.. genex:: $<HIP_COMPILER_VERSION:version> + + .. versionadded:: 3.21 + + ``1`` if the version of the HIP compiler matches ``version``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. + .. genex:: $<ISPC_COMPILER_VERSION:version> + .. versionadded:: 3.19 + ``1`` if the version of the ISPC compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. @@ -232,6 +272,8 @@ Variable Queries .. genex:: $<COMPILE_FEATURES:features> + .. versionadded:: 3.1 + where ``features`` is a comma-spearated list. Evaluates to ``1`` if all of the ``features`` are available for the 'head' target, and ``0`` otherwise. If this expression is used while evaluating @@ -245,6 +287,8 @@ Variable Queries .. genex:: $<COMPILE_LANG_AND_ID:language,compiler_ids> + .. versionadded:: 3.15 + ``1`` when the language used for compilation unit matches ``language`` and the 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 @@ -282,6 +326,8 @@ Variable Queries .. genex:: $<COMPILE_LANGUAGE:languages> + .. 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 @@ -328,6 +374,8 @@ Variable Queries .. genex:: $<LINK_LANG_AND_ID:language,compiler_ids> + .. 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 @@ -368,6 +416,8 @@ Variable Queries .. genex:: $<LINK_LANGUAGE:languages> + .. 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 @@ -431,6 +481,8 @@ Variable Queries .. genex:: $<DEVICE_LINK:list> + .. versionadded:: 3.18 + Returns the list if it is the device link step, an empty list otherwise. The device link step is controlled by :prop_tgt:`CUDA_SEPARABLE_COMPILATION` and :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties and @@ -439,6 +491,8 @@ Variable Queries .. genex:: $<HOST_LINK:list> + .. versionadded:: 3.18 + Returns the list if it is the normal link step, an empty list otherwise. This expression is mainly useful when a device link step is also involved (see ``$<DEVICE_LINK:list>`` generator expression). This expression can only @@ -521,6 +575,8 @@ that must be ``0`` or ``1``. .. genex:: $<IF:condition,true_string,false_string> + .. versionadded:: 3.8 + Evaluates to ``true_string`` if ``condition`` is ``1``. Otherwise evaluates to ``false_string``. @@ -545,10 +601,14 @@ String Transformations .. genex:: $<REMOVE_DUPLICATES:list> + .. versionadded:: 3.15 + Removes duplicated items in the given ``list``. .. genex:: $<FILTER:list,INCLUDE|EXCLUDE,regex> + .. versionadded:: 3.15 + Includes or removes items from ``list`` that match the regular expression ``regex``. .. genex:: $<LOWER_CASE:string> @@ -561,12 +621,16 @@ String Transformations .. genex:: $<GENEX_EVAL:expr> + .. versionadded:: 3.12 + Content of ``expr`` evaluated as a generator expression in the current context. This enables consumption of generator expressions whose evaluation results itself in generator expressions. .. genex:: $<TARGET_GENEX_EVAL:tgt,expr> + .. versionadded:: 3.12 + Content of ``expr`` evaluated as a generator expression in the context of ``tgt`` target. This enables consumption of custom target properties that themselves contain generator expressions. @@ -635,11 +699,15 @@ Variable Queries .. genex:: $<OBJC_COMPILER_ID> + .. versionadded:: 3.16 + The CMake's compiler id of the OBJC compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. .. genex:: $<OBJCXX_COMPILER_ID> + .. versionadded:: 3.16 + The CMake's compiler id of the OBJCXX compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. @@ -648,8 +716,17 @@ Variable Queries The CMake's compiler id of the Fortran compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +.. genex:: $<HIP_COMPILER_ID> + + .. versionadded:: 3.21 + + The CMake's compiler id of the HIP compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. + .. genex:: $<ISPC_COMPILER_ID> + .. versionadded:: 3.19 + The CMake's compiler id of the ISPC compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. @@ -670,11 +747,15 @@ Variable Queries .. genex:: $<OBJC_COMPILER_VERSION> + .. versionadded:: 3.16 + The version of the OBJC compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<OBJCXX_COMPILER_VERSION> + .. versionadded:: 3.16 + The version of the OBJCXX compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. @@ -683,13 +764,24 @@ Variable Queries The version of the Fortran compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +.. genex:: $<HIP_COMPILER_VERSION> + + .. versionadded:: 3.21 + + The version of the HIP compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. + .. genex:: $<ISPC_COMPILER_VERSION> + .. versionadded:: 3.19 + The version of the ISPC compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<COMPILE_LANGUAGE> + .. versionadded:: 3.3 + The compile language of source files when evaluating compile options. See :ref:`the related boolean expression <Boolean COMPILE_LANGUAGE Generator Expression>` @@ -698,6 +790,8 @@ Variable Queries .. genex:: $<LINK_LANGUAGE> + .. versionadded:: 3.18 + The link language of target when evaluating link options. See :ref:`the related boolean expression <Boolean LINK_LANGUAGE Generator Expression>` ``$<LINK_LANGUAGE:language>`` @@ -728,6 +822,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_NAME_IF_EXISTS:tgt> + .. versionadded:: 3.12 + The target name ``tgt`` if the target exists, an empty string otherwise. Note that ``tgt`` is not added as a dependency of the target this @@ -739,6 +835,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_FILE_BASE_NAME:tgt> + .. versionadded:: 3.15 + Base name of ``tgt``, i.e. ``$<TARGET_FILE_NAME:tgt>`` without prefix and suffix. For example, if the ``tgt`` filename is ``libbase.so``, the base name is ``base``. @@ -758,6 +856,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_FILE_PREFIX:tgt> + .. versionadded:: 3.15 + Prefix of the ``tgt`` filename (such as ``lib``). See also the :prop_tgt:`PREFIX` target property. @@ -767,6 +867,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_FILE_SUFFIX:tgt> + .. versionadded:: 3.15 + Suffix of the ``tgt`` filename (extension such as ``.so`` or ``.exe``). See also the :prop_tgt:`SUFFIX` target property. @@ -797,6 +899,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_LINKER_FILE_BASE_NAME:tgt> + .. versionadded:: 3.15 + Base name of file used to link the target ``tgt``, i.e. ``$<TARGET_LINKER_FILE_NAME:tgt>`` without prefix and suffix. For example, if target file name is ``libbase.a``, the base name is ``base``. @@ -815,6 +919,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_LINKER_FILE_PREFIX:tgt> + .. versionadded:: 3.15 + Prefix of file used to link target ``tgt``. See also the :prop_tgt:`PREFIX` and :prop_tgt:`IMPORT_PREFIX` target @@ -825,6 +931,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_LINKER_FILE_SUFFIX:tgt> + .. versionadded:: 3.15 + Suffix of file used to link where ``tgt`` is the name of a target. The suffix corresponds to the file extension (such as ".so" or ".lib"). @@ -868,6 +976,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_PDB_FILE:tgt> + .. versionadded:: 3.1 + Full path to the linker generated program database file (.pdb) where ``tgt`` is the name of a target. @@ -877,6 +987,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_PDB_FILE_BASE_NAME:tgt> + .. versionadded:: 3.15 + Base name of the linker generated program database file (.pdb) where ``tgt`` is the name of a target. @@ -895,6 +1007,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_PDB_FILE_NAME:tgt> + .. versionadded:: 3.1 + Name of the linker generated program database file (.pdb). Note that ``tgt`` is not added as a dependency of the target this @@ -902,6 +1016,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_PDB_FILE_DIR:tgt> + .. versionadded:: 3.1 + Directory of the linker generated program database file (.pdb). Note that ``tgt`` is not added as a dependency of the target this @@ -909,6 +1025,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_BUNDLE_DIR:tgt> + .. versionadded:: 3.9 + Full path to the bundle directory (``my.app``, ``my.framework``, or ``my.bundle``) where ``tgt`` is the name of a target. @@ -917,6 +1035,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_BUNDLE_CONTENT_DIR:tgt> + .. versionadded:: 3.9 + Full path to the bundle content directory where ``tgt`` is the name of a target. For the macOS SDK it leads to ``my.app/Contents``, ``my.framework``, or ``my.bundle/Contents``. For all other SDKs (e.g. iOS) it leads to @@ -940,11 +1060,46 @@ which is just the string ``tgt``. :ref:`Target Usage Requirements` this is the consuming target rather than the target specifying the requirement. +.. genex:: $<TARGET_RUNTIME_DLLS:tgt> + + .. versionadded:: 3.21 + + List of DLLs that the target depends on at runtime. This is determined by + the locations of all the ``SHARED`` targets in the target's transitive + dependencies. Using this generator expression on targets other than + executables, ``SHARED`` libraries, and ``MODULE`` libraries is an error. On + non-DLL platforms, it evaluates to an empty string. + + This generator expression can be used to copy all of the DLLs that a target + depends on into its output directory in a ``POST_BUILD`` custom command. For + example: + + .. code-block:: cmake + + find_package(foo CONFIG REQUIRED) # package generated by install(EXPORT) + + add_executable(exe main.c) + target_link_libraries(exe PRIVATE foo::foo foo::bar) + add_custom_command(TARGET exe POST_BUILD + COMMAND ${CMAKE_COMMAND} -E copy $<TARGET_RUNTIME_DLLS:exe> $<TARGET_FILE_DIR:exe> + COMMAND_EXPAND_LISTS + ) + + .. note:: + + :ref:`Imported Targets` are supported only if they know the location + of their ``.dll`` files. An imported ``SHARED`` library must have + :prop_tgt:`IMPORTED_LOCATION` set to its ``.dll`` file. See the + :ref:`add_library imported libraries <add_library imported libraries>` + section for details. Many :ref:`Find Modules` produce imported targets + with the ``UNKNOWN`` type and therefore will be ignored. + .. genex:: $<INSTALL_PREFIX> Content of the install prefix when the target is exported via - :command:`install(EXPORT)`, or when evaluated in - :prop_tgt:`INSTALL_NAME_DIR`, and empty otherwise. + :command:`install(EXPORT)`, or when evaluated in the + :prop_tgt:`INSTALL_NAME_DIR` property or the ``INSTALL_NAME_DIR`` argument of + :command:`install(RUNTIME_DEPENDENCY_SET)`, and empty otherwise. Output-Related Expressions -------------------------- @@ -957,6 +1112,8 @@ Output-Related Expressions .. genex:: $<LINK_ONLY:...> + .. versionadded:: 3.1 + Content of ``...`` except when evaluated in a link interface while propagating :ref:`Target Usage Requirements`, in which case it is the empty string. @@ -982,18 +1139,24 @@ Output-Related Expressions .. genex:: $<TARGET_OBJECTS:objLib> + .. versionadded:: 3.1 + List of objects resulting from build of ``objLib``. .. genex:: $<SHELL_PATH:...> + .. versionadded:: 3.4 + Content of ``...`` converted to shell path style. For example, slashes are converted to backslashes in Windows shells and drive letters are converted to posix paths in MSYS shells. The ``...`` must be an absolute path. - The ``...`` may be a :ref:`semicolon-separated list <CMake Language Lists>` - of paths, in which case each path is converted individually and a result - list is generated using the shell path separator (``:`` on POSIX and - ``;`` on Windows). Be sure to enclose the argument containing this genex - in double quotes in CMake source code so that ``;`` does not split arguments. + + .. versionadded:: 3.14 + The ``...`` may be a :ref:`semicolon-separated list <CMake Language Lists>` + of paths, in which case each path is converted individually and a result + list is generated using the shell path separator (``:`` on POSIX and + ``;`` on Windows). Be sure to enclose the argument containing this genex + in double quotes in CMake source code so that ``;`` does not split arguments. .. genex:: $<OUTPUT_CONFIG:...> diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index 8ca2bf6..034e218 100644 --- a/Help/manual/cmake-generators.7.rst +++ b/Help/manual/cmake-generators.7.rst @@ -91,6 +91,7 @@ Visual Studio Generators /generator/Visual Studio 14 2015 /generator/Visual Studio 15 2017 /generator/Visual Studio 16 2019 + /generator/Visual Studio 17 2022 Other Generators ^^^^^^^^^^^^^^^^ @@ -101,6 +102,8 @@ Other Generators /generator/Green Hills MULTI /generator/Xcode +.. _`Extra Generators`: + Extra Generators ================ diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index b7f0861..e7d2694 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -627,3 +627,45 @@ in list elements, thus flattening nested lists: .. code-block:: cmake set(x a "b;c") # sets "x" to "a;b;c", not "a;b\;c" + +In general, lists do not support elements containing ``;`` characters. +To avoid problems, consider the following advice: + +* The interfaces of many CMake commands, variables, and properties accept + semicolon-separated lists. Avoid passing lists with elements containing + semicolons to these interfaces unless they document either direct support + or some way to escape or encode semicolons. + +* When constructing a list, substitute an otherwise-unused placeholder + for ``;`` in elements when. Then substitute ``;`` for the placeholder + when processing list elements. + For example, the following code uses ``|`` in place of ``;`` characters: + + .. code-block:: cmake + + set(mylist a "b|c") + foreach(entry IN LISTS mylist) + string(REPLACE "|" ";" entry "${entry}") + # use "${entry}" normally + endforeach() + + The :module:`ExternalProject` module's ``LIST_SEPARATOR`` option is an + example of an interface built using this approach. + +* In lists of :manual:`generator expressions <cmake-generator-expressions(7)>`, + use the :genex:`$<SEMICOLON>` generator expression. + +* In command calls, use `Quoted Argument`_ syntax whenever possible. + The called command will receive the content of the argument with + semicolons preserved. An `Unquoted Argument`_ will be split on + semicolons. + +* In :command:`function` implementations, avoid ``ARGV`` and ``ARGN``, + which do not distinguish semicolons in values from those separating values. + Instead, prefer using named positional arguments and the ``ARGC`` and + ``ARGV#`` variables. + When using :command:`cmake_parse_arguments` to parse arguments, prefer + its ``PARSE_ARGV`` signature, which uses the ``ARGV#`` variables. + + Note that this approach does not apply to :command:`macro` implementations + because they reference arguments using placeholders, not real variables. diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 17c1a1e..141eeaa 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -185,6 +185,7 @@ They are normally called through the :command:`find_package` command. /module/FindMPEG /module/FindMPEG2 /module/FindMPI + /module/FindMsys /module/FindODBC /module/FindOpenACC /module/FindOpenAL diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst index 4b2934a..ed85dc4 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -74,7 +74,9 @@ package. By setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``, the ``<PackageName>`` package will not be searched, and will always -be ``NOTFOUND``. +be ``NOTFOUND``. Likewise, setting the +:variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` to ``TRUE`` will make the +package REQUIRED. .. _`Config File Packages`: @@ -444,10 +446,10 @@ be true. This can be tested with logic in the package configuration file: include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake") include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsMacros.cmake") - set(_supported_components Plot Table) + set(_ClimbingStats_supported_components Plot Table) foreach(_comp ${ClimbingStats_FIND_COMPONENTS}) - if (NOT ";${_supported_components};" MATCHES _comp) + if (NOT ";${_ClimbingStats_supported_components};" MATCHES ";${_comp};") set(ClimbingStats_FOUND False) set(ClimbingStats_NOT_FOUND_MESSAGE "Unsupported component: ${_comp}") endif() diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index bd6b2f0..0939a82 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,37 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used to determine whether to report an error on use of deprecated macros or functions. + +Policies Introduced by CMake 3.23 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0129: Compiler id for MCST LCC compilers is now LCC, not GNU. </policy/CMP0129> + +Policies Introduced by CMake 3.22 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0128: Selection of language standard and extension flags improved. </policy/CMP0128> + CMP0127: cmake_dependent_option() supports full Condition Syntax. </policy/CMP0127> + +Policies Introduced by CMake 3.21 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0126: set(CACHE) does not remove a normal variable of the same name. </policy/CMP0126> + CMP0125: find_(path|file|library|program) have consistent behavior for cache variables. </policy/CMP0125> + CMP0124: foreach() loop variables are only available in the loop scope. </policy/CMP0124> + CMP0123: ARMClang cpu/arch compile and link flags must be set explicitly. </policy/CMP0123> + CMP0122: UseSWIG use standard library name conventions for csharp language. </policy/CMP0122> + CMP0121: The list command detects invalid indices. </policy/CMP0121> + Policies Introduced by CMake 3.20 ================================= diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst index 467818d..03bb5aa 100644 --- a/Help/manual/cmake-presets.7.rst +++ b/Help/manual/cmake-presets.7.rst @@ -12,18 +12,21 @@ Introduction One problem that CMake users often face is sharing settings with other people for common ways to configure a project. This may be done to support CI builds, -or for users who frequently use the same build. CMake supports two files, +or for users who frequently use the same build. CMake supports two main files, ``CMakePresets.json`` and ``CMakeUserPresets.json``, that allow users to -specify common configure options and share them with others. +specify common configure options and share them with others. CMake also +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 save project-wide builds, while -``CMakeUserPresets.json`` is meant for developers to save their own local -builds. ``CMakePresets.json`` may be checked into a version control system, and -``CMakeUserPresets.json`` should NOT be checked in. For example, if a project -is using Git, ``CMakePresets.json`` may be tracked, and +(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. + +``CMakePresets.json`` may be checked into a version control system, and +``CMakeUserPresets.json`` should NOT be checked in. For example, if a +project is using Git, ``CMakePresets.json`` may be tracked, and ``CMakeUserPresets.json`` should be added to the ``.gitignore``. Format @@ -39,7 +42,7 @@ The root object recognizes the following fields: ``version`` A required integer representing the version of the JSON schema. - The supported versions are ``1`` and ``2``. + The supported versions are ``1``, ``2``, ``3``, and ``4``. ``cmakeMinimumRequired`` @@ -58,6 +61,13 @@ The root object recognizes the following fields: 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 @@ -70,17 +80,37 @@ The root object recognizes the following fields: ``configurePresets`` An optional array of `Configure Preset`_ objects. - This is allowed in preset files specifying version 1 or above. + 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. + 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. + This is allowed in preset files specifying version ``2`` or above. + +Includes +^^^^^^^^ + +``CMakePresets.json`` and ``CMakeUserPresets.json`` can include other files +with the ``include`` field in file version ``4`` and later. Files included +by these files can also include other files. If ``CMakePresets.json`` and +``CMakeUserPresets.json`` are both present, ``CMakeUserPresets.json`` +implicitly includes ``CMakePresets.json``, even with no ``include`` field, +in all versions of the format. + +If a preset file contains presets that inherit from presets in another file, +the file must include the other file either directly or indirectly. +Include cycles are not allowed among files. If ``a.json`` includes +``b.json``, ``b.json`` cannot include ``a.json``. However, a file may be +included multiple times from the same file or from different files. + +Files directly or indirectly included from ``CMakePresets.json`` should be +guaranteed to be provided by the project. ``CMakeUserPresets.json`` may +include files from anywhere. Configure Preset ^^^^^^^^^^^^^^^^ @@ -108,16 +138,25 @@ that may contain the following fields: ``inherits`` An optional array of strings representing the names of presets to inherit - from. The preset will inherit all of the fields from the ``inherits`` + from. This field can also be a string, which is equivalent to an array + containing one string. + + The preset will inherit all of the fields from the ``inherits`` presets by default (except ``name``, ``hidden``, ``inherits``, ``description``, and ``displayName``), but can override them as desired. If multiple ``inherits`` presets provide conflicting values for the same field, the earlier preset in the ``inherits`` list will be - preferred. Presets in ``CMakePresets.json`` may not inherit from presets - in ``CMakeUserPresets.json``. + preferred. - This field can also be a string, which is equivalent to an array - containing one string. + 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. This is allowed in preset files specifying + version ``3`` or above. ``vendor`` @@ -140,7 +179,9 @@ that may contain the following fields: 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``). + ``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 @@ -175,13 +216,30 @@ that may contain the following fields: ignore the field, but the IDE can use them to set up the environment before invoking CMake. +``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, + relative to the source directory. This field takes precedence over any + :variable:`CMAKE_TOOLCHAIN_FILE` value. It is allowed in preset files + 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 specified, it must be inherited from the ``inherits`` preset (unless this - preset is ``hidden``). + preset is ``hidden``). In version ``3`` or above, this field may be + 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`` @@ -326,17 +384,26 @@ that may contain the following fields: ``inherits`` - An optional array of strings representing the names of presets to - inherit from. The preset will inherit all of the fields from the + An optional array of strings representing the names of presets to inherit + from. This field can also be a string, which is equivalent to an array + containing one string. + + The preset will inherit all of the fields from the ``inherits`` presets by default (except ``name``, ``hidden``, ``inherits``, ``description``, and ``displayName``), but can override them as desired. If multiple ``inherits`` presets provide conflicting values for the same field, the earlier preset in the ``inherits`` list - will be preferred. Presets in ``CMakePresets.json`` may not inherit from - presets in ``CMakeUserPresets.json``. + will be preferred. - This field can also be a string, which is equivalent to an array - containing one string. + 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. This is allowed in preset files specifying + version ``3`` or above. ``vendor`` @@ -373,6 +440,19 @@ that may contain the following fields: are applied. Setting a variable to ``null`` causes it to not be set, even if a value was inherited from another preset. + .. note:: + + For a CMake project using ExternalProject with a configuration preset + having environment variables needed in the ExternalProject, use a build + preset that inherits that configuration preset or the ExternalProject + will not have the environment variables set in the configuration preset. + Example: suppose the host defaults to one compiler (say Clang) + and the user wishes to use another compiler (say GCC). Set configuration + preset environment variables ``CC`` and ``CXX`` and use a build preset + that inherits that configuration preset. Otherwise the ExternalProject + may use a different (system default) compiler than the top-level CMake + project. + ``configurePreset`` An optional string specifying the name of a configure preset to @@ -411,6 +491,42 @@ that may contain the following fields: An optional bool. If true, equivalent to passing ``--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. + + Package references are used to define dependencies to packages from + external package managers. Currently only NuGet in combination with the + Visual Studio generator is supported. If there are no targets that define + 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. + + When using the Visual Studio generator, package references are defined + using the :prop_tgt:`VS_PACKAGE_REFERENCES` property. Package references + are restored using NuGet. It can be disabled by setting the + ``CMAKE_VS_NUGET_PACKAGE_RESTORE`` variable to ``OFF``. This can also be + done from within a configure preset. + ``verbose`` An optional bool. If true, equivalent to passing ``--verbose`` on the @@ -445,17 +561,26 @@ that may contain the following fields: ``inherits`` - An optional array of strings representing the names of presets to - inherit from. The preset will inherit all of the fields from the + An optional array of strings representing the names of presets to inherit + from. This field can also be a string, which is equivalent to an array + containing one string. + + The preset will inherit all of the fields from the ``inherits`` presets by default (except ``name``, ``hidden``, ``inherits``, ``description``, and ``displayName``), but can override them as desired. If multiple ``inherits`` presets provide conflicting values for the same field, the earlier preset in the ``inherits`` list - will be preferred. Presets in ``CMakePresets.json`` may not inherit from - presets in ``CMakeUserPresets.json``. + will be preferred. - This field can also be a string, which is equivalent to an array - containing one string. + 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. This is allowed in preset files specifying + version ``3`` or above. ``vendor`` @@ -609,7 +734,8 @@ that may contain the following fields: An optional string specifying a regex for test names. Equivalent to passing ``--tests-regex`` on the command line. This field supports - macro expansion. + macro expansion. CMake regex syntax is described under + :ref:`string(REGEX) <Regex Specification>`. ``label`` @@ -782,6 +908,103 @@ that may contain the following fields: Equivalent to passing ``--no-tests=ignore`` on the command line. +Condition +^^^^^^^^^ + +The ``condition`` field of a preset, allowed in preset files specifying version +``3`` or above, is used to determine whether or not the preset is enabled. For +example, this can be used to disable a preset on platforms other than Windows. +``condition`` may be either a boolean, ``null``, or an object. If it is a +boolean, the boolean indicates whether the preset is enabled or disabled. If it +is ``null``, the preset is enabled, but the ``null`` condition is not inherited +by any presets that may inherit from the preset. Sub-conditions (for example in +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 + 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. + + ``"anyOf"`` + + ``"allOf"`` + + Indicates that the condition is an aggregation of zero or more nested + 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 ^^^^^^^^^^^^^^^ @@ -802,7 +1025,8 @@ Recognized macros include: ``${sourceDir}`` - Path to the project source directory. + Path to the project source directory (i.e. the same as + :variable:`CMAKE_SOURCE_DIR`). ``${sourceParentDir}`` @@ -823,6 +1047,17 @@ Recognized macros include: 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 (``$``). diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index af170da..ddb917a 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -21,6 +21,7 @@ Properties of Global Scope /prop_gbl/AUTOMOC_SOURCE_GROUP /prop_gbl/AUTOMOC_TARGETS_FOLDER /prop_gbl/AUTORCC_SOURCE_GROUP + /prop_gbl/AUTOUIC_SOURCE_GROUP /prop_gbl/CMAKE_C_KNOWN_FEATURES /prop_gbl/CMAKE_CUDA_KNOWN_FEATURES /prop_gbl/CMAKE_CXX_KNOWN_FEATURES @@ -73,6 +74,7 @@ Properties on Directories /prop_dir/DEFINITIONS /prop_dir/EXCLUDE_FROM_ALL /prop_dir/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM + /prop_dir/IMPORTED_TARGETS /prop_dir/INCLUDE_DIRECTORIES /prop_dir/INCLUDE_REGULAR_EXPRESSION /prop_dir/INTERPROCEDURAL_OPTIMIZATION @@ -189,6 +191,7 @@ Properties on Targets /prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY /prop_tgt/DEPRECATION /prop_tgt/DISABLE_PRECOMPILE_HEADERS + /prop_tgt/DOTNET_SDK /prop_tgt/DOTNET_TARGET_FRAMEWORK /prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION /prop_tgt/EchoString @@ -200,6 +203,7 @@ Properties on Targets /prop_tgt/EXPORT_NAME /prop_tgt/EXPORT_PROPERTIES /prop_tgt/FOLDER + /prop_tgt/Fortran_BUILDING_INSTRINSIC_MODULES /prop_tgt/Fortran_FORMAT /prop_tgt/Fortran_MODULE_DIRECTORY /prop_tgt/Fortran_PREPROCESS @@ -211,6 +215,15 @@ Properties on Targets /prop_tgt/GHS_NO_SOURCE_GROUP_FILE /prop_tgt/GNUtoMS /prop_tgt/HAS_CXX + /prop_tgt/HEADER_DIRS + /prop_tgt/HEADER_DIRS_NAME + /prop_tgt/HEADER_SET + /prop_tgt/HEADER_SET_NAME + /prop_tgt/HEADER_SETS + /prop_tgt/HIP_ARCHITECTURES + /prop_tgt/HIP_EXTENSIONS + /prop_tgt/HIP_STANDARD + /prop_tgt/HIP_STANDARD_REQUIRED /prop_tgt/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM /prop_tgt/IMPORTED /prop_tgt/IMPORTED_COMMON_LANGUAGE_RUNTIME @@ -232,6 +245,7 @@ Properties on Targets /prop_tgt/IMPORTED_LOCATION_CONFIG /prop_tgt/IMPORTED_NO_SONAME /prop_tgt/IMPORTED_NO_SONAME_CONFIG + /prop_tgt/IMPORTED_NO_SYSTEM /prop_tgt/IMPORTED_OBJECTS /prop_tgt/IMPORTED_OBJECTS_CONFIG /prop_tgt/IMPORTED_SONAME @@ -247,6 +261,7 @@ Properties on Targets /prop_tgt/INTERFACE_COMPILE_DEFINITIONS /prop_tgt/INTERFACE_COMPILE_FEATURES /prop_tgt/INTERFACE_COMPILE_OPTIONS + /prop_tgt/INTERFACE_HEADER_SETS /prop_tgt/INTERFACE_INCLUDE_DIRECTORIES /prop_tgt/INTERFACE_LINK_DEPENDS /prop_tgt/INTERFACE_LINK_DIRECTORIES @@ -270,7 +285,11 @@ Properties on Targets /prop_tgt/LANG_COMPILER_LAUNCHER /prop_tgt/LANG_CPPCHECK /prop_tgt/LANG_CPPLINT + /prop_tgt/LANG_EXTENSIONS /prop_tgt/LANG_INCLUDE_WHAT_YOU_USE + /prop_tgt/LANG_LINKER_LAUNCHER + /prop_tgt/LANG_STANDARD + /prop_tgt/LANG_STANDARD_REQUIRED /prop_tgt/LANG_VISIBILITY_PRESET /prop_tgt/LIBRARY_OUTPUT_DIRECTORY /prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG @@ -286,6 +305,7 @@ Properties on Targets /prop_tgt/LINK_INTERFACE_MULTIPLICITY /prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG /prop_tgt/LINK_LIBRARIES + /prop_tgt/LINK_LIBRARIES_ONLY_TARGETS /prop_tgt/LINK_OPTIONS /prop_tgt/LINK_SEARCH_END_STATIC /prop_tgt/LINK_SEARCH_START_STATIC @@ -402,7 +422,9 @@ Properties on Targets /prop_tgt/XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY /prop_tgt/XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY /prop_tgt/XCODE_EMBED_type + /prop_tgt/XCODE_EMBED_type_CODE_SIGN_ON_COPY /prop_tgt/XCODE_EMBED_type_PATH + /prop_tgt/XCODE_EMBED_type_REMOVE_HEADERS_ON_COPY /prop_tgt/XCODE_EXPLICIT_FILE_TYPE /prop_tgt/XCODE_GENERATE_SCHEME /prop_tgt/XCODE_LINK_BUILD_PHASE_MODE @@ -412,6 +434,7 @@ 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 @@ -444,6 +467,7 @@ Properties on Tests /prop_test/DEPENDS /prop_test/DISABLED /prop_test/ENVIRONMENT + /prop_test/ENVIRONMENT_MODIFICATION /prop_test/FAIL_REGULAR_EXPRESSION /prop_test/FIXTURES_CLEANUP /prop_test/FIXTURES_REQUIRED diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index 1ededee..a941310 100644 --- a/Help/manual/cmake-toolchains.7.rst +++ b/Help/manual/cmake-toolchains.7.rst @@ -96,8 +96,8 @@ Cross Compiling =============== If :manual:`cmake(1)` is invoked with the command line parameter -``-DCMAKE_TOOLCHAIN_FILE=path/to/file``, the file will be loaded early to set -values for the compilers. +``--toolchain path/to/file`` or ``-DCMAKE_TOOLCHAIN_FILE=path/to/file``, 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. diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 4317dd4..4df0237 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -49,10 +49,12 @@ Variables that Provide Information /variable/CMAKE_DEBUG_TARGET_PROPERTIES /variable/CMAKE_DIRECTORY_LABELS /variable/CMAKE_DL_LIBS + /variable/CMAKE_DOTNET_SDK /variable/CMAKE_DOTNET_TARGET_FRAMEWORK /variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION /variable/CMAKE_EDIT_COMMAND /variable/CMAKE_EXECUTABLE_SUFFIX + /variable/CMAKE_EXECUTABLE_SUFFIX_LANG /variable/CMAKE_EXTRA_GENERATOR /variable/CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES /variable/CMAKE_FIND_DEBUG_MODE @@ -70,6 +72,7 @@ Variables that Provide Information /variable/CMAKE_JOB_POOL_PRECOMPILE_HEADER /variable/CMAKE_JOB_POOLS /variable/CMAKE_LANG_COMPILER_AR + /variable/CMAKE_LANG_COMPILER_FRONTEND_VARIANT /variable/CMAKE_LANG_COMPILER_RANLIB /variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX /variable/CMAKE_LINK_LIBRARY_SUFFIX @@ -116,6 +119,7 @@ Variables that Provide Information /variable/CMAKE_VS_DEVENV_COMMAND /variable/CMAKE_VS_MSBUILD_COMMAND /variable/CMAKE_VS_NsightTegra_VERSION + /variable/CMAKE_VS_NUGET_PACKAGE_RESTORE /variable/CMAKE_VS_PLATFORM_NAME /variable/CMAKE_VS_PLATFORM_NAME_DEFAULT /variable/CMAKE_VS_PLATFORM_TOOLSET @@ -123,6 +127,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_WINDOWS_TARGET_PLATFORM_VERSION /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM /variable/CMAKE_XCODE_BUILD_SYSTEM @@ -130,6 +137,7 @@ Variables that Provide Information /variable/PROJECT-NAME_BINARY_DIR /variable/PROJECT-NAME_DESCRIPTION /variable/PROJECT-NAME_HOMEPAGE_URL + /variable/PROJECT-NAME_IS_TOP_LEVEL /variable/PROJECT-NAME_SOURCE_DIR /variable/PROJECT-NAME_VERSION /variable/PROJECT-NAME_VERSION_MAJOR @@ -139,6 +147,7 @@ Variables that Provide Information /variable/PROJECT_BINARY_DIR /variable/PROJECT_DESCRIPTION /variable/PROJECT_HOMEPAGE_URL + /variable/PROJECT_IS_TOP_LEVEL /variable/PROJECT_NAME /variable/PROJECT_SOURCE_DIR /variable/PROJECT_VERSION @@ -203,6 +212,7 @@ Variables that Change Behavior /variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY /variable/CMAKE_FRAMEWORK_PATH /variable/CMAKE_IGNORE_PATH + /variable/CMAKE_IGNORE_PREFIX_PATH /variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE /variable/CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE /variable/CMAKE_INCLUDE_PATH @@ -213,6 +223,7 @@ Variables that Change Behavior /variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT /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 @@ -228,6 +239,7 @@ Variables that Change Behavior /variable/CMAKE_PROJECT_INCLUDE_BEFORE /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE + /variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY /variable/CMAKE_STAGING_PREFIX /variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS @@ -239,10 +251,13 @@ Variables that Change Behavior /variable/CMAKE_SYSTEM_APPBUNDLE_PATH /variable/CMAKE_SYSTEM_FRAMEWORK_PATH /variable/CMAKE_SYSTEM_IGNORE_PATH + /variable/CMAKE_SYSTEM_IGNORE_PREFIX_PATH /variable/CMAKE_SYSTEM_INCLUDE_PATH /variable/CMAKE_SYSTEM_LIBRARY_PATH /variable/CMAKE_SYSTEM_PREFIX_PATH /variable/CMAKE_SYSTEM_PROGRAM_PATH + /variable/CMAKE_TLS_CAINFO + /variable/CMAKE_TLS_VERIFY /variable/CMAKE_USER_MAKE_RULES_OVERRIDE /variable/CMAKE_WARN_DEPRECATED /variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION @@ -252,6 +267,7 @@ 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 @@ -297,7 +313,7 @@ Variables that Describe the System /variable/CMAKE_SYSTEM_PROCESSOR /variable/CMAKE_SYSTEM_VERSION /variable/CYGWIN - /variable/GHS-MULTI + /variable/GHSMULTI /variable/IOS /variable/MINGW /variable/MSVC @@ -421,8 +437,10 @@ Variables that Control the Build /variable/CMAKE_LANG_CPPCHECK /variable/CMAKE_LANG_CPPLINT /variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE + /variable/CMAKE_LANG_LINKER_LAUNCHER /variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LANG_LINK_LIBRARY_FLAG + /variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG /variable/CMAKE_LANG_VISIBILITY_PRESET /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG @@ -433,6 +451,7 @@ Variables that Control the Build /variable/CMAKE_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LINK_LIBRARY_FLAG /variable/CMAKE_LINK_WHAT_YOU_USE + /variable/CMAKE_LINK_WHAT_YOU_USE_CHECK /variable/CMAKE_MACOSX_BUNDLE /variable/CMAKE_MACOSX_RPATH /variable/CMAKE_MAP_IMPORTED_CONFIG_CONFIG @@ -453,6 +472,7 @@ Variables that Control the Build /variable/CMAKE_PCH_INSTANTIATE_TEMPLATES /variable/CMAKE_PDB_OUTPUT_DIRECTORY /variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG + /variable/CMAKE_PLATFORM_NO_VERSIONED_SONAME /variable/CMAKE_POSITION_INDEPENDENT_CODE /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG @@ -519,6 +539,10 @@ Variables for Languages /variable/CMAKE_Fortran_MODDIR_DEFAULT /variable/CMAKE_Fortran_MODDIR_FLAG /variable/CMAKE_Fortran_MODOUT_FLAG + /variable/CMAKE_HIP_ARCHITECTURES + /variable/CMAKE_HIP_EXTENSIONS + /variable/CMAKE_HIP_STANDARD + /variable/CMAKE_HIP_STANDARD_REQUIRED /variable/CMAKE_ISPC_HEADER_DIRECTORY /variable/CMAKE_ISPC_HEADER_SUFFIX /variable/CMAKE_ISPC_INSTRUCTION_SETS @@ -540,6 +564,8 @@ Variables for Languages /variable/CMAKE_LANG_CREATE_SHARED_LIBRARY /variable/CMAKE_LANG_CREATE_SHARED_MODULE /variable/CMAKE_LANG_CREATE_STATIC_LIBRARY + /variable/CMAKE_LANG_EXTENSIONS + /variable/CMAKE_LANG_EXTENSIONS_DEFAULT /variable/CMAKE_LANG_FLAGS /variable/CMAKE_LANG_FLAGS_CONFIG /variable/CMAKE_LANG_FLAGS_CONFIG_INIT @@ -559,8 +585,6 @@ Variables for Languages /variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES /variable/CMAKE_LANG_LIBRARY_ARCHITECTURE /variable/CMAKE_LANG_LINK_EXECUTABLE - /variable/CMAKE_LANG_LINKER_PREFERENCE - /variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES /variable/CMAKE_LANG_LINKER_WRAPPER_FLAG /variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP /variable/CMAKE_LANG_OUTPUT_EXTENSION @@ -568,8 +592,11 @@ Variables for Languages /variable/CMAKE_LANG_SIMULATE_VERSION /variable/CMAKE_LANG_SIZEOF_DATA_PTR /variable/CMAKE_LANG_SOURCE_FILE_EXTENSIONS + /variable/CMAKE_LANG_STANDARD + /variable/CMAKE_LANG_STANDARD_DEFAULT /variable/CMAKE_LANG_STANDARD_INCLUDE_DIRECTORIES /variable/CMAKE_LANG_STANDARD_LIBRARIES + /variable/CMAKE_LANG_STANDARD_REQUIRED /variable/CMAKE_OBJC_EXTENSIONS /variable/CMAKE_OBJC_STANDARD /variable/CMAKE_OBJC_STANDARD_REQUIRED @@ -644,7 +671,9 @@ Variables for CTest /variable/CTEST_RESOURCE_SPEC_FILE /variable/CTEST_RUN_CURRENT_SCRIPT /variable/CTEST_SCP_COMMAND + /variable/CTEST_SCRIPT_DIRECTORY /variable/CTEST_SITE + /variable/CTEST_SUBMIT_INACTIVITY_TIMEOUT /variable/CTEST_SUBMIT_URL /variable/CTEST_SOURCE_DIRECTORY /variable/CTEST_SVN_COMMAND @@ -667,6 +696,7 @@ Variables for CPack /variable/CPACK_ABSOLUTE_DESTINATION_FILES /variable/CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY + /variable/CPACK_CUSTOM_INSTALL_VARIABLES /variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION /variable/CPACK_INCLUDE_TOPLEVEL_DIRECTORY /variable/CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS @@ -699,6 +729,8 @@ are subject to change, and not recommended for use in project code. /variable/CMAKE_LANG_COMPILER_ABI /variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID /variable/CMAKE_LANG_COMPILER_VERSION_INTERNAL + /variable/CMAKE_LANG_LINKER_PREFERENCE + /variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES /variable/CMAKE_LANG_PLATFORM_ID /variable/CMAKE_NOT_USING_CONFIG_FLAGS /variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 02828ac..18bdc5f 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -151,6 +151,33 @@ 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: + +============================== ============ =========== + Command Line Source Dir Build Dir +============================== ============ =========== + ``cmake src`` ``src`` `cwd` + ``cmake build`` (existing) `loaded` ``build`` + ``cmake -S src`` ``src`` `cwd` + ``cmake -S src build`` ``src`` ``build`` + ``cmake -S src -B build`` ``src`` ``build`` + ``cmake -B build`` `cwd` ``build`` + ``cmake -B build src`` ``src`` ``build`` + ``cmake -B build -S src`` ``src`` ``build`` +============================== ============ =========== + +.. versionchanged:: 3.23 + + CMake warns when multiple source paths are specified. This has never + been officially documented or supported, but older versions accidentally + accepted multiple source paths and used the last path specified. + Avoid passing multiple source path arguments. + After generating a buildsystem one may use the corresponding native build tool to build the project. For example, after using the :generator:`Unix Makefiles` generator one may run ``make`` directly: @@ -250,6 +277,21 @@ Options See also the :variable:`CMAKE_FIND_DEBUG_MODE` variable for debugging a more local part of the project. +``--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. + +``--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. + ``--trace`` Put cmake in trace mode. @@ -381,9 +423,9 @@ Options ``--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 specifies the - generator and the build directory, and optionally a list of variables and - other arguments to pass to CMake. The current working directory must contain + ``<path-to-source>/CMakeUserPresets.json``. The preset may specify the + generator and the build directory, and a list of variables and other + arguments to pass to CMake. The current working directory must contain CMake preset files. The :manual:`CMake GUI <cmake-gui(1)>` can also recognize ``CMakePresets.json`` and ``CMakeUserPresets.json`` files. For full details on these files, see :manual:`cmake-presets(7)`. @@ -408,7 +450,8 @@ project binary tree: .. code-block:: shell - cmake --build [<dir> | --preset <preset>] [<options>] [-- <build-tool-options>] + cmake --build <dir> [<options>] [-- <build-tool-options>] + cmake --build --preset <preset> [<options>] [-- <build-tool-options>] This abstracts a native build tool's command-line interface with the following options: @@ -448,6 +491,29 @@ following options: Build target ``clean`` first, then build. (To clean only, use ``--target clean``.) +``--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. + + If the target does not define any package references, this option does nothing. + + This setting can be specified in a build preset (using + ``resolvePackageReferences``). The preset setting will be ignored, if this + command line option is specified. + + If no command line parameter or preset option are provided, 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 + are restored using NuGet. It can be disabled by setting the + ``CMAKE_VS_NUGET_PACKAGE_RESTORE`` variable to ``OFF``. + ``--use-stderr`` Ignored. Behavior is default in CMake >= 3.0. @@ -546,6 +612,8 @@ Run ``cmake -E`` or ``cmake -E help`` for a summary of commands. Available commands are: ``capabilities`` + .. versionadded:: 3.7 + Report cmake capabilities in JSON format. The output is a JSON object with the following keys: @@ -575,6 +643,12 @@ Available commands are: ``true`` if the generator supports toolsets and ``false`` otherwise. ``platformSupport`` ``true`` if the generator supports platforms and ``false`` otherwise. + ``supportedPlatforms`` + .. versionadded:: 3.21 + + 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. ``extraGenerators`` A list of strings with all the extra generators compatible with the generator. @@ -600,6 +674,8 @@ Available commands are: Always false since CMake 3.20. ``cat <files>...`` + .. versionadded:: 3.18 + Concatenate files and print on the standard output. ``chdir <dir> <cmd> [<arg>...]`` @@ -608,8 +684,11 @@ Available commands are: ``compare_files [--ignore-eol] <file1> <file2>`` Check if ``<file1>`` is same as ``<file2>``. If files are the same, then returns ``0``, if not it returns ``1``. In case of invalid - arguments, it returns 2. The ``--ignore-eol`` option - implies line-wise comparison and ignores LF/CRLF differences. + arguments, it returns 2. + + .. versionadded:: 3.14 + The ``--ignore-eol`` option implies line-wise comparison and ignores + LF/CRLF differences. ``copy <file>... <destination>`` Copy files to ``<destination>`` (either file or directory). @@ -618,11 +697,21 @@ Available commands are: ``copy`` does follow symlinks. That means it does not copy symlinks, but the files or directories it point to. + .. versionadded:: 3.5 + Support for multiple input files. + ``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. + .. versionadded:: 3.5 + Support for multiple input directories. + + .. versionadded:: 3.15 + 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>`` Copy files to ``<destination>`` (either file or directory) if they have changed. @@ -630,13 +719,21 @@ Available commands are: directory and it must exist. ``copy_if_different`` does follow symlinks. + .. versionadded:: 3.5 + Support for multiple input files. + ``create_symlink <old> <new>`` Create a symbolic link ``<new>`` naming ``<old>``. + .. versionadded:: 3.13 + Support for creating symlinks on Windows. + .. note:: Path to where ``<new>`` symbolic link will be created has to exist beforehand. ``create_hardlink <old> <new>`` + .. versionadded:: 3.19 + Create a hard link ``<new>`` naming ``<old>``. .. note:: @@ -650,12 +747,16 @@ Available commands are: Displays arguments as text but no new line. ``env [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...`` + .. versionadded:: 3.1 + Run command in a modified environment. ``environment`` Display the current environment variables. ``false`` + .. versionadded:: 3.16 + Do nothing, with an exit code of 1. ``make_directory <dir>...`` @@ -663,6 +764,9 @@ Available commands are: directories too. If a directory already exists it will be silently ignored. + .. versionadded:: 3.5 + Support for multiple input directories. + ``md5sum <file>...`` Create MD5 checksum of files in ``md5sum`` compatible format:: @@ -670,30 +774,40 @@ Available commands are: 052f86c15bbde68af55c7f7b340ab639 file2.txt ``sha1sum <file>...`` + .. versionadded:: 3.10 + Create SHA1 checksum of files in ``sha1sum`` compatible format:: 4bb7932a29e6f73c97bb9272f2bdc393122f86e0 file1.txt 1df4c8f318665f9a5f2ed38f55adadb7ef9f559c file2.txt ``sha224sum <file>...`` + .. versionadded:: 3.10 + Create SHA224 checksum of files in ``sha224sum`` compatible format:: b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930 file1.txt 6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24 file2.txt ``sha256sum <file>...`` + .. versionadded:: 3.10 + Create SHA256 checksum of files in ``sha256sum`` compatible format:: 76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc file1.txt 15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea file2.txt ``sha384sum <file>...`` + .. versionadded:: 3.10 + Create SHA384 checksum of files in ``sha384sum`` compatible format:: acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434 file1.txt 668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d file2.txt ``sha512sum <file>...`` + .. versionadded:: 3.10 + Create SHA512 checksum of files in ``sha512sum`` compatible format:: 2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89 file1.txt @@ -702,7 +816,7 @@ Available commands are: ``remove [-f] <file>...`` .. deprecated:: 3.17 - Remove the file(s). The planned behaviour was that if any of the + Remove the file(s). The planned behavior was that if any of the listed files already do not exist, the command returns a non-zero exit code, but no message is logged. The ``-f`` option changes the behavior to return a zero exit code (i.e. success) in such situations instead. @@ -716,16 +830,24 @@ Available commands are: .. deprecated:: 3.17 Remove ``<dir>`` directories and their contents. If a directory does - not exist it will be silently ignored. If ``<dir>`` is a symlink to - a directory, just the symlink will be removed. + not exist it will be silently ignored. Use ``rm`` instead. + .. versionadded:: 3.15 + Support for multiple directories. + + .. versionadded:: 3.16 + If ``<dir>`` is a symlink to a directory, just the symlink will be removed. + ``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>...`` - Remove the files ``<file>`` or directories ``dir``. + .. versionadded:: 3.17 + + Remove the files ``<file>`` or directories ``<dir>``. + Use ``-r`` or ``-R`` to remove directories and their contents recursively. If any of the listed files/directories do not exist, the command returns a non-zero exit code, but no message is logged. The ``-f`` option changes @@ -736,6 +858,8 @@ Available commands are: Launch :manual:`cmake-server(7)` mode. ``sleep <number>...`` + .. versionadded:: 3.0 + Sleep for given number of seconds. ``tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]`` @@ -744,45 +868,85 @@ Available commands are: ``c`` Create a new archive containing the specified files. If used, the ``<pathname>...`` argument is mandatory. + ``x`` Extract to disk from the archive. - The ``<pathname>...`` argument could be used to extract only selected files - or directories. - When extracting selected files or directories, you must provide their exact - names including the path, as printed by list (``-t``). + + .. versionadded:: 3.15 + The ``<pathname>...`` argument could be used to extract only selected files + or directories. + When extracting selected files or directories, you must provide their exact + names including the path, as printed by list (``-t``). + ``t`` List archive contents. - The ``<pathname>...`` argument could be used to list only selected files - or directories. + + .. versionadded:: 3.15 + The ``<pathname>...`` argument could be used to list only selected files + or directories. + ``v`` Produce verbose output. + ``z`` Compress the resulting archive with gzip. + ``j`` Compress the resulting archive with bzip2. + ``J`` + .. versionadded:: 3.1 + Compress the resulting archive with XZ. + ``--zstd`` + .. versionadded:: 3.15 + Compress the resulting archive with Zstandard. + ``--files-from=<file>`` + .. versionadded:: 3.1 + Read file names from the given file, one per line. Blank lines are ignored. Lines may not start in ``-`` except for ``--add-file=<name>`` to add files whose names start in ``-``. + ``--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>`` + .. versionadded:: 3.1 + Specify modification time recorded in tarball entries. + ``--`` + .. versionadded:: 3.1 + Stop interpreting options and treat all remaining arguments as file names, even if they start with ``-``. + .. versionadded:: 3.1 + LZMA (7zip) support. + + .. versionadded:: 3.15 + The command now continues adding files to an archive even if some of the + files are not readable. This behavior is more consistent with the classic + ``tar`` tool. The command now also parses all flags, and if an invalid flag + was provided, a warning is issued. ``time <command> [<args>...]`` Run command and display elapsed time. + .. versionadded:: 3.5 + The command now properly passes arguments with spaces or special characters + through to the child process. This may break scripts that worked around the + bug with their own extra quoting or escaping. + ``touch <file>...`` Creates ``<file>`` if file do not exist. If ``<file>`` exists, it is changing ``<file>`` access and modification times. @@ -792,6 +956,8 @@ Available commands are: not exist it will be silently ignored. ``true`` + .. versionadded:: 3.16 + Do nothing, with an exit code of 0. Windows-specific Command-Line Tools @@ -803,10 +969,14 @@ The following ``cmake -E`` commands are available only on Windows: Delete Windows registry value. ``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>`` + .. versionadded:: 3.2 + Displays a batch file which sets the environment for the provided Windows CE SDK installed in VS2008. diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 175359d..1e7b077 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -134,6 +134,14 @@ Options This option tells CTest to write all its output to a ``<file>`` log file. +``--output-junit <file>`` + 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. + ``-N,--show-only[=<format>]`` Disable actual execution of tests. @@ -152,10 +160,14 @@ Options See `Show as JSON Object Model`_. ``-L <regex>, --label-regex <regex>`` - Run tests with labels matching regular expression. + Run tests with labels matching regular expression as described under + :ref:`string(REGEX) <Regex Specification>`. This option tells CTest to run only the tests whose labels match the - given regular expression. + given regular expression. When more than one ``-L`` option is given, + a test will only be run if each regular expression matches at least one + of the test's labels (i.e. the multiple ``-L`` labels form an ``AND`` + relationship). See `Label Matching`_. ``-R <regex>, --tests-regex <regex>`` Run tests matching regular expression. @@ -173,7 +185,10 @@ Options Exclude tests with labels matching regular expression. This option tells CTest to NOT run the tests whose labels match the - given regular expression. + given regular expression. When more than one ``-LE`` option is given, + a test will only be excluded if each regular expression matches at least one + of the test's labels (i.e. the multiple ``-LE`` labels form an ``AND`` + relationship). See `Label Matching`_. ``-FA <regex>, --fixture-exclude-any <regex>`` Exclude fixtures matching ``<regex>`` from automatically adding any tests to @@ -309,11 +324,13 @@ Options Set the interactive mode to ``0`` or ``1``. This option causes CTest to run tests in either an interactive mode - or a non-interactive mode. On Windows this means that in - non-interactive mode, all system debug pop up windows are blocked. - In dashboard mode (``Experimental``, ``Nightly``, ``Continuous``), the default - is non-interactive. When just running tests not for a dashboard the - default is to allow popups and interactive debugging. + or a non-interactive mode. In dashboard mode (``Experimental``, ``Nightly``, + ``Continuous``), the default is non-interactive. In non-interactive mode, + the environment variable :envvar:`DASHBOARD_TEST_FROM_CTEST` is set. + + Prior to CMake 3.11, interactive mode on Windows allowed system debug + 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`` Disable timing summary information for labels. @@ -398,6 +415,46 @@ Specify the directory in which to look for tests. .. include:: OPTIONS_HELP.txt +.. _`Label Matching`: + +Label Matching +============== + +Tests may have labels attached to them. Tests may be included +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 +test run, each regular expression must match at least one +label. Using more than one ``-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. + +If a test has no labels attached to it, then ``-L`` will never +include that test, and ``-LE`` will never exclude that test. +As an example of tests with labels, consider five tests, +with the following labels: + +* *test1* has labels *tuesday* and *production* +* *test2* has labels *tuesday* and *test* +* *test3* has labels *wednesday* and *production* +* *test4* has label *wednesday* +* *test5* has labels *friday* and *test* + +Running ``ctest`` with ``-L tuesday -L test`` will select *test2*, which has +both labels. Running CTest with ``-L test`` will select *test2* and +*test5*, because both of them have a label that matches that regular +expression. + +Because the matching works with regular expressions, take note that +running CTest with ``-L es`` will match all five tests. +To select the *tuesday* and *wednesday* tests together, use a single +regular expression that matches either of them, like ``-L "tue|wed"``. + .. _`Label and Subproject Summary`: Label and Subproject Summary @@ -407,6 +464,10 @@ CTest prints timing summary information for each ``LABEL`` and subproject associated with the tests run. The label time summary will not include labels that are mapped to subprojects. +.. versionadded:: 3.22 + Labels added dynamically during test execution are also reported in the + timing summary. See :ref:`Additional Labels`. + When the :prop_test:`PROCESSORS` test property is set, CTest will display a weighted test timing result in label and subproject summaries. The time is reported with `sec*proc` instead of just `sec`. @@ -1043,6 +1104,8 @@ Configuration settings include: * `CTest Script`_ variable: :variable:`CTEST_TEST_TIMEOUT` * :module:`CTest` module variable: ``DART_TESTING_TIMEOUT`` +To report extra test values to CDash, see :ref:`Additional Test Measurements`. + .. _`CTest Coverage Step`: CTest Coverage Step @@ -1290,6 +1353,13 @@ Configuration settings include: * :module:`CTest` module variable: ``SUBMIT_URL`` if set, else ``CTEST_SUBMIT_URL`` +``SubmitInactivityTimeout`` + The time to wait for the submission after which it is canceled + if not completed. Specify a zero value to disable timeout. + + * `CTest Script`_ variable: :variable:`CTEST_SUBMIT_INACTIVITY_TIMEOUT` + * :module:`CTest` module variable: ``CTEST_SUBMIT_INACTIVITY_TIMEOUT`` + ``TriggerSite`` Legacy option. Not used. @@ -1619,4 +1689,4 @@ See Also .. include:: LINKS.txt -.. _`CDash`: http://cdash.org/ +_`CDash`: https://cdash.org diff --git a/Help/manual/presets/example.json b/Help/manual/presets/example.json index dfc2910..873c4ad 100644 --- a/Help/manual/presets/example.json +++ b/Help/manual/presets/example.json @@ -1,10 +1,14 @@ { - "version": 2, + "version": 4, "cmakeMinimumRequired": { "major": 3, - "minor": 20, + "minor": 23, "patch": 0 }, + "include": [ + "otherThings.json", + "moreThings.json" + ], "configurePresets": [ { "name": "default", @@ -35,6 +39,17 @@ "displayName": "Ninja Multi-Config", "description": "Default build using Ninja Multi-Config generator", "generator": "Ninja Multi-Config" + }, + { + "name": "windows-only", + "inherits": "default", + "displayName": "Windows-only configuration", + "description": "This build is only available on Windows", + "condition": { + "type": "equals", + "lhs": "${hostSystemName}", + "rhs": "Windows" + } } ], "buildPresets": [ diff --git a/Help/manual/presets/schema.json b/Help/manual/presets/schema.json index f8faf3d..12f8b5e 100644 --- a/Help/manual/presets/schema.json +++ b/Help/manual/presets/schema.json @@ -11,7 +11,7 @@ }, "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, "vendor": { "$ref": "#/definitions/vendor" }, - "configurePresets": { "$ref": "#/definitions/configurePresets"} + "configurePresets": { "$ref": "#/definitions/configurePresetsV1"} }, "additionalProperties": false }, @@ -23,9 +23,38 @@ }, "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, "vendor": { "$ref": "#/definitions/vendor" }, - "configurePresets": { "$ref": "#/definitions/configurePresets"}, - "buildPresets": { "$ref": "#/definitions/buildPresets"}, - "testPresets": { "$ref": "#/definitions/testPresets"} + "configurePresets": { "$ref": "#/definitions/configurePresetsV1"}, + "buildPresets": { "$ref": "#/definitions/buildPresetsV2"}, + "testPresets": { "$ref": "#/definitions/testPresetsV2"} + }, + "additionalProperties": false + }, + { + "properties": { + "version": { + "const": 3, + "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/buildPresetsV3"}, + "testPresets": { "$ref": "#/definitions/testPresetsV3"} + }, + "additionalProperties": false + }, + { + "properties": { + "version": { + "const": 4, + "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/testPresetsV3"}, + "include": { "$ref": "#/definitions/include"} }, "additionalProperties": false } @@ -58,7 +87,34 @@ "description": "An optional map containing vendor-specific information. CMake does not interpret the contents of this field except to verify that it is a map if it does exist. However, the keys should be a vendor-specific domain name followed by a /-separated path. For example, the Example IDE 1.0 could use example.com/ExampleIDE/1.0. The value of each field can be anything desired by the vendor, though will typically be a map.", "properties": {} }, - "configurePresets": { + "configurePresetsItemsV3": { + "type": "array", + "description": "A configure preset object.", + "items": { + "type": "object", + "description": "A configure preset object.", + "properties": { + "binaryDir": { + "type": "string", + "description": "An optional string representing the path to the output binary directory. This field supports macro expansion. If a relative path is specified, it is calculated relative to the source directory. If binaryDir is not specified, the path is calculated using regular methods." + }, + "generator": { + "type": "string", + "description": "An optional string representing the generator to use for the preset. If generator is not specified, the normal generator discovery procedure is used. 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." + }, + "toolchainFile": { + "type": "string", + "description": "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, relative to the source directory." + }, + "installDir": { + "type": "string", + "description": "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." + }, + "condition": { "$ref": "#/definitions/topCondition" } + } + } + }, + "configurePresetsItemsV1": { "type": "array", "description": "An optional array of configure preset objects.", "items": { @@ -83,7 +139,7 @@ }, { "type": "array", - "description": "An optional array of strings representing the names of presets to inherit from. The preset will inherit all of the fields from the inherits presets by default (except name, hidden, inherits, description, and 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 may not inherit from presets in CMakeUserPresets.json.", + "description": "An optional array of strings representing the names of presets to inherit from. The preset will inherit all of the fields from the inherits presets by default (except name, hidden, inherits, description, and 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.", @@ -302,6 +358,68 @@ }, "additionalProperties": false } + } + } + }, + "configurePresetsV3": { + "type": "array", + "description": "An optional array of configure preset objects.", + "allOf": [ + { "$ref": "#/definitions/configurePresetsItemsV1" }, + { "$ref": "#/definitions/configurePresetsItemsV3" } + ], + "items": { + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "generator": {}, + "architecture": {}, + "toolset": {}, + "toolchainFile": {}, + "binaryDir": {}, + "installDir": {}, + "cmakeExecutable": {}, + "cacheVariables": {}, + "environment": {}, + "warnings": {}, + "errors": {}, + "debug": {}, + "condition": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, + "configurePresetsV1": { + "type": "array", + "description": "An optional array of configure preset objects.", + "allOf": [ + { "$ref": "#/definitions/configurePresetsItemsV1" } + ], + "items": { + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "generator": {}, + "architecture": {}, + "toolset": {}, + "binaryDir": {}, + "cmakeExecutable": {}, + "cacheVariables": {}, + "environment": {}, + "warnings": {}, + "errors": {}, + "debug": {} }, "required": [ "name" @@ -309,7 +427,33 @@ "additionalProperties": false } }, - "buildPresets": { + "buildPresetsItemsV4": { + "type": "array", + "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 4 and higher.", + "items": { + "type": "object", + "properties": { + "resolvePackageReferences": { + "type": "string", + "description": "An optional string specifying the package resolve behavior. Valid values are \"on\" (packages are resolved prior to the build), \"off\" (packages are not resolved prior to the build), and \"only\" (packages are resolved, but no build will be performed).", + "enum": [ + "on", "off", "only" + ] + } + } + } + }, + "buildPresetsItemsV3": { + "type": "array", + "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 3 and higher.", + "items": { + "type": "object", + "properties": { + "condition": { "$ref": "#/definitions/topCondition" } + } + } + }, + "buildPresetsItemsV2": { "type": "array", "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.", "items": { @@ -333,7 +477,7 @@ }, { "type": "array", - "description": "An optional array of strings representing the names of build 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 may not inherit from presets in CMakeUserPresets.json.", + "description": "An optional array of strings representing the names of build 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.", @@ -427,11 +571,119 @@ }, "required": [ "name" + ] + } + }, + "buildPresetsV4": { + "type": "array", + "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 4 and higher.", + "allOf": [ + { "$ref": "#/definitions/buildPresetsItemsV4" }, + { "$ref": "#/definitions/buildPresetsItemsV3" }, + { "$ref": "#/definitions/buildPresetsItemsV2" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "jobs": {}, + "targets": {}, + "configuration": {}, + "cleanFirst": {}, + "resolvePackageReferences": {}, + "verbose": {}, + "nativeToolOptions": {}, + "condition": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, + "buildPresetsV3": { + "type": "array", + "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 3 and higher.", + "allOf": [ + { "$ref": "#/definitions/buildPresetsItemsV3" }, + { "$ref": "#/definitions/buildPresetsItemsV2" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "jobs": {}, + "targets": {}, + "configuration": {}, + "cleanFirst": {}, + "verbose": {}, + "nativeToolOptions": {}, + "condition": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, + "buildPresetsV2": { + "type": "array", + "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.", + "allOf": [ + { "$ref": "#/definitions/buildPresetsItemsV2" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "jobs": {}, + "targets": {}, + "configuration": {}, + "cleanFirst": {}, + "verbose": {}, + "nativeToolOptions": {} + }, + "required": [ + "name" ], "additionalProperties": false } }, - "testPresets": { + "testPresetsItemsV3": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 3 and higher.", + "items": { + "type": "object", + "properties": { + "condition": { "$ref": "#/definitions/topCondition" } + } + } + }, + "testPresetsItemsV2": { "type": "array", "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.", "items": { @@ -455,7 +707,7 @@ }, { "type": "array", - "description": "An optional array of strings representing the names of test 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 may not inherit from presets in CMakeUserPresets.json.", + "description": "An optional array of strings representing the names of test 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.", @@ -743,9 +995,319 @@ }, "required": [ "name" + ] + } + }, + "testPresetsV3": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 3 and higher.", + "allOf": [ + { "$ref": "#/definitions/testPresetsItemsV2" }, + { "$ref": "#/definitions/testPresetsItemsV3" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "configuration": {}, + "overwriteConfigurationFile": {}, + "output": {}, + "filter": {}, + "execution": {}, + "condition": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, + "testPresetsV2": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.", + "allOf": [ + { "$ref": "#/definitions/testPresetsItemsV2" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "configuration": {}, + "overwriteConfigurationFile": {}, + "output": {}, + "filter": {}, + "execution": {} + }, + "required": [ + "name" ], "additionalProperties": false } + }, + "condition": { + "anyOf": [ + { + "type": "boolean", + "description": "A boolean which provides a constant value for the condition's evaluation." + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "const" + }, + "value": { + "type": "boolean", + "description": "A required boolean which provides a constant value for the condition's evaluation." + } + }, + "required": [ + "type", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "equals" + }, + "lhs": { + "type": "string", + "description": "First string to compare. This field supports macro expansion." + }, + "rhs": { + "type": "string", + "description": "Second string to compare. This field supports macro expansion." + } + }, + "required": [ + "type", + "lhs", + "rhs" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "notEquals" + }, + "lhs": { + "type": "string", + "description": "First string to compare. This field supports macro expansion." + }, + "rhs": { + "type": "string", + "description": "Second string to compare. This field supports macro expansion." + } + }, + "required": [ + "type", + "lhs", + "rhs" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "inList" + }, + "string": { + "type": "string", + "description": "A required string to search for. This field supports macro expansion." + }, + "list": { + "type": "array", + "description": "A required list of strings to search. This field supports macro expansion, and uses short-circuit evaluation.", + "items": { + "type": "string" + } + } + }, + "required": [ + "type", + "string", + "list" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "notInList" + }, + "string": { + "type": "string", + "description": "A required string to search for. This field supports macro expansion." + }, + "list": { + "type": "array", + "description": "A required list of strings to search. This field supports macro expansion, and uses short-circuit evaluation.", + "items": { + "type": "string" + } + } + }, + "required": [ + "type", + "string", + "list" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "matches" + }, + "string": { + "type": "string", + "description": "A required string to search. This field supports macro expansion." + }, + "regex": { + "type": "string", + "description": "A required regular expression to search for. This field supports macro expansion." + } + }, + "required": [ + "type", + "string", + "regex" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "notMatches" + }, + "string": { + "type": "string", + "description": "A required string to search. This field supports macro expansion." + }, + "regex": { + "type": "string", + "description": "A required regular expression to search for. This field supports macro expansion." + } + }, + "required": [ + "type", + "string", + "regex" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "anyOf" + }, + "conditions": { + "type": "array", + "description": "A required array of condition objects. These conditions use short-circuit evaluation.", + "items": { "$ref": "#/definitions/condition" } + } + }, + "required": [ + "type", + "conditions" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "allOf" + }, + "conditions": { + "type": "array", + "description": "A required array of condition objects. These conditions use short-circuit evaluation.", + "items": { "$ref": "#/definitions/condition" } + } + }, + "required": [ + "type", + "conditions" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A required string specifying the type of the condition.", + "const": "not" + }, + "condition": { "$ref": "#/definitions/condition" } + }, + "required": [ + "type", + "condition" + ], + "additionalProperties": false + } + ] + }, + "topCondition": { + "anyOf": [ + { "$ref": "#/definitions/condition" }, + { + "type": "null", + "description": "Null indicates that the condition always evaluates to true and is not inherited." + } + ] + }, + "include": { + "type": "array", + "description": "An optional array of strings representing files to include. If the filenames are not absolute, they are considered relative to the current file.", + "items": { + "type": "string" + } } } } |