diff --git a/.clang-format b/.clang-format index 162c56d76..0c7d6b072 100644 --- a/.clang-format +++ b/.clang-format @@ -18,4 +18,28 @@ ColumnLimit: 79 IndentPPDirectives: AfterHash SortUsingDeclarations: false SpaceAfterTemplateKeyword: true +IncludeBlocks: Regroup +IncludeCategories: + - Regex: '^[<"]cmConfigure\.h' + Priority: -1 + - Regex: '^(<|")cm/' + Priority: 2 + - Regex: '^(<|")windows\.h' + Priority: 3 + - Regex: '^/dev/null | + tail -n +2 | cut -f1 -d: )' -P "$prefix" -- "$cur" ) ) compopt -o nospace fi return diff --git a/Auxiliary/cmake-mode.el b/Auxiliary/cmake-mode.el index e4fa6c175..caaf0d52f 100644 --- a/Auxiliary/cmake-mode.el +++ b/Auxiliary/cmake-mode.el @@ -1,5 +1,7 @@ ;;; cmake-mode.el --- major-mode for editing CMake sources +;; Package-Requires: ((emacs "24.1")) + ; Distributed under the OSI-approved BSD 3-Clause License. See accompanying ; file Copyright.txt or https://cmake.org/licensing for details. @@ -224,17 +226,11 @@ the indentation. Otherwise it retains the same position on the line" ;; (defvar cmake-mode-hook nil) -;------------------------------------------------------------------------------ - -;; For compatibility with Emacs < 24 -(defalias 'cmake--parent-mode - (if (fboundp 'prog-mode) 'prog-mode 'fundamental-mode)) - ;;------------------------------------------------------------------------------ ;; Mode definition. ;; ;;;###autoload -(define-derived-mode cmake-mode cmake--parent-mode "CMake" +(define-derived-mode cmake-mode prog-mode "CMake" "Major mode for editing CMake source files." ; Setup font-lock mode. diff --git a/Auxiliary/vim/syntax/cmake.vim b/Auxiliary/vim/syntax/cmake.vim index cd8385b67..5de117b82 100644 --- a/Auxiliary/vim/syntax/cmake.vim +++ b/Auxiliary/vim/syntax/cmake.vim @@ -288,6 +288,7 @@ syn keyword cmakeProperty contained \ SKIP_AUTORCC \ SKIP_AUTOUIC \ SKIP_BUILD_RPATH + \ SKIP_REGULAR_EXPRESSION \ SKIP_RETURN_CODE \ SOURCES \ SOURCE_DIR @@ -915,6 +916,7 @@ syn keyword cmakeVariable contained \ CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES \ CMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT \ CMAKE_ECLIPSE_MAKE_ARGUMENTS + \ CMAKE_ECLIPSE_RESOURCE_ENCODING \ CMAKE_ECLIPSE_VERSION \ CMAKE_EDIT_COMMAND \ CMAKE_ENABLE_EXPORTS @@ -948,6 +950,12 @@ syn keyword cmakeVariable contained \ CMAKE_FIND_ROOT_PATH_MODE_LIBRARY \ CMAKE_FIND_ROOT_PATH_MODE_PACKAGE \ CMAKE_FIND_ROOT_PATH_MODE_PROGRAM + \ CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH + \ CMAKE_FIND_USE_CMAKE_PATH + \ CMAKE_FIND_USE_CMAKE_SYSTEM_PATH + \ CMAKE_FIND_USE_PACKAGE_REGISTRY + \ CMAKE_FIND_USE_PACKAGE_ROOT_PATH + \ CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH \ CMAKE_FOLDER \ CMAKE_FRAMEWORK \ CMAKE_FRAMEWORK_PATH @@ -1765,6 +1773,7 @@ syn keyword cmakeKWadd_test contained \ NAME \ OFF \ PASS_REGULAR_EXPRESSION + \ SKIP_REGULAR_EXPRESSION \ TARGET_FILE \ WILL_FAIL \ WORKING_DIRECTORY diff --git a/CMakeCPack.cmake b/CMakeCPack.cmake index 78e22cc85..31c2fe456 100644 --- a/CMakeCPack.cmake +++ b/CMakeCPack.cmake @@ -215,7 +215,7 @@ if(NOT DEFINED CPACK_PACKAGE_FILE_NAME) endif() endif() -set(CPACK_PACKAGE_CONTACT "cmake@cmake.org") +set(CPACK_PACKAGE_CONTACT "cmake+development@discourse.cmake.org") if(UNIX) set(CPACK_STRIP_FILES "${CMAKE_BIN_DIR}/ccmake;${CMAKE_BIN_DIR}/cmake;${CMAKE_BIN_DIR}/cpack;${CMAKE_BIN_DIR}/ctest") diff --git a/CMakeLists.txt b/CMakeLists.txt index e60b6c568..da99a6ee8 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,13 +1,24 @@ # Distributed under the OSI-approved BSD 3-Clause License. See accompanying # file Copyright.txt or https://cmake.org/licensing for details. -cmake_minimum_required(VERSION 3.1...3.14 FATAL_ERROR) +cmake_minimum_required(VERSION 3.1...3.15 FATAL_ERROR) set(CMAKE_USER_MAKE_RULES_OVERRIDE_C ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideC.cmake) set(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideCXX.cmake) project(CMake) unset(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX) unset(CMAKE_USER_MAKE_RULES_OVERRIDE_C) +# FIXME: This block should go away after a transition period. +if(MSVC AND NOT CMAKE_VERSION VERSION_LESS 3.15) + # Filter out MSVC runtime library flags that may have come from + # the cache of an existing build tree or from scripts. + foreach(l C CXX) + foreach(c DEBUG MINSIZEREL RELEASE RELWITHDEBINFO) + string(REGEX REPLACE "[-/]M[DT]d?( |$)" "" "CMAKE_${l}_FLAGS_${c}" "${CMAKE_${l}_FLAGS_${c}}") + endforeach() + endforeach() +endif() + # Make sure we can find internal find_package modules only used for # building CMake and not for shipping externally list(INSERT CMAKE_MODULE_PATH 0 ${CMake_SOURCE_DIR}/Source/Modules) @@ -18,6 +29,10 @@ if(CMAKE_BOOTSTRAP) unset(CMAKE_BOOTSTRAP CACHE) endif() +if(CMake_TEST_HOST_CMAKE) + get_filename_component(CMake_TEST_EXTERNAL_CMAKE "${CMAKE_COMMAND}" DIRECTORY) +endif() + if(NOT CMake_TEST_EXTERNAL_CMAKE) if(CMAKE_SYSTEM_NAME STREQUAL "HP-UX") message(FATAL_ERROR @@ -353,11 +368,24 @@ macro (CMAKE_BUILD_UTILITIES) # Setup third-party libraries. # Everything in the tree should be able to include files from the # Utilities directory. + if (CMAKE_SYSTEM_NAME STREQUAL "AIX" AND CMAKE_CXX_COMPILER_ID STREQUAL "GNU") + # using -isystem option generate error "template with C linkage" + include_directories("${CMake_SOURCE_DIR}/Utilities/std") + else() + include_directories(SYSTEM "${CMake_SOURCE_DIR}/Utilities/std") + endif() + include_directories( ${CMake_BINARY_DIR}/Utilities ${CMake_SOURCE_DIR}/Utilities ) + #--------------------------------------------------------------------- + # Build CMake std library for CMake and CTest. + set(CMAKE_STD_LIBRARY cmstd) + add_subdirectory(Utilities/std) + CMAKE_SET_TARGET_FOLDER(cmstd "Utilities/std") + # check for the use of system libraries versus builtin ones # (a macro defined in this file) CMAKE_HANDLE_SYSTEM_LIBRARIES() @@ -429,10 +457,7 @@ macro (CMAKE_BUILD_UTILITIES) set(_CMAKE_USE_OPENSSL_DEFAULT OFF) if(NOT DEFINED CMAKE_USE_OPENSSL AND NOT WIN32 AND NOT APPLE AND CMAKE_SYSTEM_NAME MATCHES "(Linux|FreeBSD)") - find_package(OpenSSL QUIET) - if(OPENSSL_FOUND) - set(_CMAKE_USE_OPENSSL_DEFAULT ON) - endif() + set(_CMAKE_USE_OPENSSL_DEFAULT ON) endif() option(CMAKE_USE_OPENSSL "Use OpenSSL." ${_CMAKE_USE_OPENSSL_DEFAULT}) mark_as_advanced(CMAKE_USE_OPENSSL) @@ -629,8 +654,7 @@ endif() # The main section of the CMakeLists file # #----------------------------------------------------------------------- -# Compute CMake_VERSION, etc. -include(Source/CMakeVersionCompute.cmake) +include(Source/CMakeVersion.cmake) # Include the standard Dart testing module enable_testing() @@ -677,7 +701,7 @@ endif() # to a cdash4simpletest database. In these cases, the CDash dashboards # should be run first. # -if("x${CMAKE_TESTS_CDASH_SERVER}" STREQUAL "x") +if("x${CMAKE_TESTS_CDASH_SERVER}" STREQUAL "x" AND NOT CMake_TEST_NO_NETWORK) set(CMAKE_TESTS_CDASH_SERVER "http://open.cdash.org") endif() @@ -817,7 +841,7 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE) PATTERN "*.sh*" PERMISSIONS OWNER_READ OWNER_EXECUTE OWNER_WRITE GROUP_READ GROUP_EXECUTE WORLD_READ WORLD_EXECUTE - REGEX "Help/dev($|/)" EXCLUDE + REGEX "Help/(dev|guide)($|/)" EXCLUDE ) # Install auxiliary files integrating with other tools. diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 7e7111164..7983be16b 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -27,14 +27,15 @@ To contribute patches: #. Run `Utilities/SetupForDevelopment.sh`_ for local git configuration. #. See `Building CMake`_ for building CMake locally. #. See the `CMake Source Code Guide`_ for coding guidelines. -#. Base all new work on the upstream ``master`` branch. +#. Create a topic branch named suitably for your work. + Base all new work on the upstream ``master`` branch. Base work on the upstream ``release`` branch only if it fixes a regression or bug in a feature new to that release. If in doubt, prefer ``master``. Reviewers may simply ask for a rebase if deemed appropriate in particular cases. #. Create commits making incremental, distinct, logically complete changes with appropriate `commit messages`_. -#. Push a topic branch to a personal repository fork on GitLab. +#. Push the topic branch to a personal repository fork on GitLab. #. Create a GitLab Merge Request targeting the upstream ``master`` branch (even if the change is intended for merge to the ``release`` branch). Check the box labelled "Allow commits from members who can merge to the diff --git a/CTestCustom.cmake.in b/CTestCustom.cmake.in index 823ee3cb7..d3ab9d3ef 100644 --- a/CTestCustom.cmake.in +++ b/CTestCustom.cmake.in @@ -49,6 +49,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION "WarningMessagesDialog\\.cxx" "warning.*directory name.*CMake-Xcode.*/bin/.*does not exist.*" "stl_deque.h:1051" + "Tests/CMakeLib/testCTestResourceSpec.cxx:.*warning: missing initializer for member.*cmCTestResourceSpec::.*" # GCC 4.8 disagrees with later compilers on C++11 initializer list conversion "(Lexer|Parser).*warning.*conversion.*may (alter its value|change the sign)" "(Lexer|Parser).*warning.*(statement is unreachable|will never be executed)" "(Lexer|Parser).*warning.*variable.*was set but never used" diff --git a/CompileFlags.cmake b/CompileFlags.cmake index 91f2adffe..053259f47 100644 --- a/CompileFlags.cmake +++ b/CompileFlags.cmake @@ -54,12 +54,20 @@ if(CMAKE_SYSTEM_PROCESSOR MATCHES "^parisc") endif() # Workaround for TOC Overflow on ppc64 +set(bigTocFlag "") if(CMAKE_SYSTEM_NAME STREQUAL "AIX" AND CMAKE_SYSTEM_PROCESSOR MATCHES "powerpc") - set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -Wl,-bbigtoc") + set(bigTocFlag "-Wl,-bbigtoc") elseif(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_SYSTEM_PROCESSOR MATCHES "ppc64") - set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -Wl,--no-multi-toc") + set(bigTocFlag "-Wl,--no-multi-toc") +endif() +if(bigTocFlag) + include(CheckCXXLinkerFlag) + check_cxx_linker_flag(${bigTocFlag} BIG_TOC_FLAG_SUPPORTED) + if(BIG_TOC_FLAG_SUPPORTED) + set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${bigTocFlag}") + endif() endif() if (CMAKE_CXX_COMPILER_ID STREQUAL SunPro AND diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index dde4dbbbc..42bf52b08 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -79,17 +79,19 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: |prefix_XXX_SUBDIR| for each ```` in :variable:`CMAKE_SYSTEM_PREFIX_PATH` -1. If called from within a find module loaded by +1. If called from within a find module or any other script loaded by a call to :command:`find_package()`, search prefixes unique to the - current package being found. Specifically look in the + current package being found. Specifically, look in the :variable:`_ROOT` CMake variable and the :envvar:`_ROOT` environment variable. - The package root variables are maintained as a stack so if called from - nested find modules, root paths from the parent's find module will be - searched after paths from the current module, - i.e. ``_ROOT``, ``ENV{_ROOT}``, + The package root variables are maintained as a stack, so if called from + nested find modules or config packages, root paths from the parent's find + module or config package will be searched after paths from the current + module or package. In other words, the search order would be + ``_ROOT``, ``ENV{_ROOT}``, ``_ROOT``, ``ENV{_ROOT}``, etc. - This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed. + This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting + the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``. See policy :policy:`CMP0074`. * |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| @@ -97,7 +99,8 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: 2. Search paths specified in cmake-specific cache variables. These are intended to be used on the command line with a ``-DVAR=value``. The values are interpreted as :ref:`semicolon-separated lists `. - This can be skipped if ``NO_CMAKE_PATH`` is passed. + This can be skipped if ``NO_CMAKE_PATH`` is passed or by setting the + :variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``. * |CMAKE_PREFIX_PATH_XXX| * |CMAKE_XXX_PATH| @@ -107,7 +110,8 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: These are intended to be set in the user's shell configuration, and therefore use the host's native path separator (``;`` on Windows and ``:`` on UNIX). - This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed. + This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed or + by setting the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``. * |CMAKE_PREFIX_PATH_XXX| * |CMAKE_XXX_PATH| @@ -119,13 +123,16 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: Hard-coded guesses should be specified with the ``PATHS`` option. 5. Search the standard system environment variables. - This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is an argument. + This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed or by + setting the :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` to ``FALSE``. * |SYSTEM_ENVIRONMENT_PATH_XXX| + * |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| 6. Search cmake variables defined in the Platform files for the current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` - is passed. + is passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` + to ``FALSE``. * |CMAKE_SYSTEM_PREFIX_PATH_XXX| * |CMAKE_SYSTEM_XXX_PATH| diff --git a/Help/command/LINK_OPTIONS_LINKER.txt b/Help/command/LINK_OPTIONS_LINKER.txt index a72337515..3f66181be 100644 --- a/Help/command/LINK_OPTIONS_LINKER.txt +++ b/Help/command/LINK_OPTIONS_LINKER.txt @@ -1,8 +1,8 @@ -To pass options to the linker tool, each compiler driver has is own syntax. -The ``LINKER:`` prefix can be used to specify, in a portable way, options -to pass to the linker tool. The ``LINKER:`` prefix is replaced by the required -driver option and the rest of the option string defines linker arguments using -``,`` as separator. These arguments will be formatted according to the +To pass options to the linker tool, each compiler driver has its own syntax. +The ``LINKER:`` prefix and ``,`` separator can be used to specify, in a portable +way, options to pass to the linker tool. ``LINKER:`` is replaced by the +appropriate driver option and ``,`` by the appropriate driver separator. +The driver prefix and driver separator are given by the values of the :variable:`CMAKE__LINKER_WRAPPER_FLAG` and :variable:`CMAKE__LINKER_WRAPPER_FLAG_SEP` variables. @@ -12,11 +12,11 @@ For example, ``"LINKER:-z,defs"`` becomes ``-Xlinker -z -Xlinker defs`` for The ``LINKER:`` prefix can be specified as part of a ``SHELL:`` prefix expression. -The ``LINKER:`` prefix supports, as alternate syntax, specification of -arguments using ``SHELL:`` prefix and space as separator. Previous example -becomes ``"LINKER:SHELL:-z defs"``. +The ``LINKER:`` prefix supports, as an alternative syntax, specification of +arguments using the ``SHELL:`` prefix and space as separator. The previous +example then becomes ``"LINKER:SHELL:-z defs"``. .. note:: - Specifying ``SHELL:`` prefix elsewhere than at the beginning of the + Specifying the ``SHELL:`` prefix anywhere other than at the beginning of the ``LINKER:`` prefix is not supported. diff --git a/Help/command/OPTIONS_SHELL.txt b/Help/command/OPTIONS_SHELL.txt index 530c0126f..0f8ec323c 100644 --- a/Help/command/OPTIONS_SHELL.txt +++ b/Help/command/OPTIONS_SHELL.txt @@ -1,9 +1,9 @@ The final set of compile or link options used for a target is constructed by accumulating options from the current target and the usage requirements of -it dependencies. The set of options is de-duplicated to avoid repetition. +its dependencies. The set of options is de-duplicated to avoid repetition. While beneficial for individual options, the de-duplication step can break up option groups. For example, ``-D A -D B`` becomes ``-D A B``. One may specify a group of options using shell-like quoting along with a ``SHELL:`` -prefix. The ``SHELL:`` prefix is dropped and the rest of the option string +prefix. The ``SHELL:`` prefix is dropped, and the rest of the option string is parsed using the :command:`separate_arguments` ``UNIX_COMMAND`` mode. For example, ``"SHELL:-D A" "SHELL:-D B"`` becomes ``-D A -D B``. diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index ed321fcef..aba374261 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -68,9 +68,6 @@ The options are: order-only dependencies to ensure the byproducts will be available before their dependents build. - The ``BYPRODUCTS`` option is ignored on non-Ninja generators - except to mark byproducts ``GENERATED``. - ``COMMAND`` Specify the command-line(s) to execute at build time. If more than one ``COMMAND`` is specified they will be executed in order, @@ -82,25 +79,33 @@ The options are: will be ignored. If ``COMMAND`` specifies an executable target name (created by the - :command:`add_executable` command) it will automatically be replaced - by the location of the executable created at build time. If set, the - :prop_tgt:`CROSSCOMPILING_EMULATOR` executable target property will - also be prepended to the command to allow the executable to run on - the host. - (Use the ``TARGET_FILE`` - :manual:`generator expression ` to - reference an executable later in the command line.) - Additionally a target-level dependency will be added so that the - executable target will be built before any target using this custom - command. However this does NOT add a file-level dependency that - would cause the custom command to re-run whenever the executable is - recompiled. + :command:`add_executable` command), it will automatically be replaced + by the location of the executable created at build time if either of + the following is true: + + * The target is not being cross-compiled (i.e. the + :variable:`CMAKE_CROSSCOMPILING` variable is not set to true). + * The target is being cross-compiled and an emulator is provided (i.e. + its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set). + In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be + prepended to the command before the location of the target executable. + + If neither of the above conditions are met, it is assumed that the + command name is a program to be found on the ``PATH`` at build time. Arguments to ``COMMAND`` may use :manual:`generator expressions `. - References to target names in generator expressions imply target-level - dependencies, but NOT file-level dependencies. List target names with - the ``DEPENDS`` option to add file-level dependencies. + Use the ``TARGET_FILE`` generator expression to refer to the location of + a target later in the command line (i.e. as a command argument rather + than as the command to execute). + + Whenever a target is used as a command to execute or is mentioned in a + generator expression as a command argument, a target-level dependency + will be added automatically so that the mentioned target will be built + before any target using this custom command. However this does NOT add + a file-level dependency that would cause the custom command to re-run + whenever the executable is recompiled. List target names with + the ``DEPENDS`` option to add such file-level dependencies. ``COMMENT`` Display the given message before the commands are executed at @@ -111,6 +116,9 @@ The options are: an ``OUTPUT`` of another custom command in the same directory (``CMakeLists.txt`` file) CMake automatically brings the other custom command into the target in which this command is built. + A target-level dependency is added if any dependency is listed as + ``BYPRODUCTS`` of a target or any of its build events in the same + directory to ensure the byproducts will be available. If ``DEPENDS`` is not specified the command will run whenever the ``OUTPUT`` is missing; if the command does not actually create the ``OUTPUT`` then the rule will always run. @@ -219,7 +227,8 @@ target is already built, the command will not execute. [BYPRODUCTS [files...]] [WORKING_DIRECTORY dir] [COMMENT comment] - [VERBATIM] [USES_TERMINAL]) + [VERBATIM] [USES_TERMINAL] + [COMMAND_EXPAND_LISTS]) This defines a new command that will be associated with building the specified ````. The ```` must be defined in the current diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst index 08b95168b..2d5f5f081 100644 --- a/Help/command/add_custom_target.rst +++ b/Help/command/add_custom_target.rst @@ -49,9 +49,6 @@ The options are: order-only dependencies to ensure the byproducts will be available before their dependents build. - The ``BYPRODUCTS`` option is ignored on non-Ninja generators - except to mark byproducts ``GENERATED``. - ``COMMAND`` Specify the command-line(s) to execute at build time. If more than one ``COMMAND`` is specified they will be executed in order, @@ -61,18 +58,30 @@ The options are: a ``COMMAND`` to launch it.) If ``COMMAND`` specifies an executable target name (created by the - :command:`add_executable` command) it will automatically be replaced - by the location of the executable created at build time. If set, the - :prop_tgt:`CROSSCOMPILING_EMULATOR` executable target property will - also be prepended to the command to allow the executable to run on - the host. - Additionally a target-level dependency will be added so that the - executable target will be built before this custom target. + :command:`add_executable` command), it will automatically be replaced + by the location of the executable created at build time if either of + the following is true: + + * The target is not being cross-compiled (i.e. the + :variable:`CMAKE_CROSSCOMPILING` variable is not set to true). + * The target is being cross-compiled and an emulator is provided (i.e. + its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set). + In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be + prepended to the command before the location of the target executable. + + If neither of the above conditions are met, it is assumed that the + command name is a program to be found on the ``PATH`` at build time. Arguments to ``COMMAND`` may use :manual:`generator expressions `. - References to target names in generator expressions imply target-level - dependencies. + Use the ``TARGET_FILE`` generator expression to refer to the location of + a target later in the command line (i.e. as a command argument rather + than as the command to execute). + + Whenever a target is used as a command to execute or is mentioned in a + generator expression as a command argument, a target-level dependency + will be added automatically so that the mentioned target will be built + before this custom target. The command and arguments are optional and if not specified an empty target will be created. @@ -86,6 +95,9 @@ The options are: :command:`add_custom_command` command calls in the same directory (``CMakeLists.txt`` file). They will be brought up to date when the target is built. + A target-level dependency is added if any dependency is a byproduct + of a target or any of its build events in the same directory to ensure + the byproducts will be available before this target is built. Use the :command:`add_dependencies` command to add dependencies on other targets. diff --git a/Help/command/add_test.rst b/Help/command/add_test.rst index 46b9b63c5..a77ba37cc 100644 --- a/Help/command/add_test.rst +++ b/Help/command/add_test.rst @@ -7,7 +7,8 @@ Add a test to the project to be run by :manual:`ctest(1)`. add_test(NAME COMMAND [...] [CONFIGURATIONS ...] - [WORKING_DIRECTORY ]) + [WORKING_DIRECTORY ] + [COMMAND_EXPAND_LISTS]) Adds a test called ````. The test name may not contain spaces, quotes, or other characters special in CMake syntax. The options are: @@ -28,12 +29,18 @@ quotes, or other characters special in CMake syntax. The options are: directory set to the build directory corresponding to the current source directory. +``COMMAND_EXPAND_LISTS`` + Lists in ``COMMAND`` arguments will be expanded, including those + created with + :manual:`generator expressions `. + The given test command is expected to exit with code ``0`` to pass and non-zero to fail, or vice-versa if the :prop_test:`WILL_FAIL` test property is set. Any output written to stdout or stderr will be captured by :manual:`ctest(1)` but does not affect the pass/fail status -unless the :prop_test:`PASS_REGULAR_EXPRESSION` or -:prop_test:`FAIL_REGULAR_EXPRESSION` test property is used. +unless the :prop_test:`PASS_REGULAR_EXPRESSION`, +:prop_test:`FAIL_REGULAR_EXPRESSION` or +:prop_test:`SKIP_REGULAR_EXPRESSION` test property is used. The ``COMMAND`` and ``WORKING_DIRECTORY`` options may use "generator expressions" with the syntax ``$<...>``. See the diff --git a/Help/command/ctest_coverage.rst b/Help/command/ctest_coverage.rst index 8d27b9c1b..d50f63498 100644 --- a/Help/command/ctest_coverage.rst +++ b/Help/command/ctest_coverage.rst @@ -8,7 +8,7 @@ Perform the :ref:`CTest Coverage Step` as a :ref:`Dashboard Client`. ctest_coverage([BUILD ] [APPEND] [LABELS