diff options
Diffstat (limited to 'Help/manual')
| -rw-r--r-- | Help/manual/cmake-buildsystem.7.rst | 6 | ||||
| -rw-r--r-- | Help/manual/cmake-commands.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-env-variables.7.rst | 54 | ||||
| -rw-r--r-- | Help/manual/cmake-generator-expressions.7.rst | 12 | ||||
| -rw-r--r-- | Help/manual/cmake-language.7.rst | 18 | ||||
| -rw-r--r-- | Help/manual/cmake-modules.7.rst | 5 | ||||
| -rw-r--r-- | Help/manual/cmake-policies.7.rst | 17 | ||||
| -rw-r--r-- | Help/manual/cmake-properties.7.rst | 13 | ||||
| -rw-r--r-- | Help/manual/cmake-qt.7.rst | 54 | ||||
| -rw-r--r-- | Help/manual/cmake-server.7.rst | 124 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 20 | ||||
| -rw-r--r-- | Help/manual/cmake.1.rst | 41 | ||||
| -rw-r--r-- | Help/manual/ctest.1.rst | 311 |
13 files changed, 529 insertions, 147 deletions
diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 95f5b87..ae538ed 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -266,7 +266,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 @@ -687,7 +687,8 @@ 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 ``Headers`` directory of the framework is also treated as a usage requirement. @@ -970,7 +971,6 @@ are: * ``EXPORT_NAME`` * ``IMPORTED`` * ``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 611c989..f8bfb32 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst @@ -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 diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst new file mode 100644 index 0000000..fed129e --- /dev/null +++ b/Help/manual/cmake-env-variables.7.rst @@ -0,0 +1,54 @@ +.. cmake-manual-description: CMake Environment Variables Reference + +cmake-env-variables(7) +********************** + +.. only:: html + + .. contents:: + +Environment Variables that Control the Build +============================================ + +.. toctree:: + :maxdepth: 1 + + /envvar/CMAKE_CONFIG_TYPE + /envvar/CMAKE_MSVCIDE_RUN_PATH + /envvar/CMAKE_OSX_ARCHITECTURES + /envvar/LDFLAGS + /envvar/MACOSX_DEPLOYMENT_TARGET + +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 + +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_USE_LAUNCHERS_DEFAULT + /envvar/DASHBOARD_TEST_FROM_CTEST diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index bddb174..dc5621a 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -97,7 +97,7 @@ Available logical expressions are: 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 + otherwise ``0``. This expression may be 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): @@ -109,10 +109,12 @@ Available logical expressions are: PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions> ) - 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: + Note that with :ref:`Visual Studio Generators` there is no way to represent + target-wide flags separately for ``C`` and ``CXX`` languages. Under these + generators, target-wide flags 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: .. code-block:: cmake diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index 27b5d30..87f8f9d 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. @@ -334,6 +334,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 @@ -514,7 +516,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 diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 4a03b7a..694bae5 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -60,6 +60,7 @@ All Modules /module/CPackCygwin /module/CPackDeb /module/CPackDMG + /module/CPackFreeBSD /module/CPackIFW /module/CPackIFWConfigureFile /module/CPackNSIS @@ -79,6 +80,7 @@ All Modules /module/ExternalData /module/ExternalProject /module/FeatureSummary + /module/FetchContent /module/FindALSA /module/FindArmadillo /module/FindASPELL @@ -128,6 +130,7 @@ All Modules /module/FindIcotool /module/FindICU /module/FindImageMagick + /module/FindIconv /module/FindIntl /module/FindITK /module/FindJasper @@ -152,6 +155,7 @@ All Modules /module/FindMPEG2 /module/FindMPEG /module/FindMPI + /module/FindOpenACC /module/FindOpenAL /module/FindOpenCL /module/FindOpenGL @@ -181,6 +185,7 @@ All Modules /module/FindosgWidget /module/FindPackageHandleStandardArgs /module/FindPackageMessage + /module/FindPatch /module/FindPerlLibs /module/FindPerl /module/FindPHP4 diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 7b85817..96d5c7d 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,23 @@ 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.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 ec25596..2c63c4b 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -74,6 +74,7 @@ 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/LISTFILE_STACK /prop_dir/MACROS @@ -83,7 +84,7 @@ Properties on Directories /prop_dir/RULE_LAUNCH_LINK /prop_dir/SOURCE_DIR /prop_dir/SUBDIRECTORIES - /prop_dir/TEST_INCLUDE_FILE + /prop_dir/TEST_INCLUDE_FILES /prop_dir/VARIABLES /prop_dir/VS_GLOBAL_SECTION_POST_section /prop_dir/VS_GLOBAL_SECTION_PRE_section @@ -121,7 +122,9 @@ Properties on Targets /prop_tgt/ARCHIVE_OUTPUT_NAME /prop_tgt/AUTOGEN_BUILD_DIR /prop_tgt/AUTOGEN_TARGET_DEPENDS + /prop_tgt/AUTOMOC_COMPILER_PREDEFINES /prop_tgt/AUTOMOC_DEPEND_FILTERS + /prop_tgt/AUTOMOC_MACRO_NAMES /prop_tgt/AUTOMOC_MOC_OPTIONS /prop_tgt/AUTOMOC /prop_tgt/AUTOUIC @@ -181,6 +184,7 @@ Properties on Targets /prop_tgt/HAS_CXX /prop_tgt/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM /prop_tgt/IMPORTED_CONFIGURATIONS + /prop_tgt/IMPORTED_GLOBAL /prop_tgt/IMPORTED_IMPLIB_CONFIG /prop_tgt/IMPORTED_IMPLIB /prop_tgt/IMPORTED_LIBNAME_CONFIG @@ -225,6 +229,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 @@ -291,6 +296,7 @@ Properties on Targets /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 @@ -385,10 +391,14 @@ 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_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 @@ -434,6 +444,7 @@ Deprecated Properties on Directories :maxdepth: 1 /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 00d6e6e..cafeae1 100644 --- a/Help/manual/cmake-qt.7.rst +++ b/Help/manual/cmake-qt.7.rst @@ -59,9 +59,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 @@ -70,7 +71,11 @@ be included by the user in the C++ implementation file with a preprocessor Included ``moc_*.cpp`` and ``*.moc`` files will be generated in the ``<AUTOGEN_BUILD_DIR>/include`` directory which is automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`. -(This differs from CMake 3.7 and below; see their documentation for details.) + +* 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`. @@ -91,6 +96,8 @@ 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`. @@ -107,15 +114,26 @@ inspects the C++ files in the target to determine if they require ``uic`` to be run, and to create rules to execute ``uic`` at the appropriate time. If a preprocessor ``#include`` directive is found which matches -``ui_<basename>.h``, and a ``<basename>.ui`` file exists, then ``uic`` will -be executed to generate the appropriate file. The ``<basename>.ui`` file is -searched for first in the vicinity of including file and afterwards in the -optional :prop_tgt:`AUTOUIC_SEARCH_PATHS` of the target. +``<path>ui_<basename>.h``, and a ``<basename>.ui`` file exists, +then ``uic`` will be executed to generate the appropriate file. +The ``<basename>.ui`` file is searched for in the following places + +1. ``<source_dir>/<basename>.ui`` +2. ``<source_dir>/<path><basename>.ui`` +3. ``<AUTOUIC_SEARCH_PATHS>/<basename>.ui`` +4. ``<AUTOUIC_SEARCH_PATHS>/<path><basename>.ui`` + +where ``<source_dir>`` is the directory of the C++ file and +:prop_tgt:`AUTOUIC_SEARCH_PATHS` is a list of additional search paths. The generated generated ``ui_*.h`` files are placed in the ``<AUTOGEN_BUILD_DIR>/include`` directory which is automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`. -(This differs from CMake 3.7 and below; see their documentation for details.) + +* 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`. @@ -195,6 +213,24 @@ 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`. +Visual Studio Generators +======================== + +When using the :manual:`Visual Studio generators <cmake-generators(7)>` +CMake tries to use a ``PRE_BUILD`` +:command:`custom command <add_custom_command>` instead +of a :command:`custom target <add_custom_target>` for autogen. +``PRE_BUILD`` can't be used when the autogen target depends on files. +This happens when + +- :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` is enabled and the origin target + depends on :prop_sf:`GENERATED` files which aren't excluded from autogen by + :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC`, :prop_sf:`SKIP_AUTOGEN` + or :policy:`CMP0071` +- :prop_tgt:`AUTORCC` is enabled and a ``.qrc`` file is listed in + the origin target sources +- :prop_tgt:`AUTOGEN_TARGET_DEPENDS` lists a source file + qtmain.lib on Windows ===================== diff --git a/Help/manual/cmake-server.7.rst b/Help/manual/cmake-server.7.rst index 9520cc1..c2aef99 100644 --- a/Help/manual/cmake-server.7.rst +++ b/Help/manual/cmake-server.7.rst @@ -254,6 +254,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 +273,13 @@ The first request that the client may send to the server is of type "handshake". This request needs to pass one of the "supportedProtocolVersions" of the "hello" type response received earlier back to the server in the "protocolVersion" field. +Giving the "major" version of the requested protocol version will make the server +use the latest minor version of that protocol. Use this if you do not explicitly +need to depend on a specific minor version. -Each protocol version may request additional attributes to be present. +If the build directory already contains a CMake cache, it is sufficient to set +the "buildDirectory" attribute. To create a fresh build directory, additional +attributes are required depending on the protocol version. Protocol version 1.0 requires the following attributes to be set: @@ -448,6 +458,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 +486,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 @@ -496,6 +517,9 @@ Each target object can have the following keys: with the sysroot path. "fileGroups" contains the source files making up the target. +"crossReferences" + contains the location of the target in the corresponding CMakeLists.txt + file and the locations of the related statements like "target_link_libraries" FileGroups are used to group sources using similar settings together. @@ -521,6 +545,16 @@ Each fileGroup object may contain the following keys: All file paths in the fileGroup are either absolute or relative to the sourceDirectory of the target. +CrossReferences object is used to report the location of the target (including +the entire call stack if the target is defined in a function) and the related +"target_link_libraries", "target_include_directories", "target_compile_definitions" +and "target_compile_options" statements. + +See the example below for details on the internal format of the "crossReferences" object. +Line numbers stated in the "backtrace" entries are 1-based. The last entry of a backtrace +is a special entry with missing "line" and "name" fields that specifies the initial +CMakeLists.txt file. + Example:: [== "CMake Server" ==[ @@ -557,7 +591,34 @@ CMake will reply:: "linkerLanguage": "C", "name": "cmForm", "sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form", - "type": "STATIC_LIBRARY" + "type": "STATIC_LIBRARY", + "crossReferences": { + "backtrace": [ + { + "line": 7, + "name": "add_executable", + "path": "C:/full/path/CMakeLists.txt" + }, + { + "path": "c:/full/path/CMakeLists.txt" + } + ], + "relatedStatements": [ + { + "backtrace": [ + { + "line": 8, + "name": "target_link_libraries", + "path": "c:/full/path/CMakeLists.txt" + }, + { + "path": "c:/full/path/CMakeLists.txt" + } + ], + "type": "target_link_libraries" + } + ] + } } ] }, @@ -572,6 +633,62 @@ 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. +"backtrace" + contains a list of backtrace objects that specify where the test was defined. + +Each backtrace object can have the following keys: + +"path" + contains the full path to the file containing the statement. +"line" + contains the line number in the file where the statement was defined. +"name" + contains the name of the statement that added the test. + +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 +733,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-variables.7.rst b/Help/manual/cmake-variables.7.rst index 1a2726d..735b93b 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -32,6 +32,7 @@ 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_EDIT_COMMAND /variable/CMAKE_EXECUTABLE_SUFFIX @@ -41,6 +42,7 @@ 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 @@ -48,6 +50,7 @@ Variables that Provide Information /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_LINK_LIBRARY_SUFFIX @@ -59,6 +62,8 @@ Variables that Provide Information /variable/CMAKE_MATCH_n /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 @@ -120,6 +125,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 @@ -154,6 +161,7 @@ Variables that Change Behavior /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 @@ -183,6 +191,7 @@ 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 Variables that Describe the System ================================== @@ -268,7 +277,9 @@ Variables that Control the Build /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG /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_AUTORCC /variable/CMAKE_AUTORCC_OPTIONS @@ -281,6 +292,7 @@ Variables that Control the Build /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_CONFIG_POSTFIX + /variable/CMAKE_CUDA_SEPARABLE_COMPILATION /variable/CMAKE_DEBUG_POSTFIX /variable/CMAKE_ENABLE_EXPORTS /variable/CMAKE_EXE_LINKER_FLAGS @@ -300,6 +312,7 @@ 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_VISIBILITY_PRESET @@ -319,6 +332,7 @@ 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_NINJA_OUTPUT_PATH_PREFIX /variable/CMAKE_NO_BUILTIN_CHRPATH /variable/CMAKE_NO_SYSTEM_FROM_IMPORTED @@ -362,6 +376,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 @@ -386,11 +401,14 @@ Variables for Languages /variable/CMAKE_LANG_ARCHIVE_FINISH /variable/CMAKE_LANG_COMPILER /variable/CMAKE_LANG_COMPILER_ABI + /variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID /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_COMPILER_VERSION_INTERNAL /variable/CMAKE_LANG_COMPILE_OBJECT /variable/CMAKE_LANG_CREATE_SHARED_LIBRARY /variable/CMAKE_LANG_CREATE_SHARED_MODULE @@ -480,6 +498,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 @@ -514,6 +533,7 @@ Variables for CPack /variable/CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY /variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION /variable/CPACK_INCLUDE_TOPLEVEL_DIRECTORY + /variable/CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS /variable/CPACK_INSTALL_SCRIPT /variable/CPACK_PACKAGING_INSTALL_PREFIX /variable/CPACK_SET_DESTDIR diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index ba925e8..ff8c6c7 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -11,6 +11,7 @@ Synopsis 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 --open <dir> cmake -E <command> [<options>...] cmake --find-package <options>... @@ -51,6 +52,10 @@ Options ``--build <dir>`` See `Build Tool Mode`_. +``--open <dir>`` + Open the generated project in the associated application. This is + only supported by some generators. + ``-N`` View mode only. @@ -69,11 +74,11 @@ Options 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. @@ -138,6 +143,8 @@ Options .. include:: OPTIONS_HELP.txt +.. _`Build Tool Mode`: + Build Tool Mode =============== @@ -262,6 +269,36 @@ 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 diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index a89c4e9..d9af3bc 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -3,12 +3,18 @@ ctest(1) ******** +.. contents:: + Synopsis ======== .. parsed-literal:: ctest [<options>] + ctest <path-to-source> <path-to-build> --build-generator <generator> + [<options>...] [-- <build-options>...] [--test-command <test>] + ctest (-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>) + [-- <dashboard-options>...] Description =========== @@ -55,17 +61,21 @@ Options ``-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 + 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 can be used with the :prop_test:`PROCESSORS` test property. + + See `Label and Subproject Summary`_. + ``--test-load <level>`` While running tests in parallel (e.g. with ``-j``), try not to start tests when they may cause the CPU load to pass above a given threshold. @@ -74,7 +84,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 +94,37 @@ 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 log file. ``-N,--show-only`` 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. ``-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,11 +147,13 @@ Options ``-D <dashboard>, --dashboard <dashboard>`` Execute dashboard test. - This option tells ctest to act as a CDash client and perform a + 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 +165,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,16 +200,12 @@ 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, + 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 @@ -214,11 +220,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>`` @@ -236,7 +242,7 @@ Options ``--interactive-debug-mode [0|1]`` Set the interactive mode to 0 or 1. - This option causes ctest to run tests in either an interactive mode + 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 @@ -246,29 +252,111 @@ Options ``--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. + +``--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 a global timeout on all tests. + + This option will set a global timeout on all tests that do not + already have a timeout set on them. + +``--stop-time <time>`` + Set a time at which all tests should stop running. - 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``. + 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 wall clock +time for the test run will be multiplied by this property to give a better +idea of how much cpu resource CTest allocated for the test. The time is +reported with `sec*proc` instead of just `sec`. + +.. _`Build and Test Mode`: + +Build and Test Mode +=================== + +CTest provides a command-line signature to 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>...] + [--test-command <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 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. @@ -317,67 +405,47 @@ Options ``--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. - ``--test-timeout`` - The time limit in seconds, internal use only. - -``--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. - - 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. + The time limit in seconds -``--overwrite`` - Overwrite CTest configuration option. +.. _`Dashboard Client`: - By default ctest uses configuration options from configuration file. - This option will overwrite the configuration option. +Dashboard Client +================ -``--extra-submit <file>[;<file>]`` - Submit extra files to the dashboard. +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:: - This option will submit extra files to the dashboard. + ctest (-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>) + [-- <dashboard-options>...] -``--force-new-ctest-process`` - Run child CTest instances as new processes. +Options for Dashboard Client include: - 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. +``--track <track>`` + Specify the track to submit dashboard to -``--schedule-random`` - Use a random order for scheduling tests. + 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. - 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. @@ -392,26 +460,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 ---------------------- @@ -724,7 +772,6 @@ Configuration settings to specify the version control tool include: * `CTest Script`_ variable: :variable:`CTEST_UPDATE_VERSION_ONLY` - Additional configuration settings include: ``NightlyStartTime`` @@ -758,6 +805,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 @@ -780,6 +837,16 @@ Configuration settings include: * :module:`CTest` module variable: ``DEFAULT_CTEST_CONFIGURATION_TYPE``, initialized by the ``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. It will be executed in the location specified by the @@ -815,6 +882,16 @@ Arguments to the command may specify some of the step settings. Configuration settings include: +``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 +930,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 @@ -1047,3 +1126,5 @@ See Also ======== .. include:: LINKS.txt + +.. _`CDash`: http://cdash.org/ |