diff options
Diffstat (limited to 'Help/manual')
25 files changed, 3889 insertions, 1304 deletions
diff --git a/Help/manual/LINKS.txt b/Help/manual/LINKS.txt index 3993ff83d..810fa0b34 100644 --- a/Help/manual/LINKS.txt +++ b/Help/manual/LINKS.txt @@ -5,21 +5,13 @@ Home Page The primary starting point for learning about CMake. -Frequently Asked Questions - https://cmake.org/Wiki/CMake_FAQ - - A Wiki is provided containing answers to frequently asked questions. - -Online Documentation +Online Documentation and Community Resources https://cmake.org/documentation - Links to available documentation may be found on this web page. + Links to available documentation and community resources may be + found on this web page. -Mailing List - https://cmake.org/mailing-lists +Discourse Forum + https://discourse.cmake.org - For help and discussion about using cmake, a mailing list is - provided at cmake@cmake.org. The list is member-post-only but one - may sign up on the CMake web page. Please first read the full - documentation at https://cmake.org before posting questions to - the list. + The Discourse Forum hosts discussion and questions about CMake. diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt index e8b87c923..0947e41cb 100644 --- a/Help/manual/OPTIONS_BUILD.txt +++ b/Help/manual/OPTIONS_BUILD.txt @@ -1,23 +1,34 @@ +``-S <path-to-source>`` + Path to root directory of the CMake project to build. + +``-B <path-to-build>`` + Path to directory which CMake will use as the root of build directory. + + If the directory doesn't already exist CMake will make it. + ``-C <initial-cache>`` Pre-load a script to populate the cache. - When cmake is first run in an empty build tree, it creates a - CMakeCache.txt file and populates it with customizable settings for + When CMake is first run in an empty build tree, it creates a + ``CMakeCache.txt`` file and populates it with customizable settings for the project. This option may be used to specify a file from which to load cache entries before the first pass through the project's - cmake listfiles. The loaded entries take priority over the + CMake listfiles. The loaded entries take priority over the project's default values. The given file should be a CMake script - containing SET commands that use the CACHE option, not a + containing :command:`set` commands that use the ``CACHE`` option, not a cache-format file. + References to :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR` + within the script evaluate to the top-level source and build tree. + ``-D <var>:<type>=<value>, -D <var>=<value>`` - Create a cmake cache entry. + Create or update a CMake ``CACHE`` entry. - When cmake is first run in an empty build tree, it creates a - CMakeCache.txt file and populates it with customizable settings for + When CMake is first run in an empty build tree, it creates a + ``CMakeCache.txt`` file and populates it with customizable settings for the project. This option may be used to specify a setting that takes priority over the project's default value. The option may be - repeated for as many cache entries as desired. + repeated for as many ``CACHE`` entries as desired. If the ``:<type>`` portion is given it must be one of the types specified by the :command:`set` command documentation for its @@ -31,14 +42,14 @@ ``-D<var>:<type>=<value>`` or ``-D<var>=<value>``. ``-U <globbing_expr>`` - Remove matching entries from CMake cache. + Remove matching entries from CMake ``CACHE``. This option may be used to remove one or more variables from the - CMakeCache.txt file, globbing expressions using * and ? are - supported. The option may be repeated for as many cache entries as + ``CMakeCache.txt`` file, globbing expressions using ``*`` and ``?`` are + supported. The option may be repeated for as many ``CACHE`` entries as desired. - Use with care, you can make your CMakeCache.txt non-working. + Use with care, you can make your ``CMakeCache.txt`` non-working. ``-G <generator-name>`` Specify a build system generator. @@ -48,6 +59,9 @@ build system. Possible generator names are specified in the :manual:`cmake-generators(7)` manual. + If not specified, CMake checks the :envvar:`CMAKE_GENERATOR` environment + variable and otherwise falls back to a builtin default selection. + ``-T <toolset-spec>`` Toolset specification for the generator, if supported. @@ -66,47 +80,47 @@ Suppress developer warnings. Suppress warnings that are meant for the author of the - CMakeLists.txt files. By default this will also turn off + ``CMakeLists.txt`` files. By default this will also turn off deprecation warnings. ``-Wdev`` Enable developer warnings. - Enable warnings that are meant for the author of the CMakeLists.txt + Enable warnings that are meant for the author of the ``CMakeLists.txt`` files. By default this will also turn on deprecation warnings. ``-Werror=dev`` Make developer warnings errors. - Make warnings that are meant for the author of the CMakeLists.txt files + Make warnings that are meant for the author of the ``CMakeLists.txt`` files errors. By default this will also turn on deprecated warnings as errors. ``-Wno-error=dev`` Make developer warnings not errors. - Make warnings that are meant for the author of the CMakeLists.txt files not + Make warnings that are meant for the author of the ``CMakeLists.txt`` files not errors. By default this will also turn off deprecated warnings as errors. ``-Wdeprecated`` Enable deprecated functionality warnings. Enable warnings for usage of deprecated functionality, that are meant - for the author of the CMakeLists.txt files. + for the author of the ``CMakeLists.txt`` files. ``-Wno-deprecated`` Suppress deprecated functionality warnings. Suppress warnings for usage of deprecated functionality, that are meant - for the author of the CMakeLists.txt files. + for the author of the ``CMakeLists.txt`` files. ``-Werror=deprecated`` Make deprecated macro and function warnings errors. Make warnings for usage of deprecated macros and functions, that are meant - for the author of the CMakeLists.txt files, errors. + for the author of the ``CMakeLists.txt`` files, errors. ``-Wno-error=deprecated`` Make deprecated macro and function warnings not errors. Make warnings for usage of deprecated macros and functions, that are meant - for the author of the CMakeLists.txt files, not errors. + for the author of the ``CMakeLists.txt`` files, not errors. diff --git a/Help/manual/ccmake.1.rst b/Help/manual/ccmake.1.rst index a5fe19168..60d45a35d 100644 --- a/Help/manual/ccmake.1.rst +++ b/Help/manual/ccmake.1.rst @@ -8,19 +8,19 @@ Synopsis .. parsed-literal:: - ccmake [<options>] (<path-to-source> | <path-to-existing-build>) + ccmake [<options>] {<path-to-source> | <path-to-existing-build>} Description =========== -The "ccmake" executable is the CMake curses interface. Project +The **ccmake** executable is the CMake curses interface. Project configuration settings may be specified interactively through this GUI. Brief instructions are provided at the bottom of the terminal when the program is running. CMake is a cross-platform build system generator. Projects specify their build process with platform-independent CMake listfiles included -in each directory of a source tree with the name CMakeLists.txt. +in each directory of a source tree with the name ``CMakeLists.txt``. Users build a project by using CMake to generate a build system for a native tool on their platform. diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 95f5b8735..d8142a263 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -21,7 +21,7 @@ Binary Targets Executables and libraries are defined using the :command:`add_executable` and :command:`add_library` commands. The resulting binary files have -appropriate prefixes, suffixes and extensions for the platform targeted. +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: @@ -31,7 +31,7 @@ Dependencies between binary targets are expressed using the add_executable(zipapp zipapp.cpp) target_link_libraries(zipapp archive) -``archive`` is defined as a static library -- an archive containing objects +``archive`` is defined as a ``STATIC`` library -- an archive containing objects compiled from ``archive.cpp``, ``zip.cpp``, and ``lzma.cpp``. ``zipapp`` is defined as an executable formed by compiling and linking ``zipapp.cpp``. When linking the ``zipapp`` executable, the ``archive`` static library is @@ -59,7 +59,7 @@ Binary Library Types Normal Libraries ^^^^^^^^^^^^^^^^ -By default, the :command:`add_library` command defines a static library, +By default, the :command:`add_library` command defines a ``STATIC`` library, unless a type is specified. A type may be specified when using the command: .. code-block:: cmake @@ -95,7 +95,7 @@ Apple Frameworks """""""""""""""" A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK` -target property to create an OS X or iOS Framework Bundle. +target property to create an macOS or iOS Framework Bundle. The ``MACOSX_FRAMEWORK_IDENTIFIER`` sets ``CFBundleIdentifier`` key and it uniquely identifies the bundle. @@ -113,9 +113,9 @@ and it uniquely identifies the bundle. Object Libraries ^^^^^^^^^^^^^^^^ -The ``OBJECT`` library type is also not linked to. It defines a non-archival -collection of object files resulting from compiling the given source files. -The object files collection can be used as source inputs to other targets: +The ``OBJECT`` library type defines a non-archival collection of object files +resulting from compiling the given source files. The object files collection +may be used as source inputs to other targets: .. code-block:: cmake @@ -125,22 +125,31 @@ The object files collection can be used as source inputs to other targets: add_executable(test_exe $<TARGET_OBJECTS:archive> test.cpp) -``OBJECT`` libraries may not be used in the right hand side of -:command:`target_link_libraries`. They also may not be used as the ``TARGET`` -in a use of the :command:`add_custom_command(TARGET)` command signature. They -may be installed, and will be exported as an INTERFACE library. +The link (or archiving) step of those other targets will use the object +files collection in addition to those from their own sources. -Although object libraries may not be named directly in calls to -the :command:`target_link_libraries` command, they can be "linked" -indirectly by using an :ref:`Interface Library <Interface Libraries>` -whose :prop_tgt:`INTERFACE_SOURCES` target property is set to name -``$<TARGET_OBJECTS:objlib>``. +Alternatively, object libraries may be linked into other targets: -Although object libraries may not be used as the ``TARGET`` -in a use of the :command:`add_custom_command(TARGET)` command signature, -the list of objects can be used by :command:`add_custom_command(OUTPUT)` or -:command:`file(GENERATE)` by using ``$<TARGET_OBJECTS:objlib>``. +.. code-block:: cmake + + add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp) + + add_library(archiveExtras STATIC extras.cpp) + target_link_libraries(archiveExtras PUBLIC archive) + + add_executable(test_exe test.cpp) + target_link_libraries(test_exe archive) +The link (or archiving) step of those other targets will use the object +files from ``OBJECT`` libraries that are *directly* linked. Additionally, +usage requirements of the ``OBJECT`` libraries will be honored when compiling +sources in those other targets. Furthermore, those usage requirements +will propagate transitively to dependents of those other targets. + +Object libraries may not be used as the ``TARGET`` in a use of the +:command:`add_custom_command(TARGET)` command signature. However, +the list of objects can be used by :command:`add_custom_command(OUTPUT)` +or :command:`file(GENERATE)` by using ``$<TARGET_OBJECTS:objlib>``. Build Specification and Usage Requirements ========================================== @@ -266,7 +275,7 @@ The :command:`target_link_libraries` command has ``PRIVATE``, Because ``archive`` is a ``PUBLIC`` dependency of ``archiveExtras``, the usage requirements of it are propagated to ``consumer`` too. Because -``serialization`` is a ``PRIVATE`` dependency of ``archive``, the usage +``serialization`` is a ``PRIVATE`` dependency of ``archiveExtras``, the usage requirements of it are not propagated to ``consumer``. Generally, a dependency should be specified in a use of @@ -356,8 +365,8 @@ non-compatible requirements :manual:`cmake(1)` issues a diagnostic: target_link_libraries(exe2 lib1 lib2) The ``lib1`` requirement ``INTERFACE_POSITION_INDEPENDENT_CODE`` is not -"compatible" with the ``POSITION_INDEPENDENT_CODE`` property of the ``exe1`` -target. The library requires that consumers are built as +"compatible" with the :prop_tgt:`POSITION_INDEPENDENT_CODE` property of +the ``exe1`` target. The library requires that consumers are built as position-independent-code, while the executable specifies to not built as position-independent-code, so a diagnostic is issued. @@ -538,10 +547,10 @@ is not known until build-time. Therefore, code such as target_compile_definitions(exe1 PRIVATE DEBUG_BUILD) endif() -may appear to work for ``Makefile`` based and ``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. +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 @@ -687,9 +696,10 @@ property are treated as ``SYSTEM`` include directories, as if they were 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 with the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target property. +be controlled by setting the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target +property on the *consumers* of imported targets. -If a binary target is linked transitively to a Mac OX framework, the +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. This has the same effect as passing the framework directory as an include directory. @@ -774,7 +784,7 @@ A *library* output artifact of a buildsystem target may be: with the ``MODULE`` option. * On non-DLL platforms: the shared library file (e.g. ``.so`` or ``.dylib``) - of a shared shared library target created by the :command:`add_library` + of a shared library target created by the :command:`add_library` command with the ``SHARED`` option. The :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY` and :prop_tgt:`LIBRARY_OUTPUT_NAME` @@ -801,6 +811,10 @@ An *archive* output artifact of a buildsystem target may be: executable target created by the :command:`add_executable` command when its :prop_tgt:`ENABLE_EXPORTS` target property is set. +* On AIX: the linker import file (e.g. ``.imp``) of an executable target + created by the :command:`add_executable` command when its + :prop_tgt:`ENABLE_EXPORTS` target property is set. + The :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY` and :prop_tgt:`ARCHIVE_OUTPUT_NAME` target properties may be used to control archive output artifact locations and names in the build tree. @@ -811,7 +825,7 @@ Directory-Scoped Commands The :command:`target_include_directories`, :command:`target_compile_definitions` and :command:`target_compile_options` commands have an effect on only one -target at a time. The commands :command:`add_definitions`, +target at a time. The commands :command:`add_compile_definitions`, :command:`add_compile_options` and :command:`include_directories` have a similar function, but operate at directory scope instead of target scope for convenience. @@ -830,12 +844,11 @@ Imported Targets An :prop_tgt:`IMPORTED` target represents a pre-existing dependency. Usually such targets are defined by an upstream package and should be treated as -immutable. It is not possible to use an :prop_tgt:`IMPORTED` target in the -left-hand-side of the :command:`target_compile_definitions`, -:command:`target_include_directories`, :command:`target_compile_options` or -:command:`target_link_libraries` commands, as that would be an attempt to -modify it. :prop_tgt:`IMPORTED` targets are designed to be used only in the -right-hand-side of those commands. +immutable. After declaring an :prop_tgt:`IMPORTED` target one can adjust its +target properties by using the customary commands such as +:command:`target_compile_definitions`, :command:`target_include_directories`, +:command:`target_compile_options` or :command:`target_link_libraries` just like +with any other regular target. :prop_tgt:`IMPORTED` targets may have the same usage requirement properties populated as binary targets, such as @@ -968,9 +981,10 @@ are: * Properties matching ``INTERFACE_*`` * Built-in properties matching ``COMPATIBLE_INTERFACE_*`` * ``EXPORT_NAME`` +* ``EXPORT_PROPERTIES`` * ``IMPORTED`` +* ``MANUALLY_ADDED_DEPENDENCIES`` * ``NAME`` -* ``NO_SYSTEM_FROM_IMPORTED`` * Properties matching ``IMPORTED_LIBNAME_*`` * Properties matching ``MAP_IMPORTED_CONFIG_*`` diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst index 611c989a0..59ba89727 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst @@ -22,8 +22,8 @@ These commands are always available. /command/cmake_policy /command/configure_file /command/continue - /command/elseif /command/else + /command/elseif /command/endforeach /command/endfunction /command/endif @@ -44,6 +44,7 @@ These commands are always available. /command/get_property /command/if /command/include + /command/include_guard /command/list /command/macro /command/mark_as_advanced @@ -52,9 +53,9 @@ These commands are always available. /command/option /command/return /command/separate_arguments + /command/set /command/set_directory_properties /command/set_property - /command/set /command/site_name /command/string /command/unset @@ -69,6 +70,7 @@ These commands are available only in CMake projects. .. toctree:: :maxdepth: 1 + /command/add_compile_definitions /command/add_compile_options /command/add_custom_command /command/add_custom_target @@ -76,6 +78,7 @@ These commands are available only in CMake projects. /command/add_dependencies /command/add_executable /command/add_library + /command/add_link_options /command/add_subdirectory /command/add_test /command/aux_source_directory @@ -97,8 +100,6 @@ These commands are available only in CMake projects. /command/link_libraries /command/load_cache /command/project - /command/qt_wrap_cpp - /command/qt_wrap_ui /command/remove_definitions /command/set_source_files_properties /command/set_target_properties @@ -108,7 +109,10 @@ These commands are available only in CMake projects. /command/target_compile_features /command/target_compile_options /command/target_include_directories + /command/target_link_directories /command/target_link_libraries + /command/target_link_options + /command/target_precompile_headers /command/target_sources /command/try_compile /command/try_run @@ -140,8 +144,10 @@ These commands are available only in CTest scripts. Deprecated Commands =================== -These commands are available only for compatibility with older -versions of CMake. Do not use them in new code. +These commands are deprecated and are only made available to maintain +backward compatibility. The documentation of each command states the +CMake version in which it was deprecated. Do not use these commands +in new code. .. toctree:: :maxdepth: 1 @@ -155,6 +161,8 @@ versions of CMake. Do not use them in new code. /command/load_command /command/make_directory /command/output_required_files + /command/qt_wrap_cpp + /command/qt_wrap_ui /command/remove /command/subdir_depends /command/subdirs diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index 012439500..a14e3222c 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -28,10 +28,15 @@ CMake knows are known to the compiler, regardless of language standard or compile flags needed to use them. Features known to CMake are named mostly following the same convention -as the Clang feature test macros. The are some exceptions, such as +as the Clang feature test macros. There are some exceptions, such as CMake using ``cxx_final`` and ``cxx_override`` instead of the single ``cxx_override_control`` used by Clang. +Note that there are no separate compile features properties or variables for +the ``OBJC`` or ``OBJCXX`` languages. These are based off ``C`` or ``C++`` +respectively, so the properties and variables for their corresponding base +language should be used instead. + Compile Feature Requirements ============================ @@ -90,21 +95,21 @@ Requiring Language Standards In projects that use a large number of commonly available features from a particular language standard (e.g. C++ 11) one may specify a meta-feature (e.g. ``cxx_std_11``) that requires use of a compiler mode -aware of that standard. This is simpler than specifying all the -features individually, but does not guarantee the existence of any -particular feature. Diagnosis of use of unsupported features will be -delayed until compile time. +that is at minimum aware of that standard, but could be greater. +This is simpler than specifying all the features individually, but does +not guarantee the existence of any particular feature. +Diagnosis of use of unsupported features will be delayed until compile time. For example, if C++ 11 features are used extensively in a project's -header files, then clients must use a compiler mode aware of C++ 11 -or above. This can be requested with the code: +header files, then clients must use a compiler mode that is no less +than C++ 11. This can be requested with the code: .. code-block:: cmake target_compile_features(mylib PUBLIC cxx_std_11) In this example, CMake will ensure the compiler is invoked in a mode -that is aware of C++ 11 (or above), adding flags such as +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``). @@ -331,12 +336,12 @@ and :prop_gbl:`compile features <CMAKE_CXX_KNOWN_FEATURES>` available from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: -* ``AppleClang``: Apple Clang for Xcode versions 4.4 though 6.2. -* ``Clang``: Clang compiler versions 2.9 through 3.4. -* ``GNU``: GNU compiler versions 4.4 through 5.0. -* ``MSVC``: Microsoft Visual Studio versions 2010 through 2017. -* ``SunPro``: Oracle SolarisStudio versions 12.4 through 12.5. -* ``Intel``: Intel compiler versions 12.1 through 17.0. +* ``AppleClang``: Apple Clang for Xcode versions 4.4+. +* ``Clang``: Clang compiler versions 2.9+. +* ``GNU``: GNU compiler versions 4.4+. +* ``MSVC``: Microsoft Visual Studio versions 2010+. +* ``SunPro``: Oracle SolarisStudio versions 12.4+. +* ``Intel``: Intel compiler versions 12.1+. CMake is currently aware of the :prop_tgt:`C standards <C_STANDARD>` and :prop_gbl:`compile features <CMAKE_C_KNOWN_FEATURES>` available from @@ -344,16 +349,16 @@ the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: * all compilers and versions listed above for C++. -* ``GNU``: GNU compiler versions 3.4 through 5.0. +* ``GNU``: GNU compiler versions 3.4+ CMake is currently aware of the :prop_tgt:`C++ standards <CXX_STANDARD>` and their associated meta-features (e.g. ``cxx_std_11``) available from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: -* ``Cray``: Cray Compiler Environment version 8.1 through 8.5.8. -* ``PGI``: PGI version 12.10 through 17.5. -* ``XL``: IBM XL version 10.1 through 13.1.5. +* ``Cray``: Cray Compiler Environment version 8.1+. +* ``PGI``: PGI version 12.10+. +* ``XL``: IBM XL version 10.1+. CMake is currently aware of the :prop_tgt:`C standards <C_STANDARD>` and their associated meta-features (e.g. ``c_std_99``) available from the @@ -361,9 +366,10 @@ following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: * all compilers and versions listed above with only meta-features for C++. +* ``TI``: Texas Instruments compiler. CMake is currently aware of the :prop_tgt:`CUDA standards <CUDA_STANDARD>` from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: -* ``NVIDIA``: NVIDIA nvcc compiler 7.5 though 8.0. +* ``NVIDIA``: NVIDIA nvcc compiler 7.5+. diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index cd509ac20..85ed935e6 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -10,580 +10,24 @@ cmake-developer(7) Introduction ============ -This manual is intended for reference by developers modifying the CMake -source tree itself, and by those authoring externally-maintained modules. - -Adding Compile Features -======================= - -CMake reports an error if a compiler whose features are known does not report -support for a particular requested feature. A compiler is considered to have -known features if it reports support for at least one feature. - -When adding a new compile feature to CMake, it is therefore necessary to list -support for the feature for all CompilerIds which already have one or more -feature supported, if the new feature is available for any version of the -compiler. - -When adding the first supported feature to a particular CompilerId, it is -necessary to list support for all features known to cmake (See -:variable:`CMAKE_C_COMPILE_FEATURES` and -:variable:`CMAKE_CXX_COMPILE_FEATURES` as appropriate), where available for -the compiler. Ensure that the ``CMAKE_<LANG>_STANDARD_DEFAULT`` is set to -the computed internal variable ``CMAKE_<LANG>_STANDARD_COMPUTED_DEFAULT`` -for compiler versions which should be supported. - -It is sensible to record the features for the most recent version of a -particular CompilerId first, and then work backwards. It is sensible to -try to create a continuous range of versions of feature releases of the -compiler. Gaps in the range indicate incorrect features recorded for -intermediate releases. - -Generally, features are made available for a particular version if the -compiler vendor documents availability of the feature with that -version. Note that sometimes partially implemented features appear to -be functional in previous releases (such as ``cxx_constexpr`` in GNU 4.6, -though availability is documented in GNU 4.7), and sometimes compiler vendors -document availability of features, though supporting infrastructure is -not available (such as ``__has_feature(cxx_generic_lambdas)`` indicating -non-availability in Clang 3.4, though it is documented as available, and -fixed in Clang 3.5). Similar cases for other compilers and versions -need to be investigated when extending CMake to support them. - -When a vendor releases a new version of a known compiler which supports -a previously unsupported feature, and there are already known features for -that compiler, the feature should be listed as supported in CMake for -that version of the compiler as soon as reasonably possible. - -Standard-specific/compiler-specific variables such -``CMAKE_CXX98_COMPILE_FEATURES`` are deliberately not documented. They -only exist for the compiler-specific implementation of adding the ``-std`` -compile flag for compilers which need that. - -Help -==== - -The ``Help`` directory contains CMake help manual source files. -They are written using the `reStructuredText`_ markup syntax and -processed by `Sphinx`_ to generate the CMake help manuals. - -.. _`reStructuredText`: http://docutils.sourceforge.net/docs/ref/rst/introduction.html -.. _`Sphinx`: http://sphinx-doc.org - -Markup Constructs ------------------ - -In addition to using Sphinx to generate the CMake help manuals, we -also use a C++-implemented document processor to print documents for -the ``--help-*`` command-line help options. It supports a subset of -reStructuredText markup. When authoring or modifying documents, -please verify that the command-line help looks good in addition to the -Sphinx-generated html and man pages. - -The command-line help processor supports the following constructs -defined by reStructuredText, Sphinx, and a CMake extension to Sphinx. - -.. - Note: This list must be kept consistent with the cmRST implementation. - -CMake Domain directives - Directives defined in the `CMake Domain`_ for defining CMake - documentation objects are printed in command-line help output as - if the lines were normal paragraph text with interpretation. - -CMake Domain interpreted text roles - Interpreted text roles defined in the `CMake Domain`_ for - cross-referencing CMake documentation objects are replaced by their - link text in command-line help output. Other roles are printed - literally and not processed. - -``code-block`` directive - Add a literal code block without interpretation. The command-line - help processor prints the block content without the leading directive - line and with common indentation replaced by one space. - -``include`` directive - Include another document source file. The command-line help - processor prints the included document inline with the referencing - document. - -literal block after ``::`` - A paragraph ending in ``::`` followed by a blank line treats - the following indented block as literal text without interpretation. - The command-line help processor prints the ``::`` literally and - prints the block content with common indentation replaced by one - space. - -``note`` directive - Call out a side note. The command-line help processor prints the - block content as if the lines were normal paragraph text with - interpretation. - -``parsed-literal`` directive - Add a literal block with markup interpretation. The command-line - help processor prints the block content without the leading - directive line and with common indentation replaced by one space. - -``productionlist`` directive - Render context-free grammar productions. The command-line help - processor prints the block content as if the lines were normal - paragraph text with interpretation. - -``replace`` directive - Define a ``|substitution|`` replacement. - The command-line help processor requires a substitution replacement - to be defined before it is referenced. - -``|substitution|`` reference - Reference a substitution replacement previously defined by - the ``replace`` directive. The command-line help processor - performs the substitution and replaces all newlines in the - replacement text with spaces. - -``toctree`` directive - Include other document sources in the Table-of-Contents - document tree. The command-line help processor prints - the referenced documents inline as part of the referencing - document. - -Inline markup constructs not listed above are printed literally in the -command-line help output. We prefer to use inline markup constructs that -look correct in source form, so avoid use of \\-escapes in favor of inline -literals when possible. - -Explicit markup blocks not matching directives listed above are removed from -command-line help output. Do not use them, except for plain ``..`` comments -that are removed by Sphinx too. +This manual is intended for reference by developers working with +:manual:`cmake-language(7)` code, whether writing their own modules, +authoring their own build systems, or working on CMake itself. -Note that nested indentation of blocks is not recognized by the -command-line help processor. Therefore: - -* Explicit markup blocks are recognized only when not indented - inside other blocks. - -* Literal blocks after paragraphs ending in ``::`` but not - at the top indentation level may consume all indented lines - following them. - -Try to avoid these cases in practice. - -CMake Domain ------------- - -CMake adds a `Sphinx Domain`_ called ``cmake``, also called the -"CMake Domain". It defines several "object" types for CMake -documentation: - -``command`` - A CMake language command. - -``generator`` - A CMake native build system generator. - See the :manual:`cmake(1)` command-line tool's ``-G`` option. - -``manual`` - A CMake manual page, like this :manual:`cmake-developer(7)` manual. - -``module`` - A CMake module. - See the :manual:`cmake-modules(7)` manual - and the :command:`include` command. - -``policy`` - A CMake policy. - See the :manual:`cmake-policies(7)` manual - and the :command:`cmake_policy` command. - -``prop_cache, prop_dir, prop_gbl, prop_sf, prop_inst, prop_test, prop_tgt`` - A CMake cache, directory, global, source file, installed file, test, - or target property, respectively. See the :manual:`cmake-properties(7)` - manual and the :command:`set_property` command. - -``variable`` - A CMake language variable. - See the :manual:`cmake-variables(7)` manual - and the :command:`set` command. - -Documentation objects in the CMake Domain come from two sources. -First, the CMake extension to Sphinx transforms every document named -with the form ``Help/<type>/<file-name>.rst`` to a domain object with -type ``<type>``. The object name is extracted from the document title, -which is expected to be of the form:: - - <object-name> - ------------- - -and to appear at or near the top of the ``.rst`` file before any other -lines starting in a letter, digit, or ``<``. If no such title appears -literally in the ``.rst`` file, the object name is the ``<file-name>``. -If a title does appear, it is expected that ``<file-name>`` is equal -to ``<object-name>`` with any ``<`` and ``>`` characters removed. - -Second, the CMake Domain provides directives to define objects inside -other documents: - -.. code-block:: rst - - .. command:: <command-name> - - This indented block documents <command-name>. - - .. variable:: <variable-name> - - This indented block documents <variable-name>. - -Object types for which no directive is available must be defined using -the first approach above. - -.. _`Sphinx Domain`: http://sphinx-doc.org/domains.html - -Cross-References ----------------- - -Sphinx uses reStructuredText interpreted text roles to provide -cross-reference syntax. The `CMake Domain`_ provides for each -domain object type a role of the same name to cross-reference it. -CMake Domain roles are inline markup of the forms:: - - :type:`name` - :type:`text <name>` - -where ``type`` is the domain object type and ``name`` is the -domain object name. In the first form the link text will be -``name`` (or ``name()`` if the type is ``command``) and in -the second form the link text will be the explicit ``text``. -For example, the code: - -.. code-block:: rst - - * The :command:`list` command. - * The :command:`list(APPEND)` sub-command. - * The :command:`list() command <list>`. - * The :command:`list(APPEND) sub-command <list>`. - * The :variable:`CMAKE_VERSION` variable. - * The :prop_tgt:`OUTPUT_NAME_<CONFIG>` target property. - -produces: - -* The :command:`list` command. -* The :command:`list(APPEND)` sub-command. -* The :command:`list() command <list>`. -* The :command:`list(APPEND) sub-command <list>`. -* The :variable:`CMAKE_VERSION` variable. -* The :prop_tgt:`OUTPUT_NAME_<CONFIG>` target property. - -Note that CMake Domain roles differ from Sphinx and reStructuredText -convention in that the form ``a<b>``, without a space preceding ``<``, -is interpreted as a name instead of link text with an explicit target. -This is necessary because we use ``<placeholders>`` frequently in -object names like ``OUTPUT_NAME_<CONFIG>``. The form ``a <b>``, -with a space preceding ``<``, is still interpreted as a link text -with an explicit target. - -Style ------ - -Style: Section Headers -^^^^^^^^^^^^^^^^^^^^^^ - -When marking section titles, make the section decoration line as long as -the title text. Use only a line below the title, not above. For -example: - -.. code-block:: rst - - Title Text - ---------- - -Capitalize the first letter of each non-minor word in the title. - -The section header underline character hierarchy is - -* ``#``: Manual group (part) in the master document -* ``*``: Manual (chapter) title -* ``=``: Section within a manual -* ``-``: Subsection or `CMake Domain`_ object document title -* ``^``: Subsubsection or `CMake Domain`_ object document section -* ``"``: Paragraph or `CMake Domain`_ object document subsection - -Style: Whitespace -^^^^^^^^^^^^^^^^^ - -Use two spaces for indentation. Use two spaces between sentences in -prose. - -Style: Line Length -^^^^^^^^^^^^^^^^^^ - -Prefer to restrict the width of lines to 75-80 columns. This is not a -hard restriction, but writing new paragraphs wrapped at 75 columns -allows space for adding minor content without significant re-wrapping of -content. - -Style: Prose -^^^^^^^^^^^^ - -Use American English spellings in prose. - -Style: Starting Literal Blocks -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Prefer to mark the start of literal blocks with ``::`` at the end of -the preceding paragraph. In cases where the following block gets -a ``code-block`` marker, put a single ``:`` at the end of the preceding -paragraph. - -Style: CMake Command Signatures -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Command signatures should be marked up as plain literal blocks, not as -cmake ``code-blocks``. - -Signatures are separated from preceding content by a section header. -That is, use: - -.. code-block:: rst - - ... preceding paragraph. - - Normal Libraries - ^^^^^^^^^^^^^^^^ - - :: - - add_library(<lib> ...) - - This signature is used for ... - -Signatures of commands should wrap optional parts with square brackets, -and should mark list of optional arguments with an ellipsis (``...``). -Elements of the signature which are specified by the user should be -specified with angle brackets, and may be referred to in prose using -``inline-literal`` syntax. - -Style: Boolean Constants -^^^^^^^^^^^^^^^^^^^^^^^^ - -Use "``OFF``" and "``ON``" for boolean values which can be modified by -the user, such as :prop_tgt:`POSITION_INDEPENDENT_CODE`. Such properties -may be "enabled" and "disabled". Use "``True``" and "``False``" for -inherent values which can't be modified after being set, such as the -:prop_tgt:`IMPORTED` property of a build target. - -Style: Inline Literals -^^^^^^^^^^^^^^^^^^^^^^ - -Mark up references to keywords in signatures, file names, and other -technical terms with ``inline-literal`` syntax, for example: - -.. code-block:: rst - - If ``WIN32`` is used with :command:`add_executable`, the - :prop_tgt:`WIN32_EXECUTABLE` target property is enabled. That command - creates the file ``<name>.exe`` on Windows. - -Style: Cross-References -^^^^^^^^^^^^^^^^^^^^^^^ - -Mark up linkable references as links, including repeats. -An alternative, which is used by wikipedia -(`<http://en.wikipedia.org/wiki/WP:REPEATLINK>`_), -is to link to a reference only once per article. That style is not used -in CMake documentation. - -Style: Referencing CMake Concepts -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If referring to a concept which corresponds to a property, and that -concept is described in a high-level manual, prefer to link to the -manual section instead of the property. For example: - -.. code-block:: rst - - This command creates an :ref:`Imported Target <Imported Targets>`. - -instead of: - -.. code-block:: rst - - This command creates an :prop_tgt:`IMPORTED` target. - -The latter should be used only when referring specifically to the -property. - -References to manual sections are not automatically created by creating -a section, but code such as: - -.. code-block:: rst - - .. _`Imported Targets`: - -creates a suitable anchor. Use an anchor name which matches the name -of the corresponding section. Refer to the anchor using a -cross-reference with specified text. - -Imported Targets need the ``IMPORTED`` term marked up with care in -particular because the term may refer to a command keyword -(``IMPORTED``), a target property (:prop_tgt:`IMPORTED`), or a -concept (:ref:`Imported Targets`). - -Where a property, command or variable is related conceptually to others, -by for example, being related to the buildsystem description, generator -expressions or Qt, each relevant property, command or variable should -link to the primary manual, which provides high-level information. Only -particular information relating to the command should be in the -documentation of the command. - -Style: Referencing CMake Domain Objects -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -When referring to `CMake Domain`_ objects such as properties, variables, -commands etc, prefer to link to the target object and follow that with -the type of object it is. For example: - -.. code-block:: rst - - Set the :prop_tgt:`AUTOMOC` target property to ``ON``. - -Instead of - -.. code-block:: rst - - Set the target property :prop_tgt:`AUTOMOC` to ``ON``. - -The ``policy`` directive is an exception, and the type us usually -referred to before the link: - -.. code-block:: rst - - If policy :prop_tgt:`CMP0022` is set to ``NEW`` the behavior is ... - -However, markup self-references with ``inline-literal`` syntax. -For example, within the :command:`add_executable` command -documentation, use - -.. code-block:: rst - - ``add_executable`` - -not - -.. code-block:: rst - - :command:`add_executable` - -which is used elsewhere. - -Modules -======= - -The ``Modules`` directory contains CMake-language ``.cmake`` module files. - -Module Documentation --------------------- - -To document CMake module ``Modules/<module-name>.cmake``, modify -``Help/manual/cmake-modules.7.rst`` to reference the module in the -``toctree`` directive, in sorted order, as:: - - /module/<module-name> - -Then add the module document file ``Help/module/<module-name>.rst`` -containing just the line:: - - .. cmake-module:: ../../Modules/<module-name>.cmake - -The ``cmake-module`` directive will scan the module file to extract -reStructuredText markup from comment blocks that start in ``.rst:``. -At the top of ``Modules/<module-name>.cmake``, begin with the following -license notice: - -.. code-block:: cmake - - # Distributed under the OSI-approved BSD 3-Clause License. See accompanying - # file Copyright.txt or https://cmake.org/licensing for details. - -After this notice, add a *BLANK* line. Then, add documentation using -a :ref:`Line Comment` block of the form: - -.. code-block:: cmake - - #.rst: - # <module-name> - # ------------- - # - # <reStructuredText documentation of module> - -or a :ref:`Bracket Comment` of the form: - -:: - - #[[.rst: - <module-name> - ------------- - - <reStructuredText documentation of module> - #]] - -Any number of ``=`` may be used in the opening and closing brackets -as long as they match. Content on the line containing the closing -bracket is excluded if and only if the line starts in ``#``. - -Additional such ``.rst:`` comments may appear anywhere in the module file. -All such comments must start with ``#`` in the first column. - -For example, a ``Modules/Findxxx.cmake`` module may contain: - -:: - - # Distributed under the OSI-approved BSD 3-Clause License. See accompanying - # file Copyright.txt or https://cmake.org/licensing for details. - - #.rst: - # FindXxx - # ------- - # - # This is a cool module. - # This module does really cool stuff. - # It can do even more than you think. - # - # It even needs two paragraphs to tell you about it. - # And it defines the following variables: - # - # * VAR_COOL: this is great isn't it? - # * VAR_REALLY_COOL: cool right? - - <code> - - #[========================================[.rst: - .. command:: xxx_do_something - - This command does something for Xxx:: - - xxx_do_something(some arguments) - #]========================================] - macro(xxx_do_something) - <code> - endmacro() - -Test the documentation formatting by running -``cmake --help-module <module-name>``, and also by enabling the -``SPHINX_HTML`` and ``SPHINX_MAN`` options to build the documentation. -Edit the comments until generated documentation looks satisfactory. To -have a .cmake file in this directory NOT show up in the modules -documentation, simply leave out the ``Help/module/<module-name>.rst`` -file and the ``Help/manual/cmake-modules.7.rst`` toctree entry. +See https://cmake.org/get-involved/ to get involved in development of +CMake upstream. It includes links to contribution instructions, which +in turn link to developer guides for CMake itself. .. _`Find Modules`: Find Modules ------------- +============ -A "find module" is a ``Modules/Find<package>.cmake`` file to be loaded -by the :command:`find_package` command when invoked for ``<package>``. +A "find module" is a ``Find<PackageName>.cmake`` file to be loaded +by the :command:`find_package` command when invoked for ``<PackageName>``. The primary task of a find module is to determine whether a package -exists on the system, set the ``<package>_FOUND`` variable to reflect +exists on the system, set the ``<PackageName>_FOUND`` variable to reflect this and provide any variables, macros and imported targets required to use the package. A find module is useful in cases where an upstream library does not provide a @@ -638,14 +82,11 @@ and required is up to the find module, but should be documented. For internal implementation, it is a generally accepted convention that variables starting with underscore are for temporary use only. -Like all modules, find modules should be properly documented. To add a -module to the CMake documentation, follow the steps in the `Module -Documentation`_ section above. - +.. _`CMake Developer Standard Variable Names`: Standard Variable Names -^^^^^^^^^^^^^^^^^^^^^^^ +----------------------- For a ``FindXxx.cmake`` module that takes the approach of setting variables (either instead of or in addition to creating imported @@ -752,54 +193,81 @@ Make sure you comment them as deprecated, so that no-one starts using them. - A Sample Find Module -^^^^^^^^^^^^^^^^^^^^ +-------------------- -We will describe how to create a simple find module for a library -``Foo``. +We will describe how to create a simple find module for a library ``Foo``. -The first thing that is needed is a license notice. +The top of the module should begin with a license notice, followed by +a blank line, and then followed by a :ref:`Bracket Comment`. The comment +should begin with ``.rst:`` to indicate that the rest of its content is +reStructuredText-format documentation. For example: -.. code-block:: cmake +:: - # Distributed under the OSI-approved BSD 3-Clause License. See accompanying - # file Copyright.txt or https://cmake.org/licensing for details. + # Distributed under the OSI-approved BSD 3-Clause License. See accompanying + # file Copyright.txt or https://cmake.org/licensing for details. -Next we need module documentation. CMake's documentation system requires you -to follow the license notice with a blank line and then with a documentation -marker and the name of the module. You should follow this with a simple -statement of what the module does. + #[=======================================================================[.rst: + FindFoo + ------- -.. code-block:: cmake + Finds the Foo library. - #.rst: - # FindFoo - # ------- - # - # Finds the Foo library - # + Imported Targets + ^^^^^^^^^^^^^^^^ -More description may be required for some packages. If there are -caveats or other details users of the module should be aware of, you can -add further paragraphs below this. Then you need to document what -variables and imported targets are set by the module, such as + This module provides the following imported targets, if found: -.. code-block:: cmake + ``Foo::Foo`` + The Foo library + + Result Variables + ^^^^^^^^^^^^^^^^ + + This will define the following variables: + + ``Foo_FOUND`` + True if the system has the Foo library. + ``Foo_VERSION`` + The version of the Foo library which was found. + ``Foo_INCLUDE_DIRS`` + Include directories needed to use Foo. + ``Foo_LIBRARIES`` + Libraries needed to link to Foo. + + Cache Variables + ^^^^^^^^^^^^^^^ + + The following cache variables may also be set: + + ``Foo_INCLUDE_DIR`` + The directory containing ``foo.h``. + ``Foo_LIBRARY`` + The path to the Foo library. + + #]=======================================================================] + +The module documentation consists of: + +* An underlined heading specifying the module name. + +* A simple description of what the module finds. + More description may be required for some packages. If there are + caveats or other details users of the module should be aware of, + specify them here. + +* A section listing imported targets provided by the module, if any. + +* A section listing result variables provided by the module. - # This will define the following variables:: - # - # Foo_FOUND - True if the system has the Foo library - # Foo_VERSION - The version of the Foo library which was found - # - # and the following imported targets:: - # - # Foo::Foo - The Foo library +* Optionally a section listing cache variables used by the module, if any. -If the package provides any macros, they should be listed here, but can -be documented where they are defined. See the `Module -Documentation`_ section above for more details. +If the package provides any macros or functions, they should be listed in +an additional section, but can be documented by additional ``.rst:`` +comment blocks immediately above where those macros or functions are defined. +The find module implementation may begin below the documentation block. Now the actual libraries and so on have to be found. The code here will obviously vary from module to module (dealing with that, after all, is the point of find modules), but there tends to be a common pattern for libraries. @@ -943,7 +411,7 @@ populated: endif() The ``RELEASE`` variant should be listed first in the property -so that that variant is chosen if the user uses a configuration which is +so that the variant is chosen if the user uses a configuration which is not an exact match for any listed ``IMPORTED_CONFIGURATIONS``. Most of the cache variables should be hidden in the ``ccmake`` interface unless diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst new file mode 100644 index 000000000..96ceb945a --- /dev/null +++ b/Help/manual/cmake-env-variables.7.rst @@ -0,0 +1,73 @@ +.. cmake-manual-description: CMake Environment Variables Reference + +cmake-env-variables(7) +********************** + +.. only:: html + + .. contents:: + +This page lists environment variables that have special +meaning to CMake. + +For general information on environment variables, see the +:ref:`Environment Variables <CMake Language Environment Variables>` +section in the cmake-language manual. + + +Environment Variables that Control the Build +============================================ + +.. toctree:: + :maxdepth: 1 + + /envvar/CMAKE_BUILD_PARALLEL_LEVEL + /envvar/CMAKE_CONFIG_TYPE + /envvar/CMAKE_GENERATOR + /envvar/CMAKE_GENERATOR_INSTANCE + /envvar/CMAKE_GENERATOR_PLATFORM + /envvar/CMAKE_GENERATOR_TOOLSET + /envvar/CMAKE_MSVCIDE_RUN_PATH + /envvar/CMAKE_NO_VERBOSE + /envvar/CMAKE_OSX_ARCHITECTURES + /envvar/DESTDIR + /envvar/LDFLAGS + /envvar/MACOSX_DEPLOYMENT_TARGET + /envvar/PackageName_ROOT + /envvar/VERBOSE + +Environment Variables for Languages +=================================== + +.. toctree:: + :maxdepth: 1 + + /envvar/ASM_DIALECT + /envvar/ASM_DIALECTFLAGS + /envvar/CC + /envvar/CFLAGS + /envvar/CSFLAGS + /envvar/CUDACXX + /envvar/CUDAFLAGS + /envvar/CUDAHOSTCXX + /envvar/CXX + /envvar/CXXFLAGS + /envvar/FC + /envvar/FFLAGS + /envvar/RC + /envvar/RCFLAGS + /envvar/SWIFTC + +Environment Variables for CTest +=============================== + +.. toctree:: + :maxdepth: 1 + + /envvar/CMAKE_CONFIG_TYPE + /envvar/CTEST_INTERACTIVE_DEBUG_MODE + /envvar/CTEST_OUTPUT_ON_FAILURE + /envvar/CTEST_PARALLEL_LEVEL + /envvar/CTEST_PROGRESS_OUTPUT + /envvar/CTEST_USE_LAUNCHERS_DEFAULT + /envvar/DASHBOARD_TEST_FROM_CTEST diff --git a/Help/manual/cmake-file-api.7.rst b/Help/manual/cmake-file-api.7.rst new file mode 100644 index 000000000..04b6ed259 --- /dev/null +++ b/Help/manual/cmake-file-api.7.rst @@ -0,0 +1,1113 @@ +.. cmake-manual-description: CMake File-Based API + +cmake-file-api(7) +***************** + +.. only:: html + + .. contents:: + +Introduction +============ + +CMake provides a file-based API that clients may use to get semantic +information about the buildsystems CMake generates. Clients may use +the API by writing query files to a specific location in a build tree +to request zero or more `Object Kinds`_. When CMake generates the +buildsystem in that build tree it will read the query files and write +reply files for the client to read. + +The file-based API uses a ``<build>/.cmake/api/`` directory at the top +of a build tree. The API is versioned to support changes to the layout +of files within the API directory. API file layout versioning is +orthogonal to the versioning of `Object Kinds`_ used in replies. +This version of CMake supports only one API version, `API v1`_. + +API v1 +====== + +API v1 is housed in the ``<build>/.cmake/api/v1/`` directory. +It has the following subdirectories: + +``query/`` + Holds query files written by clients. + These may be `v1 Shared Stateless Query Files`_, + `v1 Client Stateless Query Files`_, or `v1 Client Stateful Query Files`_. + +``reply/`` + Holds reply files written by CMake whenever it runs to generate a build + system. These are indexed by a `v1 Reply Index File`_ file that may + reference additional `v1 Reply Files`_. CMake owns all reply files. + Clients must never remove them. + + Clients may look for and read a reply index file at any time. + Clients may optionally create the ``reply/`` directory at any time + and monitor it for the appearance of a new reply index file. + +v1 Shared Stateless Query Files +------------------------------- + +Shared stateless query files allow clients to share requests for +major versions of the `Object Kinds`_ and get all requested versions +recognized by the CMake that runs. + +Clients may create shared requests by creating empty files in the +``v1/query/`` directory. The form is:: + + <build>/.cmake/api/v1/query/<kind>-v<major> + +where ``<kind>`` is one of the `Object Kinds`_, ``-v`` is literal, +and ``<major>`` is the major version number. + +Files of this form are stateless shared queries not owned by any specific +client. Once created they should not be removed without external client +coordination or human intervention. + +v1 Client Stateless Query Files +------------------------------- + +Client stateless query files allow clients to create owned requests for +major versions of the `Object Kinds`_ and get all requested versions +recognized by the CMake that runs. + +Clients may create owned requests by creating empty files in +client-specific query subdirectories. The form is:: + + <build>/.cmake/api/v1/query/client-<client>/<kind>-v<major> + +where ``client-`` is literal, ``<client>`` is a string uniquely +identifying the client, ``<kind>`` is one of the `Object Kinds`_, +``-v`` is literal, and ``<major>`` is the major version number. +Each client must choose a unique ``<client>`` identifier via its +own means. + +Files of this form are stateless queries owned by the client ``<client>``. +The owning client may remove them at any time. + +v1 Client Stateful Query Files +------------------------------ + +Stateful query files allow clients to request a list of versions of +each of the `Object Kinds`_ and get only the most recent version +recognized by the CMake that runs. + +Clients may create owned stateful queries by creating ``query.json`` +files in client-specific query subdirectories. The form is:: + + <build>/.cmake/api/v1/query/client-<client>/query.json + +where ``client-`` is literal, ``<client>`` is a string uniquely +identifying the client, and ``query.json`` is literal. Each client +must choose a unique ``<client>`` identifier via its own means. + +``query.json`` files are stateful queries owned by the client ``<client>``. +The owning client may update or remove them at any time. When a +given client installation is updated it may then update the stateful +query it writes to build trees to request newer object versions. +This can be used to avoid asking CMake to generate multiple object +versions unnecessarily. + +A ``query.json`` file must contain a JSON object: + +.. code-block:: json + + { + "requests": [ + { "kind": "<kind>" , "version": 1 }, + { "kind": "<kind>" , "version": { "major": 1, "minor": 2 } }, + { "kind": "<kind>" , "version": [2, 1] }, + { "kind": "<kind>" , "version": [2, { "major": 1, "minor": 2 }] }, + { "kind": "<kind>" , "version": 1, "client": {} }, + { "kind": "..." } + ], + "client": {} + } + +The members are: + +``requests`` + A JSON array containing zero or more requests. Each request is + a JSON object with members: + + ``kind`` + Specifies one of the `Object Kinds`_ to be included in the reply. + + ``version`` + Indicates the version(s) of the object kind that the client + understands. Versions have major and minor components following + semantic version conventions. The value must be + + * a JSON integer specifying a (non-negative) major version number, or + * a JSON object containing ``major`` and (optionally) ``minor`` + members specifying non-negative integer version components, or + * a JSON array whose elements are each one of the above. + + ``client`` + Optional member reserved for use by the client. This value is + preserved in the reply written for the client in the + `v1 Reply Index File`_ but is otherwise ignored. Clients may use + this to pass custom information with a request through to its reply. + + For each requested object kind CMake will choose the *first* version + that it recognizes for that kind among those listed in the request. + The response will use the selected *major* version with the highest + *minor* version known to the running CMake for that major version. + Therefore clients should list all supported major versions in + preferred order along with the minimal minor version required + for each major version. + +``client`` + Optional member reserved for use by the client. This value is + preserved in the reply written for the client in the + `v1 Reply Index File`_ but is otherwise ignored. Clients may use + this to pass custom information with a query through to its reply. + +Other ``query.json`` top-level members are reserved for future use. +If present they are ignored for forward compatibility. + +v1 Reply Index File +------------------- + +CMake writes an ``index-*.json`` file to the ``v1/reply/`` directory +whenever it runs to generate a build system. Clients must read the +reply index file first and may read other `v1 Reply Files`_ only by +following references. The form of the reply index file name is:: + + <build>/.cmake/api/v1/reply/index-<unspecified>.json + +where ``index-`` is literal and ``<unspecified>`` is an unspecified +name selected by CMake. Whenever a new index file is generated it +is given a new name and any old one is deleted. During the short +time between these steps there may be multiple index files present; +the one with the largest name in lexicographic order is the current +index file. + +The reply index file contains a JSON object: + +.. code-block:: json + + { + "cmake": { + "version": { + "major": 3, "minor": 14, "patch": 0, "suffix": "", + "string": "3.14.0", "isDirty": false + }, + "paths": { + "cmake": "/prefix/bin/cmake", + "ctest": "/prefix/bin/ctest", + "cpack": "/prefix/bin/cpack", + "root": "/prefix/share/cmake-3.14" + }, + "generator": { + "name": "Unix Makefiles" + } + }, + "objects": [ + { "kind": "<kind>", + "version": { "major": 1, "minor": 0 }, + "jsonFile": "<file>" }, + { "...": "..." } + ], + "reply": { + "<kind>-v<major>": { "kind": "<kind>", + "version": { "major": 1, "minor": 0 }, + "jsonFile": "<file>" }, + "<unknown>": { "error": "unknown query file" }, + "...": {}, + "client-<client>": { + "<kind>-v<major>": { "kind": "<kind>", + "version": { "major": 1, "minor": 0 }, + "jsonFile": "<file>" }, + "<unknown>": { "error": "unknown query file" }, + "...": {}, + "query.json": { + "requests": [ {}, {}, {} ], + "responses": [ + { "kind": "<kind>", + "version": { "major": 1, "minor": 0 }, + "jsonFile": "<file>" }, + { "error": "unknown query file" }, + { "...": {} } + ], + "client": {} + } + } + } + } + +The members are: + +``cmake`` + A JSON object containing information about the instance of CMake that + generated the reply. It contains members: + + ``version`` + A JSON object specifying the version of CMake with members: + + ``major``, ``minor``, ``patch`` + Integer values specifying the major, minor, and patch version components. + ``suffix`` + A string specifying the version suffix, if any, e.g. ``g0abc3``. + ``string`` + A string specifying the full version in the format + ``<major>.<minor>.<patch>[-<suffix>]``. + ``isDirty`` + A boolean indicating whether the version was built from a version + controlled source tree with local modifications. + + ``paths`` + A JSON object specifying paths to things that come with CMake. + It has members for ``cmake``, ``ctest``, and ``cpack`` whose values + are JSON strings specifying the absolute path to each tool, + represented with forward slashes. It also has a ``root`` member for + the absolute path to the directory containing CMake resources like the + ``Modules/`` directory (see :variable:`CMAKE_ROOT`). + + ``generator`` + A JSON object describing the CMake generator used for the build. + It has members: + + ``name`` + A string specifying the name of the generator. + ``platform`` + If the generator supports :variable:`CMAKE_GENERATOR_PLATFORM`, + this is a string specifying the generator platform name. + +``objects`` + A JSON array listing all versions of all `Object Kinds`_ generated + as part of the reply. Each array entry is a + `v1 Reply File Reference`_. + +``reply`` + A JSON object mirroring the content of the ``query/`` directory + that CMake loaded to produce the reply. The members are of the form + + ``<kind>-v<major>`` + A member of this form appears for each of the + `v1 Shared Stateless Query Files`_ that CMake recognized as a + request for object kind ``<kind>`` with major version ``<major>``. + The value is a `v1 Reply File Reference`_ to the corresponding + reply file for that object kind and version. + + ``<unknown>`` + A member of this form appears for each of the + `v1 Shared Stateless Query Files`_ that CMake did not recognize. + The value is a JSON object with a single ``error`` member + containing a string with an error message indicating that the + query file is unknown. + + ``client-<client>`` + A member of this form appears for each client-owned directory + holding `v1 Client Stateless Query Files`_. + The value is a JSON object mirroring the content of the + ``query/client-<client>/`` directory. The members are of the form: + + ``<kind>-v<major>`` + A member of this form appears for each of the + `v1 Client Stateless Query Files`_ that CMake recognized as a + request for object kind ``<kind>`` with major version ``<major>``. + The value is a `v1 Reply File Reference`_ to the corresponding + reply file for that object kind and version. + + ``<unknown>`` + A member of this form appears for each of the + `v1 Client Stateless Query Files`_ that CMake did not recognize. + The value is a JSON object with a single ``error`` member + containing a string with an error message indicating that the + query file is unknown. + + ``query.json`` + This member appears for clients using + `v1 Client Stateful Query Files`_. + If the ``query.json`` file failed to read or parse as a JSON object, + this member is a JSON object with a single ``error`` member + containing a string with an error message. Otherwise, this member + is a JSON object mirroring the content of the ``query.json`` file. + The members are: + + ``client`` + A copy of the ``query.json`` file ``client`` member, if it exists. + + ``requests`` + A copy of the ``query.json`` file ``requests`` member, if it exists. + + ``responses`` + If the ``query.json`` file ``requests`` member is missing or invalid, + this member is a JSON object with a single ``error`` member + containing a string with an error message. Otherwise, this member + contains a JSON array with a response for each entry of the + ``requests`` array, in the same order. Each response is + + * a JSON object with a single ``error`` member containing a string + with an error message, or + * a `v1 Reply File Reference`_ to the corresponding reply file for + the requested object kind and selected version. + +After reading the reply index file, clients may read the other +`v1 Reply Files`_ it references. + +v1 Reply File Reference +^^^^^^^^^^^^^^^^^^^^^^^ + +The reply index file represents each reference to another reply file +using a JSON object with members: + +``kind`` + A string specifying one of the `Object Kinds`_. +``version`` + A JSON object with members ``major`` and ``minor`` specifying + integer version components of the object kind. +``jsonFile`` + A JSON string specifying a path relative to the reply index file + to another JSON file containing the object. + +v1 Reply Files +-------------- + +Reply files containing specific `Object Kinds`_ are written by CMake. +The names of these files are unspecified and must not be interpreted +by clients. Clients must first read the `v1 Reply Index File`_ and +and follow references to the names of the desired response objects. + +Reply files (including the index file) will never be replaced by +files of the same name but different content. This allows a client +to read the files concurrently with a running CMake that may generate +a new reply. However, after generating a new reply CMake will attempt +to remove reply files from previous runs that it did not just write. +If a client attempts to read a reply file referenced by the index but +finds the file missing, that means a concurrent CMake has generated +a new reply. The client may simply start again by reading the new +reply index file. + +.. _`file-api object kinds`: + +Object Kinds +============ + +The CMake file-based API reports semantic information about the build +system using the following kinds of JSON objects. Each kind of object +is versioned independently using semantic versioning with major and +minor components. Every kind of object has the form: + +.. code-block:: json + + { + "kind": "<kind>", + "version": { "major": 1, "minor": 0 }, + "...": {} + } + +The ``kind`` member is a string specifying the object kind name. +The ``version`` member is a JSON object with ``major`` and ``minor`` +members specifying integer components of the object kind's version. +Additional top-level members are specific to each object kind. + +Object Kind "codemodel" +----------------------- + +The ``codemodel`` object kind describes the build system structure as +modeled by CMake. + +There is only one ``codemodel`` object major version, version 2. +Version 1 does not exist to avoid confusion with that from +:manual:`cmake-server(7)` mode. + +"codemodel" version 2 +^^^^^^^^^^^^^^^^^^^^^ + +``codemodel`` object version 2 is a JSON object: + +.. code-block:: json + + { + "kind": "codemodel", + "version": { "major": 2, "minor": 0 }, + "paths": { + "source": "/path/to/top-level-source-dir", + "build": "/path/to/top-level-build-dir" + }, + "configurations": [ + { + "name": "Debug", + "directories": [ + { + "source": ".", + "build": ".", + "childIndexes": [ 1 ], + "projectIndex": 0, + "targetIndexes": [ 0 ], + "hasInstallRule": true, + "minimumCMakeVersion": { + "string": "3.14" + } + }, + { + "source": "sub", + "build": "sub", + "parentIndex": 0, + "projectIndex": 0, + "targetIndexes": [ 1 ], + "minimumCMakeVersion": { + "string": "3.14" + } + } + ], + "projects": [ + { + "name": "MyProject", + "directoryIndexes": [ 0, 1 ], + "targetIndexes": [ 0, 1 ] + } + ], + "targets": [ + { + "name": "MyExecutable", + "directoryIndex": 0, + "projectIndex": 0, + "jsonFile": "<file>" + }, + { + "name": "MyLibrary", + "directoryIndex": 1, + "projectIndex": 0, + "jsonFile": "<file>" + } + ] + } + ] + } + +The members specific to ``codemodel`` objects are: + +``paths`` + A JSON object containing members: + + ``source`` + A string specifying the absolute path to the top-level source directory, + represented with forward slashes. + + ``build`` + A string specifying the absolute path to the top-level build directory, + represented with forward slashes. + +``configurations`` + A JSON array of entries corresponding to available build configurations. + On single-configuration generators there is one entry for the value + of the :variable:`CMAKE_BUILD_TYPE` variable. For multi-configuration + generators there is an entry for each configuration listed in the + :variable:`CMAKE_CONFIGURATION_TYPES` variable. + Each entry is a JSON object containing members: + + ``name`` + A string specifying the name of the configuration, e.g. ``Debug``. + + ``directories`` + A JSON array of entries each corresponding to a build system directory + whose source directory contains a ``CMakeLists.txt`` file. The first + entry corresponds to the top-level directory. Each entry is 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. + + ``parentIndex`` + Optional member that is present when the directory is not top-level. + The value is an unsigned integer 0-based index of another entry in + the main ``directories`` array that corresponds to the parent + directory that added this directory as a subdirectory. + + ``childIndexes`` + Optional member that is present when the directory has subdirectories. + The value is a JSON array of entries corresponding to child directories + created by the :command:`add_subdirectory` or :command:`subdirs` + command. Each entry is an unsigned integer 0-based index of another + entry in the main ``directories`` array. + + ``projectIndex`` + An unsigned integer 0-based index into the main ``projects`` array + indicating the build system project to which the this directory belongs. + + ``targetIndexes`` + Optional member that is present when the directory itself has targets, + excluding those belonging to subdirectories. The value is a JSON + array of entries corresponding to the targets. Each entry is an + unsigned integer 0-based index into the main ``targets`` array. + + ``minimumCMakeVersion`` + Optional member present when a minimum required version of CMake is + known for the directory. This is the ``<min>`` version given to the + most local call to the :command:`cmake_minimum_required(VERSION)` + command in the directory itself or one of its ancestors. + The value is a JSON object with one member: + + ``string`` + A string specifying the minimum required version in the format:: + + <major>.<minor>[.<patch>[.<tweak>]][<suffix>] + + Each component is an unsigned integer and the suffix may be an + arbitrary string. + + ``hasInstallRule`` + Optional member that is present with boolean value ``true`` when + the directory or one of its subdirectories contains any + :command:`install` rules, i.e. whether a ``make install`` + or equivalent rule is available. + + ``projects`` + A JSON array of entries corresponding to the top-level project + and sub-projects defined in the build system. Each (sub-)project + corresponds to a source directory whose ``CMakeLists.txt`` file + calls the :command:`project` command with a project name different + from its parent directory. The first entry corresponds to the + top-level project. + + Each entry is a JSON object containing members: + + ``name`` + A string specifying the name given to the :command:`project` command. + + ``parentIndex`` + Optional member that is present when the project is not top-level. + The value is an unsigned integer 0-based index of another entry in + the main ``projects`` array that corresponds to the parent project + that added this project as a sub-project. + + ``childIndexes`` + Optional member that is present when the project has sub-projects. + The value is a JSON array of entries corresponding to the sub-projects. + Each entry is an unsigned integer 0-based index of another + entry in the main ``projects`` array. + + ``directoryIndexes`` + A JSON array of entries corresponding to build system directories + that are part of the project. The first entry corresponds to the + top-level directory of the project. Each entry is an unsigned + integer 0-based index into the main ``directories`` array. + + ``targetIndexes`` + Optional member that is present when the project itself has targets, + excluding those belonging to sub-projects. The value is a JSON + array of entries corresponding to the targets. Each entry is an + unsigned integer 0-based index into the main ``targets`` array. + + ``targets`` + A JSON array of entries corresponding to the build system targets. + Such targets are created by calls to :command:`add_executable`, + :command:`add_library`, and :command:`add_custom_target`, excluding + imported targets and interface libraries (which do not generate any + build rules). Each entry is a JSON object containing members: + + ``name`` + A string specifying the target name. + + ``id`` + A string uniquely identifying the target. This matches the ``id`` + field in the file referenced by ``jsonFile``. + + ``directoryIndex`` + An unsigned integer 0-based index into the main ``directories`` array + indicating the build system directory in which the target is defined. + + ``projectIndex`` + An unsigned integer 0-based index into the main ``projects`` array + indicating the build system project in which the target is defined. + + ``jsonFile`` + A JSON string specifying a path relative to the codemodel file + to another JSON file containing a + `"codemodel" version 2 "target" object`_. + +"codemodel" version 2 "target" object +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A codemodel "target" object is referenced by a `"codemodel" version 2`_ +object's ``targets`` array. Each "target" object is a JSON object +with members: + +``name`` + A string specifying the logical name of the target. + +``id`` + A string uniquely identifying the target. The format is unspecified + and should not be interpreted by clients. + +``type`` + A string specifying the type of the target. The value is one of + ``EXECUTABLE``, ``STATIC_LIBRARY``, ``SHARED_LIBRARY``, + ``MODULE_LIBRARY``, ``OBJECT_LIBRARY``, or ``UTILITY``. + +``backtrace`` + Optional member that is present when a CMake language backtrace to + the command in the source code that created the target is available. + The value is an unsigned integer 0-based index into the + ``backtraceGraph`` member's ``nodes`` array. + +``folder`` + Optional member that is present when the :prop_tgt:`FOLDER` target + property is set. The value is a JSON object with one member: + + ``name`` + A string specifying the name of the target folder. + +``paths`` + A JSON object containing members: + + ``source`` + A string specifying the path to the target's 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 target's 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. + +``nameOnDisk`` + Optional member that is present for executable and library targets + that are linked or archived into a single primary artifact. + The value is a string specifying the file name of that artifact on disk. + +``artifacts`` + Optional member that is present for executable and library targets + that produce artifacts on disk meant for consumption by dependents. + The value is a JSON array of entries corresponding to the artifacts. + Each entry is a JSON object containing one member: + + ``path`` + A string specifying the path to the file on disk, represented with + forward slashes. If the file is inside the top-level build directory + then the path is specified relative to that directory. + Otherwise the path is absolute. + +``isGeneratorProvided`` + Optional member that is present with boolean value ``true`` if the + target is provided by CMake's build system generator rather than by + a command in the source code. + +``install`` + Optional member that is present when the target has an :command:`install` + rule. The value is a JSON object with members: + + ``prefix`` + A JSON object specifying the installation prefix. It has one member: + + ``path`` + A string specifying the value of :variable:`CMAKE_INSTALL_PREFIX`. + + ``destinations`` + A JSON array of entries specifying an install destination path. + Each entry is a JSON object with members: + + ``path`` + A string specifying the install destination path. The path may + be absolute or relative to the install prefix. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to + the :command:`install` command invocation that specified this + destination is available. The value is an unsigned integer 0-based + index into the ``backtraceGraph`` member's ``nodes`` array. + +``link`` + Optional member that is present for executables and shared library + targets that link into a runtime binary. The value is a JSON object + with members describing the link step: + + ``language`` + A string specifying the language (e.g. ``C``, ``CXX``, ``Fortran``) + of the toolchain is used to invoke the linker. + + ``commandFragments`` + Optional member that is present when fragments of the link command + line invocation are available. The value is a JSON array of entries + specifying ordered fragments. Each entry is a JSON object with members: + + ``fragment`` + A string specifying a fragment of the link command line invocation. + The value is encoded in the build system's native shell format. + + ``role`` + A string specifying the role of the fragment's content: + + * ``flags``: link flags. + * ``libraries``: link library file paths or flags. + * ``libraryPath``: library search path flags. + * ``frameworkPath``: macOS framework search path flags. + + ``lto`` + Optional member that is present with boolean value ``true`` + when link-time optimization (a.k.a. interprocedural optimization + or link-time code generation) is enabled. + + ``sysroot`` + Optional member that is present when the :variable:`CMAKE_SYSROOT_LINK` + or :variable:`CMAKE_SYSROOT` variable is defined. The value is a + JSON object with one member: + + ``path`` + A string specifying the absolute path to the sysroot, represented + with forward slashes. + +``archive`` + Optional member that is present for static library targets. The value + is a JSON object with members describing the archive step: + + ``commandFragments`` + Optional member that is present when fragments of the archiver command + line invocation are available. The value is a JSON array of entries + specifying the fragments. Each entry is a JSON object with members: + + ``fragment`` + A string specifying a fragment of the archiver command line invocation. + The value is encoded in the build system's native shell format. + + ``role`` + A string specifying the role of the fragment's content: + + * ``flags``: archiver flags. + + ``lto`` + Optional member that is present with boolean value ``true`` + when link-time optimization (a.k.a. interprocedural optimization + or link-time code generation) is enabled. + +``dependencies`` + Optional member that is present when the target depends on other targets. + The value is a JSON array of entries corresponding to the dependencies. + Each entry is a JSON object with members: + + ``id`` + A string uniquely identifying the target on which this target depends. + This matches the main ``id`` member of the other target. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to + the :command:`add_dependencies`, :command:`target_link_libraries`, + or other command invocation that created this dependency is + available. The value is an unsigned integer 0-based index into + the ``backtraceGraph`` member's ``nodes`` array. + +``sources`` + A JSON array of entries corresponding to the target's source files. + Each entry is a JSON object with members: + + ``path`` + A string specifying the path to the source 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. + + ``compileGroupIndex`` + Optional member that is present when the source is compiled. + The value is an unsigned integer 0-based index into the + ``compileGroups`` array. + + ``sourceGroupIndex`` + Optional member that is present when the source is part of a source + group either via the :command:`source_group` command or by default. + The value is an unsigned integer 0-based index into the + ``sourceGroups`` array. + + ``isGenerated`` + Optional member that is present with boolean value ``true`` if + the source is :prop_sf:`GENERATED`. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to + the :command:`target_sources`, :command:`add_executable`, + :command:`add_library`, :command:`add_custom_target`, or other + command invocation that added this source to the target is + available. The value is an unsigned integer 0-based index into + the ``backtraceGraph`` member's ``nodes`` array. + +``sourceGroups`` + Optional member that is present when sources are grouped together by + the :command:`source_group` command or by default. The value is a + JSON array of entries corresponding to the groups. Each entry is + a JSON object with members: + + ``name`` + A string specifying the name of the source group. + + ``sourceIndexes`` + A JSON array listing the sources belonging to the group. + Each entry is an unsigned integer 0-based index into the + main ``sources`` array for the target. + +``compileGroups`` + Optional member that is present when the target has sources that compile. + The value is a JSON array of entries corresponding to groups of sources + that all compile with the same settings. Each entry is a JSON object + with members: + + ``sourceIndexes`` + A JSON array listing the sources belonging to the group. + Each entry is an unsigned integer 0-based index into the + main ``sources`` array for the target. + + ``language`` + A string specifying the language (e.g. ``C``, ``CXX``, ``Fortran``) + of the toolchain is used to compile the source file. + + ``compileCommandFragments`` + Optional member that is present when fragments of the compiler command + line invocation are available. The value is a JSON array of entries + specifying ordered fragments. Each entry is a JSON object with + one member: + + ``fragment`` + A string specifying a fragment of the compile command line invocation. + The value is encoded in the build system's native shell format. + + ``includes`` + Optional member that is present when there are include directories. + The value is a JSON array with an entry for each directory. Each + entry is a JSON object with members: + + ``path`` + A string specifying the path to the include directory, + represented with forward slashes. + + ``isSystem`` + Optional member that is present with boolean value ``true`` if + the include directory is marked as a system include directory. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to + the :command:`target_include_directories` or other command invocation + that added this include directory is available. The value is + an unsigned integer 0-based index into the ``backtraceGraph`` + member's ``nodes`` array. + + ``defines`` + Optional member that is present when there are preprocessor definitions. + The value is a JSON array with an entry for each definition. Each + entry is a JSON object with members: + + ``define`` + A string specifying the preprocessor definition in the format + ``<name>[=<value>]``, e.g. ``DEF`` or ``DEF=1``. + + ``backtrace`` + Optional member that is present when a CMake language backtrace to + the :command:`target_compile_definitions` or other command invocation + that added this preprocessor definition is available. The value is + an unsigned integer 0-based index into the ``backtraceGraph`` + member's ``nodes`` array. + + ``sysroot`` + Optional member that is present when the + :variable:`CMAKE_SYSROOT_COMPILE` or :variable:`CMAKE_SYSROOT` + variable is defined. The value is a JSON object with one member: + + ``path`` + A string specifying the absolute path to the sysroot, represented + with forward slashes. + +``backtraceGraph`` + A JSON object describing the graph of backtraces whose nodes are + referenced from ``backtrace`` members elsewhere. The members are: + + ``nodes`` + A JSON array listing nodes in the backtrace graph. Each entry + is a JSON object with members: + + ``file`` + An unsigned integer 0-based index into the backtrace ``files`` 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. + + ``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. + + ``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" +------------------- + +The ``cache`` object kind lists cache entries. These are the +:ref:`CMake Language Variables` stored in the persistent cache +(``CMakeCache.txt``) for the build tree. + +There is only one ``cache`` object major version, version 2. +Version 1 does not exist to avoid confusion with that from +:manual:`cmake-server(7)` mode. + +"cache" version 2 +^^^^^^^^^^^^^^^^^ + +``cache`` object version 2 is a JSON object: + +.. code-block:: json + + { + "kind": "cache", + "version": { "major": 2, "minor": 0 }, + "entries": [ + { + "name": "BUILD_SHARED_LIBS", + "value": "ON", + "type": "BOOL", + "properties": [ + { + "name": "HELPSTRING", + "value": "Build shared libraries" + } + ] + }, + { + "name": "CMAKE_GENERATOR", + "value": "Unix Makefiles", + "type": "INTERNAL", + "properties": [ + { + "name": "HELPSTRING", + "value": "Name of generator." + } + ] + } + ] + } + +The members specific to ``cache`` objects are: + +``entries`` + A JSON array whose entries are each a JSON object specifying a + cache entry. The members of each entry are: + + ``name`` + A string specifying the name of the entry. + + ``value`` + A string specifying the value of the entry. + + ``type`` + A string specifying the type of the entry used by + :manual:`cmake-gui(1)` to choose a widget for editing. + + ``properties`` + A JSON array of entries specifying associated + :ref:`cache entry properties <Cache Entry Properties>`. + Each entry is a JSON object containing members: + + ``name`` + A string specifying the name of the cache entry property. + + ``value`` + A string specifying the value of the cache entry property. + +Object Kind "cmakeFiles" +------------------------ + +The ``cmakeFiles`` object kind lists files used by CMake while +configuring and generating the build system. These include the +``CMakeLists.txt`` files as well as included ``.cmake`` files. + +There is only one ``cmakeFiles`` object major version, version 1. + +"cmakeFiles" version 1 +^^^^^^^^^^^^^^^^^^^^^^ + +``cmakeFiles`` object version 1 is a JSON object: + +.. code-block:: json + + { + "kind": "cmakeFiles", + "version": { "major": 1, "minor": 0 }, + "paths": { + "build": "/path/to/top-level-build-dir", + "source": "/path/to/top-level-source-dir" + }, + "inputs": [ + { + "path": "CMakeLists.txt" + }, + { + "isGenerated": true, + "path": "/path/to/top-level-build-dir/.../CMakeSystem.cmake" + }, + { + "isExternal": true, + "path": "/path/to/external/third-party/module.cmake" + }, + { + "isCMake": true, + "isExternal": true, + "path": "/path/to/cmake/Modules/CMakeGenericSystem.cmake" + } + ] + } + +The members specific to ``cmakeFiles`` objects are: + +``paths`` + A JSON object containing members: + + ``source`` + A string specifying the absolute path to the top-level source directory, + represented with forward slashes. + + ``build`` + A string specifying the absolute path to the top-level build directory, + represented with forward slashes. + +``inputs`` + A JSON array whose entries are each a JSON object specifying an input + file used by CMake when configuring and generating the build system. + The members of each entry are: + + ``path`` + A string specifying the path to an input file to CMake, 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. + + ``isGenerated`` + Optional member that is present with boolean value ``true`` + if the path specifies a file that is under the top-level + build directory and the build is out-of-source. + This member is not available on in-source builds. + + ``isExternal`` + Optional member that is present with boolean value ``true`` + if the path specifies a file that is not under the top-level + source or build directories. + + ``isCMake`` + Optional member that is present with boolean value ``true`` + if the path specifies a file in the CMake installation. diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index bddb17477..75f4bd48a 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -20,54 +20,74 @@ commands to populate those properties, such as :command:`target_link_libraries`, :command:`target_include_directories`, :command:`target_compile_definitions` and others. -This means that they enable conditional linking, conditional -definitions used when compiling, and conditional include directories and -more. The conditions may be based on the build configuration, target -properties, platform information or any other queryable information. +They enable conditional linking, conditional definitions used when compiling, +conditional include directories, and more. The conditions may be based on +the build configuration, target properties, platform information or any other +queryable information. -Logical Expressions -=================== +Generator expressions have the form ``$<...>``. To avoid confusion, this page +deviates from most of the CMake documentation in that it omits angular brackets +``<...>`` around placeholders like ``condition``, ``string``, ``target``, +among others. -Logical expressions are used to create conditional output. The basic -expressions are the ``0`` and ``1`` expressions. Because other logical -expressions evaluate to either ``0`` or ``1``, they can be composed to -create conditional output:: +Generator expressions can be nested, as shown in most of the examples below. - $<$<CONFIG:Debug>:DEBUG_MODE> +.. _`Boolean Generator Expressions`: -expands to ``DEBUG_MODE`` when the ``Debug`` configuration is used, and -otherwise expands to nothing. - -Available logical expressions are: - -``$<BOOL:...>`` - ``1`` if the ``...`` is true, else ``0`` -``$<AND:?[,?]...>`` - ``1`` if all ``?`` are ``1``, else ``0`` - - The ``?`` must always be either ``0`` or ``1`` in boolean expressions. - -``$<OR:?[,?]...>`` - ``0`` if all ``?`` are ``0``, else ``1`` -``$<NOT:?>`` - ``0`` if ``?`` is ``1``, else ``1`` -``$<IF:?,true-value...,false-value...>``` - ``true-value...`` if ``?`` is ``1``, ``false-value...`` if ``?`` is ``0`` -``$<STREQUAL:a,b>`` - ``1`` if ``a`` is STREQUAL ``b``, else ``0`` -``$<EQUAL:a,b>`` - ``1`` if ``a`` is EQUAL ``b`` in a numeric comparison, else ``0`` -``$<CONFIG:cfg>`` - ``1`` if config is ``cfg``, else ``0``. This is a case-insensitive comparison. - The mapping in :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by - this expression when it is evaluated on a property on an :prop_tgt:`IMPORTED` - target. -``$<PLATFORM_ID:comp>`` - ``1`` if the CMake-id of the platform matches ``comp``, otherwise ``0``. -``$<C_COMPILER_ID:comp>`` - ``1`` if the CMake-id of the C compiler matches ``comp``, otherwise ``0``. -``$<CXX_COMPILER_ID:comp>`` - ``1`` if the CMake-id of the CXX compiler matches ``comp``, otherwise ``0``. +Boolean Generator Expressions +============================= + +Boolean expressions evaluate to either ``0`` or ``1``. +They are typically used to construct the condition in a :ref:`conditional +generator expression<Conditional Generator Expressions>`. + +Available boolean expressions are: + +Logical Operators +----------------- + +``$<BOOL:string>`` + Converts ``string`` to ``0`` or ``1``. Evaluates to ``0`` if any of the + following is true: + + * ``string`` is empty, + * ``string`` is a case-insensitive equal of + ``0``, ``FALSE``, ``OFF``, ``N``, ``NO``, ``IGNORE``, or ``NOTFOUND``, or + * ``string`` ends in the suffix ``-NOTFOUND`` (case-sensitive). + + Otherwise evaluates to ``1``. + +``$<AND:conditions>`` + where ``conditions`` is a comma-separated list of boolean expressions. + Evaluates to ``1`` if all conditions are ``1``. + Otherwise evaluates to ``0``. + +``$<OR:conditions>`` + where ``conditions`` is a comma-separated list of boolean expressions. + Evaluates to ``1`` if at least one of the conditions is ``1``. + Otherwise evaluates to ``0``. + +``$<NOT:condition>`` + ``0`` if ``condition`` is ``1``, else ``1``. + +String Comparisons +------------------ + +``$<STREQUAL:string1,string2>`` + ``1`` if ``string1`` and ``string2`` are equal, else ``0``. + The comparison is case-sensitive. For a case-insensitive comparison, + combine with a :ref:`string transforming generator expression + <String Transforming Generator Expressions>`, + + .. code-block:: cmake + + $<STREQUAL:$<UPPER_CASE:${foo}>,"BAR"> # "1" if ${foo} is any of "BAR", "Bar", "bar", ... + +``$<EQUAL:value1,value2>`` + ``1`` if ``value1`` and ``value2`` are numerically equal, else ``0``. +``$<IN_LIST:string,list>`` + ``1`` if ``string`` is member of the semicolon-separated ``list``, else ``0``. + Uses case-sensitive comparisons. ``$<VERSION_LESS:v1,v2>`` ``1`` if ``v1`` is a version less than ``v2``, else ``0``. ``$<VERSION_GREATER:v1,v2>`` @@ -78,76 +98,185 @@ Available logical expressions are: ``1`` if ``v1`` is a version less than or equal to ``v2``, else ``0``. ``$<VERSION_GREATER_EQUAL:v1,v2>`` ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``. -``$<C_COMPILER_VERSION:ver>`` - ``1`` if the version of the C compiler matches ``ver``, otherwise ``0``. -``$<CXX_COMPILER_VERSION:ver>`` - ``1`` if the version of the CXX compiler matches ``ver``, otherwise ``0``. -``$<TARGET_POLICY:pol>`` - ``1`` if the policy ``pol`` was NEW when the 'head' target was created, - else ``0``. If the policy was not set, the warning message for the policy + + +Variable Queries +---------------- + +``$<TARGET_EXISTS:target>`` + ``1`` if ``target`` exists, else ``0``. +``$<CONFIG:cfg>`` + ``1`` if config is ``cfg``, else ``0``. This is a case-insensitive comparison. + The mapping in :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by + this expression when it is evaluated on a property on an :prop_tgt:`IMPORTED` + target. +``$<PLATFORM_ID:platform_ids>`` + where ``platform_ids`` is a comma-separated list. + ``1`` if the CMake's platform id matches any one of the entries in + ``platform_ids``, otherwise ``0``. + See also the :variable:`CMAKE_SYSTEM_NAME` variable. +``$<C_COMPILER_ID:compiler_ids>`` + where ``compiler_ids`` is a comma-separated list. + ``1`` if the CMake's compiler id of the C compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<CXX_COMPILER_ID:compiler_ids>`` + where ``compiler_ids`` is a comma-separated list. + ``1`` if the CMake's compiler id of the CXX compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<CUDA_COMPILER_ID:compiler_ids>`` + 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``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<OBJC_COMPILER_ID:compiler_ids>`` + 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``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<OBJCXX_COMPILER_ID:compiler_ids>`` + 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``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<Fortran_COMPILER_ID:compiler_ids>`` + where ``compiler_ids`` is a comma-separated list. + ``1`` if the CMake's compiler id of the Fortran compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<C_COMPILER_VERSION:version>`` + ``1`` if the version of the C compiler matches ``version``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<CXX_COMPILER_VERSION:version>`` + ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<CUDA_COMPILER_VERSION:version>`` + ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<OBJC_COMPILER_VERSION:version>`` + ``1`` if the version of the OBJC compiler matches ``version``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<OBJCXX_COMPILER_VERSION:version>`` + ``1`` if the version of the OBJCXX compiler matches ``version``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<Fortran_COMPILER_VERSION:version>`` + ``1`` if the version of the Fortran compiler matches ``version``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<TARGET_POLICY:policy>`` + ``1`` if the ``policy`` was NEW when the 'head' target was created, + else ``0``. If the ``policy`` was not set, the warning message for the policy will be emitted. This generator expression only works for a subset of policies. -``$<COMPILE_FEATURES:feature[,feature]...>`` - ``1`` if all of the ``feature`` features are available for the 'head' +``$<COMPILE_FEATURES:features>`` + 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 the link implementation of a target and if any dependency transitively increases the required :prop_tgt:`C_STANDARD` or :prop_tgt:`CXX_STANDARD` for the 'head' target, an error is reported. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. -``$<COMPILE_LANGUAGE:lang>`` - ``1`` when the language used for compilation unit matches ``lang``, - otherwise ``0``. This expression used to specify compile options for - source files of a particular language in a target. For example, to specify - the use of the ``-fno-exceptions`` compile option (compiler id checks - elided): + +.. _`Boolean COMPILE_LANGUAGE Generator Expression`: + +``$<COMPILE_LANG_AND_ID:language,compiler_ids>`` + ``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 + for the combination of ``$<COMPILE_LANGUAGE:language>`` and + ``$<LANG_COMPILER_ID:compiler_ids>``. This expression may be used to specify + compile options, compile definitions, and include directories for source files of a + particular language and compiler combination in a target. For example: .. code-block:: cmake - add_executable(myapp main.cpp foo.c bar.cpp) - target_compile_options(myapp - PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions> + add_executable(myapp main.cpp foo.c bar.cpp zot.cu) + target_compile_definitions(myapp + PRIVATE $<$<COMPILE_LANG_AND_ID:CXX,AppleClang,Clang>:COMPILING_CXX_WITH_CLANG> + $<$<COMPILE_LANG_AND_ID:CXX,Intel>:COMPILING_CXX_WITH_INTEL> + $<$<COMPILE_LANG_AND_ID:C,Clang>:COMPILING_C_WITH_CLANG> ) - This generator expression has limited use because it is not possible to - use it with the Visual Studio generators. Portable buildsystems would - not use this expression, and would create separate libraries for each - source file language instead: + This specifies the use of different compile definitions based on both + the compiler id and compilation language. This example will have a + ``COMPILING_CXX_WITH_CLANG`` compile definition when Clang is the CXX + compiler, and ``COMPILING_CXX_WITH_INTEL`` when Intel is the CXX compiler. + Likewise when the C compiler is Clang it will only see the ``COMPILING_C_WITH_CLANG`` + definition. + + Without the ``COMPILE_LANG_AND_ID`` generator expression the same logic + would be expressed as: .. code-block:: cmake - add_library(myapp_c foo.c) - add_library(myapp_cxx bar.cpp) - target_compile_options(myapp_cxx PUBLIC -fno-exceptions) - add_executable(myapp main.cpp) - target_link_libraries(myapp myapp_c myapp_cxx) + target_compile_definitions(myapp + PRIVATE $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:AppleClang,Clang>>:COMPILING_CXX_WITH_CLANG> + $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:Intel>>:COMPILING_CXX_WITH_INTEL> + $<$<AND:$<COMPILE_LANGUAGE:C>,$<C_COMPILER_ID:Clang>>:COMPILING_C_WITH_CLANG> + ) - The ``Makefile`` and ``Ninja`` based generators can also use this - expression to specify compile-language specific compile definitions - and include directories: +``$<COMPILE_LANGUAGE:languages>`` + ``1`` when the language used for compilation unit matches any of the entries + in ``languages``, otherwise ``0``. This expression may be used to specify + compile options, compile definitions, and include directories for source files of a + particular language in a target. For example: .. code-block:: cmake - add_executable(myapp main.cpp foo.c bar.cpp) + add_executable(myapp main.cpp foo.c bar.cpp zot.cu) + target_compile_options(myapp + PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions> + ) target_compile_definitions(myapp PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX> + $<$<COMPILE_LANGUAGE:CUDA>:COMPILING_CUDA> ) target_include_directories(myapp - PRIVATE $<$<COMPILE_LANGUAGE:CXX>:/opt/foo/cxx_headers> + PRIVATE $<$<COMPILE_LANGUAGE:CXX,CUDA>:/opt/foo/headers> ) -Informational Expressions -========================= + This specifies the use of the ``-fno-exceptions`` compile option, + ``COMPILING_CXX`` compile definition, and ``cxx_headers`` include + directory for C++ only (compiler id checks elided). It also specifies + a ``COMPILING_CUDA`` compile definition for CUDA. + + Note that with :ref:`Visual Studio Generators` and :generator:`Xcode` there + is no way to represent target-wide compile definitions or include directories + separately for ``C`` and ``CXX`` languages. + Also, with :ref:`Visual Studio Generators` there is no way to represent + target-wide flags separately for ``C`` and ``CXX`` languages. Under these + generators, expressions for both C and C++ sources will be evaluated + using ``CXX`` if there are any C++ sources and otherwise using ``C``. + A workaround is to create separate libraries for each source file language + instead: -These expressions expand to some information. The information may be used -directly, eg:: + .. code-block:: cmake + + add_library(myapp_c foo.c) + add_library(myapp_cxx bar.cpp) + target_compile_options(myapp_cxx PUBLIC -fno-exceptions) + add_executable(myapp main.cpp) + target_link_libraries(myapp myapp_c myapp_cxx) + +String-Valued Generator Expressions +=================================== + +These expressions expand to some string. +For example, + +.. code-block:: cmake include_directories(/usr/include/$<CXX_COMPILER_ID>/) expands to ``/usr/include/GNU/`` or ``/usr/include/Clang/`` etc, depending on -the Id of the compiler. +the compiler identifier. + +String-valued expressions may also be combined with other expressions. +Here an example for a string-valued expression within a boolean expressions +within a conditional expression: -These expressions may also may be combined with logical expressions:: +.. code-block:: cmake $<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER> @@ -155,20 +284,147 @@ expands to ``OLD_COMPILER`` if the :variable:`CMAKE_CXX_COMPILER_VERSION <CMAKE_<LANG>_COMPILER_VERSION>` is less than 4.2.0. -Available informational expressions are: +And here two nested string-valued expressions: + +.. code-block:: cmake + + -I$<JOIN:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>, -I> + +generates a string of the entries in the :prop_tgt:`INCLUDE_DIRECTORIES` target +property with each entry preceded by ``-I``. + +Expanding on the previous example, if one first wants to check if the +``INCLUDE_DIRECTORIES`` property is non-empty, then it is advisable to +introduce a helper variable to keep the code readable: + +.. code-block:: cmake + + set(prop "$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>") # helper variable + $<$<BOOL:${prop}>:-I$<JOIN:${prop}, -I>> + +The following string-valued generator expressions are available: + +Escaped Characters +------------------ + +String literals to escape the special meaning a character would otherwise have: + +``$<ANGLE-R>`` + A literal ``>``. Used for example to compare strings that contain a ``>``. +``$<COMMA>`` + A literal ``,``. Used for example to compare strings which contain a ``,``. +``$<SEMICOLON>`` + A literal ``;``. Used to prevent list expansion on an argument with ``;``. + +.. _`Conditional Generator Expressions`: + +Conditional Expressions +----------------------- + +Conditional generator expressions depend on a boolean condition +that must be ``0`` or ``1``. + +``$<condition:true_string>`` + Evaluates to ``true_string`` if ``condition`` is ``1``. + Otherwise evaluates to the empty string. + +``$<IF:condition,true_string,false_string>`` + Evaluates to ``true_string`` if ``condition`` is ``1``. + Otherwise evaluates to ``false_string``. + +Typically, the ``condition`` is a :ref:`boolean generator expression +<Boolean Generator Expressions>`. For instance, + +.. code-block:: cmake + + $<$<CONFIG:Debug>:DEBUG_MODE> + +expands to ``DEBUG_MODE`` when the ``Debug`` configuration is used, and +otherwise expands to the empty string. + +.. _`String Transforming Generator Expressions`: + +String Transformations +---------------------- + +``$<JOIN:list,string>`` + Joins the list with the content of ``string``. +``$<REMOVE_DUPLICATES:list>`` + Removes duplicated items in the given ``list``. +``$<FILTER:list,INCLUDE|EXCLUDE,regex>`` + Includes or removes items from ``list`` that match the regular expression ``regex``. +``$<LOWER_CASE:string>`` + Content of ``string`` converted to lower case. +``$<UPPER_CASE:string>`` + Content of ``string`` converted to upper case. + +``$<GENEX_EVAL:expr>`` + 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. +``$<TARGET_GENEX_EVAL:tgt,expr>`` + 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. + + Having the capability to evaluate generator expressions is very useful when + you want to manage custom properties supporting generator expressions. + For example: + + .. code-block:: cmake + + add_library(foo ...) + + set_property(TARGET foo PROPERTY + CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS> + ) + + add_custom_target(printFooKeys + COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS> + ) + + This naive implementation of the ``printFooKeys`` custom command is wrong + because ``CUSTOM_KEYS`` target property is not evaluated and the content + is passed as is (i.e. ``$<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>``). + + To have the expected result (i.e. ``FOO_EXTRA_THINGS`` if config is + ``Debug``), it is required to evaluate the output of + ``$<TARGET_PROPERTY:foo,CUSTOM_KEYS>``: + + .. code-block:: cmake + + add_custom_target(printFooKeys + COMMAND ${CMAKE_COMMAND} -E + echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>> + ) + +Variable Queries +---------------- -``$<CONFIGURATION>`` - Configuration name. Deprecated. Use ``CONFIG`` instead. ``$<CONFIG>`` - Configuration name + Configuration name. +``$<CONFIGURATION>`` + Configuration name. Deprecated since CMake 3.0. Use ``CONFIG`` instead. ``$<PLATFORM_ID>`` - The CMake-id of the platform. + The current system's CMake platform id. See also the :variable:`CMAKE_SYSTEM_NAME` variable. ``$<C_COMPILER_ID>`` - The CMake-id of the C compiler used. + The CMake's compiler id of the C compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. ``$<CXX_COMPILER_ID>`` - The CMake-id of the CXX compiler used. + The CMake's compiler id of the CXX compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<CUDA_COMPILER_ID>`` + The CMake's compiler id of the CUDA compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<OBJC_COMPILER_ID>`` + The CMake's compiler id of the OBJC compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<OBJCXX_COMPILER_ID>`` + The CMake's compiler id of the OBJCXX compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<Fortran_COMPILER_ID>`` + The CMake's compiler id of the Fortran compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. ``$<C_COMPILER_VERSION>`` The version of the C compiler used. @@ -176,14 +432,111 @@ Available informational expressions are: ``$<CXX_COMPILER_VERSION>`` The version of the CXX compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<CUDA_COMPILER_VERSION>`` + The version of the CUDA compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<OBJC_COMPILER_VERSION>`` + The version of the OBJC compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<OBJCXX_COMPILER_VERSION>`` + The version of the OBJCXX compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<Fortran_COMPILER_VERSION>`` + The version of the Fortran compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<COMPILE_LANGUAGE>`` + The compile language of source files when evaluating compile options. + See :ref:`the related boolean expression + <Boolean COMPILE_LANGUAGE Generator Expression>` + ``$<COMPILE_LANGUAGE:language>`` + for notes about the portability of this generator expression. + +Target-Dependent Queries +------------------------ + +``$<TARGET_NAME_IF_EXISTS:tgt>`` + Expands to the ``tgt`` if the given target exists, an empty string + otherwise. ``$<TARGET_FILE:tgt>`` - Full path to main file (.exe, .so.1.2, .a) where ``tgt`` is the name of a target. + Full path to main file (.exe, .so.1.2, .a) where ``tgt`` is the name of a + target. +``$<TARGET_FILE_BASE_NAME:tgt>`` + Base name of main file where ``tgt`` is the name of a target. + + The base name corresponds to the target file name (see + ``$<TARGET_FILE_NAME:tgt>``) without prefix and suffix. For example, if + target file name is ``libbase.so``, the base name is ``base``. + + See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, + :prop_tgt:`LIBRARY_OUTPUT_NAME` and :prop_tgt:`RUNTIME_OUTPUT_NAME` + target properties and their configuration specific variants + :prop_tgt:`OUTPUT_NAME_<CONFIG>`, :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>`, + :prop_tgt:`LIBRARY_OUTPUT_NAME_<CONFIG>` and + :prop_tgt:`RUNTIME_OUTPUT_NAME_<CONFIG>`. + + The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target + properties can also be considered. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. +``$<TARGET_FILE_PREFIX:tgt>`` + Prefix of main file where ``tgt`` is the name of a target. + + See also the :prop_tgt:`PREFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. +``$<TARGET_FILE_SUFFIX:tgt>`` + Suffix of main file where ``tgt`` is the name of a target. + + The suffix corresponds to the file extension (such as ".so" or ".exe"). + + See also the :prop_tgt:`SUFFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. ``$<TARGET_FILE_NAME:tgt>`` Name of main file (.exe, .so.1.2, .a). ``$<TARGET_FILE_DIR:tgt>`` Directory of main file (.exe, .so.1.2, .a). ``$<TARGET_LINKER_FILE:tgt>`` File used to link (.a, .lib, .so) where ``tgt`` is the name of a target. +``$<TARGET_LINKER_FILE_BASE_NAME:tgt>`` + Base name of file used to link where ``tgt`` is the name of a target. + + The base name corresponds to the target linker file name (see + ``$<TARGET_LINKER_FILE_NAME:tgt>``) without prefix and suffix. For example, + if target file name is ``libbase.a``, the base name is ``base``. + + See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, + and :prop_tgt:`LIBRARY_OUTPUT_NAME` target properties and their configuration + specific variants :prop_tgt:`OUTPUT_NAME_<CONFIG>`, + :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>` and + :prop_tgt:`LIBRARY_OUTPUT_NAME_<CONFIG>`. + + The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target + properties can also be considered. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. +``$<TARGET_LINKER_FILE_PREFIX:tgt>`` + Prefix of file used to link where ``tgt`` is the name of a target. + + See also the :prop_tgt:`PREFIX` and :prop_tgt:`IMPORT_PREFIX` target + properties. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. +``$<TARGET_LINKER_FILE_SUFFIX:tgt>`` + 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"). + + See also the :prop_tgt:`SUFFIX` and :prop_tgt:`IMPORT_SUFFIX` target + properties. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. ``$<TARGET_LINKER_FILE_NAME:tgt>`` Name of file used to link (.a, .lib, .so). ``$<TARGET_LINKER_FILE_DIR:tgt>`` @@ -201,6 +554,22 @@ Available informational expressions are: See also the :prop_tgt:`PDB_NAME` and :prop_tgt:`PDB_OUTPUT_DIRECTORY` target properties and their configuration specific variants :prop_tgt:`PDB_NAME_<CONFIG>` and :prop_tgt:`PDB_OUTPUT_DIRECTORY_<CONFIG>`. +``$<TARGET_PDB_FILE_BASE_NAME:tgt>`` + Base name of the linker generated program database file (.pdb) + where ``tgt`` is the name of a target. + + The base name corresponds to the target PDB file name (see + ``$<TARGET_PDB_FILE_NAME:tgt>``) without prefix and suffix. For example, + if target file name is ``base.pdb``, the base name is ``base``. + + See also the :prop_tgt:`PDB_NAME` target property and its configuration + specific variant :prop_tgt:`PDB_NAME_<CONFIG>`. + + The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target + properties can also be considered. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. ``$<TARGET_PDB_FILE_NAME:tgt>`` Name of the linker generated program database file (.pdb). ``$<TARGET_PDB_FILE_DIR:tgt>`` @@ -221,49 +590,17 @@ Available informational expressions are: expression is evaluated on. ``$<TARGET_PROPERTY:prop>`` Value of the property ``prop`` on the target on which the generator - expression is evaluated. + expression is evaluated. Note that for generator expressions in + :ref:`Target Usage Requirements` this is the value of the property + on the consuming target rather than the target specifying the + requirement. ``$<INSTALL_PREFIX>`` Content of the install prefix when the target is exported via :command:`install(EXPORT)` and empty otherwise. -``$<COMPILE_LANGUAGE>`` - The compile language of source files when evaluating compile options. See - the unary version for notes about portability of this generator - expression. -Output Expressions -================== +Output-Related Expressions +-------------------------- -These expressions generate output, in some cases depending on an input. These -expressions may be combined with other expressions for information or logical -comparison:: - - -I$<JOIN:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>, -I> - -generates a string of the entries in the :prop_tgt:`INCLUDE_DIRECTORIES` target -property with each entry preceded by ``-I``. Note that a more-complete use -in this situation would require first checking if the INCLUDE_DIRECTORIES -property is non-empty:: - - $<$<BOOL:${prop}>:-I$<JOIN:${prop}, -I>> - -where ``${prop}`` refers to a helper variable:: - - set(prop "$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>") - -Available output expressions are: - -``$<0:...>`` - Empty string (ignores ``...``) -``$<1:...>`` - Content of ``...`` -``$<JOIN:list,...>`` - Joins the list with the content of ``...`` -``$<ANGLE-R>`` - A literal ``>``. Used to compare strings which contain a ``>`` for example. -``$<COMMA>`` - A literal ``,``. Used to compare strings which contain a ``,`` for example. -``$<SEMICOLON>`` - A literal ``;``. Used to prevent list expansion on an argument with ``;``. ``$<TARGET_NAME:...>`` Marks ``...`` as being the name of a target. This is required if exporting targets to multiple dependent export sets. The ``...`` must be a literal @@ -282,16 +619,39 @@ Available output expressions are: Content of ``...`` when the property is exported using :command:`export`, or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise. -``$<LOWER_CASE:...>`` - Content of ``...`` converted to lower case. -``$<UPPER_CASE:...>`` - Content of ``...`` converted to upper case. ``$<MAKE_C_IDENTIFIER:...>`` - Content of ``...`` converted to a C identifier. + Content of ``...`` converted to a C identifier. The conversion follows the + same behavior as :command:`string(MAKE_C_IDENTIFIER)`. ``$<TARGET_OBJECTS:objLib>`` - List of objects resulting from build of ``objLib``. ``objLib`` must be an - object of type ``OBJECT_LIBRARY``. + List of objects resulting from build of ``objLib``. ``$<SHELL_PATH:...>`` 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. + +Debugging +========= + +Since generator expressions are evaluated during generation of the buildsystem, +and not during processing of ``CMakeLists.txt`` files, it is not possible to +inspect their result with the :command:`message()` command. + +One possible way to generate debug messages is to add a custom target, + +.. code-block:: cmake + + add_custom_target(genexdebug COMMAND ${CMAKE_COMMAND} -E echo "$<...>") + +The shell command ``make genexdebug`` (invoked after execution of ``cmake``) +would then print the result of ``$<...>``. + +Another way is to write debug messages to a file: + +.. code-block:: cmake + + file(GENERATE OUTPUT filename CONTENT "$<...>") diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index a37c65b39..41f765220 100644 --- a/Help/manual/cmake-generators.7.rst +++ b/Help/manual/cmake-generators.7.rst @@ -27,6 +27,8 @@ when creating a new build tree. CMake Generators ================ +.. _`Command-Line Build Tool Generators`: + Command-Line Build Tool Generators ---------------------------------- @@ -58,6 +60,8 @@ Ninja Generator /generator/Ninja +.. _`IDE Build Tool Generators`: + IDE Build Tool Generators ------------------------- @@ -83,6 +87,7 @@ Visual Studio Generators /generator/Visual Studio 12 2013 /generator/Visual Studio 14 2015 /generator/Visual Studio 15 2017 + /generator/Visual Studio 16 2019 Other Generators ^^^^^^^^^^^^^^^^ @@ -108,6 +113,5 @@ The following extra generators are known to CMake. /generator/CodeBlocks /generator/CodeLite /generator/Eclipse CDT4 - /generator/KDevelop3 /generator/Kate /generator/Sublime Text 2 diff --git a/Help/manual/cmake-gui.1.rst b/Help/manual/cmake-gui.1.rst index 032b51fda..ff8311bbe 100644 --- a/Help/manual/cmake-gui.1.rst +++ b/Help/manual/cmake-gui.1.rst @@ -9,24 +9,33 @@ Synopsis .. parsed-literal:: cmake-gui [<options>] - cmake-gui [<options>] (<path-to-source> | <path-to-existing-build>) + cmake-gui [<options>] {<path-to-source> | <path-to-existing-build>} + cmake-gui [<options>] -S <path-to-source> -B <path-to-build> Description =========== -The "cmake-gui" executable is the CMake GUI. Project configuration +The **cmake-gui** executable is the CMake GUI. Project configuration settings may be specified interactively. Brief instructions are provided at the bottom of the window when the program is running. CMake is a cross-platform build system generator. Projects specify their build process with platform-independent CMake listfiles included -in each directory of a source tree with the name CMakeLists.txt. +in each directory of a source tree with the name ``CMakeLists.txt``. Users build a project by using CMake to generate a build system for a native tool on their platform. Options ======= +``-S <path-to-source>`` + Path to root directory of the CMake project to build. + +``-B <path-to-build>`` + Path to directory which CMake will use as the root of build directory. + + If the directory doesn't already exist CMake will make it. + .. include:: OPTIONS_HELP.txt See Also diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index 27b5d30b4..4ca8e3a26 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -183,18 +183,18 @@ same length: .. productionlist:: bracket_argument: `bracket_open` `bracket_content` `bracket_close` - bracket_open: '[' '='{len} '[' - bracket_content: <any text not containing a `bracket_close` - : of the same {len} as the `bracket_open`> - bracket_close: ']' '='{len} ']' + bracket_open: '[' '='* '[' + bracket_content: <any text not containing a `bracket_close` with + : the same number of '=' as the `bracket_open`> + bracket_close: ']' '='* ']' .. raw:: latex \end{small} -An opening bracket of length *len >= 0* is written ``[`` followed -by *len* ``=`` followed by ``[`` and the corresponding closing -bracket is written ``]`` followed by *len* ``=`` followed by ``]``. +An opening bracket is written ``[`` followed by zero or more ``=`` followed +by ``[``. The corresponding closing bracket is written ``]`` followed +by the same number of ``=`` followed by ``]``. Brackets do not nest. A unique length may always be chosen for the opening and closing brackets to contain closing brackets of other lengths. @@ -206,9 +206,10 @@ enclosed content, such as `Escape Sequences`_ or `Variable References`_, is performed. A bracket argument is always given to the command invocation as exactly one argument. -For example: +.. No code-block syntax highlighting in the following example + (long string literal not supported by our cmake.py) -.. code-block:: cmake +For example:: message([=[ This is the first line in a bracket argument with bracket length 1. @@ -253,16 +254,22 @@ closing quotes. Both `Escape Sequences`_ and `Variable References`_ are evaluated. A quoted argument is always given to the command invocation as exactly one argument. +.. No code-block syntax highlighting in the following example + (escape \" not supported by our cmake.py) + For example: -:: +.. code-block:: cmake - message("This is a quoted argument containing multiple lines. - This is always one argument even though it contains a ; character. - Both \\-escape sequences and ${variable} references are evaluated. - The text does not end on an escaped double-quote like \". - It does end in an unescaped double quote. - ") + message("This is a quoted argument containing multiple lines. + This is always one argument even though it contains a ; character. + Both \\-escape sequences and ${variable} references are evaluated. + The text does not end on an escaped double-quote like \". + It does end in an unescaped double quote. + ") + +.. No code-block syntax highlighting in the following example + (for conformity with the two above examples) The final ``\`` on any line ending in an odd number of backslashes is treated as a line continuation and ignored along with the @@ -270,11 +277,11 @@ immediately following newline character. For example: .. code-block:: cmake - message("\ - This is the first line of a quoted argument. \ - In fact it is the only line but since it is long \ - the source code uses line continuation.\ - ") + message("\ + This is the first line of a quoted argument. \ + In fact it is the only line but since it is long \ + the source code uses line continuation.\ + ") .. note:: CMake versions prior to 3.0 do not support continuation with ``\``. @@ -334,6 +341,8 @@ For example: beginning of an unquoted argument, and are treated as part of the content. For example, the unquoted arguments ``-Da="b c"``, ``-Da=$(v)``, and ``a" "b"c"d`` are each interpreted literally. + They may instead be written as quoted arguments ``"-Da=\"b c\""``, + ``"-Da=$(v)"``, and ``"a\" \"b\"c\"d"``, respectively. Make-style references are treated literally as part of the content and do not undergo variable expansion. They are treated as part @@ -380,7 +389,7 @@ historical considerations.) Variable References ------------------- -A *variable reference* has the form ``${variable_name}`` and is +A *variable reference* has the form ``${<variable>}`` and is evaluated inside a `Quoted Argument`_ or an `Unquoted Argument`_. A variable reference is replaced by the value of the variable, or by the empty string if the variable is not set. @@ -389,14 +398,24 @@ inside out, e.g. ``${outer_${inner_variable}_variable}``. Literal variable references may consist of alphanumeric characters, the characters ``/_.+-``, and `Escape Sequences`_. Nested references -may be used to evaluate variables of any name. (See also policy -:policy:`CMP0053` documentation for historical considerations.) +may be used to evaluate variables of any name. See also policy +:policy:`CMP0053` documentation for historical considerations and reasons why +the ``$`` is also technically permitted but is discouraged. The `Variables`_ section documents the scope of variable names and how their values are set. -An *environment variable reference* has the form ``$ENV{VAR}`` and -is evaluated in the same contexts as a normal variable reference. +An *environment variable reference* has the form ``$ENV{<variable>}``. +See the `Environment Variables`_ section for more information. + +A *cache variable reference* has the form ``$CACHE{<variable>}``. +See :variable:`CACHE` for more information. + +The :command:`if` command has a special condition syntax that +allows for variable references in the short form ``<variable>`` +instead of ``${<variable>}``. +However, environment and cache variables always need to be +referenced as ``$ENV{<variable>}`` or ``$CACHE{<variable>}``. Comments -------- @@ -411,7 +430,7 @@ comments: a `Bracket Comment`_ and a `Line Comment`_. Bracket Comment ^^^^^^^^^^^^^^^ -A ``#`` immediately followed by a `Bracket Argument`_ forms a +A ``#`` immediately followed by a :token:`bracket_open` forms a *bracket comment* consisting of the entire bracket enclosure: .. raw:: latex @@ -442,7 +461,7 @@ For example: Line Comment ^^^^^^^^^^^^ -A ``#`` not immediately followed by a `Bracket Argument`_ forms a +A ``#`` not immediately followed by a :token:`bracket_open` forms a *line comment* that runs until the end of the line: .. raw:: latex @@ -450,7 +469,7 @@ A ``#`` not immediately followed by a `Bracket Argument`_ forms a \begin{small} .. productionlist:: - line_comment: '#' <any text not starting in a `bracket_argument` + line_comment: '#' <any text not starting in a `bracket_open` : and not containing a `newline`> .. raw:: latex @@ -514,7 +533,7 @@ Function Scope create commands that, when invoked, process the recorded commands in a new variable binding scope. A variable "set" or "unset" binds in this scope and is visible for the current function and - any nested calls, but not after the function returns. + any nested calls within it, but not after the function returns. Directory Scope Each of the `Directories`_ in a source tree has its own variable @@ -541,11 +560,41 @@ to the binding in the current directory scope, if any. If a is found, or no binding is found, CMake then searches for a cache entry. If a cache entry is found, its value is used. Otherwise, the variable reference evaluates to an empty string. +The ``$CACHE{VAR}`` syntax can be used to do direct cache entry +lookups. -The :manual:`cmake-variables(7)` manual documents many variables +The :manual:`cmake-variables(7)` manual documents the many variables that are provided by CMake or have meaning to CMake when set by project code. +.. _`CMake Language Environment Variables`: + +Environment Variables +===================== + +Environment Variables are like ordinary `Variables`_, with the +following differences: + +Scope + Environment variables have global scope in a CMake process. + They are never cached. + +References + `Variable References`_ have the form ``$ENV{<variable>}``. + +Initialization + Initial values of the CMake environment variables are those of + the calling process. + Values can be changed using the :command:`set` and :command:`unset` + commands. + These commands only affect the running CMake process, + not the system environment at large. + Changed values are not written back to the calling process, + and they are not seen by subsequent build or test processes. + +The :manual:`cmake-env-variables(7)` manual documents environment +variables that have special meaning to CMake. + .. _`CMake Language Lists`: Lists diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 4a03b7a80..c60dc4010 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -3,12 +3,14 @@ cmake-modules(7) **************** -.. only:: html +The modules listed here are part of the CMake distribution. +Projects may provide further modules; their location(s) +can be specified in the :variable:`CMAKE_MODULE_PATH` variable. - .. contents:: +Utility Modules +^^^^^^^^^^^^^^^ -All Modules -=========== +These modules are loaded using the :command:`include` command. .. toctree:: :maxdepth: 1 @@ -26,6 +28,7 @@ All Modules /module/CheckFortranCompilerFlag /module/CheckFortranFunctionExists /module/CheckFortranSourceCompiles + /module/CheckFortranSourceRuns /module/CheckFunctionExists /module/CheckIPOSupported /module/CheckIncludeFileCXX @@ -33,6 +36,13 @@ All Modules /module/CheckIncludeFiles /module/CheckLanguage /module/CheckLibraryExists + /module/CheckOBJCCompilerFlag + /module/CheckOBJCSourceCompiles + /module/CheckOBJCSourceRuns + /module/CheckOBJCXXCompilerFlag + /module/CheckOBJCXXSourceCompiles + /module/CheckOBJCXXSourceRuns + /module/CheckPIESupported /module/CheckPrototypeDefinition /module/CheckStructHasMember /module/CheckSymbolExists @@ -41,33 +51,19 @@ All Modules /module/CMakeAddFortranSubdirectory /module/CMakeBackwardCompatibilityCXX /module/CMakeDependentOption - /module/CMakeDetermineVSServicePack - /module/CMakeExpandImportedTargets /module/CMakeFindDependencyMacro /module/CMakeFindFrameworks /module/CMakeFindPackageMode - /module/CMakeForceCompiler /module/CMakeGraphVizOptions /module/CMakePackageConfigHelpers - /module/CMakeParseArguments /module/CMakePrintHelpers /module/CMakePrintSystemInformation /module/CMakePushCheckState /module/CMakeVerifyManifest - /module/CPackArchive - /module/CPackBundle /module/CPackComponent - /module/CPackCygwin - /module/CPackDeb - /module/CPackDMG /module/CPackIFW /module/CPackIFWConfigureFile - /module/CPackNSIS - /module/CPackPackageMaker - /module/CPackProductBuild - /module/CPackRPM /module/CPack - /module/CPackWIX /module/CSharpUtilities /module/CTest /module/CTestCoverageCollectGCOV @@ -79,6 +75,40 @@ All Modules /module/ExternalData /module/ExternalProject /module/FeatureSummary + /module/FetchContent + /module/FindPackageHandleStandardArgs + /module/FindPackageMessage + /module/FortranCInterface + /module/GenerateExportHeader + /module/GetPrerequisites + /module/GNUInstallDirs + /module/GoogleTest + /module/InstallRequiredSystemLibraries + /module/ProcessorCount + /module/SelectLibraryConfigurations + /module/SquishTestScript + /module/TestBigEndian + /module/TestForANSIForScope + /module/TestForANSIStreamHeaders + /module/TestForSSTREAM + /module/TestForSTDNamespace + /module/UseEcos + /module/UseJavaClassFilelist + /module/UseJava + /module/UseJavaSymlinks + /module/UseSWIG + /module/UsewxWidgets + /module/WriteCompilerDetectionHeader + +Find Modules +^^^^^^^^^^^^ + +These modules search for third-party software. +They are normally called through the :command:`find_package` command. + +.. toctree:: + :maxdepth: 1 + /module/FindALSA /module/FindArmadillo /module/FindASPELL @@ -91,7 +121,6 @@ All Modules /module/FindBZip2 /module/FindCABLE /module/FindCoin3D - /module/FindCUDA /module/FindCups /module/FindCURL /module/FindCurses @@ -102,10 +131,12 @@ All Modules /module/FindDCMTK /module/FindDevIL /module/FindDoxygen + /module/FindEnvModules /module/FindEXPAT /module/FindFLEX /module/FindFLTK2 /module/FindFLTK + /module/FindFontconfig /module/FindFreetype /module/FindGCCXML /module/FindGDAL @@ -128,6 +159,7 @@ All Modules /module/FindIcotool /module/FindICU /module/FindImageMagick + /module/FindIconv /module/FindIntl /module/FindITK /module/FindJasper @@ -139,6 +171,7 @@ All Modules /module/FindLAPACK /module/FindLATEX /module/FindLibArchive + /module/FindLibinput /module/FindLibLZMA /module/FindLibXml2 /module/FindLibXslt @@ -152,6 +185,8 @@ All Modules /module/FindMPEG2 /module/FindMPEG /module/FindMPI + /module/FindODBC + /module/FindOpenACC /module/FindOpenAL /module/FindOpenCL /module/FindOpenGL @@ -179,8 +214,7 @@ All Modules /module/FindosgViewer /module/FindosgVolume /module/FindosgWidget - /module/FindPackageHandleStandardArgs - /module/FindPackageMessage + /module/FindPatch /module/FindPerlLibs /module/FindPerl /module/FindPHP4 @@ -191,11 +225,11 @@ All Modules /module/FindPostgreSQL /module/FindProducer /module/FindProtobuf - /module/FindPythonInterp - /module/FindPythonLibs + /module/FindPython + /module/FindPython2 + /module/FindPython3 /module/FindQt3 /module/FindQt4 - /module/FindQt /module/FindQuickTime /module/FindRTI /module/FindRuby @@ -207,6 +241,7 @@ All Modules /module/FindSDL_ttf /module/FindSelfPackers /module/FindSquish + /module/FindSQLite3 /module/FindSubversion /module/FindSWIG /module/FindTCL @@ -220,36 +255,63 @@ All Modules /module/FindWget /module/FindWish /module/FindwxWidgets - /module/FindwxWindows /module/FindXCTest /module/FindXalanC /module/FindXercesC /module/FindX11 /module/FindXMLRPC /module/FindZLIB - /module/FortranCInterface - /module/GenerateExportHeader - /module/GetPrerequisites - /module/GNUInstallDirs - /module/GoogleTest - /module/InstallRequiredSystemLibraries + +Deprecated Modules +^^^^^^^^^^^^^^^^^^^ + +Deprecated Utility Modules +========================== + +.. toctree:: + :maxdepth: 1 + + /module/CMakeDetermineVSServicePack + /module/CMakeExpandImportedTargets + /module/CMakeForceCompiler + /module/CMakeParseArguments /module/MacroAddFileDependencies - /module/ProcessorCount - /module/SelectLibraryConfigurations - /module/SquishTestScript - /module/TestBigEndian /module/TestCXXAcceptsFlag - /module/TestForANSIForScope - /module/TestForANSIStreamHeaders - /module/TestForSSTREAM - /module/TestForSTDNamespace - /module/UseEcos - /module/UseJavaClassFilelist - /module/UseJava - /module/UseJavaSymlinks /module/UsePkgConfig - /module/UseSWIG - /module/UsewxWidgets /module/Use_wxWindows /module/WriteBasicConfigVersionFile - /module/WriteCompilerDetectionHeader + +Deprecated Find Modules +======================= + +.. toctree:: + :maxdepth: 1 + + /module/FindCUDA + /module/FindPythonInterp + /module/FindPythonLibs + /module/FindQt + /module/FindwxWindows + +Legacy CPack Modules +==================== + +These modules used to be mistakenly exposed to the user, and have been moved +out of user visibility. They are for CPack internal use, and should never be +used directly. + +.. toctree:: + :maxdepth: 1 + + /module/CPackArchive + /module/CPackBundle + /module/CPackCygwin + /module/CPackDeb + /module/CPackDMG + /module/CPackFreeBSD + /module/CPackNSIS + /module/CPackNuGet + /module/CPackPackageMaker + /module/CPackProductBuild + /module/CPackRPM + /module/CPackWIX diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst index c9442bc19..4b2934a8e 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -12,7 +12,7 @@ Introduction Packages provide dependency information to CMake based buildsystems. Packages are found with the :command:`find_package` command. The result of -using ``find_package`` is either a set of :prop_tgt:`IMPORTED` targets, or +using :command:`find_package` is either a set of :prop_tgt:`IMPORTED` targets, or a set of variables corresponding to build-relevant information. Using Packages @@ -73,7 +73,7 @@ Handling of ``COMPONENTS`` and ``OPTIONAL_COMPONENTS`` is defined by the package. By setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to -``TRUE``, the ``PackageName`` package will not be searched, and will always +``TRUE``, the ``<PackageName>`` package will not be searched, and will always be ``NOTFOUND``. .. _`Config File Packages`: @@ -92,9 +92,9 @@ packages, that is, they belong with the header files and any other files provided to assist downstreams in using the package. A set of variables which provide package status information are also set -automatically when using a config-file package. The ``<Package>_FOUND`` +automatically when using a config-file package. The ``<PackageName>_FOUND`` variable is set to true or false, depending on whether the package was -found. The ``<Package>_DIR`` cache variable is set to the location of the +found. The ``<PackageName>_DIR`` cache variable is set to the location of the package configuration file. Find-module Packages @@ -108,10 +108,10 @@ file, it is not shipped with upstream, but is used by downstream to find the files by guessing locations of files with platform-specific hints. Unlike the case of an upstream-provided package configuration file, no single point -of reference identifies the package as being found, so the ``<Package>_FOUND`` +of reference identifies the package as being found, so the ``<PackageName>_FOUND`` variable is not automatically set by the :command:`find_package` command. It can still be expected to be set by convention however and should be set by -the author of the Find-module. Similarly there is no ``<Package>_DIR`` variable, +the author of the Find-module. Similarly there is no ``<PackageName>_DIR`` variable, but each of the artifacts such as library locations and header file locations provide a separate cache variable. @@ -197,7 +197,7 @@ When the :command:`find_package` command loads a version file it first sets the following variables: ``PACKAGE_FIND_NAME`` - The <package> name + The ``<PackageName>`` ``PACKAGE_FIND_VERSION`` Full requested version string @@ -240,26 +240,26 @@ variables. When the version file claims to be an acceptable match for the requested version the find_package command sets the following variables for use by the project: -``<package>_VERSION`` +``<PackageName>_VERSION`` Full provided version string -``<package>_VERSION_MAJOR`` +``<PackageName>_VERSION_MAJOR`` Major version if provided, else 0 -``<package>_VERSION_MINOR`` +``<PackageName>_VERSION_MINOR`` Minor version if provided, else 0 -``<package>_VERSION_PATCH`` +``<PackageName>_VERSION_PATCH`` Patch version if provided, else 0 -``<package>_VERSION_TWEAK`` +``<PackageName>_VERSION_TWEAK`` Tweak version if provided, else 0 -``<package>_VERSION_COUNT`` +``<PackageName>_VERSION_COUNT`` Number of version components, 0 to 4 The variables report the version of the package that was actually found. -The ``<package>`` part of their name matches the argument given to the +The ``<PackageName>`` part of their name matches the argument given to the :command:`find_package` command. .. _`Creating Packages`: @@ -347,8 +347,8 @@ The :module:`CMakePackageConfigHelpers` module provides a macro for creating a simple ``ConfigVersion.cmake`` file. This file sets the version of the package. It is read by CMake when :command:`find_package` is called to determine the compatibility with the requested version, and to set some -version-specific variables ``<Package>_VERSION``, ``<Package>_VERSION_MAJOR``, -``<Package>_VERSION_MINOR`` etc. The :command:`install(EXPORT)` command is +version-specific variables ``<PackageName>_VERSION``, ``<PackageName>_VERSION_MAJOR``, +``<PackageName>_VERSION_MINOR`` etc. The :command:`install(EXPORT)` command is used to export the targets in the ``ClimbingStatsTargets`` export-set, defined previously by the :command:`install(TARGETS)` command. This command generates the ``ClimbingStatsTargets.cmake`` file to contain :prop_tgt:`IMPORTED` @@ -432,8 +432,8 @@ the dependency is not found, along with a diagnostic that the ``ClimbingStats`` package can not be used without the ``Stats`` package. If ``COMPONENTS`` are specified when the downstream uses :command:`find_package`, -they are listed in the ``<Package>_FIND_COMPONENTS`` variable. If a particular -component is non-optional, then the ``<Package>_FIND_REQUIRED_<comp>`` will +they are listed in the ``<PackageName>_FIND_COMPONENTS`` variable. If a particular +component is non-optional, then the ``<PackageName>_FIND_REQUIRED_<comp>`` will be true. This can be tested with logic in the package configuration file: .. code-block:: cmake @@ -580,8 +580,8 @@ non-standard install locations or directly in their own build trees. A project may populate either the user or system registry (using its own means, see below) to refer to its location. In either case the package should store at the registered location a -`Package Configuration File`_ (``<package>Config.cmake``) and optionally a -`Package Version File`_ (``<package>ConfigVersion.cmake``). +`Package Configuration File`_ (``<PackageName>Config.cmake``) and optionally a +`Package Version File`_ (``<PackageName>ConfigVersion.cmake``). The :command:`find_package` command searches the two package registries as two of the search steps specified in its documentation. If it has @@ -603,18 +603,18 @@ must be manually taught to register their packages if desired. On Windows the user package registry is stored in the Windows registry under a key in ``HKEY_CURRENT_USER``. -A ``<package>`` may appear under registry key:: +A ``<PackageName>`` may appear under registry key:: - HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<package> + HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<PackageName> as a ``REG_SZ`` value, with arbitrary name, that specifies the directory containing the package configuration file. On UNIX platforms the user package registry is stored in the user home -directory under ``~/.cmake/packages``. A ``<package>`` may appear under +directory under ``~/.cmake/packages``. A ``<PackageName>`` may appear under the directory:: - ~/.cmake/packages/<package> + ~/.cmake/packages/<PackageName> as a file, with arbitrary name, whose content specifies the directory containing the package configuration file. @@ -629,10 +629,10 @@ CMake currently provides no interface to add to the system package registry. Installers must be manually taught to register their packages if desired. On Windows the system package registry is stored in the Windows registry -under a key in ``HKEY_LOCAL_MACHINE``. A ``<package>`` may appear under +under a key in ``HKEY_LOCAL_MACHINE``. A ``<PackageName>`` may appear under registry key:: - HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<package> + HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<PackageName> as a ``REG_SZ`` value, with arbitrary name, that specifies the directory containing the package configuration file. @@ -647,12 +647,22 @@ Disabling the Package Registry In some cases using the Package Registries is not desirable. CMake allows one to disable them using the following variables: - * :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` disables the - :command:`export(PACKAGE)` command. - * :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` disables the - User Package Registry in all the :command:`find_package` calls. - * :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` disables - the System Package Registry in all the :command:`find_package` calls. +* The :command:`export(PACKAGE)` command does not populate the user + package registry when :policy:`CMP0090` is set to ``NEW`` unless the + :variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable explicitly enables it. + When :policy:`CMP0090` is *not* set to ``NEW`` then + :command:`export(PACKAGE)` populates the user package registry unless + the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable explicitly + disables it. +* :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` disables the + User Package Registry in all the :command:`find_package` calls when + set to ``FALSE``. +* Deprecated :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` disables the + User Package Registry in all the :command:`find_package` calls when set + to ``TRUE``. This variable is ignored when + :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` has been set. +* :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` disables + the System Package Registry in all the :command:`find_package` calls. Package Registry Example ------------------------ diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 7b858176f..44ea1a8fd 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,84 @@ 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.16 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0097: ExternalProject_Add with GIT_SUBMODULES "" initializes no submodules. </policy/CMP0097> + CMP0096: project() preserves leading zeros in version components. </policy/CMP0096> + CMP0095: RPATH entries are properly escaped in the intermediary CMake install script. </policy/CMP0095> + +Policies Introduced by CMake 3.15 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0094: FindPython3, FindPython2 and FindPython use LOCATION for lookup strategy. </policy/CMP0094> + CMP0093: FindBoost reports Boost_VERSION in x.y.z format. </policy/CMP0093> + CMP0092: MSVC warning flags are not in CMAKE_{C,CXX}_FLAGS by default. </policy/CMP0092> + CMP0091: MSVC runtime library flags are selected by an abstraction. </policy/CMP0091> + CMP0090: export(PACKAGE) does not populate package registry by default. </policy/CMP0090> + CMP0089: Compiler id for IBM Clang-based XL compilers is now XLClang. </policy/CMP0089> + +Policies Introduced by CMake 3.14 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0088: FindBISON runs bison in CMAKE_CURRENT_BINARY_DIR when executing. </policy/CMP0088> + CMP0087: install(SCRIPT | CODE) supports generator expressions. </policy/CMP0087> + CMP0086: UseSWIG honors SWIG_MODULE_NAME via -module flag. </policy/CMP0086> + CMP0085: IN_LIST generator expression handles empty list items. </policy/CMP0085> + CMP0084: The FindQt module does not exist for find_package(). </policy/CMP0084> + CMP0083: Add PIE options when linking executable. </policy/CMP0083> + CMP0082: Install rules from add_subdirectory() are interleaved with those in caller. </policy/CMP0082> + + +Policies Introduced by CMake 3.13 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0081: Relative paths not allowed in LINK_DIRECTORIES target property. </policy/CMP0081> + CMP0080: BundleUtilities cannot be included at configure time. </policy/CMP0080> + CMP0079: target_link_libraries allows use with targets in other directories. </policy/CMP0079> + CMP0078: UseSWIG generates standard target names. </policy/CMP0078> + CMP0077: option() honors normal variables. </policy/CMP0077> + CMP0076: target_sources() command converts relative paths to absolute. </policy/CMP0076> + +Policies Introduced by CMake 3.12 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0075: Include file check macros honor CMAKE_REQUIRED_LIBRARIES. </policy/CMP0075> + CMP0074: find_package uses PackageName_ROOT variables. </policy/CMP0074> + CMP0073: Do not produce legacy _LIB_DEPENDS cache entries. </policy/CMP0073> + +Policies Introduced by CMake 3.11 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0072: FindOpenGL prefers GLVND by default when available. </policy/CMP0072> + +Policies Introduced by CMake 3.10 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0071: Let AUTOMOC and AUTOUIC process GENERATED files. </policy/CMP0071> + CMP0070: Define file(GENERATE) behavior for relative paths. </policy/CMP0070> + Policies Introduced by CMake 3.9 ================================ diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index ec25596f3..e7043714c 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -23,6 +23,7 @@ Properties of Global Scope /prop_gbl/AUTORCC_SOURCE_GROUP /prop_gbl/CMAKE_C_KNOWN_FEATURES /prop_gbl/CMAKE_CXX_KNOWN_FEATURES + /prop_gbl/CMAKE_ROLE /prop_gbl/DEBUG_CONFIGURATIONS /prop_gbl/DISABLED_FEATURES /prop_gbl/ENABLED_FEATURES @@ -40,6 +41,7 @@ Properties of Global Scope /prop_gbl/JOB_POOLS /prop_gbl/PREDEFINED_TARGETS_FOLDER /prop_gbl/ECLIPSE_EXTRA_NATURES + /prop_gbl/ECLIPSE_EXTRA_CPROJECT_CONTENTS /prop_gbl/REPORT_UNDEFINED_PROPERTIES /prop_gbl/RULE_LAUNCH_COMPILE /prop_gbl/RULE_LAUNCH_CUSTOM @@ -59,7 +61,7 @@ Properties on Directories .. toctree:: :maxdepth: 1 - /prop_dir/ADDITIONAL_MAKE_CLEAN_FILES + /prop_dir/ADDITIONAL_CLEAN_FILES /prop_dir/BINARY_DIR /prop_dir/BUILDSYSTEM_TARGETS /prop_dir/CACHE_VARIABLES @@ -74,7 +76,9 @@ Properties on Directories /prop_dir/INCLUDE_REGULAR_EXPRESSION /prop_dir/INTERPROCEDURAL_OPTIMIZATION_CONFIG /prop_dir/INTERPROCEDURAL_OPTIMIZATION + /prop_dir/LABELS /prop_dir/LINK_DIRECTORIES + /prop_dir/LINK_OPTIONS /prop_dir/LISTFILE_STACK /prop_dir/MACROS /prop_dir/PARENT_DIRECTORY @@ -83,7 +87,8 @@ Properties on Directories /prop_dir/RULE_LAUNCH_LINK /prop_dir/SOURCE_DIR /prop_dir/SUBDIRECTORIES - /prop_dir/TEST_INCLUDE_FILE + /prop_dir/TESTS + /prop_dir/TEST_INCLUDE_FILES /prop_dir/VARIABLES /prop_dir/VS_GLOBAL_SECTION_POST_section /prop_dir/VS_GLOBAL_SECTION_PRE_section @@ -97,6 +102,7 @@ Properties on Targets .. toctree:: :maxdepth: 1 + /prop_tgt/ADDITIONAL_CLEAN_FILES /prop_tgt/ALIASED_TARGET /prop_tgt/ANDROID_ANT_ADDITIONAL_OPTIONS /prop_tgt/ANDROID_API @@ -120,17 +126,26 @@ Properties on Targets /prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG /prop_tgt/ARCHIVE_OUTPUT_NAME /prop_tgt/AUTOGEN_BUILD_DIR + /prop_tgt/AUTOGEN_ORIGIN_DEPENDS + /prop_tgt/AUTOGEN_PARALLEL /prop_tgt/AUTOGEN_TARGET_DEPENDS + /prop_tgt/AUTOMOC_COMPILER_PREDEFINES /prop_tgt/AUTOMOC_DEPEND_FILTERS + /prop_tgt/AUTOMOC_EXECUTABLE + /prop_tgt/AUTOMOC_MACRO_NAMES /prop_tgt/AUTOMOC_MOC_OPTIONS + /prop_tgt/AUTOMOC_PATH_PREFIX /prop_tgt/AUTOMOC /prop_tgt/AUTOUIC + /prop_tgt/AUTOUIC_EXECUTABLE /prop_tgt/AUTOUIC_OPTIONS /prop_tgt/AUTOUIC_SEARCH_PATHS /prop_tgt/AUTORCC + /prop_tgt/AUTORCC_EXECUTABLE /prop_tgt/AUTORCC_OPTIONS /prop_tgt/BINARY_DIR /prop_tgt/BUILD_RPATH + /prop_tgt/BUILD_RPATH_USE_ORIGIN /prop_tgt/BUILD_WITH_INSTALL_NAME_DIR /prop_tgt/BUILD_WITH_INSTALL_RPATH /prop_tgt/BUNDLE_EXTENSION @@ -138,6 +153,7 @@ Properties on Targets /prop_tgt/C_EXTENSIONS /prop_tgt/C_STANDARD /prop_tgt/C_STANDARD_REQUIRED + /prop_tgt/COMMON_LANGUAGE_RUNTIME /prop_tgt/COMPATIBLE_INTERFACE_BOOL /prop_tgt/COMPATIBLE_INTERFACE_NUMBER_MAX /prop_tgt/COMPATIBLE_INTERFACE_NUMBER_MIN @@ -165,22 +181,30 @@ Properties on Targets /prop_tgt/DEBUG_POSTFIX /prop_tgt/DEFINE_SYMBOL /prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY + /prop_tgt/DEPLOYMENT_ADDITIONAL_FILES + /prop_tgt/DISABLE_PRECOMPILE_HEADERS + /prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION /prop_tgt/EchoString /prop_tgt/ENABLE_EXPORTS /prop_tgt/EXCLUDE_FROM_ALL /prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG /prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD /prop_tgt/EXPORT_NAME + /prop_tgt/EXPORT_PROPERTIES /prop_tgt/FOLDER /prop_tgt/Fortran_FORMAT /prop_tgt/Fortran_MODULE_DIRECTORY /prop_tgt/FRAMEWORK /prop_tgt/FRAMEWORK_VERSION /prop_tgt/GENERATOR_FILE_NAME + /prop_tgt/GHS_INTEGRITY_APP + /prop_tgt/GHS_NO_SOURCE_GROUP_FILE /prop_tgt/GNUtoMS /prop_tgt/HAS_CXX /prop_tgt/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM + /prop_tgt/IMPORTED_COMMON_LANGUAGE_RUNTIME /prop_tgt/IMPORTED_CONFIGURATIONS + /prop_tgt/IMPORTED_GLOBAL /prop_tgt/IMPORTED_IMPLIB_CONFIG /prop_tgt/IMPORTED_IMPLIB /prop_tgt/IMPORTED_LIBNAME_CONFIG @@ -206,6 +230,7 @@ Properties on Targets /prop_tgt/IMPORT_SUFFIX /prop_tgt/INCLUDE_DIRECTORIES /prop_tgt/INSTALL_NAME_DIR + /prop_tgt/INSTALL_REMOVE_ENVIRONMENT_RPATH /prop_tgt/INSTALL_RPATH /prop_tgt/INSTALL_RPATH_USE_LINK_PATH /prop_tgt/INTERFACE_AUTOUIC_OPTIONS @@ -213,7 +238,11 @@ Properties on Targets /prop_tgt/INTERFACE_COMPILE_FEATURES /prop_tgt/INTERFACE_COMPILE_OPTIONS /prop_tgt/INTERFACE_INCLUDE_DIRECTORIES + /prop_tgt/INTERFACE_LINK_DEPENDS + /prop_tgt/INTERFACE_LINK_DIRECTORIES /prop_tgt/INTERFACE_LINK_LIBRARIES + /prop_tgt/INTERFACE_LINK_OPTIONS + /prop_tgt/INTERFACE_PRECOMPILE_HEADERS /prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE /prop_tgt/INTERFACE_SOURCES /prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES @@ -225,6 +254,7 @@ Properties on Targets /prop_tgt/LABELS /prop_tgt/LANG_CLANG_TIDY /prop_tgt/LANG_COMPILER_LAUNCHER + /prop_tgt/LANG_CPPCHECK /prop_tgt/LANG_CPPLINT /prop_tgt/LANG_INCLUDE_WHAT_YOU_USE /prop_tgt/LANG_VISIBILITY_PRESET @@ -235,6 +265,7 @@ Properties on Targets /prop_tgt/LINK_DEPENDS_NO_SHARED /prop_tgt/LINK_DEPENDS /prop_tgt/LINKER_LANGUAGE + /prop_tgt/LINK_DIRECTORIES /prop_tgt/LINK_FLAGS_CONFIG /prop_tgt/LINK_FLAGS /prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG @@ -242,6 +273,7 @@ Properties on Targets /prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG /prop_tgt/LINK_INTERFACE_MULTIPLICITY /prop_tgt/LINK_LIBRARIES + /prop_tgt/LINK_OPTIONS /prop_tgt/LINK_SEARCH_END_STATIC /prop_tgt/LINK_SEARCH_START_STATIC /prop_tgt/LINK_WHAT_YOU_USE @@ -253,9 +285,16 @@ Properties on Targets /prop_tgt/MACOSX_RPATH /prop_tgt/MANUALLY_ADDED_DEPENDENCIES /prop_tgt/MAP_IMPORTED_CONFIG_CONFIG + /prop_tgt/MSVC_RUNTIME_LIBRARY /prop_tgt/NAME /prop_tgt/NO_SONAME /prop_tgt/NO_SYSTEM_FROM_IMPORTED + /prop_tgt/OBJC_EXTENSIONS + /prop_tgt/OBJC_STANDARD + /prop_tgt/OBJC_STANDARD_REQUIRED + /prop_tgt/OBJCXX_EXTENSIONS + /prop_tgt/OBJCXX_STANDARD + /prop_tgt/OBJCXX_STANDARD_REQUIRED /prop_tgt/OSX_ARCHITECTURES_CONFIG /prop_tgt/OSX_ARCHITECTURES /prop_tgt/OUTPUT_NAME_CONFIG @@ -265,6 +304,8 @@ Properties on Targets /prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG /prop_tgt/PDB_OUTPUT_DIRECTORY /prop_tgt/POSITION_INDEPENDENT_CODE + /prop_tgt/PRECOMPILE_HEADERS + /prop_tgt/PRECOMPILE_HEADERS_REUSE_FROM /prop_tgt/PREFIX /prop_tgt/PRIVATE_HEADER /prop_tgt/PROJECT_LABEL @@ -283,25 +324,43 @@ Properties on Targets /prop_tgt/SOVERSION /prop_tgt/STATIC_LIBRARY_FLAGS_CONFIG /prop_tgt/STATIC_LIBRARY_FLAGS + /prop_tgt/STATIC_LIBRARY_OPTIONS /prop_tgt/SUFFIX + /prop_tgt/Swift_DEPENDENCIES_FILE + /prop_tgt/Swift_LANGUAGE_VERSION + /prop_tgt/Swift_MODULE_DIRECTORY + /prop_tgt/Swift_MODULE_NAME /prop_tgt/TYPE + /prop_tgt/UNITY_BUILD + /prop_tgt/UNITY_BUILD_BATCH_SIZE + /prop_tgt/UNITY_BUILD_CODE_AFTER_INCLUDE + /prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE /prop_tgt/VERSION /prop_tgt/VISIBILITY_INLINES_HIDDEN /prop_tgt/VS_CONFIGURATION_TYPE + /prop_tgt/VS_DEBUGGER_COMMAND + /prop_tgt/VS_DEBUGGER_COMMAND_ARGUMENTS + /prop_tgt/VS_DEBUGGER_ENVIRONMENT /prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY /prop_tgt/VS_DESKTOP_EXTENSIONS_VERSION /prop_tgt/VS_DOTNET_REFERENCE_refname + /prop_tgt/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname /prop_tgt/VS_DOTNET_REFERENCES /prop_tgt/VS_DOTNET_REFERENCES_COPY_LOCAL /prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION + /prop_tgt/VS_DPI_AWARE /prop_tgt/VS_GLOBAL_KEYWORD /prop_tgt/VS_GLOBAL_PROJECT_TYPES /prop_tgt/VS_GLOBAL_ROOTNAMESPACE /prop_tgt/VS_GLOBAL_variable /prop_tgt/VS_IOT_EXTENSIONS_VERSION /prop_tgt/VS_IOT_STARTUP_TASK + /prop_tgt/VS_JUST_MY_CODE_DEBUGGING /prop_tgt/VS_KEYWORD /prop_tgt/VS_MOBILE_EXTENSIONS_VERSION + /prop_tgt/VS_NO_SOLUTION_DEPLOY + /prop_tgt/VS_PACKAGE_REFERENCES + /prop_tgt/VS_PROJECT_IMPORT /prop_tgt/VS_SCC_AUXPATH /prop_tgt/VS_SCC_LOCALPATH /prop_tgt/VS_SCC_PROJECTNAME @@ -316,7 +375,28 @@ Properties on Targets /prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS /prop_tgt/XCODE_ATTRIBUTE_an-attribute /prop_tgt/XCODE_EXPLICIT_FILE_TYPE + /prop_tgt/XCODE_GENERATE_SCHEME /prop_tgt/XCODE_PRODUCT_TYPE + /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER + /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN + /prop_tgt/XCODE_SCHEME_ARGUMENTS + /prop_tgt/XCODE_SCHEME_DEBUG_AS_ROOT + /prop_tgt/XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING + /prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER + /prop_tgt/XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS + /prop_tgt/XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE + /prop_tgt/XCODE_SCHEME_ENVIRONMENT + /prop_tgt/XCODE_SCHEME_EXECUTABLE + /prop_tgt/XCODE_SCHEME_GUARD_MALLOC + /prop_tgt/XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP + /prop_tgt/XCODE_SCHEME_MALLOC_GUARD_EDGES + /prop_tgt/XCODE_SCHEME_MALLOC_SCRIBBLE + /prop_tgt/XCODE_SCHEME_MALLOC_STACK + /prop_tgt/XCODE_SCHEME_THREAD_SANITIZER + /prop_tgt/XCODE_SCHEME_THREAD_SANITIZER_STOP + /prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER + /prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP + /prop_tgt/XCODE_SCHEME_ZOMBIE_OBJECTS /prop_tgt/XCTEST .. _`Test Properties`: @@ -340,10 +420,13 @@ Properties on Tests /prop_test/LABELS /prop_test/MEASUREMENT /prop_test/PASS_REGULAR_EXPRESSION + /prop_test/PROCESSOR_AFFINITY /prop_test/PROCESSORS /prop_test/REQUIRED_FILES + /prop_test/RESOURCE_GROUPS /prop_test/RESOURCE_LOCK /prop_test/RUN_SERIAL + /prop_test/SKIP_REGULAR_EXPRESSION /prop_test/SKIP_RETURN_CODE /prop_test/TIMEOUT /prop_test/TIMEOUT_AFTER_MATCH @@ -363,10 +446,12 @@ Properties on Source Files /prop_sf/AUTORCC_OPTIONS /prop_sf/COMPILE_DEFINITIONS /prop_sf/COMPILE_FLAGS + /prop_sf/COMPILE_OPTIONS /prop_sf/EXTERNAL_OBJECT /prop_sf/Fortran_FORMAT /prop_sf/GENERATED /prop_sf/HEADER_FILE_ONLY + /prop_sf/INCLUDE_DIRECTORIES /prop_sf/KEEP_EXTENSION /prop_sf/LABELS /prop_sf/LANGUAGE @@ -378,6 +463,10 @@ Properties on Source Files /prop_sf/SKIP_AUTOMOC /prop_sf/SKIP_AUTORCC /prop_sf/SKIP_AUTOUIC + /prop_sf/SKIP_PRECOMPILE_HEADERS + /prop_sf/SKIP_UNITY_BUILD_INCLUSION + /prop_sf/Swift_DEPENDENCIES_FILE + /prop_sf/Swift_DIAGNOSTICS_FILE /prop_sf/SYMBOLIC /prop_sf/VS_COPY_TO_OUT_DIR /prop_sf/VS_CSHARP_tagname @@ -385,10 +474,15 @@ Properties on Source Files /prop_sf/VS_DEPLOYMENT_LOCATION /prop_sf/VS_INCLUDE_IN_VSIX /prop_sf/VS_RESOURCE_GENERATOR + /prop_sf/VS_SHADER_DISABLE_OPTIMIZATIONS + /prop_sf/VS_SHADER_ENABLE_DEBUG /prop_sf/VS_SHADER_ENTRYPOINT /prop_sf/VS_SHADER_FLAGS /prop_sf/VS_SHADER_MODEL + /prop_sf/VS_SHADER_OBJECT_FILE_NAME + /prop_sf/VS_SHADER_OUTPUT_HEADER_FILE /prop_sf/VS_SHADER_TYPE + /prop_sf/VS_SHADER_VARIABLE_NAME /prop_sf/VS_TOOL_OVERRIDE.rst /prop_sf/VS_XAML_TYPE /prop_sf/WRAP_EXCLUDE @@ -433,7 +527,9 @@ Deprecated Properties on Directories .. toctree:: :maxdepth: 1 + /prop_dir/ADDITIONAL_MAKE_CLEAN_FILES /prop_dir/COMPILE_DEFINITIONS_CONFIG + /prop_dir/TEST_INCLUDE_FILE Deprecated Properties on Targets diff --git a/Help/manual/cmake-qt.7.rst b/Help/manual/cmake-qt.7.rst index b7f16b9ea..d8d61729e 100644 --- a/Help/manual/cmake-qt.7.rst +++ b/Help/manual/cmake-qt.7.rst @@ -44,14 +44,10 @@ Qt Build Tools Qt relies on some bundled tools for code generation, such as ``moc`` for meta-object code generation, ``uic`` for widget layout and population, -and ``rcc`` for virtual filesystem content generation. These tools may be +and ``rcc`` for virtual file system content generation. These tools may be automatically invoked by :manual:`cmake(1)` if the appropriate conditions are met. The automatic tool invocation may be used with both Qt 4 and Qt 5. -The tools are executed as part of a synthesized custom target generated by -CMake. Target dependencies may be added to that custom target by adding them -to the :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property. - AUTOMOC ^^^^^^^ @@ -59,9 +55,10 @@ The :prop_tgt:`AUTOMOC` target property controls whether :manual:`cmake(1)` inspects the C++ files in the target to determine if they require ``moc`` to be run, and to create rules to execute ``moc`` at the appropriate time. -If a ``Q_OBJECT`` or ``Q_GADGET`` macro is found in a header file, ``moc`` -will be run on the file. The result will be put into a file named according -to ``moc_<basename>.cpp``. If the macro is found in a C++ implementation +If a macro from :prop_tgt:`AUTOMOC_MACRO_NAMES` is found in a header file, +``moc`` will be run on the file. The result will be put into a file named +according to ``moc_<basename>.cpp``. +If the macro is found in a C++ implementation file, the moc output will be put into a file named according to ``<basename>.moc``, following the Qt conventions. The ``<basename>.moc`` must be included by the user in the C++ implementation file with a preprocessor @@ -72,6 +69,10 @@ Included ``moc_*.cpp`` and ``*.moc`` files will be generated in the automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`. * This differs from CMake 3.7 and below; see their documentation for details. + +* For :prop_gbl:`multi configuration generators <GENERATOR_IS_MULTI_CONFIG>`, + the include directory is ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>``. + * See :prop_tgt:`AUTOGEN_BUILD_DIR`. Not included ``moc_<basename>.cpp`` files will be generated in custom @@ -91,6 +92,9 @@ following targets by setting the :variable:`CMAKE_AUTOMOC` variable. The options to pass to ``moc``. The :variable:`CMAKE_AUTOMOC_MOC_OPTIONS` variable may be populated to pre-set the options for all following targets. +Additional macro names to search for can be added to +:prop_tgt:`AUTOMOC_MACRO_NAMES`. + Additional ``moc`` dependency file names can be extracted from source code by using :prop_tgt:`AUTOMOC_DEPEND_FILTERS`. @@ -124,6 +128,10 @@ The generated generated ``ui_*.h`` files are placed in the automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`. * This differs from CMake 3.7 and below; see their documentation for details. + +* For :prop_gbl:`multi configuration generators <GENERATOR_IS_MULTI_CONFIG>`, + the include directory is ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>``. + * See :prop_tgt:`AUTOGEN_BUILD_DIR`. The :prop_tgt:`AUTOUIC` target property may be pre-set for all following @@ -202,6 +210,34 @@ overrides options from the :prop_tgt:`AUTORCC_OPTIONS` target property. Source files can be excluded from :prop_tgt:`AUTORCC` processing by enabling :prop_sf:`SKIP_AUTORCC` or the broader :prop_sf:`SKIP_AUTOGEN`. +The ``<ORIGIN>_autogen`` target +=============================== + +The ``moc`` and ``uic`` tools are executed as part of a synthesized +``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` generated by +CMake. By default that ``<ORIGIN>_autogen`` target inherits the dependencies +of the ``<ORIGIN>`` target (see :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`). +Target dependencies may be added to the ``<ORIGIN>_autogen`` target by adding +them to the :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property. + +Visual Studio Generators +======================== + +When using the :manual:`Visual Studio generators <cmake-generators(7)>`, CMake +generates a ``PRE_BUILD`` :command:`custom command <add_custom_command>` +instead of the ``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` +(for :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`). +This isn't always possible though and +an ``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` is used, +when either + +- the ``<ORIGIN>`` target depends on :prop_sf:`GENERATED` files which aren't + excluded from :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` by + :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC`, :prop_sf:`SKIP_AUTOGEN` + or :policy:`CMP0071` +- :prop_tgt:`AUTOGEN_TARGET_DEPENDS` lists a source file +- :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET` is enabled + qtmain.lib on Windows ===================== diff --git a/Help/manual/cmake-server.7.rst b/Help/manual/cmake-server.7.rst index 9520cc140..8f10b9f0e 100644 --- a/Help/manual/cmake-server.7.rst +++ b/Help/manual/cmake-server.7.rst @@ -7,6 +7,11 @@ cmake-server(7) .. contents:: +.. deprecated:: 3.15 + + This will be removed from a future version of CMake. + Clients should use the :manual:`cmake-file-api(7)` instead. + Introduction ============ @@ -49,10 +54,12 @@ Operation Start :manual:`cmake(1)` in the server command mode, supplying the path to the build directory to process:: - cmake -E server (--debug|--pipe <NAMED_PIPE>) + cmake -E server (--debug|--pipe=<NAMED_PIPE>) The server will communicate using stdin/stdout (with the ``--debug`` parameter) -or using a named pipe (with the ``--pipe <NAMED_PIPE>`` parameter). +or using a named pipe (with the ``--pipe=<NAMED_PIPE>`` parameter). Note +that "named pipe" refers to a local domain socket on Unix and to a named pipe +on Windows. When connecting to the server (via named pipe or by starting it in ``--debug`` mode), the server will reply with a hello message:: @@ -162,7 +169,7 @@ When the server is busy for a long time, it is polite to send back replies of type "progress" to the client. These will contain a "progressMessage" with a string describing the action currently taking place as well as "progressMinimum", "progressMaximum" and "progressCurrent" with integer values -describing the range of progess. +describing the range of progress. Messages of type "progress" will be followed by more "progress" messages or with a message of type "reply" or "error" that complete the request. @@ -254,6 +261,11 @@ versions supported by the cmake server. These are JSON objects with "major" and as experimental. These will contain the "isExperimental" key set to true. Enabling these requires a special command line argument when starting the cmake server mode. +Within a "major" version all "minor" versions are fully backwards compatible. +New "minor" versions may introduce functionality in such a way that existing +clients of the same "major" version will continue to work, provided they +ignore keys in the output that they do not know about. + Example:: [== "CMake Server" ==[ @@ -268,8 +280,9 @@ The first request that the client may send to the server is of type "handshake". This request needs to pass one of the "supportedProtocolVersions" of the "hello" type response received earlier back to the server in the "protocolVersion" field. - -Each protocol version may request additional attributes to be present. +Giving the "major" version of the requested protocol version will make the server +use the latest minor version of that protocol. Use this if you do not explicitly +need to depend on a specific minor version. Protocol version 1.0 requires the following attributes to be set: @@ -280,6 +293,10 @@ Protocol version 1.0 requires the following attributes to be set: * "platform" with the generator platform (if supported by the generator) * "toolset" with the generator toolset (if supported by the generator) +Protocol version 1.2 makes all but the build directory optional, provided +there is a valid cache in the build directory that contains all the other +information already. + Example:: [== "CMake Server" ==[ @@ -448,6 +465,11 @@ Each project object can have the following keys: "name" contains the (sub-)projects name. +"minimumCMakeVersion" + contains the minimum cmake version allowed for this project, null if the + project doesn't specify one. +"hasInstallRule" + true if the project contains any install rules, false otherwise. "sourceDirectory" contains the current source directory "buildDirectory" @@ -471,6 +493,12 @@ Each target object can have the following keys: contains the current source directory. "buildDirectory" contains the current build directory. +"isGeneratorProvided" + true if the target is auto-created by a generator, false otherwise +"hasInstallRule" + true if the target contains any install rules, false otherwise. +"installPaths" + full path to the destination directories defined by target install rules. "artifacts" with a list of build artifacts. The list is sorted with the most important artifacts first (e.g. a .DLL file is listed before a @@ -572,6 +600,51 @@ CMake will reply:: ]== "CMake Server" ==] +Type "ctestInfo" +^^^^^^^^^^^^^^^^ + +The "ctestInfo" request can be used after a project was "compute"d successfully. + +It will list the complete project test structure as it is known to cmake. + +The reply will contain a key "configurations", which will contain a list of +configuration objects. Configuration objects are used to destinquish between +different configurations the build directory might have enabled. While most +generators only support one configuration, others might support several. + +Each configuration object can have the following keys: + +"name" + contains the name of the configuration. The name may be empty. +"projects" + contains a list of project objects, one for each build project. + +Project objects define one (sub-)project defined in the cmake build system. + +Each project object can have the following keys: + +"name" + contains the (sub-)projects name. +"ctestInfo" + contains a list of test objects. + +Each test object can have the following keys: + +"ctestName" + contains the name of the test. +"ctestCommand" + contains the test command. +"properties" + contains a list of test property objects. + +Each test property object can have the following keys: + +"key" + contains the test property key. +"value" + contains the test property value. + + Type "cmakeInputs" ^^^^^^^^^^^^^^^^^^ @@ -616,8 +689,7 @@ and will not survive the build directory getting cleaned out. Type "cache" ^^^^^^^^^^^^ -The "cache" request can be used once a project is configured and will -list the cached configuration values. +The "cache" request will list the cached configuration values. Example:: diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index 8554e87f9..f233d0884 100644 --- a/Help/manual/cmake-toolchains.7.rst +++ b/Help/manual/cmake-toolchains.7.rst @@ -26,13 +26,13 @@ built-in variables, such as :variable:`CMAKE_CXX_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` etc are set by invoking the :command:`project` command. If no project command is in the top-level CMakeLists file, one will be implicitly generated. By default -the enabled languages are C and CXX: +the enabled languages are ``C`` and ``CXX``: .. code-block:: cmake project(C_Only C) -A special value of NONE can also be used with the :command:`project` command +A special value of ``NONE`` can also be used with the :command:`project` command to enable no languages: .. code-block:: cmake @@ -101,6 +101,14 @@ values for the compilers. The :variable:`CMAKE_CROSSCOMPILING` variable is set to true when CMake is cross-compiling. +Note that using the :variable:`CMAKE_SOURCE_DIR` or :variable:`CMAKE_BINARY_DIR` +variables inside a toolchain file is typically undesirable. The toolchain +file is used in contexts where these variables have different values when used +in different places (e.g. as part of a call to :command:`try_compile`). In most +cases, where there is a need to evaluate paths inside a toolchain file, the more +appropriate variable to use would be :variable:`CMAKE_CURRENT_LIST_DIR`, since +it always has an unambiguous, predictable value. + Cross Compiling for Linux ------------------------- @@ -391,8 +399,10 @@ Configure use of an Android NDK with the following variables: be false unless using a NDK that does not provide unified headers. :variable:`CMAKE_ANDROID_NDK_TOOLCHAIN_VERSION` - Set to the version of the NDK toolchain to be selected as the compiler. - If not specified, the default will be the latest available GCC toolchain. + On NDK r19 or above, this variable must be unset or set to ``clang``. + On NDK r18 or below, set this to the version of the NDK toolchain to + be selected as the compiler. If not specified, the default will be + the latest available GCC toolchain. :variable:`CMAKE_ANDROID_STL_TYPE` Set to specify which C++ standard library to use. If not specified, @@ -468,10 +478,10 @@ The following variables will be computed and provided automatically: The Android ABI detected from the standalone toolchain. :variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_PREFIX` - The absolute path prefix to the binutils in the standalone toolchain. + The absolute path prefix to the ``binutils`` in the standalone toolchain. :variable:`CMAKE_<LANG>_ANDROID_TOOLCHAIN_SUFFIX` - The host platform suffix of the binutils in the standalone toolchain. + The host platform suffix of the ``binutils`` in the standalone toolchain. For example, a toolchain file might contain: @@ -522,3 +532,132 @@ See also target properties: * :prop_tgt:`ANDROID_SECURE_PROPS_PATH` * :prop_tgt:`ANDROID_SKIP_ANT_STEP` * :prop_tgt:`ANDROID_STL_TYPE` + +.. _`Cross Compiling for iOS, tvOS, or watchOS`: + +Cross Compiling for iOS, tvOS, or watchOS +----------------------------------------- + +For cross-compiling to iOS, tvOS, or watchOS, the :generator:`Xcode` +generator is recommended. The :generator:`Unix Makefiles` or +:generator:`Ninja` generators can also be used, but they require the +project to handle more areas like target CPU selection and code signing. + +Any of the three systems can be targeted by setting the +:variable:`CMAKE_SYSTEM_NAME` variable to a value from the table below. +By default, the latest Device SDK is chosen. As for all Apple platforms, +a different SDK (e.g. a simulator) can be selected by setting the +:variable:`CMAKE_OSX_SYSROOT` variable, although this should rarely be +necessary (see :ref:`Switching Between Device and Simulator` below). +A list of available SDKs can be obtained by running ``xcodebuild -showsdks``. + +======= ================= ==================== ================ +OS CMAKE_SYSTEM_NAME Device SDK (default) Simulator SDK +======= ================= ==================== ================ +iOS iOS iphoneos iphonesimulator +tvOS tvOS appletvos appletvsimulator +watchOS watchOS watchos watchsimulator +======= ================= ==================== ================ + +For example, to create a CMake configuration for iOS, the following +command is sufficient: + +.. code-block:: console + + cmake .. -GXcode -DCMAKE_SYSTEM_NAME=iOS + +Variable :variable:`CMAKE_OSX_ARCHITECTURES` can be used to set architectures +for both device and simulator. Variable :variable:`CMAKE_OSX_DEPLOYMENT_TARGET` +can be used to set an iOS/tvOS/watchOS deployment target. + +Next configuration will install fat 5 architectures iOS library +and add the ``-miphoneos-version-min=9.3``/``-mios-simulator-version-min=9.3`` +flags to the compiler: + +.. code-block:: console + + $ cmake -S. -B_builds -GXcode \ + -DCMAKE_SYSTEM_NAME=iOS \ + "-DCMAKE_OSX_ARCHITECTURES=armv7;armv7s;arm64;i386;x86_64" \ + -DCMAKE_OSX_DEPLOYMENT_TARGET=9.3 \ + -DCMAKE_INSTALL_PREFIX=`pwd`/_install \ + -DCMAKE_XCODE_ATTRIBUTE_ONLY_ACTIVE_ARCH=NO \ + -DCMAKE_IOS_INSTALL_COMBINED=YES + +Example: + +.. code-block:: cmake + + # CMakeLists.txt + cmake_minimum_required(VERSION 3.14) + project(foo) + add_library(foo foo.cpp) + install(TARGETS foo DESTINATION lib) + +Install: + +.. code-block:: console + + $ cmake --build _builds --config Release --target install + +Check library: + +.. code-block:: console + + $ lipo -info _install/lib/libfoo.a + Architectures in the fat file: _install/lib/libfoo.a are: i386 armv7 armv7s x86_64 arm64 + +.. code-block:: console + + $ otool -l _install/lib/libfoo.a | grep -A2 LC_VERSION_MIN_IPHONEOS + cmd LC_VERSION_MIN_IPHONEOS + cmdsize 16 + version 9.3 + +Code Signing +^^^^^^^^^^^^ + +Some build artifacts for the embedded Apple platforms require mandatory +code signing. If the :generator:`Xcode` generator is being used and +code signing is required or desired, the development team ID can be +specified via the ``CMAKE_XCODE_ATTRIBUTE_DEVELOPMENT_TEAM`` CMake variable. +This team ID will then be included in the generated Xcode project. +By default, CMake avoids the need for code signing during the internal +configuration phase (i.e compiler ID and feature detection). + +.. _`Switching Between Device and Simulator`: + +Switching Between Device and Simulator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When configuring for any of the embedded platforms, one can target either +real devices or the simulator. Both have their own separate SDK, but CMake +only supports specifying a single SDK for the configuration phase. This +means the developer must select one or the other at configuration time. +When using the :generator:`Xcode` generator, this is less of a limitation +because Xcode still allows you to build for either a device or a simulator, +even though configuration was only performed for one of the two. From +within the Xcode IDE, builds are performed for the selected "destination" +platform. When building from the command line, the desired sdk can be +specified directly by passing a ``-sdk`` option to the underlying build +tool (``xcodebuild``). For example: + +.. code-block:: console + + $ cmake --build ... -- -sdk iphonesimulator + +Please note that checks made during configuration were performed against +the configure-time SDK and might not hold true for other SDKs. Commands +like :command:`find_package`, :command:`find_library`, etc. store and use +details only for the configured SDK/platform, so they can be problematic +if wanting to switch between device and simulator builds. You can follow +the next rules to make device + simulator configuration work: + +- Use explicit ``-l`` linker flag, + e.g. ``target_link_libraries(foo PUBLIC "-lz")`` + +- Use explicit ``-framework`` linker flag, + e.g. ``target_link_libraries(foo PUBLIC "-framework CoreFoundation")`` + +- Use :command:`find_package` only for libraries installed with + :variable:`CMAKE_IOS_INSTALL_COMBINED` feature diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 1a2726dd3..53b7f8ddd 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -7,6 +7,14 @@ cmake-variables(7) .. contents:: +This page documents variables that are provided by CMake +or have meaning to CMake when set by project code. + +For general information on variables, see the +:ref:`Variables <CMake Language Variables>` +section in the cmake-language manual. + + Variables that Provide Information ================================== @@ -24,6 +32,7 @@ Variables that Provide Information /variable/CMAKE_CACHE_PATCH_VERSION /variable/CMAKE_CFG_INTDIR /variable/CMAKE_COMMAND + /variable/CMAKE_CPACK_COMMAND /variable/CMAKE_CROSSCOMPILING /variable/CMAKE_CROSSCOMPILING_EMULATOR /variable/CMAKE_CTEST_COMMAND @@ -32,7 +41,9 @@ Variables that Provide Information /variable/CMAKE_CURRENT_LIST_FILE /variable/CMAKE_CURRENT_LIST_LINE /variable/CMAKE_CURRENT_SOURCE_DIR + /variable/CMAKE_DIRECTORY_LABELS /variable/CMAKE_DL_LIBS + /variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION /variable/CMAKE_EDIT_COMMAND /variable/CMAKE_EXECUTABLE_SUFFIX /variable/CMAKE_EXTRA_GENERATOR @@ -41,15 +52,17 @@ Variables that Provide Information /variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION /variable/CMAKE_FIND_PACKAGE_SORT_ORDER /variable/CMAKE_GENERATOR + /variable/CMAKE_GENERATOR_INSTANCE /variable/CMAKE_GENERATOR_PLATFORM /variable/CMAKE_GENERATOR_TOOLSET - /variable/CMAKE_HOME_DIRECTORY /variable/CMAKE_IMPORT_LIBRARY_PREFIX /variable/CMAKE_IMPORT_LIBRARY_SUFFIX /variable/CMAKE_JOB_POOL_COMPILE /variable/CMAKE_JOB_POOL_LINK + /variable/CMAKE_JOB_POOLS /variable/CMAKE_LANG_COMPILER_AR /variable/CMAKE_LANG_COMPILER_RANLIB + /variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX /variable/CMAKE_LINK_LIBRARY_SUFFIX /variable/CMAKE_LINK_SEARCH_END_STATIC /variable/CMAKE_LINK_SEARCH_START_STATIC @@ -57,14 +70,24 @@ Variables that Provide Information /variable/CMAKE_MAKE_PROGRAM /variable/CMAKE_MATCH_COUNT /variable/CMAKE_MATCH_n + /variable/CMAKE_MESSAGE_INDENT /variable/CMAKE_MINIMUM_REQUIRED_VERSION /variable/CMAKE_MINOR_VERSION + /variable/CMAKE_NETRC + /variable/CMAKE_NETRC_FILE /variable/CMAKE_PARENT_LIST_FILE /variable/CMAKE_PATCH_VERSION /variable/CMAKE_PROJECT_DESCRIPTION + /variable/CMAKE_PROJECT_HOMEPAGE_URL /variable/CMAKE_PROJECT_NAME + /variable/CMAKE_PROJECT_VERSION + /variable/CMAKE_PROJECT_VERSION_MAJOR + /variable/CMAKE_PROJECT_VERSION_MINOR + /variable/CMAKE_PROJECT_VERSION_PATCH + /variable/CMAKE_PROJECT_VERSION_TWEAK /variable/CMAKE_RANLIB /variable/CMAKE_ROOT + /variable/CMAKE_RULE_MESSAGES /variable/CMAKE_SCRIPT_MODE_FILE /variable/CMAKE_SHARED_LIBRARY_PREFIX /variable/CMAKE_SHARED_LIBRARY_SUFFIX @@ -76,22 +99,28 @@ Variables that Provide Information /variable/CMAKE_SOURCE_DIR /variable/CMAKE_STATIC_LIBRARY_PREFIX /variable/CMAKE_STATIC_LIBRARY_SUFFIX + /variable/CMAKE_Swift_MODULE_DIRECTORY + /variable/CMAKE_Swift_NUM_THREADS /variable/CMAKE_TOOLCHAIN_FILE /variable/CMAKE_TWEAK_VERSION /variable/CMAKE_VERBOSE_MAKEFILE /variable/CMAKE_VERSION /variable/CMAKE_VS_DEVENV_COMMAND - /variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION /variable/CMAKE_VS_MSBUILD_COMMAND /variable/CMAKE_VS_NsightTegra_VERSION /variable/CMAKE_VS_PLATFORM_NAME + /variable/CMAKE_VS_PLATFORM_NAME_DEFAULT /variable/CMAKE_VS_PLATFORM_TOOLSET /variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA + /variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR /variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE + /variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION /variable/CMAKE_XCODE_GENERATE_SCHEME /variable/CMAKE_XCODE_PLATFORM_TOOLSET /variable/PROJECT-NAME_BINARY_DIR + /variable/PROJECT-NAME_DESCRIPTION + /variable/PROJECT-NAME_HOMEPAGE_URL /variable/PROJECT-NAME_SOURCE_DIR /variable/PROJECT-NAME_VERSION /variable/PROJECT-NAME_VERSION_MAJOR @@ -100,6 +129,7 @@ Variables that Provide Information /variable/PROJECT-NAME_VERSION_TWEAK /variable/PROJECT_BINARY_DIR /variable/PROJECT_DESCRIPTION + /variable/PROJECT_HOMEPAGE_URL /variable/PROJECT_NAME /variable/PROJECT_SOURCE_DIR /variable/PROJECT_VERSION @@ -120,6 +150,8 @@ Variables that Change Behavior /variable/CMAKE_AUTOMOC_RELAXED_MODE /variable/CMAKE_BACKWARDS_COMPATIBILITY /variable/CMAKE_BUILD_TYPE + /variable/CMAKE_CODEBLOCKS_COMPILER_ID + /variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES /variable/CMAKE_CODELITE_USE_TARGETS /variable/CMAKE_COLOR_MAKEFILE /variable/CMAKE_CONFIGURATION_TYPES @@ -129,10 +161,13 @@ Variables that Change Behavior /variable/CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES /variable/CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT /variable/CMAKE_ECLIPSE_MAKE_ARGUMENTS + /variable/CMAKE_ECLIPSE_RESOURCE_ENCODING /variable/CMAKE_ECLIPSE_VERSION /variable/CMAKE_ERROR_DEPRECATED /variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION + /variable/CMAKE_EXECUTE_PROCESS_COMMAND_ECHO /variable/CMAKE_EXPORT_COMPILE_COMMANDS + /variable/CMAKE_EXPORT_PACKAGE_REGISTRY /variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY /variable/CMAKE_FIND_APPBUNDLE /variable/CMAKE_FIND_FRAMEWORK @@ -142,34 +177,48 @@ Variables that Change Behavior /variable/CMAKE_FIND_NO_INSTALL_PREFIX /variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY /variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY + /variable/CMAKE_FIND_PACKAGE_PREFER_CONFIG + /variable/CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS /variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE /variable/CMAKE_FIND_ROOT_PATH /variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE /variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY /variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE /variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM + /variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH + /variable/CMAKE_FIND_USE_CMAKE_PATH + /variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH + /variable/CMAKE_FIND_USE_PACKAGE_REGISTRY + /variable/CMAKE_FIND_USE_PACKAGE_ROOT_PATH + /variable/CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH + /variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY /variable/CMAKE_FRAMEWORK_PATH /variable/CMAKE_IGNORE_PATH /variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE /variable/CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE /variable/CMAKE_INCLUDE_PATH /variable/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME + /variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS /variable/CMAKE_INSTALL_MESSAGE /variable/CMAKE_INSTALL_PREFIX /variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT /variable/CMAKE_LIBRARY_PATH + /variable/CMAKE_LINK_DIRECTORIES_BEFORE /variable/CMAKE_MFC_FLAG + /variable/CMAKE_MAXIMUM_RECURSION_DEPTH /variable/CMAKE_MODULE_PATH - /variable/CMAKE_NOT_USING_CONFIG_FLAGS /variable/CMAKE_POLICY_DEFAULT_CMPNNNN /variable/CMAKE_POLICY_WARNING_CMPNNNN /variable/CMAKE_PREFIX_PATH /variable/CMAKE_PROGRAM_PATH + /variable/CMAKE_PROJECT_INCLUDE + /variable/CMAKE_PROJECT_INCLUDE_BEFORE /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY /variable/CMAKE_STAGING_PREFIX /variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS /variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE + /variable/CMAKE_SUPPRESS_REGENERATION /variable/CMAKE_SYSROOT /variable/CMAKE_SYSROOT_COMPILE /variable/CMAKE_SYSROOT_LINK @@ -183,6 +232,24 @@ Variables that Change Behavior /variable/CMAKE_USER_MAKE_RULES_OVERRIDE /variable/CMAKE_WARN_DEPRECATED /variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION + /variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY + /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_DISABLE_MAIN_THREAD_CHECKER + /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS + /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE + /variable/CMAKE_XCODE_SCHEME_GUARD_MALLOC + /variable/CMAKE_XCODE_SCHEME_MAIN_THREAD_CHECKER_STOP + /variable/CMAKE_XCODE_SCHEME_MALLOC_GUARD_EDGES + /variable/CMAKE_XCODE_SCHEME_MALLOC_SCRIBBLE + /variable/CMAKE_XCODE_SCHEME_MALLOC_STACK + /variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER + /variable/CMAKE_XCODE_SCHEME_THREAD_SANITIZER_STOP + /variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER + /variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP + /variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS + /variable/PackageName_ROOT Variables that Describe the System ================================== @@ -211,8 +278,8 @@ Variables that Describe the System /variable/CMAKE_SYSTEM_PROCESSOR /variable/CMAKE_SYSTEM_VERSION /variable/CYGWIN - /variable/ENV /variable/GHS-MULTI + /variable/IOS /variable/MINGW /variable/MSVC /variable/MSVC10 @@ -225,7 +292,9 @@ Variables that Describe the System /variable/MSVC80 /variable/MSVC90 /variable/MSVC_IDE + /variable/MSVC_TOOLSET_VERSION /variable/MSVC_VERSION + /variable/MSYS /variable/UNIX /variable/WIN32 /variable/WINCE @@ -267,32 +336,50 @@ Variables that Control the Build /variable/CMAKE_ANDROID_STL_TYPE /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG + /variable/CMAKE_AUTOGEN_ORIGIN_DEPENDS + /variable/CMAKE_AUTOGEN_PARALLEL + /variable/CMAKE_AUTOGEN_VERBOSE /variable/CMAKE_AUTOMOC + /variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES /variable/CMAKE_AUTOMOC_DEPEND_FILTERS + /variable/CMAKE_AUTOMOC_MACRO_NAMES /variable/CMAKE_AUTOMOC_MOC_OPTIONS + /variable/CMAKE_AUTOMOC_PATH_PREFIX /variable/CMAKE_AUTORCC /variable/CMAKE_AUTORCC_OPTIONS /variable/CMAKE_AUTOUIC /variable/CMAKE_AUTOUIC_OPTIONS /variable/CMAKE_AUTOUIC_SEARCH_PATHS /variable/CMAKE_BUILD_RPATH + /variable/CMAKE_BUILD_RPATH_USE_ORIGIN /variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR /variable/CMAKE_BUILD_WITH_INSTALL_RPATH /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_CONFIG_POSTFIX + /variable/CMAKE_CUDA_SEPARABLE_COMPILATION + /variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS /variable/CMAKE_DEBUG_POSTFIX + /variable/CMAKE_DISABLE_PRECOMPILE_HEADERS /variable/CMAKE_ENABLE_EXPORTS /variable/CMAKE_EXE_LINKER_FLAGS /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_EXE_LINKER_FLAGS_INIT + /variable/CMAKE_FOLDER + /variable/CMAKE_FRAMEWORK /variable/CMAKE_Fortran_FORMAT /variable/CMAKE_Fortran_MODULE_DIRECTORY + /variable/CMAKE_GHS_NO_SOURCE_GROUP_FILE + /variable/CMAKE_GLOBAL_AUTOGEN_TARGET + /variable/CMAKE_GLOBAL_AUTOGEN_TARGET_NAME + /variable/CMAKE_GLOBAL_AUTORCC_TARGET + /variable/CMAKE_GLOBAL_AUTORCC_TARGET_NAME /variable/CMAKE_GNUtoMS /variable/CMAKE_INCLUDE_CURRENT_DIR /variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE /variable/CMAKE_INSTALL_NAME_DIR + /variable/CMAKE_INSTALL_REMOVE_ENVIRONMENT_RPATH /variable/CMAKE_INSTALL_RPATH /variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH /variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION @@ -300,8 +387,11 @@ Variables that Control the Build /variable/CMAKE_IOS_INSTALL_COMBINED /variable/CMAKE_LANG_CLANG_TIDY /variable/CMAKE_LANG_COMPILER_LAUNCHER + /variable/CMAKE_LANG_CPPCHECK /variable/CMAKE_LANG_CPPLINT /variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE + /variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG + /variable/CMAKE_LANG_LINK_LIBRARY_FLAG /variable/CMAKE_LANG_VISIBILITY_PRESET /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG @@ -319,6 +409,8 @@ Variables that Control the Build /variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG /variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_MODULE_LINKER_FLAGS_INIT + /variable/CMAKE_MSVCIDE_RUN_PATH + /variable/CMAKE_MSVC_RUNTIME_LIBRARY /variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX /variable/CMAKE_NO_BUILTIN_CHRPATH /variable/CMAKE_NO_SYSTEM_FROM_IMPORTED @@ -343,10 +435,22 @@ Variables that Control the Build /variable/CMAKE_TRY_COMPILE_CONFIGURATION /variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES /variable/CMAKE_TRY_COMPILE_TARGET_TYPE + /variable/CMAKE_UNITY_BUILD + /variable/CMAKE_UNITY_BUILD_BATCH_SIZE /variable/CMAKE_USE_RELATIVE_PATHS /variable/CMAKE_VISIBILITY_INLINES_HIDDEN + /variable/CMAKE_VS_GLOBALS /variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD /variable/CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD + /variable/CMAKE_VS_JUST_MY_CODE_DEBUGGING + /variable/CMAKE_VS_SDK_EXCLUDE_DIRECTORIES + /variable/CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES + /variable/CMAKE_VS_SDK_INCLUDE_DIRECTORIES + /variable/CMAKE_VS_SDK_LIBRARY_DIRECTORIES + /variable/CMAKE_VS_SDK_LIBRARY_WINRT_DIRECTORIES + /variable/CMAKE_VS_SDK_REFERENCE_DIRECTORIES + /variable/CMAKE_VS_SDK_SOURCE_DIRECTORIES + /variable/CMAKE_VS_WINRT_BY_DEFAULT /variable/CMAKE_WIN32_EXECUTABLE /variable/CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS /variable/CMAKE_XCODE_ATTRIBUTE_an-attribute @@ -362,6 +466,7 @@ Variables for Languages /variable/CMAKE_COMPILER_IS_GNUCC /variable/CMAKE_COMPILER_IS_GNUCXX /variable/CMAKE_COMPILER_IS_GNUG77 + /variable/CMAKE_CUDA_HOST_COMPILER /variable/CMAKE_CUDA_EXTENSIONS /variable/CMAKE_CUDA_STANDARD /variable/CMAKE_CUDA_STANDARD_REQUIRED @@ -377,7 +482,6 @@ Variables for Languages /variable/CMAKE_Fortran_MODDIR_DEFAULT /variable/CMAKE_Fortran_MODDIR_FLAG /variable/CMAKE_Fortran_MODOUT_FLAG - /variable/CMAKE_INTERNAL_PLATFORM_ABI /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_MACHINE /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_PREFIX /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_SUFFIX @@ -385,10 +489,10 @@ Variables for Languages /variable/CMAKE_LANG_ARCHIVE_CREATE /variable/CMAKE_LANG_ARCHIVE_FINISH /variable/CMAKE_LANG_COMPILER - /variable/CMAKE_LANG_COMPILER_ABI /variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN /variable/CMAKE_LANG_COMPILER_ID /variable/CMAKE_LANG_COMPILER_LOADED + /variable/CMAKE_LANG_COMPILER_PREDEFINES_COMMAND /variable/CMAKE_LANG_COMPILER_TARGET /variable/CMAKE_LANG_COMPILER_VERSION /variable/CMAKE_LANG_COMPILE_OBJECT @@ -396,6 +500,8 @@ Variables for Languages /variable/CMAKE_LANG_CREATE_SHARED_MODULE /variable/CMAKE_LANG_CREATE_STATIC_LIBRARY /variable/CMAKE_LANG_FLAGS + /variable/CMAKE_LANG_FLAGS_CONFIG + /variable/CMAKE_LANG_FLAGS_CONFIG_INIT /variable/CMAKE_LANG_FLAGS_DEBUG /variable/CMAKE_LANG_FLAGS_DEBUG_INIT /variable/CMAKE_LANG_FLAGS_INIT @@ -405,10 +511,6 @@ Variables for Languages /variable/CMAKE_LANG_FLAGS_RELEASE_INIT /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT - /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG - /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL - /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE - /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO /variable/CMAKE_LANG_IGNORE_EXTENSIONS /variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES /variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES @@ -417,15 +519,22 @@ Variables for Languages /variable/CMAKE_LANG_LIBRARY_ARCHITECTURE /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_LINK_EXECUTABLE /variable/CMAKE_LANG_OUTPUT_EXTENSION - /variable/CMAKE_LANG_PLATFORM_ID /variable/CMAKE_LANG_SIMULATE_ID /variable/CMAKE_LANG_SIMULATE_VERSION /variable/CMAKE_LANG_SIZEOF_DATA_PTR /variable/CMAKE_LANG_SOURCE_FILE_EXTENSIONS /variable/CMAKE_LANG_STANDARD_INCLUDE_DIRECTORIES /variable/CMAKE_LANG_STANDARD_LIBRARIES + /variable/CMAKE_OBJC_EXTENSIONS + /variable/CMAKE_OBJC_STANDARD + /variable/CMAKE_OBJC_STANDARD_REQUIRED + /variable/CMAKE_OBJCXX_EXTENSIONS + /variable/CMAKE_OBJCXX_STANDARD + /variable/CMAKE_OBJCXX_STANDARD_REQUIRED /variable/CMAKE_Swift_LANGUAGE_VERSION /variable/CMAKE_USER_MAKE_RULES_OVERRIDE_LANG @@ -461,7 +570,7 @@ Variables for CTest /variable/CTEST_CUSTOM_POST_TEST /variable/CTEST_CUSTOM_PRE_MEMCHECK /variable/CTEST_CUSTOM_PRE_TEST - /variable/CTEST_CUSTOM_TEST_IGNORE + /variable/CTEST_CUSTOM_TESTS_IGNORE /variable/CTEST_CUSTOM_WARNING_EXCEPTION /variable/CTEST_CUSTOM_WARNING_MATCH /variable/CTEST_CVS_CHECKOUT @@ -480,6 +589,7 @@ Variables for CTest /variable/CTEST_GIT_UPDATE_OPTIONS /variable/CTEST_HG_COMMAND /variable/CTEST_HG_UPDATE_OPTIONS + /variable/CTEST_LABELS_FOR_SUBPROJECTS /variable/CTEST_MEMORYCHECK_COMMAND /variable/CTEST_MEMORYCHECK_COMMAND_OPTIONS /variable/CTEST_MEMORYCHECK_SANITIZER_OPTIONS @@ -490,8 +600,10 @@ Variables for CTest /variable/CTEST_P4_COMMAND /variable/CTEST_P4_OPTIONS /variable/CTEST_P4_UPDATE_OPTIONS + /variable/CTEST_RUN_CURRENT_SCRIPT /variable/CTEST_SCP_COMMAND /variable/CTEST_SITE + /variable/CTEST_SUBMIT_URL /variable/CTEST_SOURCE_DIRECTORY /variable/CTEST_SVN_COMMAND /variable/CTEST_SVN_OPTIONS @@ -502,6 +614,7 @@ Variables for CTest /variable/CTEST_UPDATE_COMMAND /variable/CTEST_UPDATE_OPTIONS /variable/CTEST_UPDATE_VERSION_ONLY + /variable/CTEST_UPDATE_VERSION_OVERRIDE /variable/CTEST_USE_LAUNCHERS Variables for CPack @@ -514,7 +627,36 @@ Variables for CPack /variable/CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY /variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION /variable/CPACK_INCLUDE_TOPLEVEL_DIRECTORY - /variable/CPACK_INSTALL_SCRIPT + /variable/CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS /variable/CPACK_PACKAGING_INSTALL_PREFIX /variable/CPACK_SET_DESTDIR /variable/CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION + +Variable Expansion Operators +============================ + +.. toctree:: + :maxdepth: 1 + + /variable/CACHE + /variable/ENV + +Internal Variables +================== + +CMake has many internal variables. Most of them are undocumented. +Some of them, however, were at some point described as normal +variables, and therefore may be encountered in legacy code. They +are subject to change, and not recommended for use in project code. + +.. toctree:: + :maxdepth: 1 + + /variable/CMAKE_HOME_DIRECTORY + /variable/CMAKE_INTERNAL_PLATFORM_ABI + /variable/CMAKE_LANG_COMPILER_ABI + /variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID + /variable/CMAKE_LANG_COMPILER_VERSION_INTERNAL + /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 ba925e8ec..4ab55a0d0 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -8,72 +8,190 @@ Synopsis .. parsed-literal:: - cmake [<options>] (<path-to-source> | <path-to-existing-build>) - cmake [(-D <var>=<value>)...] -P <cmake-script-file> - cmake --build <dir> [<options>...] [-- <build-tool-options>...] - cmake -E <command> [<options>...] - cmake --find-package <options>... + `Generate a Project Buildsystem`_ + cmake [<options>] <path-to-source> + cmake [<options>] <path-to-existing-build> + cmake [<options>] -S <path-to-source> -B <path-to-build> + + `Build a Project`_ + cmake --build <dir> [<options>] [-- <build-tool-options>] + + `Install a Project`_ + cmake --install <dir> [<options>] + + `Open a Project`_ + cmake --open <dir> + + `Run a Script`_ + cmake [{-D <var>=<value>}...] -P <cmake-script-file> + + `Run a Command-Line Tool`_ + cmake -E <command> [<options>] + + `Run the Find-Package Tool`_ + cmake --find-package [<options>] + + `View Help`_ + cmake --help[-<topic>] Description =========== -The "cmake" executable is the CMake command-line interface. It may be -used to configure projects in scripts. Project configuration settings -may be specified on the command line with the -D option. +The **cmake** executable is the command-line interface of the cross-platform +buildsystem generator CMake. The above `Synopsis`_ lists various actions +the tool can perform as described in sections below. + +To build a software project with CMake, `Generate a Project Buildsystem`_. +Optionally use **cmake** to `Build a Project`_, `Install a Project`_ or just +run the corresponding build tool (e.g. ``make``) directly. **cmake** can also +be used to `View Help`_. + +The other actions are meant for use by software developers writing +scripts in the :manual:`CMake language <cmake-language(7)>` to support +their builds. + +For graphical user interfaces that may be used in place of **cmake**, +see :manual:`ccmake <ccmake(1)>` and :manual:`cmake-gui <cmake-gui(1)>`. +For command-line interfaces to the CMake testing and packaging facilities, +see :manual:`ctest <ctest(1)>` and :manual:`cpack <cpack(1)>`. + +For more information on CMake at large, `see also`_ the links at the end +of this manual. + + +Introduction to CMake Buildsystems +================================== + +A *buildsystem* describes how to build a project's executables and libraries +from its source code using a *build tool* to automate the process. For +example, a buildsystem may be a ``Makefile`` for use with a command-line +``make`` tool or a project file for an Integrated Development Environment +(IDE). In order to avoid maintaining multiple such buildsystems, a project +may specify its buildsystem abstractly using files written in the +:manual:`CMake language <cmake-language(7)>`. From these files CMake +generates a preferred buildsystem locally for each user through a backend +called a *generator*. + +To generate a buildsystem with CMake, the following must be selected: + +Source Tree + The top-level directory containing source files provided by the project. + The project specifies its buildsystem using files as described in the + :manual:`cmake-language(7)` manual, starting with a top-level file named + ``CMakeLists.txt``. These files specify build targets and their + dependencies as described in the :manual:`cmake-buildsystem(7)` manual. + +Build Tree + The top-level directory in which buildsystem files and build output + artifacts (e.g. executables and libraries) are to be stored. + CMake will write a ``CMakeCache.txt`` file to identify the directory + as a build tree and store persistent information such as buildsystem + configuration options. + + To maintain a pristine source tree, perform an *out-of-source* build + by using a separate dedicated build tree. An *in-source* build in + which the build tree is placed in the same directory as the source + tree is also supported, but discouraged. + +Generator + This chooses the kind of buildsystem to generate. See the + :manual:`cmake-generators(7)` manual for documentation of all generators. + Run ``cmake --help`` to see a list of generators available locally. + Optionally use the ``-G`` option below to specify a generator, or simply + accept the default CMake chooses for the current platform. + + When using one of the :ref:`Command-Line Build Tool Generators` + CMake expects that the environment needed by the compiler toolchain + is already configured in the shell. When using one of the + :ref:`IDE Build Tool Generators`, no particular environment is needed. + + +Generate a Project Buildsystem +============================== + +Run CMake with one of the following command signatures to specify the +source and build trees and generate a buildsystem: + +``cmake [<options>] <path-to-source>`` + Uses the current working directory as the build tree, and + ``<path-to-source>`` as the source tree. The specified path may + be absolute or relative to the current working directory. + The source tree must contain a ``CMakeLists.txt`` file and must + *not* contain a ``CMakeCache.txt`` file because the latter + identifies an existing build tree. For example: + + .. code-block:: console + + $ mkdir build ; cd build + $ cmake ../src + +``cmake [<options>] <path-to-existing-build>`` + Uses ``<path-to-existing-build>`` as the build tree, and loads the + path to the source tree from its ``CMakeCache.txt`` file, which must + have already been generated by a previous run of CMake. The specified + path may be absolute or relative to the current working directory. + For example: + + .. code-block:: console + + $ cd build + $ cmake . + +``cmake [<options>] -S <path-to-source> -B <path-to-build>`` + Uses ``<path-to-build>`` as the build tree and ``<path-to-source>`` + as the source tree. The specified paths may be absolute or relative + to the current working directory. The source tree must contain a + ``CMakeLists.txt`` file. The build tree will be created automatically + if it does not already exist. For example: + + .. code-block:: console + + $ cmake -S src -B build + +In all cases the ``<options>`` may be zero or more of the `Options`_ below. -CMake is a cross-platform build system generator. Projects specify -their build process with platform-independent CMake listfiles included -in each directory of a source tree with the name CMakeLists.txt. -Users build a project by using CMake to generate a build system for a -native tool on their platform. +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: + + .. code-block:: console + + $ make + $ make install + +Alternatively, one may use **cmake** to `Build a Project`_ by +automatically choosing and invoking the appropriate native build tool. .. _`CMake Options`: Options -======= +------- .. include:: OPTIONS_BUILD.txt -``-E <command> [<options>...]`` - See `Command-Line Tool Mode`_. - ``-L[A][H]`` List non-advanced cached variables. - List cache variables will run CMake and list all the variables from - the CMake cache that are not marked as INTERNAL or ADVANCED. This - will effectively display current CMake settings, which can then be - changed with -D option. Changing some of the variables may result - in more variables being created. If A is specified, then it will - display also advanced variables. If H is specified, it will also + List ``CACHE`` variables will run CMake and list all the variables from + the CMake ``CACHE`` that are not marked as ``INTERNAL`` or :prop_cache:`ADVANCED`. + This will effectively display current CMake settings, which can then be + changed with ``-D`` option. Changing some of the variables may result + in more variables being created. If ``A`` is specified, then it will + display also advanced variables. If ``H`` is specified, it will also display help for each variable. -``--build <dir>`` - See `Build Tool Mode`_. - ``-N`` View mode only. Only load the cache. Do not actually run configure and generate steps. -``-P <file>`` - Process script mode. - - Process the given cmake file as a script written in the CMake - language. No configure or generate step is performed and the cache - is not modified. If variables are defined using -D, this must be - done before the -P argument. - -``--find-package`` - See `Find-Package Tool Mode`_. - ``--graphviz=[file]`` - Generate graphviz of dependencies, see CMakeGraphVizOptions.cmake for more. + Generate graphviz of dependencies, see :module:`CMakeGraphVizOptions` for more. Generate a graphviz input file that will contain all the library and executable dependencies in the project. See the documentation for - CMakeGraphVizOptions.cmake for more details. + :module:`CMakeGraphVizOptions` for more details. ``--system-information [file]`` Dump information about this system. @@ -82,10 +200,20 @@ Options from the top of a binary tree for a CMake project it will dump additional information such as the cache, log files etc. +``--log-level=<ERROR|WARNING|NOTICE|STATUS|VERBOSE|DEBUG|TRACE>`` + Set the log level. + + The :command:`message` command will only output messages of the specified + log level or higher. The default log level is ``STATUS``. + + For backward compatibility reasons, ``--loglevel`` is also accepted as a + synonym for this option. + ``--debug-trycompile`` - Do not delete the try_compile build tree. Only useful on one try_compile at a time. + Do not delete the :command:`try_compile` build tree. + Only useful on one :command:`try_compile` at a time. - Do not delete the files and directories created for try_compile + Do not delete the files and directories created for :command:`try_compile` calls. This is useful in debugging failed try_compiles. It may however change the results of the try-compiles as old junk from a previous try-compile may cause a different test to either pass or @@ -96,7 +224,7 @@ Options Put cmake in a debug mode. Print extra information during the cmake run like stack traces with - message(send_error ) calls. + :command:`message(SEND_ERROR)` calls. ``--trace`` Put cmake in trace mode. @@ -113,6 +241,9 @@ Options Multiple options are allowed. +``--trace-redirect=<file>`` + Put cmake in trace mode and redirect trace output to a file instead of stderr. + ``--warn-uninitialized`` Warn about uninitialized values. @@ -133,18 +264,20 @@ Options Find problems with variable usage in system files. Normally, unused and uninitialized variables are searched for only - in CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR. This flag tells CMake to - warn about other files as well. + in :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR`. + This flag tells CMake to warn about other files as well. -.. include:: OPTIONS_HELP.txt +.. _`Build Tool Mode`: -Build Tool Mode +Build a Project =============== CMake provides a command-line signature to build an already-generated -project binary tree:: +project binary tree: - cmake --build <dir> [<options>...] [-- <build-tool-options>...] +.. code-block:: shell + + cmake --build <dir> [<options>] [-- <build-tool-options>] This abstracts a native build tool's command-line interface with the following options: @@ -152,8 +285,19 @@ following options: ``--build <dir>`` Project binary directory to be built. This is required and must be first. -``--target <tgt>`` - Build ``<tgt>`` instead of default targets. May only be specified once. +``--parallel [<jobs>], -j [<jobs>]`` + The maximum number of concurrent processes to use when building. + If ``<jobs>`` is omitted the native build tool's default number is used. + + The :envvar:`CMAKE_BUILD_PARALLEL_LEVEL` environment variable, if set, + specifies a default parallel level when this option is not given. + + Some native build tools always build in parallel. The use of ``<jobs>`` + value of ``1`` can be used to limit to a single job. + +``--target <tgt>..., -t <tgt>...`` + Build ``<tgt>`` instead of the default target. Multiple targets may be + given, separated by spaces. ``--config <cfg>`` For multi-configuration tools, choose configuration ``<cfg>``. @@ -165,17 +309,89 @@ following options: ``--use-stderr`` Ignored. Behavior is default in CMake >= 3.0. +``--verbose, -v`` + Enable verbose output - if supported - including the build commands to be + executed. + + This option can be omitted if :envvar:`VERBOSE` environment variable or + :variable:`CMAKE_VERBOSE_MAKEFILE` cached variable is set. + + ``--`` Pass remaining options to the native tool. Run ``cmake --build`` with no options for quick help. -Command-Line Tool Mode -====================== +Install a Project +================= + +CMake provides a command-line signature to install an already-generated +project binary tree: + +.. code-block:: shell + + cmake --install <dir> [<options>] + +This may be used after building a project to run installation without +using the generated build system or the native build tool. +The options are: + +``--install <dir>`` + Project binary directory to install. This is required and must be first. + +``--config <cfg>`` + For multi-configuration generators, choose configuration ``<cfg>``. + +``--component <comp>`` + Component-based install. Only install component ``<comp>``. + +``--prefix <prefix>`` + Override the installation prefix, :variable:`CMAKE_INSTALL_PREFIX`. + +``--strip`` + Strip before installing. -CMake provides builtin command-line tools through the signature:: +``-v, --verbose`` + Enable verbose output. - cmake -E <command> [<options>...] + This option can be omitted if :envvar:`VERBOSE` environment variable is set. + +Run ``cmake --install`` with no options for quick help. + +Open a Project +============== + +.. code-block:: shell + + cmake --open <dir> + +Open the generated project in the associated application. This is only +supported by some generators. + + +.. _`Script Processing Mode`: + +Run a Script +============ + +.. code-block:: shell + + cmake [{-D <var>=<value>}...] -P <cmake-script-file> + +Process the given cmake file as a script written in the CMake +language. No configure or generate step is performed and the cache +is not modified. If variables are defined using ``-D``, this must be +done before the ``-P`` argument. + + +Run a Command-Line Tool +======================= + +CMake provides builtin command-line tools through the signature + +.. code-block:: shell + + cmake -E <command> [<options>] Run ``cmake -E`` or ``cmake -E help`` for a summary of commands. Available commands are: @@ -214,30 +430,57 @@ Available commands are: A list of strings with all the extra generators compatible with the generator. + ``fileApi`` + Optional member that is present when the :manual:`cmake-file-api(7)` + is available. The value is a JSON object with one member: + + ``requests`` + A JSON array containing zero or more supported file-api requests. + Each request is a JSON object with members: + + ``kind`` + Specifies one of the supported :ref:`file-api object kinds`. + + ``version`` + A JSON array whose elements are each a JSON object containing + ``major`` and ``minor`` members specifying non-negative integer + version components. + ``serverMode`` ``true`` if cmake supports server-mode and ``false`` otherwise. ``chdir <dir> <cmd> [<arg>...]`` Change the current working directory and run a command. -``compare_files <file1> <file2>`` +``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. + then returns ``0``, if not it returns ``1``. The ``--ignore-eol`` option + implies line-wise comparison and ignores LF/CRLF differences. ``copy <file>... <destination>`` Copy files to ``<destination>`` (either file or directory). If multiple files are specified, the ``<destination>`` must be directory and it must exist. Wildcards are not supported. + ``copy`` does follow symlinks. That means it does not copy symlinks, + but the files or directories it point to. ``copy_directory <dir>... <destination>`` - Copy directories to ``<destination>`` directory. + Copy content of ``<dir>...`` directories to ``<destination>`` directory. If ``<destination>`` directory does not exist it will be created. + ``copy_directory`` does follow symlinks. ``copy_if_different <file>... <destination>`` Copy files to ``<destination>`` (either file or directory) if they have changed. If multiple files are specified, the ``<destination>`` must be directory and it must exist. + ``copy_if_different`` does follow symlinks. + +``create_symlink <old> <new>`` + Create a symbolic link ``<new>`` naming ``<old>``. + + .. note:: + Path to where ``<new>`` symbolic link will be created has to exist beforehand. ``echo [<string>...]`` Displays arguments as text. @@ -251,6 +494,9 @@ Available commands are: ``environment`` Display the current environment variables. +``false`` + Do nothing, with an exit code of 1. + ``make_directory <dir>...`` Create ``<dir>`` directories. If necessary, create parent directories too. If a directory already exists it will be @@ -262,18 +508,52 @@ Available commands are: 351abe79cd3800b38cdfb25d45015a15 file1.txt 052f86c15bbde68af55c7f7b340ab639 file2.txt +``sha1sum <file>...`` + Create SHA1 checksum of files in ``sha1sum`` compatible format:: + + 4bb7932a29e6f73c97bb9272f2bdc393122f86e0 file1.txt + 1df4c8f318665f9a5f2ed38f55adadb7ef9f559c file2.txt + +``sha224sum <file>...`` + Create SHA224 checksum of files in ``sha224sum`` compatible format:: + + b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930 file1.txt + 6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24 file2.txt + +``sha256sum <file>...`` + Create SHA256 checksum of files in ``sha256sum`` compatible format:: + + 76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc file1.txt + 15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea file2.txt + +``sha384sum <file>...`` + Create SHA384 checksum of files in ``sha384sum`` compatible format:: + + acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434 file1.txt + 668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d file2.txt + +``sha512sum <file>...`` + Create SHA512 checksum of files in ``sha512sum`` compatible format:: + + 2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89 file1.txt + 7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d file2.txt + ``remove [-f] <file>...`` Remove the file(s). 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. + ``remove`` does not follow symlinks. That means it remove only symlinks + and not files it point to. -``remove_directory <dir>`` - Remove a directory and its contents. If a directory does - not exist it will be silently ignored. +``remove_directory <dir>...`` + 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. ``rename <oldname> <newname>`` - Rename a file or directory (on one volume). + Rename a file or directory (on one volume). If file with the ``<newname>`` name + already exists, then it will be silently replaced. ``server`` Launch :manual:`cmake-server(7)` mode. @@ -281,44 +561,61 @@ Available commands are: ``sleep <number>...`` Sleep for given number of seconds. -``tar [cxt][vf][zjJ] file.tar [<options>...] [--] [<file>...]`` +``tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]`` Create or extract a tar or zip archive. Options are: - ``--`` - Stop interpreting options and treat all remaining arguments - as file names even if they start in ``-``. + ``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``). + ``t`` + List archive contents. + 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`` + Compress the resulting archive with XZ. + ``--zstd`` + Compress the resulting archive with Zstandard. ``--files-from=<file>`` 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 ``-``. - ``--mtime=<date>`` - Specify modification time recorded in tarball entries. ``--format=<format>`` Specify the format of the archive to be created. Supported formats are: ``7zip``, ``gnutar``, ``pax``, ``paxr`` (restricted pax, default), and ``zip``. + ``--mtime=<date>`` + Specify modification time recorded in tarball entries. + ``--`` + Stop interpreting options and treat all remaining arguments + as file names, even if they start with ``-``. + ``time <command> [<args>...]`` - Run command and return elapsed time. + Run command and display elapsed time. -``touch <file>`` - Touch a file. +``touch <file>...`` + Creates ``<file>`` if file do not exist. + If ``<file>`` exists, it is changing ``<file>`` access and modification times. -``touch_nocreate <file>`` +``touch_nocreate <file>...`` Touch a file if it exists but do not create it. If a file does not exist it will be silently ignored. -UNIX-specific Command-Line Tools --------------------------------- - -The following ``cmake -E`` commands are available only on UNIX: - -``create_symlink <old> <new>`` - Create a symbolic link ``<new>`` naming ``<old>``. - -.. note:: - Path to where ``<new>`` symbolic link will be created has to exist beforehand. +``true`` + Do nothing, with an exit code of 0. Windows-specific Command-Line Tools ----------------------------------- @@ -339,24 +636,40 @@ The following ``cmake -E`` commands are available only on Windows: ``write_regv <key> <value>`` Write Windows registry value. -Find-Package Tool Mode -====================== -CMake provides a helper for Makefile-based projects with the signature:: +Run the Find-Package Tool +========================= + +CMake provides a pkg-config like helper for Makefile-based projects: - cmake --find-package <options>... +.. code-block:: shell -This runs in a pkg-config like mode. + cmake --find-package [<options>] -Search a package using :command:`find_package()` and print the resulting flags -to stdout. This can be used to use cmake instead of pkg-config to find -installed libraries in plain Makefile-based projects or in autoconf-based -projects (via ``share/aclocal/cmake.m4``). +It searches a package using :command:`find_package()` and prints the +resulting flags to stdout. This can be used instead of pkg-config +to find installed libraries in plain Makefile-based projects or in +autoconf-based projects (via ``share/aclocal/cmake.m4``). .. note:: This mode is not well-supported due to some technical limitations. It is kept for compatibility but should not be used in new projects. + +View Help +========= + +To print selected pages from the CMake documentation, use + +.. code-block:: shell + + cmake --help[-<topic>] + +with one of the following options: + +.. include:: OPTIONS_HELP.txt + + See Also ======== diff --git a/Help/manual/cpack-generators.7.rst b/Help/manual/cpack-generators.7.rst new file mode 100644 index 000000000..ade9149c1 --- /dev/null +++ b/Help/manual/cpack-generators.7.rst @@ -0,0 +1,29 @@ +.. cmake-manual-description: CPack Generator Reference + +cpack-generators(7) +******************* + +.. only:: html + + .. contents:: + +Generators +========== + +.. toctree:: + :maxdepth: 1 + + /cpack_gen/archive + /cpack_gen/bundle + /cpack_gen/cygwin + /cpack_gen/deb + /cpack_gen/dmg + /cpack_gen/external + /cpack_gen/freebsd + /cpack_gen/ifw + /cpack_gen/nsis + /cpack_gen/nuget + /cpack_gen/packagemaker + /cpack_gen/productbuild + /cpack_gen/rpm + /cpack_gen/wix diff --git a/Help/manual/cpack.1.rst b/Help/manual/cpack.1.rst index 4f9f28d4e..395cd4189 100644 --- a/Help/manual/cpack.1.rst +++ b/Help/manual/cpack.1.rst @@ -8,86 +8,102 @@ Synopsis .. parsed-literal:: - cpack -G <generator> [<options>] + cpack [<options>] Description =========== -The "cpack" executable is the CMake packaging program. -CMake-generated build trees created for projects that use the -INSTALL_* commands have packaging support. This program will generate -the package. +The **cpack** executable is the CMake packaging program. It generates +installers and source packages in a variety of formats. -CMake is a cross-platform build system generator. Projects specify -their build process with platform-independent CMake listfiles included -in each directory of a source tree with the name CMakeLists.txt. -Users build a project by using CMake to generate a build system for a -native tool on their platform. +For each installer or package format, **cpack** has a specific backend, +called "generator". A generator is responsible for generating the required +inputs and invoking the specific package creation tools. These installer +or package generators are not to be confused with the makefile generators +of the :manual:`cmake <cmake(1)>` command. -Options -======= +All supported generators are specified in the :manual:`cpack-generators +<cpack-generators(7)>` manual. The command ``cpack --help`` prints a +list of generators supported for the target platform. Which of them are +to be used can be selected through the :variable:`CPACK_GENERATOR` variable +or through the command-line option ``-G``. -``-G <generator>`` - Use the specified generator to generate package. +The **cpack** program is steered by a configuration file written in the +:manual:`CMake language <cmake-language(7)>`. Unless chosen differently +through the command-line option ``--config``, the file ``CPackConfig.cmake`` +in the current directory is used. - CPack may support multiple native packaging systems on certain - platforms. A generator is responsible for generating input files - for particular system and invoking that systems. Possible generator - names are specified in the Generators section. +In the standard CMake workflow, the file ``CPackConfig.cmake`` is generated +by the :manual:`cmake <cmake(1)>` executable, provided the :module:`CPack` +module is included by the project's ``CMakeLists.txt`` file. -``-C <Configuration>`` - Specify the project configuration +Options +======= - This option specifies the configuration that the project was build - with, for example 'Debug', 'Release'. +``-G <generators>`` + ``<generators>`` is a :ref:`semicolon-separated list <CMake Language Lists>` + of generator names. ``cpack`` will iterate through this list and produce + package(s) in that generator's format according to the details provided in + the ``CPackConfig.cmake`` configuration file. If this option is not given, + the :variable:`CPACK_GENERATOR` variable determines the default set of + generators that will be used. + +``-C <configs>`` + Specify the project configuration(s) to be packaged (e.g. ``Debug``, + ``Release``, etc.), where ``<configs>`` is a + :ref:`semicolon-separated list <CMake Language Lists>`. + When the CMake project uses a multi-configuration + generator such as Xcode or Visual Studio, this option is needed to tell + ``cpack`` which built executables to include in the package. + The user is responsible for ensuring that the configuration(s) listed + have already been built before invoking ``cpack``. ``-D <var>=<value>`` - Set a CPack variable. + Set a CPack variable. This will override any value set for ``<var>`` in the + input file read by ``cpack``. - Set a variable that can be used by the generator. +``--config <configFile>`` + Specify the configuration file read by ``cpack`` to provide the packaging + details. By default, ``CPackConfig.cmake`` in the current directory will + be used. -``--config <config file>`` - Specify the config file. - - Specify the config file to use to create the package. By default - CPackConfig.cmake in the current directory will be used. - -``--verbose,-V`` - enable verbose output - - Run cpack with verbose output. +``--verbose, -V`` + Run ``cpack`` with verbose output. This can be used to show more details + from the package generation tools and is suitable for project developers. ``--debug`` - enable debug output (for CPack developers) - - Run cpack with debug output (for CPack developers). - -``-P <package name>`` - override/define CPACK_PACKAGE_NAME - - If the package name is not specified on cpack command line - thenCPack.cmake defines it as CMAKE_PROJECT_NAME - -``-R <package version>`` - override/define CPACK_PACKAGE_VERSION - - If version is not specified on cpack command line thenCPack.cmake - defines it from CPACK_PACKAGE_VERSION_[MAJOR|MINOR|PATCH]look into - CPack.cmake for detail - -``-B <package directory>`` - override/define CPACK_PACKAGE_DIRECTORY - - The directory where CPack will be doing its packaging work.The - resulting package will be found there. Inside this directoryCPack - creates '_CPack_Packages' sub-directory which is theCPack temporary - directory. - -``--vendor <vendor name>`` - override/define CPACK_PACKAGE_VENDOR - - If vendor is not specified on cpack command line (or inside - CMakeLists.txt) thenCPack.cmake defines it with a default value + Run ``cpack`` with debug output. This option is intended mainly for the + developers of ``cpack`` itself and is not normally needed by project + developers. + +``--trace`` + Put the underlying cmake scripts in trace mode. + +``--trace-expand`` + Put the underlying cmake scripts in expanded trace mode. + +``-P <packageName>`` + Override/define the value of the :variable:`CPACK_PACKAGE_NAME` variable used + for packaging. Any value set for this variable in the ``CPackConfig.cmake`` + file will then be ignored. + +``-R <packageVersion>`` + Override/define the value of the :variable:`CPACK_PACKAGE_VERSION` + variable used for packaging. It will override a value set in the + ``CPackConfig.cmake`` file or one automatically computed from + :variable:`CPACK_PACKAGE_VERSION_MAJOR`, + :variable:`CPACK_PACKAGE_VERSION_MINOR` and + :variable:`CPACK_PACKAGE_VERSION_PATCH`. + +``-B <packageDirectory>`` + Override/define :variable:`CPACK_PACKAGE_DIRECTORY`, which controls the + directory where CPack will perform its packaging work. The resultant + package(s) will be created at this location by default and a + ``_CPack_Packages`` subdirectory will also be created below this directory to + use as a working area during package creation. + +``--vendor <vendorName>`` + Override/define :variable:`CPACK_PACKAGE_VENDOR`. .. include:: OPTIONS_HELP.txt diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index a89c4e9bb..e29ebcaf6 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -3,20 +3,27 @@ ctest(1) ******** +.. contents:: + Synopsis ======== .. parsed-literal:: ctest [<options>] + ctest --build-and-test <path-to-source> <path-to-build> + --build-generator <generator> [<options>...] + [--build-options <opts>...] [--test-command <command> [<args>...]] + ctest {-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>} + [-- <dashboard-options>...] Description =========== -The "ctest" executable is the CMake test driver program. +The **ctest** executable is the CMake test driver program. CMake-generated build trees created for projects that use the -ENABLE_TESTING and ADD_TEST commands have testing support. This -program will run the tests and report results. +:command:`enable_testing` and :command:`add_test` commands have testing support. +This program will run the tests and report results. Options ======= @@ -26,8 +33,21 @@ Options Some CMake-generated build trees can have multiple build configurations in the same tree. This option can be used to specify - which one should be tested. Example configurations are "Debug" and - "Release". + which one should be tested. Example configurations are ``Debug`` and + ``Release``. + +``--progress`` + Enable short progress output from tests. + + When the output of **ctest** is being sent directly to a terminal, the + progress through the set of tests is reported by updating the same line + rather than printing start and end messages for each test on new lines. + This can significantly reduce the verbosity of the test output. + Test completion messages are still output on their own line for failed + tests and the final test summary will also still be logged. + + This option can also be enabled by setting the environment variable + :envvar:`CTEST_PROGRESS_OUTPUT`. ``-V,--verbose`` Enable verbose output from tests. @@ -49,22 +69,35 @@ Options ``--output-on-failure`` Output anything outputted by the test program if the test should fail. - This option can also be enabled by setting the environment variable - ``CTEST_OUTPUT_ON_FAILURE``. + This option can also be enabled by setting the + :envvar:`CTEST_OUTPUT_ON_FAILURE` environment variable ``-F`` Enable failover. - This option allows ctest to resume a test set execution that was + This option allows CTest to resume a test set execution that was previously interrupted. If no interruption occurred, the ``-F`` option will have no effect. ``-j <jobs>, --parallel <jobs>`` Run the tests in parallel using the given number of jobs. - This option tells ctest to run the tests in parallel using given - number of jobs. This option can also be set by setting the - environment variable ``CTEST_PARALLEL_LEVEL``. + This option tells CTest to run the tests in parallel using given + number of jobs. This option can also be set by setting the + :envvar:`CTEST_PARALLEL_LEVEL` environment variable. + + This option can be used with the :prop_test:`PROCESSORS` test property. + + See `Label and Subproject Summary`_. + +``--resource-spec-file <file>`` + Run CTest with :ref:`resource allocation <ctest-resource-allocation>` enabled, + using the + :ref:`resource specification file <ctest-resource-specification-file>` + specified in ``<file>``. + + When ``ctest`` is run as a `Dashboard Client`_ this sets the + ``ResourceSpecFile`` option of the `CTest Test Step`_. ``--test-load <level>`` While running tests in parallel (e.g. with ``-j``), try not to start @@ -74,7 +107,7 @@ Options ``TestLoad`` option of the `CTest Test Step`_. ``-Q,--quiet`` - Make ctest quiet. + Make CTest quiet. This option will suppress all the output. The output log file will still be generated if the ``--output-log`` is specified. Options such @@ -84,37 +117,47 @@ Options ``-O <file>, --output-log <file>`` Output to log file. - This option tells ctest to write all its output to a log file. + This option tells CTest to write all its output to a ``<file>`` log file. -``-N,--show-only`` +``-N,--show-only[=<format>]`` Disable actual execution of tests. - This option tells ctest to list the tests that would be run but not + This option tells CTest to list the tests that would be run but not actually run them. Useful in conjunction with the ``-R`` and ``-E`` options. + ``<format>`` can be one of the following values. + + ``human`` + Human-friendly output. This is not guaranteed to be stable. + This is the default. + + ``json-v1`` + Dump the test information in JSON format. + See `Show as JSON Object Model`_. + ``-L <regex>, --label-regex <regex>`` Run tests with labels matching regular expression. - This option tells ctest to run only the tests whose labels match the + This option tells CTest to run only the tests whose labels match the given regular expression. ``-R <regex>, --tests-regex <regex>`` Run tests matching regular expression. - This option tells ctest to run only the tests whose names match the + This option tells CTest to run only the tests whose names match the given regular expression. ``-E <regex>, --exclude-regex <regex>`` Exclude tests matching regular expression. - This option tells ctest to NOT run the tests whose names match the + This option tells CTest to NOT run the tests whose names match the given regular expression. ``-LE <regex>, --label-exclude <regex>`` Exclude tests with labels matching regular expression. - This option tells ctest to NOT run the tests whose labels match the + This option tells CTest to NOT run the tests whose labels match the given regular expression. ``-FA <regex>, --fixture-exclude-any <regex>`` @@ -137,10 +180,13 @@ Options ``-D <dashboard>, --dashboard <dashboard>`` Execute dashboard test. - This option tells ctest to act as a CDash client and perform a - dashboard test. All tests are <Mode><Test>, where Mode can be - Experimental, Nightly, and Continuous, and Test can be Start, - Update, Configure, Build, Test, Coverage, and Submit. + This option tells CTest to act as a CDash client and perform a + dashboard test. All tests are ``<Mode><Test>``, where ``<Mode>`` can be + ``Experimental``, ``Nightly``, and ``Continuous``, and ``<Test>`` can be + ``Start``, ``Update``, ``Configure``, ``Build``, ``Test``, + ``Coverage``, and ``Submit``. + + See `Dashboard Client`_. ``-D <var>:<type>=<value>`` Define a variable for script mode. @@ -153,35 +199,33 @@ Options ``-M <model>, --test-model <model>`` Sets the model for a dashboard. - This option tells ctest to act as a CDash client where the ``<model>`` + This option tells CTest to act as a CDash client where the ``<model>`` can be ``Experimental``, ``Nightly``, and ``Continuous``. Combining ``-M`` and ``-T`` is similar to ``-D``. + See `Dashboard Client`_. + ``-T <action>, --test-action <action>`` Sets the dashboard action to perform. - This option tells ctest to act as a CDash client and perform some + This option tells CTest to act as a CDash client and perform some action such as ``start``, ``build``, ``test`` etc. See `Dashboard Client Steps`_ for the full list of actions. Combining ``-M`` and ``-T`` is similar to ``-D``. -``--track <track>`` - Specify the track to submit dashboard to - - Submit dashboard to specified track instead of default one. By - default, the dashboard is submitted to Nightly, Experimental, or - Continuous track, but by specifying this option, the track can be - arbitrary. + See `Dashboard Client`_. ``-S <script>, --script <script>`` Execute a dashboard for a configuration. - This option tells ctest to load in a configuration script which sets + This option tells CTest to load in a configuration script which sets a number of parameters such as the binary and source directories. - Then ctest will do what is required to create and run a dashboard. + Then CTest will do what is required to create and run a dashboard. This option basically sets up a dashboard and then runs ``ctest -D`` with the appropriate options. + See `Dashboard Client`_. + ``-SP <script>, --script-new-process <script>`` Execute a dashboard for a configuration. @@ -190,19 +234,15 @@ Options script may modify the environment and you do not want the modified environment to impact other ``-S`` scripts. -``-A <file>, --add-notes <file>`` - Add a notes file with submission. - - This option tells ctest to include a notes file when submitting - dashboard. + See `Dashboard Client`_. ``-I [Start,End,Stride,test#,test#|Test file], --tests-information`` Run a specific number of tests by number. - This option causes ctest to run tests starting at number Start, - ending at number End, and incrementing by Stride. Any additional - numbers after Stride are considered individual test numbers. Start, - End,or stride can be empty. Optionally a file can be given that + This option causes CTest to run tests starting at number ``Start``, + ending at number ``End``, and incrementing by ``Stride``. Any additional + numbers after ``Stride`` are considered individual test numbers. ``Start``, + ``End``, or ``Stride`` can be empty. Optionally a file can be given that contains the same syntax as the command line. ``-U, --union`` @@ -214,11 +254,11 @@ Options ``--rerun-failed`` Run only the tests that failed previously. - This option tells ctest to perform only the tests that failed during - its previous run. When this option is specified, ctest ignores all + This option tells CTest to perform only the tests that failed during + its previous run. When this option is specified, CTest ignores all other options intended to modify the list of tests to run (``-L``, ``-R``, ``-E``, ``-LE``, ``-I``, etc). In the event that CTest runs and no tests - fail, subsequent calls to ctest with the ``--rerun-failed`` option will run + fail, subsequent calls to CTest with the ``--rerun-failed`` option will run the set of tests that most recently failed (if any). ``--repeat-until-fail <n>`` @@ -234,41 +274,154 @@ Options name which can be very annoying. ``--interactive-debug-mode [0|1]`` - Set the interactive mode to 0 or 1. + Set the interactive mode to ``0`` or ``1``. - This option causes ctest to run tests in either an interactive mode + 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 + 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. ``--no-label-summary`` Disable timing summary information for labels. - This option tells ctest not to print summary information for each + This option tells CTest not to print summary information for each label associated with the tests run. If there are no labels on the tests, nothing extra is printed. -``--build-and-test <path-to-source> <path-to-build>`` - Configure, build and run a test. + See `Label and Subproject Summary`_. + +``--no-subproject-summary`` + Disable timing summary information for subprojects. + + This option tells CTest not to print summary information for each + subproject associated with the tests run. If there are no subprojects on the + tests, nothing extra is printed. + + See `Label and Subproject Summary`_. + +``--build-and-test`` +See `Build and Test Mode`_. + +``--test-output-size-passed <size>`` + Limit the output for passed tests to ``<size>`` bytes. + +``--test-output-size-failed <size>`` + Limit the output for failed tests to ``<size>`` bytes. - This option tells ctest to configure (i.e. run cmake on), build, - and or execute a test. The configure and test steps are optional. - The arguments to this command line are the source and binary - directories. - The ``--build-generator`` option *must* be provided to use - ``--build-and-test``. If ``--test-command`` is specified then that will be - run after the build is complete. Other options that affect this - mode are ``--build-target``, ``--build-nocmake``, ``--build-run-dir``, - ``--build-two-config``, ``--build-exe-dir``, - ``--build-project``, ``--build-noclean`` and ``--build-options``. +``--overwrite`` + Overwrite CTest configuration option. + + By default CTest uses configuration options from configuration file. + This option will overwrite the configuration option. + +``--force-new-ctest-process`` + Run child CTest instances as new processes. + + By default CTest will run child CTest instances within the same + process. If this behavior is not desired, this argument will + enforce new processes for child CTest processes. + +``--schedule-random`` + Use a random order for scheduling tests. + + This option will run the tests in a random order. It is commonly + used to detect implicit dependencies in a test suite. + +``--submit-index`` + Legacy option for old Dart2 dashboard server feature. + Do not use. + +``--timeout <seconds>`` + Set the default test timeout. + + This option effectively sets a timeout on all tests that do not + already have a timeout set on them via the :prop_test:`TIMEOUT` + property. + +``--stop-time <time>`` + Set a time at which all tests should stop running. + + Set a real time of day at which all tests should timeout. Example: + ``7:00:00 -0400``. Any time format understood by the curl date parser + is accepted. Local time is assumed if no timezone is specified. + +``--print-labels`` + Print all available test labels. + + This option will not run any tests, it will simply print the list of + all labels associated with the test set. + +.. include:: OPTIONS_HELP.txt + +.. _`Label and Subproject Summary`: + +Label and Subproject Summary +============================ + +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. + +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`. + +The weighted time summary reported for each label or subproject ``j`` +is computed as:: + + Weighted Time Summary for Label/Subproject j = + sum(raw_test_time[j,i] * num_processors[j,i], i=1...num_tests[j]) + + for labels/subprojects j=1...total + +where: + +* ``raw_test_time[j,i]``: Wall-clock time for the ``i`` test + for the ``j`` label or subproject +* ``num_processors[j,i]``: Value of the CTest :prop_test:`PROCESSORS` property + for the ``i`` test for the ``j`` label or subproject +* ``num_tests[j]``: Number of tests associated with the ``j`` label or subproject +* ``total``: Total number of labels or subprojects that have at least one test run + +Therefore, the weighted time summary for each label or subproject represents +the amount of time that CTest gave to run the tests for each label or +subproject and gives a good representation of the total expense of the tests +for each label or subproject when compared to other labels or subprojects. + +For example, if ``SubprojectA`` showed ``100 sec*proc`` and ``SubprojectB`` showed +``10 sec*proc``, then CTest allocated approximately 10 times the CPU/core time +to run the tests for ``SubprojectA`` than for ``SubprojectB`` (e.g. so if effort +is going to be expended to reduce the cost of the test suite for the whole +project, then reducing the cost of the test suite for ``SubprojectA`` would +likely have a larger impact than effort to reduce the cost of the test suite +for ``SubprojectB``). + +.. _`Build and Test Mode`: + +Build and Test Mode +=================== + +CTest provides a command-line signature to configure (i.e. run cmake on), +build, and/or execute a test:: + + ctest --build-and-test <path-to-source> <path-to-build> + --build-generator <generator> + [<options>...] + [--build-options <opts>...] + [--test-command <command> [<args>...]] + +The configure and test steps are optional. The arguments to this command line +are the source and binary directories. The ``--build-generator`` option *must* +be provided to use ``--build-and-test``. If ``--test-command`` is specified +then that will be run after the build is complete. Other options that affect +this mode include: ``--build-target`` Specify a specific target to build. - This option goes with the ``--build-and-test`` option, if left out the - ``all`` target is built. + If left out the ``all`` target is built. ``--build-nocmake`` Run the build without running cmake first. @@ -299,91 +452,77 @@ Options Specify the name of the project to build. ``--build-makeprogram`` - Override the make program chosen by CTest with a given one. + Specify the explicit make program to be used by CMake when configuring and + building the project. Only applicable for Make and Ninja based generators. ``--build-noclean`` Skip the make clean step. ``--build-config-sample`` A sample executable to use to determine the configuration that - should be used. e.g. Debug/Release/etc. + should be used. e.g. ``Debug``, ``Release`` etc. ``--build-options`` - Add extra options to the build step. - - This option must be the last option with the exception of - ``--test-command`` + Additional options for configuring the build (i.e. for CMake, not for + the build tool). Note that if this is specified, the ``--build-options`` + keyword and its arguments must be the last option given on the command + line, with the possible exception of ``--test-command``. ``--test-command`` - The test to run with the ``--build-and-test`` option. - -``--test-output-size-passed <size>`` - Limit the output for passed tests to ``<size>`` bytes. - -``--test-output-size-failed <size>`` - Limit the output for failed tests to ``<size>`` bytes. + The command to run as the test step with the ``--build-and-test`` option. + All arguments following this keyword will be assumed to be part of the + test command line, so it must be the last option given. ``--test-timeout`` - The time limit in seconds, internal use only. + The time limit in seconds -``--tomorrow-tag`` - Nightly or experimental starts with next day tag. - - This is useful if the build will not finish in one day. - -``--ctest-config`` - The configuration file used to initialize CTest state when submitting dashboards. +.. _`Dashboard Client`: - This option tells CTest to use different initialization file instead - of CTestConfiguration.tcl. This way multiple initialization files - can be used for example to submit to multiple dashboards. +Dashboard Client +================ -``--overwrite`` - Overwrite CTest configuration option. +CTest can operate as a client for the `CDash`_ software quality dashboard +application. As a dashboard client, CTest performs a sequence of steps +to configure, build, and test software, and then submits the results to +a `CDash`_ server. The command-line signature used to submit to `CDash`_ is:: - By default ctest uses configuration options from configuration file. - This option will overwrite the configuration option. + ctest (-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>) + [-- <dashboard-options>...] -``--extra-submit <file>[;<file>]`` - Submit extra files to the dashboard. +Options for Dashboard Client include: - This option will submit extra files to the dashboard. +``--group <group>`` + Specify what group you'd like to submit results to -``--force-new-ctest-process`` - Run child CTest instances as new processes. - - By default CTest will run child CTest instances within the same - process. If this behavior is not desired, this argument will - enforce new processes for child CTest processes. + Submit dashboard to specified group instead of default one. By + default, the dashboard is submitted to Nightly, Experimental, or + Continuous group, but by specifying this option, the group can be + arbitrary. -``--schedule-random`` - Use a random order for scheduling tests. + This replaces the deprecated option ``--track``. + Despite the name change its behavior is unchanged. - This option will run the tests in a random order. It is commonly - used to detect implicit dependencies in a test suite. +``-A <file>, --add-notes <file>`` + Add a notes file with submission. -``--submit-index`` - Legacy option for old Dart2 dashboard server feature. - Do not use. + This option tells CTest to include a notes file when submitting + dashboard. -``--timeout <seconds>`` - Set a global timeout on all tests. +``--tomorrow-tag`` + ``Nightly`` or ``Experimental`` starts with next day tag. - This option will set a global timeout on all tests that do not - already have a timeout set on them. + This is useful if the build will not finish in one day. -``--stop-time <time>`` - Set a time at which all tests should stop running. +``--extra-submit <file>[;<file>]`` + Submit extra files to the dashboard. - Set a real time of day at which all tests should timeout. Example: - ``7:00:00 -0400``. Any time format understood by the curl date parser - is accepted. Local time is assumed if no timezone is specified. + This option will submit extra files to the dashboard. ``--http1.0`` - Submit using HTTP 1.0. + Submit using `HTTP 1.0`. - This option will force CTest to use HTTP 1.0 to submit files to the - dashboard, instead of HTTP 1.1. + This option will force CTest to use `HTTP 1.0` to submit files to the + dashboard, instead of `HTTP 1.1`. ``--no-compress-output`` Do not compress test output when submitting. @@ -392,26 +531,6 @@ Options this to maintain compatibility with an older version of CDash which doesn't support compressed test output. -``--print-labels`` - Print all available test labels. - - This option will not run any tests, it will simply print the list of - all labels associated with the test set. - -.. include:: OPTIONS_HELP.txt - -.. _`Dashboard Client`: - -Dashboard Client -================ - -CTest can operate as a client for the `CDash`_ software quality dashboard -application. As a dashboard client, CTest performs a sequence of steps -to configure, build, and test software, and then submits the results to -a `CDash`_ server. - -.. _`CDash`: http://cdash.org/ - Dashboard Client Steps ---------------------- @@ -606,7 +725,7 @@ Configuration settings to specify the version control tool include: The source tree is updated by ``git fetch`` followed by ``git reset --hard`` to the ``FETCH_HEAD``. The result is the same - as ``git pull`` except that any local moficiations are overwritten. + as ``git pull`` except that any local modifications are overwritten. Use ``GITUpdateCustom`` to specify a different approach. ``GITInitSubmodules`` @@ -716,6 +835,8 @@ Configuration settings to specify the version control tool include: * :module:`CTest` module variable: ``UPDATE_TYPE`` if set, else ``CTEST_UPDATE_TYPE`` +.. _`UpdateVersionOnly`: + ``UpdateVersionOnly`` Specify that you want the version control update command to only discover the current version that is checked out, and not to update @@ -723,7 +844,18 @@ Configuration settings to specify the version control tool include: * `CTest Script`_ variable: :variable:`CTEST_UPDATE_VERSION_ONLY` +.. _`UpdateVersionOverride`: +``UpdateVersionOverride`` + Specify the current version of your source tree. + + When this variable is set to a non-empty string, CTest will report the value + you specified rather than using the update command to discover the current + version that is checked out. Use of this variable supersedes + ``UpdateVersionOnly``. Like ``UpdateVersionOnly``, using this variable tells + CTest not to update the source tree to a different version. + + * `CTest Script`_ variable: :variable:`CTEST_UPDATE_VERSION_OVERRIDE` Additional configuration settings include: @@ -758,6 +890,16 @@ Configuration settings include: * :module:`CTest` module variable: :variable:`CMAKE_COMMAND` followed by :variable:`PROJECT_SOURCE_DIR` +``LabelsForSubprojects`` + Specify a semicolon-separated list of labels that will be treated as + subprojects. This mapping will be passed on to CDash when configure, test or + build results are submitted. + + * `CTest Script`_ variable: :variable:`CTEST_LABELS_FOR_SUBPROJECTS` + * :module:`CTest` module variable: ``CTEST_LABELS_FOR_SUBPROJECTS`` + + See `Label and Subproject Summary`_. + .. _`CTest Build Step`: CTest Build Step @@ -778,7 +920,17 @@ Configuration settings include: * `CTest Script`_ variable: :variable:`CTEST_CONFIGURATION_TYPE` * :module:`CTest` module variable: ``DEFAULT_CTEST_CONFIGURATION_TYPE``, - initialized by the ``CMAKE_CONFIG_TYPE`` environment variable + initialized by the :envvar:`CMAKE_CONFIG_TYPE` environment variable + +``LabelsForSubprojects`` + Specify a semicolon-separated list of labels that will be treated as + subprojects. This mapping will be passed on to CDash when configure, test or + build results are submitted. + + * `CTest Script`_ variable: :variable:`CTEST_LABELS_FOR_SUBPROJECTS` + * :module:`CTest` module variable: ``CTEST_LABELS_FOR_SUBPROJECTS`` + + See `Label and Subproject Summary`_. ``MakeCommand`` Command-line to launch the software build process. @@ -815,6 +967,21 @@ Arguments to the command may specify some of the step settings. Configuration settings include: +``ResourceSpecFile`` + Specify a + :ref:`resource specification file <ctest-resource-specification-file>`. See + :ref:`ctest-resource-allocation` for more information. + +``LabelsForSubprojects`` + Specify a semicolon-separated list of labels that will be treated as + subprojects. This mapping will be passed on to CDash when configure, test or + build results are submitted. + + * `CTest Script`_ variable: :variable:`CTEST_LABELS_FOR_SUBPROJECTS` + * :module:`CTest` module variable: ``CTEST_LABELS_FOR_SUBPROJECTS`` + + See `Label and Subproject Summary`_. + ``TestLoad`` While running tests in parallel (e.g. with ``-j``), try not to start tests when they may cause the CPU load to pass above a given threshold. @@ -853,6 +1020,8 @@ Configuration settings include: * `CTest Script`_ variable: :variable:`CTEST_COVERAGE_EXTRA_FLAGS` * :module:`CTest` module variable: ``COVERAGE_EXTRA_FLAGS`` + These options are the first arguments passed to ``CoverageCommand``. + .. _`CTest MemCheck Step`: CTest MemCheck Step @@ -945,7 +1114,7 @@ Configuration settings include: * :module:`CTest` module variable: ``BUILDNAME`` ``CDashVersion`` - Specify the version of `CDash`_ on the server. + Legacy option. Not used. * `CTest Script`_ variable: none, detected from server * :module:`CTest` module variable: ``CTEST_CDASH_VERSION`` @@ -974,55 +1143,58 @@ Configuration settings include: * :module:`CTest` module variable: ``CTEST_CURL_OPTIONS`` ``DropLocation`` - The path on the dashboard server to send the submission. + Legacy option. When ``SubmitURL`` is not set, it is constructed from + ``DropMethod``, ``DropSiteUser``, ``DropSitePassword``, ``DropSite``, and + ``DropLocation``. * `CTest Script`_ variable: :variable:`CTEST_DROP_LOCATION` * :module:`CTest` module variable: ``DROP_LOCATION`` if set, else ``CTEST_DROP_LOCATION`` ``DropMethod`` - Specify the method by which results should be submitted to the - dashboard server. The value may be ``cp``, ``ftp``, ``http``, - ``https``, ``scp``, or ``xmlrpc`` (if CMake was built with - support for it). + Legacy option. When ``SubmitURL`` is not set, it is constructed from + ``DropMethod``, ``DropSiteUser``, ``DropSitePassword``, ``DropSite``, and + ``DropLocation``. * `CTest Script`_ variable: :variable:`CTEST_DROP_METHOD` * :module:`CTest` module variable: ``DROP_METHOD`` if set, else ``CTEST_DROP_METHOD`` ``DropSite`` - The dashboard server name - (for ``ftp``, ``http``, and ``https``, ``scp``, and ``xmlrpc``). + Legacy option. When ``SubmitURL`` is not set, it is constructed from + ``DropMethod``, ``DropSiteUser``, ``DropSitePassword``, ``DropSite``, and + ``DropLocation``. * `CTest Script`_ variable: :variable:`CTEST_DROP_SITE` * :module:`CTest` module variable: ``DROP_SITE`` if set, else ``CTEST_DROP_SITE`` ``DropSitePassword`` - The dashboard server login password, if any - (for ``ftp``, ``http``, and ``https``). + Legacy option. When ``SubmitURL`` is not set, it is constructed from + ``DropMethod``, ``DropSiteUser``, ``DropSitePassword``, ``DropSite``, and + ``DropLocation``. * `CTest Script`_ variable: :variable:`CTEST_DROP_SITE_PASSWORD` * :module:`CTest` module variable: ``DROP_SITE_PASSWORD`` if set, else ``CTEST_DROP_SITE_PASWORD`` ``DropSiteUser`` - The dashboard server login user name, if any - (for ``ftp``, ``http``, and ``https``). + Legacy option. When ``SubmitURL`` is not set, it is constructed from + ``DropMethod``, ``DropSiteUser``, ``DropSitePassword``, ``DropSite``, and + ``DropLocation``. * `CTest Script`_ variable: :variable:`CTEST_DROP_SITE_USER` * :module:`CTest` module variable: ``DROP_SITE_USER`` if set, else ``CTEST_DROP_SITE_USER`` ``IsCDash`` - Specify whether the dashboard server is `CDash`_ or an older - dashboard server implementation requiring ``TriggerSite``. + Legacy option. Not used. * `CTest Script`_ variable: :variable:`CTEST_DROP_SITE_CDASH` * :module:`CTest` module variable: ``CTEST_DROP_SITE_CDASH`` ``ScpCommand`` - ``scp`` command-line tool to use when ``DropMethod`` is ``scp``. + Legacy option. Not used. * `CTest Script`_ variable: :variable:`CTEST_SCP_COMMAND` * :module:`CTest` module variable: ``SCPCOMMAND`` @@ -1035,15 +1207,325 @@ Configuration settings include: * :module:`CTest` module variable: ``SITE``, initialized by the :command:`site_name` command +``SubmitURL`` + The ``http`` or ``https`` URL of the dashboard server to send the submission + to. + + * `CTest Script`_ variable: :variable:`CTEST_SUBMIT_URL` + * :module:`CTest` module variable: ``SUBMIT_URL`` if set, + else ``CTEST_SUBMIT_URL`` + ``TriggerSite`` - Legacy option to support older dashboard server implementations. - Not used when ``IsCDash`` is true. + Legacy option. Not used. * `CTest Script`_ variable: :variable:`CTEST_TRIGGER_SITE` * :module:`CTest` module variable: ``TRIGGER_SITE`` if set, else ``CTEST_TRIGGER_SITE`` +.. _`Show as JSON Object Model`: + +Show as JSON Object Model +========================= + +When the ``--show-only=json-v1`` command line option is given, the test +information is output in JSON format. Version 1.0 of the JSON object +model is defined as follows: + +``kind`` + The string "ctestInfo". + +``version`` + A JSON object specifying the version components. Its members are + + ``major`` + A non-negative integer specifying the major version component. + ``minor`` + A non-negative integer specifying the minor version component. + +``backtraceGraph`` + JSON object representing backtrace information with the + following members: + + ``commands`` + List of command names. + ``files`` + List of file names. + ``nodes`` + List of node JSON objects with members: + + ``command`` + Index into the ``commands`` member of the ``backtraceGraph``. + ``file`` + Index into the ``files`` member of the ``backtraceGraph``. + ``line`` + Line number in the file where the backtrace was added. + ``parent`` + Index into the ``nodes`` member of the ``backtraceGraph`` + representing the parent in the graph. + +``tests`` + A JSON array listing information about each test. Each entry + is a JSON object with members: + + ``name`` + Test name. + ``config`` + Configuration that the test can run on. + Empty string means any config. + ``command`` + List where the first element is the test command and the + remaining elements are the command arguments. + ``backtrace`` + Index into the ``nodes`` member of the ``backtraceGraph``. + ``properties`` + Test properties. + Can contain keys for each of the supported test properties. + +.. _`ctest-resource-allocation`: + +Resource Allocation +=================== + +CTest provides a mechanism for tests to specify the resources that they need +in a fine-grained way, and for users to specify the resources availiable on +the running machine. This allows CTest to internally keep track of which +resources are in use and which are free, scheduling tests in a way that +prevents them from trying to claim resources that are not available. + +A common use case for this feature is for tests that require the use of a GPU. +Multiple tests can simultaneously allocate memory from a GPU, but if too many +tests try to do this at once, some of them will fail to allocate, resulting in +a failed test, even though the test would have succeeded if it had the memory +it needed. By using the resource allocation feature, each test can specify how +much memory it requires from a GPU, allowing CTest to schedule tests in a way +that running several of these tests at once does not exhaust the GPU's memory +pool. + +Please note that CTest has no concept of what a GPU is or how much memory it +has, nor does it have any way of communicating with a GPU to retrieve this +information or perform any memory management. CTest simply keeps track of a +list of abstract resource types, each of which has a certain number of slots +available for tests to use. Each test specifies the number of slots that it +requires from a certain resource, and CTest then schedules them in a way that +prevents the total number of slots in use from exceeding the listed capacity. +When a test is executed, and slots from a resource are allocated to that test, +tests may assume that they have exclusive use of those slots for the duration +of the test's process. + +The CTest resource allocation feature consists of two inputs: + +* The :ref:`resource specification file <ctest-resource-specification-file>`, + described below, which describes the resources available on the system. +* The :prop_test:`RESOURCE_GROUPS` property of tests, which describes the + resources required by the test. + +When CTest runs a test, the resources allocated to that test are passed in the +form of a set of +:ref:`environment variables <ctest-resource-environment-variables>` as +described below. Using this information to decide which resource to connect to +is left to the test writer. + +The ``RESOURCE_GROUPS`` property tells CTest what resources a test expects +to use grouped in a way meaningful to the test. The test itself must read +the :ref:`environment variables <ctest-resource-environment-variables>` to +determine which resources have been allocated to each group. For example, +each group may correspond to a process the test will spawn when executed. + +Note that even if a test specifies a ``RESOURCE_GROUPS`` property, it is still +possible for that to test to run without any resource allocation (and without +the corresponding +:ref:`environment variables <ctest-resource-environment-variables>`) +if the user does not pass a resource specification file. Passing this file, +either through the ``--resource-spec-file`` command-line argument or the +``RESOURCE_SPEC_FILE`` argument to :command:`ctest_test`, is what activates the +resource allocation feature. Tests should check the +``CTEST_RESOURCE_GROUP_COUNT`` environment variable to find out whether or not +resource allocation is activated. This variable will always (and only) be +defined if resource allocation is activated. If resource allocation is not +activated, then the ``CTEST_RESOURCE_GROUP_COUNT`` variable will not exist, +even if it exists for the parent ``ctest`` process. If a test absolutely must +have resource allocation, then it can return a failing exit code or use the +:prop_test:`SKIP_RETURN_CODE` or :prop_test:`SKIP_REGULAR_EXPRESSION` +properties to indicate a skipped test. + +.. _`ctest-resource-specification-file`: + +Resource Specification File +--------------------------- + +The resource specification file is a JSON file which is passed to CTest, either +on the :manual:`ctest(1)` command line as ``--resource-spec-file``, or as the +``RESOURCE_SPEC_FILE`` argument of :command:`ctest_test`. The resource +specification file must be a JSON object. All examples in this document assume +the following resource specification file: + +.. code-block:: json + + { + "version": { + "major": 1, + "minor": 0 + }, + "local": [ + { + "gpus": [ + { + "id": "0", + "slots": 2 + }, + { + "id": "1", + "slots": 4 + }, + { + "id": "2", + "slots": 2 + }, + { + "id": "3" + } + ], + "crypto_chips": [ + { + "id": "card0", + "slots": 4 + } + ] + } + ] + } + +The members are: + +``version`` + An object containing a ``major`` integer field and a ``minor`` integer field. + Currently, the only supported version is major ``1``, minor ``0``. Any other + value is an error. + +``local`` + A JSON array of resource sets present on the system. Currently, this array + is restricted to being of size 1. + + Each array element is a JSON object with members whose names are equal to the + desired resource types, such as ``gpus``. These names must start with a + lowercase letter or an underscore, and subsequent characters can be a + lowercase letter, a digit, or an underscore. Uppercase letters are not + allowed, because certain platforms have case-insensitive environment + variables. See the `Environment Variables`_ section below for + more information. It is recommended that the resource type name be the plural + of a noun, such as ``gpus`` or ``crypto_chips`` (and not ``gpu`` or + ``crypto_chip``.) + + Please note that the names ``gpus`` and ``crypto_chips`` are just examples, + and CTest does not interpret them in any way. You are free to make up any + resource type you want to meet your own requirements. + + The value for each resource type is a JSON array consisting of JSON objects, + each of which describe a specific instance of the specified resource. These + objects have the following members: + + ``id`` + A string consisting of an identifier for the resource. Each character in + the identifier can be a lowercase letter, a digit, or an underscore. + Uppercase letters are not allowed. + + Identifiers must be unique within a resource type. However, they do not + have to be unique across resource types. For example, it is valid to have a + ``gpus`` resource named ``0`` and a ``crypto_chips`` resource named ``0``, + but not two ``gpus`` resources both named ``0``. + + Please note that the IDs ``0``, ``1``, ``2``, ``3``, and ``card0`` are just + examples, and CTest does not interpret them in any way. You are free to + make up any IDs you want to meet your own requirements. + + ``slots`` + An optional unsigned number specifying the number of slots available on the + resource. For example, this could be megabytes of RAM on a GPU, or + cryptography units available on a cryptography chip. If ``slots`` is not + specified, a default value of ``1`` is assumed. + +In the example file above, there are four GPUs with ID's 0 through 3. GPU 0 has +2 slots, GPU 1 has 4, GPU 2 has 2, and GPU 3 has a default of 1 slot. There is +also one cryptography chip with 4 slots. + +``RESOURCE_GROUPS`` Property +---------------------------- + +See :prop_test:`RESOURCE_GROUPS` for a description of this property. + +.. _`ctest-resource-environment-variables`: + +Environment Variables +--------------------- + +Once CTest has decided which resources to allocate to a test, it passes this +information to the test executable as a series of environment variables. For +each example below, we will assume that the test in question has a +:prop_test:`RESOURCE_GROUPS` property of +``2,gpus:2;gpus:4,gpus:1,crypto_chips:2``. + +The following variables are passed to the test process: + +.. envvar:: CTEST_RESOURCE_GROUP_COUNT + + The total number of groups specified by the :prop_test:`RESOURCE_GROUPS` + property. For example: + + * ``CTEST_RESOURCE_GROUP_COUNT=3`` + + This variable will only be defined if :manual:`ctest(1)` has been given a + ``--resource-spec-file``, or if :command:`ctest_test` has been given a + ``RESOURCE_SPEC_FILE``. If no resource specification file has been given, + this variable will not be defined. + +.. envvar:: CTEST_RESOURCE_GROUP_<num> + + The list of resource types allocated to each group, with each item + separated by a comma. ``<num>`` is a number from zero to + ``CTEST_RESOURCE_GROUP_COUNT`` minus one. ``CTEST_RESOURCE_GROUP_<num>`` + is defined for each ``<num>`` in this range. For example: + + * ``CTEST_RESOURCE_GROUP_0=gpus`` + * ``CTEST_RESOURCE_GROUP_1=gpus`` + * ``CTEST_RESOURCE_GROUP_2=crypto_chips,gpus`` + +.. envvar:: CTEST_RESOURCE_GROUP_<num>_<resource-type> + + The list of resource IDs and number of slots from each ID allocated to each + group for a given resource type. This variable consists of a series of + pairs, each pair separated by a semicolon, and with the two items in the pair + separated by a comma. The first item in each pair is ``id:`` followed by the + ID of a resource of type ``<resource-type>``, and the second item is + ``slots:`` followed by the number of slots from that resource allocated to + the given group. For example: + + * ``CTEST_RESOURCE_GROUP_0_GPUS=id:0,slots:2`` + * ``CTEST_RESOURCE_GROUP_1_GPUS=id:2,slots:2`` + * ``CTEST_RESOURCE_GROUP_2_GPUS=id:1,slots:4;id:3,slots:1`` + * ``CTEST_RESOURCE_GROUP_2_CRYPTO_CHIPS=id:card0,slots:2`` + + In this example, group 0 gets 2 slots from GPU ``0``, group 1 gets 2 slots + from GPU ``2``, and group 2 gets 4 slots from GPU ``1``, 1 slot from GPU + ``3``, and 2 slots from cryptography chip ``card0``. + + ``<num>`` is a number from zero to ``CTEST_RESOURCE_GROUP_COUNT`` minus one. + ``<resource-type>`` is the name of a resource type, converted to uppercase. + ``CTEST_RESOURCE_GROUP_<num>_<resource-type>`` is defined for the product + of each ``<num>`` in the range listed above and each resource type listed in + ``CTEST_RESOURCE_GROUP_<num>``. + + Because some platforms have case-insensitive names for environment variables, + the names of resource types may not clash in a case-insensitive environment. + Because of this, for the sake of simplicity, all resource types must be + listed in all lowercase in the + :ref:`resource specification file <ctest-resource-specification-file>` and + in the :prop_test:`RESOURCE_GROUPS` property, and they are converted to all + uppercase in the ``CTEST_RESOURCE_GROUP_<num>_<resource-type>`` environment + variable. + See Also ======== .. include:: LINKS.txt + +.. _`CDash`: http://cdash.org/ |